Tool Descriptions That Guide Selection
Explore how to craft tool descriptions that serve as behavioral instructions for Claude AI, helping it decide when and how to call tools. Understand the four key components of effective descriptions, learn to prevent common mistakes like over-calling or wrong sequencing, and distinguish between schema-level and description-level constraints to improve AI-driven tool selection and workflow reliability.
A tool definition has three parts: a name, a description, and an input schema. Most engineers treat the description as documentation for a human reader and the schema as the technical spec. That framing is backward. Claude reads the description to decide whether to call the tool, when to call it, and what to put in the arguments. The description is behavioral instruction, not documentation.
This lesson reframes tool design as the primary mechanism for shaping agent behavior. By the end, we will understand how to write descriptions that produce correct call sequences, avoid ambiguous selections, and enforce boundaries without a system prompt. By the end of this lesson, we will be able to:
Explain why tool descriptions are Claude’s primary decision signal for tool selection.
Identify the four components of an effective tool description.
Write a description that prevents a common selection mistake (over-calling, under-calling, wrong order).
Distinguish between description-level constraints and schema-level constraints. ...