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%.
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:- Markdown (Default)
- TOON (Most Efficient)
- Compact (Balanced)
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
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:- Header elimination:
# Identity→Identity: - Count prefixes: Models process
[3]faster than counting items - Compact params:
`query` (string, required):→query(string,required): - Indentation over bullets:
- Item→Item - 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
Structure Examples
Identity & Context
Identity & Context
Capabilities
Capabilities
[5] tells the model how many items to expect, improving processing.Tools
Tools
Examples (Tabular)
Examples (Tabular)
When all examples have the same structure, TOON uses a compact tabular format:This is dramatically more compact than markdown:
Constraints
Constraints
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:- Reducing line breaks:
\n\n\n→\n\n - Trimming whitespace:
text→text - Collapsing spaces:
word word→word 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
builder.ts:2462-2470 for compact generation (applies transformations to markdown output).
Choosing a Format
Decision Flow
Development Phase
Use markdown for:
- Initial prompt authoring
- Team reviews and collaboration
- Debugging agent behavior
- Understanding prompt structure
Testing/QA
Switch to compact for:
- Staging environment testing
- Performance benchmarking
- Gradual optimization
- Maintaining readability while saving ~15%
Quick Reference
| Format | Token Savings | Readability | Use Case |
|---|---|---|---|
| Markdown | 0% (baseline) | ⭐⭐⭐⭐⭐ | Development, debugging, documentation |
| Compact | 10-20% | ⭐⭐⭐⭐ | QA, staging, moderate optimization |
| TOON | 30-60% | ⭐⭐⭐ | Production, high traffic, cost optimization |
Format Comparison Tool
Compare token usage across formats:builder.ts:1477-1485 for token comparison in debug output.
Caching by Format
The builder caches each format separately:Modifying the builder (e.g.,
.withCapability()) invalidates all cached formats.cache.ts:1-90 for caching implementation.
Best Practices
Development Workflow
Environment-Specific Formats
A/B Testing
Compare model behavior across formats:Measuring Token Usage
Estimate token counts: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
- Indentation indicates hierarchy (2 spaces per level)
- Colons denote sections:
SectionName: - Square brackets indicate counts:
Items[5]: - Compact parameter syntax:
name(type,requirement): description - Tabular format for repeated structures:
Examples[3]{field1,field2}:
Section Mapping
| Markdown | TOON |
|---|---|
# Identity | Identity: |
# Capabilities | Capabilities[N]: |
# Available Tools | Tools[N]: |
## tool_name | tool_name: |
**Parameters:** | Parameters: |
- `param` (type, req): desc | param(type,req): desc |
# Behavioral Guidelines | Constraints: |
## 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:- Markdown: 4,823 chars (~1,206 tokens)
- Compact: 4,012 chars (~1,003 tokens) - 17% reduction
- TOON: 2,891 chars (~723 tokens) - 40% reduction
- Markdown: $36.18/month
- Compact: 6.09/month**
- TOON: 14.49/month**
At scale (10M requests/month), TOON saves $144.90/month compared to markdown.
Troubleshooting
Model behaves differently with TOON
Model behaves differently with TOON
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.
TOON prompt looks unreadable
TOON prompt looks unreadable
Cause: TOON is optimized for LLMs, not humans.Solution: Use markdown during development, only switch to TOON for production.
Token savings less than expected
Token savings less than expected
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.
Related
Builder
Learn about format selection and caching
Performance
Optimize prompts for production
Testing
Test prompts across formats