Tool Schema Design

The tool schema is the contract between Claude and your server. It tells Claude what the tool does (description), what inputs it accepts (JSON Schema), and implicitly, when to use it. A well-designed schema means Claude invokes the tool at the right time with the right parameters. A poorly designed schema means Claude either never invokes the tool (because it does not understand when to use it) or invokes it with wrong parameters (because the schema is ambiguous).

The description field is the most important field in the schema — more important than the parameter definitions. Claude reads the description to decide whether this tool is relevant to the current task. "Query the customer database" is vague. "Search the customer database by name, email, or account ID. Returns customer profile including subscription tier, last activity date, and support history." tells Claude exactly when this tool is useful and what it returns. The description should answer: what does this tool do, what input does it need, and what output does it produce?

// Good: specific description, typed parameters, clear output
{
  name: 'search_customers',
  description:
    'Search the customer database by name, email, or account ID. ' +
    'Returns matching customer profiles including subscription tier, ' +
    'last activity date, and support ticket count. ' +
    'Use when the user asks about a specific customer.',
  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Name, email, or account ID' },
      limit: { type: 'number', description: 'Max results (default 10)', default: 10 },
    },
    required: ['query'],
  },
}