Designing tools for AI agents: wrap the workflow, not the API

The fastest way to give an agent tools is to wrap every existing API endpoint: list_users, list_events, create_event… The results are usually poor: the agent makes a dozen calls, reads hundreds of records it doesn't need, mixes up UUIDs, and runs out of context before finishing. Anthropic's engineering post Writing effective tools for AI agents (Ken Aizawa, September 2025) argues that tools are a new kind of software: a "contract" between deterministic systems and a non-deterministic agent, so they must be designed for agents. This post summarises the process and five principles, which apply to MCP servers and API tools alike.

The process: prototype → eval → let Claude improve

1. Prototype quickly: stand up the tools (local MCP server or passed straight to the API) and try them yourself through Claude Code.
2. Evaluate with real tasks: many realistic prompts, possibly needing dozens of tool calls. "Schedule a meeting with An next week, attach the previous notes, book a room" beats "create an event for email X". Each task needs a way to check the result.
3. Track several metrics: accuracy, runtime, number of tool calls, tokens, tool errors. Redundant repeated calls are a sign tools should be merged.
4. Read transcripts and let Claude refactor: paste eval logs into Claude Code so it can fix many tools at once. According to the post, most of their advice came from this loop, with a held-out test set to avoid overfitting.

An example from the post: Claude kept appending "2025" to web search queries; fixing the tool description solved it.

Five tool design principles

1. Choose the right tools: fewer, better

More tools don't mean better results: overlapping tools distract the agent.

2. Namespace them

With dozens of MCP servers, group tools by service/resource prefix: asana_search, jira_search, asana_projects_search. The post notes prefix vs suffix naming gives different results depending on the model, so test with evals.

3. Return meaningful context

Prefer name, image_url, file_type over uuid, mime_type. Turning cryptic IDs into readable names reduces hallucinations. When the agent still needs IDs for follow-up calls, add a response_format parameter with "concise"/"detailed". In the post's Slack example, the detailed version was 206 tokens and the concise one 72, about a third.

4. Be token-efficient

• Pagination, filtering, range selection and truncation with sensible defaults. Claude Code caps tool results at 25,000 tokens by default.
• When truncating, tell the agent how to narrow its search.
• Error messages must be actionable: say what's wrong and give an example of valid input, not a bare error code or stack trace.

5. Write tool descriptions like onboarding a new hire

Descriptions and parameter names live in context, so they strongly shape behaviour. Explain special query formats, internal jargon and relationships between resources. Use unambiguous parameter names (user_id instead of user) and strict schemas. For MCP, use annotations to flag destructive or open-world tools.

Risks and caveats

• Over-merging into a multi-mode "super tool" also confuses agents; consolidate around users' real workflows.
• Evals generated by Claude itself can be biased; keep a hand-written test set.
• Tools with side effects (sending email, deleting data) need confirmation or separate permissions, not just a description.

How to apply it

• Dev: Review the MCP server you're writing: which tools just wrap an endpoint? Merge them by task, add response_format and default pagination.
• Tech Lead: Build an eval set of 20–50 real tasks for internal tools and track calls and tokens each time a description changes.
• PM: Describe user workflows ("book a meeting with documents attached") instead of an API list. That's the best input for tool design.