Learn · Tool design & MCP · CCAR-F task 2.1

Designing tool interfaces

Claude picks tools by reading their descriptions. Write them like docs: what, when, when not, input formats and boundaries.

Key ideas

• A tool is a name, a description and an input_schema; the description is the main selection mechanism.
• Good descriptions cover what it does, when to use it and when not to, input formats, examples and edge cases.
• Overlapping names or descriptions cause misrouting: rename look-alikes and sharpen boundaries.
• Split do-everything tools into purpose-specific ones; consolidate many tiny ones into a few capable ones.
• Namespace by service (github_list_prs), return high-signal fields with stable IDs, and paginate large results.
• Mistake-proof the schema with enums, required fields and absolute paths.
• Check the system prompt for wording that pulls Claude toward the wrong tool.

Worked example: An HR assistant that searches the wrong index

An HR assistant has search_policies and search_tickets, both described as 'search HR content'. Questions like 'what is the parental leave policy?' land in old tickets. The fix is precise descriptions: what each index holds, an example query for each, and 'use search_policies for rules, search_tickets only for a named employee's case'.

Exam traps

• Reaching for few-shot examples or a routing classifier before fixing thin tool descriptions.
• Merging two distinct tools into one generic tool to 'avoid confusion'.
• Returning every field from the backend; bloated results waste context and hide what matters.
• Forgetting that a system prompt instruction can override otherwise good tool descriptions.

Official docs

• Define tools
• Writing effective tools for agents

Practise CCAR-F questions · Next lesson: Structured error responses