Skip to main content

Overview

PromptSmith supports three output formats for generated system prompts, each optimized for different use cases:

Markdown

Human-readable format with headers and formatting. Best for development and debugging.

TOON

Token-Oriented Object Notation. Optimized format reducing tokens by 30-60% compared to markdown.

Compact

Minimal whitespace variant of markdown. Moderate savings of 10-20%.
Choosing the right format helps you balance readability (for humans) with efficiency (for AI models).

Why Format Matters

LLM APIs charge by tokens. System prompts are sent with every request, so reducing their size:
  • Lowers costs (fewer input tokens per request)
  • Reduces latency (faster processing of shorter prompts)
  • Increases context window (leaves more room for conversation)
  • Improves reliability (less chance of hitting token limits)
Real Impact: A 1000-token prompt in markdown becomes ~400-500 tokens in TOON format. At scale (millions of requests), this saves thousands of dollars.

Format Comparison

Let’s compare the same prompt in all three formats:
# Identity
You are a helpful coding assistant.

# Capabilities
1. Explain code concepts
2. Write code examples
3. Debug issues

# Available Tools
## search_docs
Search technical documentation for answers.

**Parameters:**
- `query` (string, required): Search query text
- `limit` (number, optional): Maximum results to return

# Behavioral Guidelines
## You MUST:
- Always include comments in code examples
- Test code mentally before suggesting it

## You MUST NOT:
- Never suggest code with obvious security vulnerabilities
Size: ~450 characters (~113 tokens)

Markdown Format

The default format, optimized for human readability.

Characteristics

  • Standard markdown headers (#, ##)
  • Bullet points and numbered lists
  • Bold text for emphasis (**Parameters:**)
  • Generous whitespace for readability
  • GitHub-flavored markdown compatible

When to Use

Development

Debugging prompts, iterating on content, team reviews

Documentation

Documenting agent behavior, sharing examples

Version Control

Git diffs are readable, changes are obvious

Learning

Understanding how PromptSmith structures prompts

Usage

import { createPromptBuilder } from 'promptsmith';

const prompt = createPromptBuilder()
  .withIdentity("You are a helpful assistant")
  .withFormat('markdown') // Explicit (optional, this is default)
  .build();

// Or use default
const prompt2 = createPromptBuilder()
  .withIdentity("You are a helpful assistant")
  .build(); // Uses markdown by default
See builder.ts:1922-2129 for markdown generation implementation.

TOON Format

Token-Oriented Object Notation - a specialized format designed to minimize token usage while maintaining clarity for LLMs.

Characteristics

  • Indentation-based structure (no markdown headers)
  • Array length declarations: Capabilities[3]:
  • Compact parameter notation: query(string,required): Description
  • Tabular format for repeated structures (examples)
  • Eliminates redundant syntax (no bullets, minimal formatting)

Token Savings

TOON achieves 30-60% token reduction through:
  1. Header elimination: # IdentityIdentity:
  2. Count prefixes: Models process [3] faster than counting items
  3. Compact params: `query` (string, required):query(string,required):
  4. Indentation over bullets: - Item Item
  5. No emphasis markers: **Parameters:**Parameters:
LLM-Optimized: TOON was designed based on how transformer models tokenize text. Indentation and colons are highly efficient tokens.

When to Use

Production

High-traffic applications where cost matters

Large Prompts

Complex agents with many tools/constraints

Cost Optimization

Reducing API costs at scale

Context Window

Preserving space for longer conversations

Usage

const prompt = createPromptBuilder()
  .withIdentity("You are a helpful assistant")
  .withFormat('toon')
  .build();

// Or override temporarily
const toonPrompt = builder.build('toon');

Structure Examples

Identity:
  You are a helpful coding assistant.

Context:
  Primary Languages: TypeScript, Python
  Frameworks: React, Next.js
Capabilities[5]:
  Explain code concepts
  Write code examples
  Debug issues
  Review code
  Suggest best practices
The [5] tells the model how many items to expect, improving processing.
Tools[2]:
  search_docs:
    Search technical documentation for answers.
    Parameters:
      query(string,required): Search query text
      limit(number,optional): Maximum results (default 10)
  
  execute_code:
    Execute code in a sandboxed environment.
    Parameters:
      code(string,required): Code to execute
      language(enum,required): Programming language
When all examples have the same structure, TOON uses a compact tabular format:
Examples[3]{user,assistant,explanation}:
  "What is TypeScript?","TypeScript is a...","Shows concise explanation"
  "How do I...","You can do this by...","Demonstrates step-by-step guidance"
  "Debug this code","I see the issue...","Shows debugging approach"
This is dramatically more compact than markdown:
## Example 1
**User:** What is TypeScript?
**Assistant:** TypeScript is a...
*Shows concise explanation*
Constraints:
  MUST[3]:
    Always verify user authentication
    Log all data access attempts
    Cite sources for factual claims
  MUST_NOT[2]:
    Never bypass authentication
    Never log passwords
  SHOULD[4]:
    Provide comprehensive answers
    Use clear language
    Include examples when helpful
    Explain reasoning
See builder.ts:2146-2412 for TOON generation implementation.

Compact Format

A balanced option that maintains markdown structure while removing excess whitespace.

Characteristics

  • Same markdown syntax as default
  • Removes extra line breaks
  • Trims leading/trailing whitespace
  • Collapses multiple spaces
  • Still human-readable

Token Savings

Achieves 10-20% reduction by:
  1. Reducing line breaks: \n\n\n\n\n
  2. Trimming whitespace: text text
  3. Collapsing spaces: word wordword word

When to Use

QA/Staging

Testing before production, still readable for debugging

Moderate Savings

Want efficiency without TOON’s radical syntax change

Team Preference

Team prefers markdown but wants some optimization

Gradual Migration

Transitioning from markdown to TOON

Usage

const prompt = createPromptBuilder()
  .withIdentity("You are a helpful assistant")
  .withFormat('compact')
  .build();
See builder.ts:2462-2470 for compact generation (applies transformations to markdown output).

Choosing a Format

Decision Flow

1

Development Phase

Use markdown for:
  • Initial prompt authoring
  • Team reviews and collaboration
  • Debugging agent behavior
  • Understanding prompt structure
2

Testing/QA

Switch to compact for:
  • Staging environment testing
  • Performance benchmarking
  • Gradual optimization
  • Maintaining readability while saving ~15%
3

Production

Deploy with TOON for:
  • High-traffic production workloads
  • Complex prompts (many tools/constraints)
  • Cost-sensitive applications
  • Maximum token efficiency (30-60% savings)

Quick Reference

FormatToken SavingsReadabilityUse Case
Markdown0% (baseline)⭐⭐⭐⭐⭐Development, debugging, documentation
Compact10-20%⭐⭐⭐⭐QA, staging, moderate optimization
TOON30-60%⭐⭐⭐Production, high traffic, cost optimization

Format Comparison Tool

Compare token usage across formats:
const builder = createPromptBuilder()
  .withIdentity("You are a helpful assistant")
  .withCapabilities(["Answer questions", "Provide help"])
  .withTool({
    name: "search",
    description: "Search for information",
    schema: z.object({ query: z.string() })
  });

// Debug shows comparison
builder.debug();

// Output includes:
// Size: 823 chars (~206 tokens)
// TOON format: 512 chars (~128 tokens) - saves 38%
See builder.ts:1477-1485 for token comparison in debug output.

Caching by Format

The builder caches each format separately:
const markdown = builder.build('markdown'); // Generated & cached
const toon = builder.build('toon');         // Generated & cached
const compact = builder.build('compact');   // Generated & cached

// Subsequent calls return cached versions
const markdown2 = builder.build('markdown'); // Instant (from cache)
Modifying the builder (e.g., .withCapability()) invalidates all cached formats.
See cache.ts:1-90 for caching implementation.

Best Practices

Development Workflow

// 1. Author in markdown
const builder = createPromptBuilder()
  .withIdentity("...")
  .withFormat('markdown');

console.log(builder.build()); // Human-readable

// 2. Test in compact
builder.withFormat('compact');
// Verify behavior still works with less whitespace

// 3. Deploy in TOON
builder.withFormat('toon');
// Maximum efficiency for production

Environment-Specific Formats

const format = process.env.NODE_ENV === 'production' ? 'toon' : 'markdown';

const prompt = createPromptBuilder()
  .withIdentity("...")
  .withFormat(format)
  .build();

A/B Testing

Compare model behavior across formats:
const builder = createPromptBuilder()
  .withIdentity("...")
  .withCapabilities([...]);

const testCases = [
  { input: "Hello", expectedBehavior: "Greet warmly" },
  { input: "Help", expectedBehavior: "Offer assistance" }
];

for (const format of ['markdown', 'compact', 'toon']) {
  const prompt = builder.build(format);
  
  // Test with your LLM
  const results = await testPrompt(prompt, testCases);
  
  console.log(`${format}: ${results.passRate}% pass rate`);
}

Measuring Token Usage

Estimate token counts:
function estimateTokens(text: string): number {
  // Rough estimate: ~4 characters per token for English
  return Math.ceil(text.length / 4);
}

const markdown = builder.build('markdown');
const toon = builder.build('toon');

const markdownTokens = estimateTokens(markdown);
const toonTokens = estimateTokens(toon);
const savings = ((markdownTokens - toonTokens) / markdownTokens) * 100;

console.log(`Markdown: ~${markdownTokens} tokens`);
console.log(`TOON: ~${toonTokens} tokens`);
console.log(`Savings: ${savings.toFixed(1)}%`);
For precise token counts, use a tokenizer library like tiktoken or @anthropic-ai/tokenizer.

TOON Specification

TOON (Token-Oriented Object Notation) is an indentation-based format optimized for LLM consumption.

Core Principles

  1. Indentation indicates hierarchy (2 spaces per level)
  2. Colons denote sections: SectionName:
  3. Square brackets indicate counts: Items[5]:
  4. Compact parameter syntax: name(type,requirement): description
  5. Tabular format for repeated structures: Examples[3]{field1,field2}:

Section Mapping

MarkdownTOON
# IdentityIdentity:
# CapabilitiesCapabilities[N]:
# Available ToolsTools[N]:
## tool_name tool_name:
**Parameters:** Parameters:
- `param` (type, req): desc param(type,req): desc
# Behavioral GuidelinesConstraints:
## You MUST: MUST[N]:
- Rule Rule

Learn More

TOON Official Docs

Full specification, benchmarks, and advanced usage patterns for TOON format.

Performance Impact

Real-world token savings with a production agent:
const productionAgent = createPromptBuilder()
  .withIdentity("Customer service assistant")
  .withCapabilities([/* 8 capabilities */])
  .withTools([/* 12 tools */])
  .withConstraints('must', [/* 15 must constraints */])
  .withConstraints('should', [/* 20 should constraints */])
  .withExamples([/* 10 examples */])
  .withGuardrails();
Results:
  • Markdown: 4,823 chars (~1,206 tokens)
  • Compact: 4,012 chars (~1,003 tokens) - 17% reduction
  • TOON: 2,891 chars (~723 tokens) - 40% reduction
Cost Savings (GPT-4 @ $0.03/1K input tokens, 1M requests/month):
  • Markdown: $36.18/month
  • Compact: 30.09/monthsaves30.09/month - **saves 6.09/month**
  • TOON: 21.69/monthsaves21.69/month - **saves 14.49/month**
At scale (10M requests/month), TOON saves $144.90/month compared to markdown.

Troubleshooting

Cause: Some models might not parse TOON as well as markdown.Solution: Test thoroughly before deploying TOON in production. Most modern LLMs (GPT-4, Claude, etc.) handle TOON well.
// A/B test formats
const testResults = {
  markdown: await testWithFormat('markdown'),
  toon: await testWithFormat('toon')
};

if (testResults.markdown.quality > testResults.toon.quality) {
  console.warn('TOON may not be optimal for this model');
}
Cause: TOON is optimized for LLMs, not humans.Solution: Use markdown during development, only switch to TOON for production.
const isDev = process.env.NODE_ENV === 'development';
const format = isDev ? 'markdown' : 'toon';
Cause: Savings vary based on prompt complexity. Simple prompts see less benefit.Solution: TOON shines with complex prompts (many tools, constraints, examples). For simple prompts, compact may be sufficient.
const summary = builder.getSummary();
const isComplex = summary.toolsCount > 5 || summary.constraintsCount > 10;

const format = isComplex ? 'toon' : 'compact';

Builder

Learn about format selection and caching

Performance

Optimize prompts for production

Testing

Test prompts across formats

Build docs developers (and LLMs) love