Designing Tool Schemas and Descriptions

A tool definition is the contract between Claude and your code. Claude reads it to decide whether to call the tool, what arguments to supply and how to interpret the result. Most tool-use failures in production trace back to the definition rather than the model: a vague description, an ambiguous parameter name, a schema that permits nonsense. The exam tests the anatomy of a definition and the design rules that make tools reliable.

Anatomy of a tool

Every user-defined tool has three required parts: a name, a description, and an input_schema in JSON Schema.

{
  "name": "get_order_status",
  "description": "Look up the current fulfilment status of a customer order by order ID. Call this whenever the user asks where an order is, whether it has shipped, or when it will arrive. Returns status, carrier and estimated delivery date. Does not modify the order.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The order identifier, e.g. ORD-48213. Always uppercase."
      },
      "include_history": {
        "type": "boolean",
        "description": "Set true to include every status transition, not just the latest."
      }
    },
    "required": ["order_id"],
    "additionalProperties": false
  },
  "strict": true
}

Names should be verbs or verb phrases in snake_case that describe one action. Avoid overloading: manage_orders with an action parameter forces the model to learn a sub-protocol, whereas get_order_status, cancel_order and update_shipping_address are self-explanatory.

Writing descriptions

The description is the single most important field. Anthropic's guidance is to write several sentences that cover:

• What the tool does and what it returns.
• When to call it, stated as trigger conditions ("call this whenever the user asks about delivery"). Recent models reach for tools conservatively, so explicit triggers raise the should-call rate.
• When not to call it, if there is a sibling tool that could be confused with it.
• Side effects and cost, so the model can weigh them ("sends an email; irreversible").

Every property needs its own description with format and examples. A parameter named date with no format note invites 03/04/2025; "ISO 8601 date, e.g. 2025-04-03" removes the ambiguity. Use enum for closed sets instead of free text, and prefer specific types (integer, boolean) to strings that encode them.

Strict mode

Setting strict: true on a tool makes the API guarantee that tool_use.input validates exactly against the schema. The schema must then set additionalProperties: false and list required properties; a supported subset of JSON Schema applies, so check the documentation for unsupported keywords such as certain numeric constraints. Strict mode removes a whole class of defensive parsing code, but it does not stop the model from choosing the wrong tool or supplying a valid but wrong value. Validation of meaning stays with you.

Designing the tool surface

The set of tools you expose is an architecture decision:

Choice	Favour when
Few broad tools (a bash tool, a generic query tool)	The model is capable, the environment is sandboxed and flexibility matters
Many narrow tools	Actions have distinct safety profiles, inputs need validation, or non-engineers audit behaviour

Narrow tools are easier to permission (allow this one, deny that one) and to make strict. Broad tools reduce the number of definitions the model must hold in context. Keep the total tool count manageable: every definition is sent on every request and consumes context, and large tool sets degrade selection accuracy. When a surface grows past a few dozen tools, use tool search or deferred loading so that only relevant definitions are presented, or split tools across subagents.

Results are part of the design

Decide what a tool returns as carefully as what it accepts. Return concise, structured text that the model can act on; strip fields it will never need; include an explicit status. Large payloads should be paginated or summarised, since the result lands in the context window. If a result could be mistaken for instructions (web page content, email bodies), wrap it in a clear delimiter and remind the model in the system prompt that tool output is data.

Testing a definition

Iterate on definitions like prompts. Write a small evaluation set of user requests that should trigger each tool, with expected arguments, and measure selection and argument accuracy as you change descriptions. A description change that fixes one case often breaks another; the evaluation set is how you find out.

Exam focus

• A tool requires name, description and input_schema; the description drives when the tool is chosen and should state triggers, returns and side effects.
• Every property should have a description with format guidance; closed sets use enum.
• strict: true guarantees schema-valid input (needs additionalProperties: false and required) but not semantic correctness or correct tool choice.
• Narrow single-purpose tools are easier to permission and validate; broad tools reduce definition overhead but need sandboxing.
• Tool definitions consume context on every request; large surfaces need tool search, deferred loading or partitioning across subagents.
• Tool results enter the context as data and should be concise, structured and clearly delimited.