CC-201d · Module 1

Designing Tool Schemas

4 min read

The tool schema is not documentation for humans. It is documentation for Claude. Every word in your tool name, description, and parameter descriptions directly influences whether Claude invokes the tool correctly, incorrectly, or not at all. This is prompt engineering disguised as API design.

Start with the tool name. It should be a verb_noun pair that describes exactly what the tool does: lookup_customer, create_invoice, list_recent_orders. Not get_data, do_thing, or process. Claude uses the name as a first-pass relevance filter — if the name does not match the user's intent, Claude will not even read the description.

The description is where most developers fail. They write descriptions for themselves — "Queries the customer database." That tells Claude nothing about when to use the tool versus the three other tools that also query databases. Write descriptions for Claude: "Look up a customer by email address or account ID. Returns the customer's name, plan tier, monthly recurring revenue, and the date of their last activity. Use this when the user asks about a specific customer, wants to check account status, or needs billing information."

Notice three things about that description. It specifies the inputs (email or account ID). It specifies the outputs (name, plan, MRR, last activity). And it specifies the trigger conditions (when to use it). All three are essential. Missing any one of them leads to Claude either not using the tool when it should, using it when it should not, or passing the wrong parameters.

Do This

  • Use verb_noun names: lookup_customer, create_invoice, list_orders
  • Describe outputs explicitly: "Returns name, plan tier, MRR, and last activity date"
  • Include trigger conditions: "Use when the user asks about a specific customer"
  • Constrain parameter types tightly: enum for status, pattern for email, min/max for counts

Avoid This

  • Name tools generically: get_data, process, handle_request
  • Write human docs: "Queries the customer database" — Claude needs more context than that
  • Leave outputs unspecified — Claude cannot decide to use a tool if it does not know what it returns
  • Accept string for everything — unconstrained parameters lead to parsing errors on the server side