Tool Definition Schema ⚠ verify

Definition

The shape of each entry in the top-level tools parameter that tells Claude a custom (client) tool exists: what it is named, what it does, and what inputs it accepts.

Key points

• Required fields: name, description, input_schema.
• name must match the regex ^[a-zA-Z0-9_-]{1,64}$ — see Tool Name Regex.
• description is detailed plaintext (aim ≥ 3–4 sentences); it is the single most important factor in tool performance — see Effective Tool Descriptions.
• input_schema is a JSON Schema object: type: "object", properties, required.
• Optional properties (siblings of name/description/input_schema): input_examples, cache_control, strict, defer_loading, allowed_callers.
• Adding tools bills against total input tokens; the tool-use system prompt itself adds ~290 (auto/none) to ~410 (any/tool) tokens on Opus 4.8. ⚠ verify (2026-07-08) — token counts drift with model releases.
• tool_use response block shape: { "type": "tool_use", "id": "toolu_…", "name": …, "input": {…} }.

Why it matters for the exam

• Domain 2 (18% of scored) repeatedly tests which three fields are required and where optional flags (strict, defer_loading, input_examples) live.
• Distractors place strict on tool_choice or omit input_schema — know the exact structure.

Common gotchas

• strict and defer_loading are on the tool definition, not on tool_choice.
• input_examples is not supported for server-side tools (400 if used).
• A missing/blank description cripples routing — the model has nothing to match on.

See also

• Tool Name Regex
• Effective Tool Descriptions
• Strict Tool Use
• Input Examples
• Structured Outputs

Sources

• docs-tools-agents
• netlight-study-guide