Token-Efficient Tool Responses

Definition

Shaping tool return values so they spend the agent's limited context efficiently — through pagination, truncation, format control, high-signal fields, and semantic identifiers.

Key points

• For any response that could consume a lot of context, implement pagination, range selection, filtering, and/or truncation with sensible default parameter values.
• Steer agents toward token-efficient strategies — e.g. many small, targeted searches instead of one broad search.
• Prioritize contextual relevance over flexibility. Eschew low-level technical identifiers (e.g. uuid, 256px_image_url, mime_type); prefer fields like name, image_url, file_type that directly inform downstream actions.
• Agents handle natural-language names/terms/identifiers significantly more successfully than cryptic identifiers. "Merely resolving arbitrary alphanumeric UUIDs to more semantically meaningful and interpretable language (or even a 0-indexed ID scheme) significantly improves Claude's precision in retrieval tasks."
• Flexible response formats via a response_format enum: let the agent request "concise" vs "detailed" output. Example: detailed ≈ 206 tokens vs concise ≈ 72 tokens — roughly a 65% reduction while preserving actionability.
• Error messages matter: prompt-engineer error responses to communicate specific, actionable improvements, not opaque error codes or tracebacks.

Why it matters for the exam

• The canonical fix for context-bloat / redundant-tool-call problems is pagination/truncation + high-signal fields.
• Semantic (or 0-indexed) IDs beating raw UUIDs on retrieval precision is a testable empirical claim.

Common gotchas

• Returning opaque UUIDs / mime_type instead of natural-language fields hurts retrieval precision.
• Omitting sensible default limits lets a single response blow the context budget.

See also

• Effective Tool Descriptions
• Structured Tool Errors
• Agentic Tool Evaluation Loop

Sources

• blog-writing-tools