How do you design a tool so a model calls it correctly?

Treat a tool as an interface for a reader who sees only its name, description and schema. Give it a clear namespaced name and a detailed description of what it does and when to use it. Use a tight schema with examples, compact outputs and error messages that say how to fix the call. Most wrong tool calls come from vague descriptions, not from the model.

1. Name and scope

• One tool per real task, not one per API endpoint. schedule_event that finds a free slot and books it beats separate list_users, list_events and create_event calls the model must chain.
• Related operations can share a tool with an action parameter, which keeps the tool list short.
• Prefix names by service (github_list_prs, jira_create_issue) so tools from different sources do not collide.

2. Description: the most important part

Anthropic's tool-use docs name the description as the biggest factor in tool performance and ask for at least 3 to 4 sentences. Say what the tool does, when to use it and when not to, what each parameter means and what it returns. Write it for a new colleague. Abbreviations and internal jargon cause wrong calls.

3. Schema

• Use enums for fixed choices, required fields for what must be there, and formats in the description ("ISO date, 2026-10-16").
• Add input_examples for complex inputs.
• Turn on strict: true where a malformed call would break your code, so inputs always match the schema.
• Design out mistakes. Anthropic's "Building effective agents" tells of a model making errors with relative file paths that went away once the tool required absolute paths. They call this poka-yoke: make the wrong call impossible.

4. Output

• Return only what the next decision needs: names and ids, not 40 fields of internal metadata. Every byte of a result is read again on every later turn.
• Paginate or truncate large results, and say so in the result ("showing 20 of 312; pass page=2").

5. Errors

Return failures as a tool result with is_error: true and an instruction, not a stack trace: "order_id must look like A-1042; you sent 1042." The model reads it and retries, usually correctly.

6. Test it like an interface

Run real tasks, read the transcripts and see where the model hesitates or calls the wrong tool. Then change the name or description, not the prompt. Anthropic calls this the agent-computer interface and advises giving it the same care as a human one.