Which Envelope Format Should I Use?
Decision Tree (confidence: high)
If LLM compliance is top priority → XML envelope. Hierarchical structure and semantic tag names improve instruction following by ~15-20%. Choose narrow XML (3-5 top-level tags) for most tools, wide XML (15+ module blocks) only for complex multi-module systems like Manus.
If human readability is top priority → Markdown headers. Flat headers (all ##, no nesting) for scannability. Deeply nested (3-4 levels, ## > ### > ####) for complex documentation-style prompts.
If machine parseability is needed → JSON or YAML. JSON-embedded works for tools like VSCode Agent (instructions inside JSON string values). YAML (Amp only) enforces strict structure but LLMs may treat it as config data rather than instructions.
If deterministic narrow operation → Template variables. Minimal skeleton with {{variable}} placeholders (Xcode actions). Best for single-purpose tool integrations where no persona or workflow is needed.
Token Budget Guidance (confidence: high)
- Tight budget (<2K tokens) → Markdown headers (no closing-tag overhead)
- Moderate budget (2K-10K tokens) → Either format works
- Generous budget (>10K tokens) → XML (added structure outweighs token cost)
Format Prevalence (confidence: high)
| Format | Prevalence | Best For |
|---|---|---|
| XML envelope | ~35% (18 tools) | Maximum LLM compliance |
| Markdown headers | ~29% (15 tools) | Developer-facing, human-editable |
| YAML config | ~2% (1 tool) | Machine-first configuration |
| JSON-embedded | ~4% (2 tools) | Code-native tools |
| Template variables | ~2% (1 tool) | Single-purpose, deterministic tools |
Implications (confidence: high)
XML and markdown together cover ~64% of the ecosystem — these are the safe choices. The emerging experiments (YAML, JSON-only) have not demonstrated clear advantages. If you’re unsure, start with markdown (prototyping speed) and migrate to XML when instruction-following reliability becomes critical.
Links: xml-envelope-format, markdown-header-format, xml-vs-markdown-envelopes, template-variable-prompts
Sources
- [raw/prompts/articles/taxonomy-synthesis-2026-07-16.md]