Writing effective tools for AI agents — with agents
by Anthropic
Design tools your agent can actually use well — then let Claude optimize them.
Overview
Published on 11 September 2025 and led by Anthropic's Ken Aizawa with contributions from more than a dozen Anthropic engineers, this post argues that a tool is a new kind of software — a contract between a deterministic system and a non-deterministic agent — and therefore cannot be designed like an ordinary API endpoint. It is organised as a workflow followed by principles. The workflow: stand up a fast prototype (feed Claude the library's llms.txt, register it with `claude mcp add`, test it by hand), then write dozens of evaluation prompts grounded in realistic workflows with verifiable outcomes, run them programmatically in a simple agentic loop, and collect accuracy, runtime, tool-call count, token consumption and error counts alongside the agent's own reasoning transcripts. Those transcripts are then pasted back into Claude Code, which refactors whole tool suites at once while a held-out test set guards against overfitting. The principles that follow are concrete: build a few high-leverage tools instead of wrapping every endpoint (a single `schedule_event` rather than `list_users` plus `list_events` plus `create_event`); namespace related tools by service or by resource; return semantically meaningful fields instead of UUIDs and MIME types; add a `response_format` enum so an agent can request concise output, which takes one Slack thread from 206 tokens to 72; paginate and truncate with steering error messages, since Claude Code caps tool responses at 25,000 tokens by default; and prompt-engineer the descriptions themselves, which the post credits for Claude Sonnet 3.5's state-of-the-art SWE-bench Verified result.
At a Glance
- Topic
- Skills
- Level
- Advanced
- Format
- Guide
- Cost
- Free
- Duration
- ~25 min read
- Provider
- Anthropic
- Hands-on
- No
- Certificate
- None
What You’ll Learn
- ✓Decide which few high-leverage tools to build instead of wrapping every endpoint
- ✓Namespace tools by service or resource so agents stop picking the wrong one
- ✓Write evaluation prompts with verifiable outcomes and run them programmatically
- ✓Instrument agent runs for accuracy, token consumption, tool errors and runtime
- ✓Feed evaluation transcripts back into Claude Code to refactor a tool suite
- ✓Return semantic fields rather than raw UUIDs to improve retrieval precision
- ✓Offer concise and detailed response formats to cut tool output tokens
- ✓Write tool descriptions the way you would onboard a new teammate
Highlights
- •Written from Anthropic's own production MCP servers for Slack and Asana
- •Reframes a tool as a contract with a non-deterministic consumer
- •Concrete token numbers: one Slack thread response drops from 206 to 72 tokens
- •Names the 25,000-token default tool-response cap in Claude Code
- •Ties description quality directly to a measured SWE-bench Verified result
Who It’s For
Best For
- ✓Engineers designing the tool surface an agent will call
- ✓MCP server authors whose tools agents keep misusing
- ✓Teams building evaluation harnesses for agent reliability
Prerequisites
- •Working knowledge of tool use and function calling
- •Some experience running or evaluating an agent end to end
FAQ
What is Writing effective tools for AI agents — with agents?
Anthropic's engineering guide to writing tools an agent can use reliably, drawn from their own production MCP servers. It gives a full workflow — prototype, evaluate, then hand the transcripts back to Claude Code to refactor — plus concrete principles on tool selection, namespacing, response shape and token efficiency. For engineers whose agents underperform because the tool surface is wrong.
Is Writing effective tools for AI agents — with agents free?
Writing effective tools for AI agents — with agents is free to access.
What level is Writing effective tools for AI agents — with agents for?
Writing effective tools for AI agents — with agents is aimed at a advanced audience. Recommended background: Working knowledge of tool use and function calling, Some experience running or evaluating an agent end to end.
How long does Writing effective tools for AI agents — with agents take?
Expect roughly ~25 min read. Most learners work through it at their own pace.
What will I learn from Writing effective tools for AI agents — with agents?
You'll learn: Decide which few high-leverage tools to build instead of wrapping every endpoint; Namespace tools by service or resource so agents stop picking the wrong one; Write evaluation prompts with verifiable outcomes and run them programmatically; Instrument agent runs for accuracy, token consumption, tool errors and runtime; Feed evaluation transcripts back into Claude Code to refactor a tool suite; Return semantic fields rather than raw UUIDs to improve retrieval precision; Offer concise and detailed response formats to cut tool output tokens; Write tool descriptions the way you would onboard a new teammate.
Topics
Sources
This page was written from 2 sources, 1 on domains other than anthropic.com.