Source: Writing effective tools for agents (Anthropic, 2025)

Anthropic engineering post on designing and evaluating agent tools: consolidation, token-efficient responses, truncation, namespacing and eval-driven iteration.

Contents

Summary

Treats tools as a contract between deterministic software and a non-deterministic agent. Recommends few, purpose-built tools whose outputs are token-efficient, and iterating on them with realistic evals and transcript review.

Key claims

  • Prefer consolidated, workflow-shaped tools (e.g. a log search returning relevant lines) over thin wrappers on every endpoint; overlapping tools distract agents.
  • Return high-signal fields; offer a concise/detailed response format; paginate, filter and set sensible default limits.
  • Claude Code caps tool responses at 25,000 tokens by default; truncation messages should steer the agent to narrower queries, and errors should say how to fix the call.
  • Namespace related tools by service/resource prefixes; the best scheme varies by model and should be tested.
  • Evaluate tools with multi-step, verifiable tasks; track tool errors and call counts; use held-out sets to avoid overfitting.

Feeds

Coding agents

Suggest changes →