← Blog

Claude Tool Definition Schema: Descriptions That Work

October 28, 2026

How to write Claude tool definitions that work: description trigger conditions, input_schema structure, required parameters, and tool disambiguation.

A Claude tool definition contains three required fields: name, description, and input_schema. Of these, description is the most consequential — it tells Claude when to invoke the tool. A vague description causes missed or misrouted calls; a precise one with scope boundaries and trigger conditions measurably improves accuracy in agentic pipelines.

Plinth Prep is an independent study resource, not affiliated with, endorsed by, or sponsored by Anthropic. The guidance below is drawn from Anthropic's published API documentation and is intended for developers building Claude-powered applications and candidates preparing for the Claude Certified Architect — Foundations (CCA-F) exam.

What fields does a Claude tool definition require?

Every tool passed to the Claude API must include three top-level fields:

  • name — A unique identifier Claude uses to label its tool call in the response. Prefer lowercase with underscores, descriptive of the action: get_weather, search_database, send_email.
  • description — Free text that Claude reads to decide whether and when to call the tool. This field controls invocation behavior more than any other, and it is the one most commonly written too vaguely.
  • input_schema — A JSON Schema object defining the parameters the tool accepts. The top level must always declare "type": "object", even for a tool that takes no parameters.

A minimal but well-formed definition looks like this:

{
  "name": "get_current_weather",
  "description": "Get the current weather for a given city. Call this when the user asks about current conditions — not forecasts or historical data.",
  "input_schema": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "The city name, e.g. 'Paris' or 'New York'"
      }
    },
    "required": ["city"]
  }
}

Missing any of the three fields produces a validation error. There are no defaults — all three are always required.

How does the description field control when Claude calls a tool?

Claude selects tools by reading their descriptions at inference time. The description is not passive documentation — it is the primary signal Claude uses to decide whether a tool is appropriate for the current moment in a conversation.

A description that only states what the tool does provides weak guidance:

"description": "Get weather data."

This tells Claude nothing about when to call it, which query types it handles, or what it cannot do. A description that adds trigger conditions and scope boundaries is significantly more reliable:

"description": "Get the current weather for a specific city. Call this when the user asks about present conditions for a named location. Do not call this for forecasts or historical data."

Three elements make a description effective:

  1. A trigger condition. State the circumstances under which Claude should call this tool. "Call this when the user asks about X" is the most direct form — it removes ambiguity about intent rather than leaving Claude to infer it.
  2. Scope boundaries. State what the tool is not for. This matters most when two tools have overlapping purposes — each description should point away from the other when context is wrong.
  3. Format hints. If the tool requires input in a specific format — a city name rather than coordinates, an ISO date rather than a natural language phrase — state that in the description or in the parameter description, not just in the schema type.

Anthropic's published tool use documentation notes that on more recent Claude Opus models, which reach for tools more conservatively by default, trigger conditions in the description give measurable lift in call rate for tools that should be invoked. Weaker descriptions do not just reduce accuracy — they actively work against the invocation behavior you want.

How should you define input parameters and their descriptions?

The input_schema uses standard JSON Schema syntax. Each property inside properties can carry a description, a type, and optional constraints such as enum. Parameter descriptions serve a distinct purpose from the tool description: the tool description tells Claude when to call the tool, while parameter descriptions tell Claude how to populate its inputs.

"properties": {
  "location": {
    "type": "string",
    "description": "City and state, e.g. 'San Francisco, CA'. Use a city name — not coordinates."
  },
  "unit": {
    "type": "string",
    "enum": ["celsius", "fahrenheit"],
    "description": "Temperature unit. Use 'celsius' unless the user has expressed a preference."
  }
}

Use enum for any parameter with a fixed set of valid values. Claude will constrain its choices to the listed options, which eliminates a class of invalid tool calls before they reach your handler. Concrete examples inside the description string — "e.g. '2024-03-15'" for a date field — anchor Claude on the expected format and reduce format errors in practice.

When should a parameter be required vs. optional?

The required array inside input_schema determines which parameters Claude must supply in every tool call. Parameters not listed in required are optional — Claude may omit them when they are absent from the conversation context.

Mark a parameter required only when the tool cannot execute meaningfully without it. For a weather tool, the city name is required: there is no sensible default, and the tool does nothing useful without it. For a temperature unit, optional is the right choice: the tool can default to Celsius when the user has not expressed a preference.

Over-requiring parameters creates a reliability problem. When Claude cannot infer a required value from context, it may either refuse to call the tool or hallucinate a plausible-sounding value. Both outcomes degrade pipeline accuracy. Prefer optional parameters with documented defaults over required parameters that are frequently absent from user input.

A useful heuristic: if a parameter's absence would cause your handler to throw an exception, it belongs in required. If your handler can fall back to a sensible default, mark it optional and document that default in the parameter description so Claude knows what to expect when it omits the value.

How do you disambiguate two tools with overlapping purposes?

Tool confusion arises when two or more tools could plausibly satisfy the same request. A get_current_weather tool and a get_forecast tool will both seem relevant when a user asks "what's the weather going to be like this week?" Without precise descriptions, Claude may call either one.

The most reliable fix is mutual exclusion in the descriptions — each tool's description should state not just when to use it, but when not to:

"name": "get_current_weather",
"description": "Get the current weather for a specific city right now. Use for present conditions only. Do not use for forecasts or multi-day outlooks — use get_forecast for those."

"name": "get_forecast",
"description": "Get a multi-day weather forecast for a specific city. Use when the user asks about future conditions, tomorrow's weather, or a date range. Do not use for current real-time conditions — use get_current_weather for those."

This cross-referencing pattern — each tool pointing explicitly at the other when context is wrong — is more reliable than positive trigger conditions added to each tool independently. It encodes the boundary in both directions rather than leaving Claude to infer the difference from names alone.

For cases where you have already determined which tool to call at the application layer, tool_choice provides a hard override. Setting {"type": "tool", "name": "get_forecast"} forces that specific tool regardless of description-level selection. The other modes — auto (Claude decides), any (Claude must use at least one tool), and none (no tool calls allowed) — give graduated control over invocation behavior without touching the definitions themselves.

What does the CCA-F exam expect you to know about tool definitions?

The Claude Certified Architect — Foundations exam, per Anthropic's published materials, includes tool use as part of its coverage of Claude API patterns and agentic pipelines. Domain names, question counts, and weightings can change between exam versions — verify the current exam guide directly with Anthropic before test day.

The areas most likely to appear in tool use questions include:

  • The three required fields of a tool definition (name, description, input_schema) and what role each plays in tool selection and execution
  • The structure of input_schema: why it must declare "type": "object" at the top level, how properties and required interact, and how enum constrains parameter values
  • The function-calling loop: stop_reason: "tool_use" signals a pending tool call; the application executes the tool and returns results via tool_result content blocks; the loop continues until stop_reason becomes "end_turn"
  • Parallel tool use: Claude can request multiple tool calls in a single response, and all results must be returned in the next API call before the conversation continues
  • The tool_choice parameter and its four modes: auto, any, tool (specific), and none

Schema quality — specifically the description field — is where real pipelines most often fail, and it is a reasonable focus for exam scenarios that ask you to diagnose why a tool is being skipped or misrouted. The mental model the exam is likely testing: descriptions are Claude's instructions for when to act, not labels for what exists. A candidate who understands that distinction will approach tool use questions differently from one who has only read the API reference.

If you are working toward the CCA-F, understanding tool definition mechanics is one piece of a larger picture. Plinth Prep is an independent study resource, not affiliated with Anthropic, and our practice questions on tool use are designed to test applied understanding — whether you can identify a poorly-scoped description, construct the right parameter structure for a given scenario, or trace the function-calling loop step by step. Visit plinthprep.com to see the exam-prep questions on tool use and agentic patterns.

Frequently asked questions

What are the three required fields in a Claude tool definition?
A Claude tool definition requires three fields: name (a unique identifier Claude uses when making a tool call), description (the text Claude reads to decide whether and when to call it), and input_schema (a JSON Schema object defining accepted parameters). All three are required; omitting any one produces a validation error.
How does the description field affect Claude's tool selection?
Claude reads the description field to decide whether to call a tool and which tool to call when multiple are available. A description that states explicit trigger conditions — such as "Call this when the user asks about current prices" — is measurably more reliable than one that only describes what the tool does.
When should a parameter be marked as required in a Claude tool definition?
Mark a parameter required in the input_schema's required array only when the tool cannot execute meaningfully without it. Leave parameters optional when the tool has a sensible default. Requiring unnecessary parameters forces Claude to guess values, which leads to hallucinated inputs or the tool being skipped entirely.
How do you stop Claude from calling the wrong tool when two tools have overlapping purposes?
Add scope boundaries to each description stating when not to use that tool — and which tool to use instead. For example: "Do not use for forecasts — use get_forecast for those." This mutual exclusion in both directions is more reliable than adding positive trigger conditions to each tool independently.
What does the CCA-F exam test about Claude tool definitions?
Per Anthropic's published exam materials, the Claude Certified Architect — Foundations exam covers tool definition structure, the function-calling loop, parallel tool use, and the tool_choice parameter. Domain weights can change between exam versions — verify current materials with Anthropic. Strong candidates understand description quality as a selection mechanism, not just syntax.

Share this post

Plinth Prep is an independent study resource and is not affiliated with, endorsed by, or sponsored by Anthropic. Practice material is written by Plinth Prep and does not reproduce real exam content.