You're designing the tools for a customer's agent over their CRM. How do you decide what tools to expose and how to shape them?
Answer it out loud first, then compare. That's what makes it stick.
I design tools for the model, not mirror the API. I pick a few tools around real workflows, like get_customer_context instead of three raw list calls, and namespace them by system. Descriptions read like docs for a new hire, with examples. Responses return only high-signal fields with stable ids, and errors say how to fix the call. Then I test the tools with real tasks and read the transcripts to see where the model gets confused.
- Few tools matched to real workflows, not 1:1 API endpoints
- Namespace by service and resource
- Clear descriptions and examples
- Concise responses, stable ids, pagination and filters
- Actionable errors
- Test with tasks, read transcripts, iterate
Tools are a contract between a deterministic system and a non-deterministic caller. Anthropic's guidance is to write them for agents, not as thin wrappers the way you would for other developers.
1. Choose workflow-shaped tools
- Prefer
search_contactsoverlist_contacts: returning every contact makes the model read them one by one and burns context. - Consolidate chained calls. Anthropic's examples: a
schedule_eventtool instead of list_users + list_events + create_event, orget_customer_contextinstead of three separate lookups.
2. Namespace
Prefix by service and resource (crm_contacts_search, zendesk_tickets_search). When overlapping tools exist, the model picks wrongly; this matters most once several MCP servers are attached.
3. Describe like documentation Write what the tool does, when to use it, when not to, and what each parameter means, with a short example. Tool examples cost roughly 20-50 tokens for simple ones and 100-200 for nested objects, which is cheap next to a wrong call.
4. Shape the output
- Return semantic, stable identifiers (slugs, UUIDs), not opaque internals.
- Offer a
response_formatof concise or detailed; truncate and tell the agent how to narrow (filters, pagination). - Include only fields needed for the next decision.
5. Poka-yoke the arguments Make mistakes hard: enums instead of free strings, required ids, absolute paths. Mark write tools clearly, and keep destructive ones out of the default set.
6. Evaluate the tools Run realistic tasks, then track accuracy, number of tool calls, tokens, runtime and tool errors per task. Many redundant calls usually means a missing consolidated tool.
FDE angle. The customer's API was built for engineers. Your value is the thin layer that makes it usable by a model: fewer tools, better names, safer arguments.
- The agent keeps picking the wrong one of two similar tools. What do you change?
- How would you handle an endpoint that returns 50KB of JSON?
- Which tools would you not expose to the agent at all?
- Writing effective tools for AI agents - Anthropic (official, 2025-09-11) Consolidating tools, namespacing, concise responses, token-efficient truncation, actionable errors and evaluating tools programmatically.
- Define tools - Claude Platform Docs (docs, unknown) Namespacing names, returning only high-signal fields with stable ids, and the token cost of tool examples.