Home / The Claude API for builders

Tools: Claude proposes, the code decides

A tool is declared with a schema named input_schema; Claude never executes it itself, it returns a usage request that the code executes before returning the result so the conversation can continue.

Claude never executes a tool itself. It returns a usage request, the developer's code actually executes it, then returns the result so the conversation can continue. This cycle rests on a single contract: the schema declared by the input_schema field.

Declaring a tool

A tool is declared with three top-level fields: name, description and input_schema, the latter describing the expected shape of the arguments. A fourth field, strict, sits alongside the first three and not on tool choice: set to true, it guarantees that the call Claude produces matches the declared schema exactly, provided that schema also carries additionalProperties set to false alongside required, the form the official documentation uses in all its examples.

// Declaring a tool, with strict schema validation
{
  "name": "verifier_stock",
  "description": "Renvoie la quantité disponible pour une référence produit.",
  "input_schema": {
    "type": "object",
    "properties": {
      "reference": { "type": "string" }
    },
    "required": ["reference"],
    "additionalProperties": false
  },
  "strict": true
}

The full cycle, from request to result

When Claude chooses to use a tool, it returns a stop_reason of value tool_use, accompanied by one or more tool_use blocks carrying the chosen arguments. The code then executes the actual call described by that block, then returns the result in a tool_result block, placed inside a message with user role. When several tools are requested in the same turn, which happens by default since parallel calls are active, all their tool_result blocks come back together in that one message.

// Usage request returned by Claude
{
  "stop_reason": "tool_use",
  "content": [
    { "type": "tool_use", "id": "toolu_01", "name": "verifier_stock",
      "input": { "reference": "REF-042" } }
  ]
}

// Result returned by the code in the next turn
{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "12 unités disponibles" }
  ]
}

The tool_choice field controls which tool Claude can pick: auto by default leaves Claude to decide, any forces the use of a tool without imposing its name, tool imposes one specific tool, and none stops it from using any. Choosing none with no tool declared adds no extra system tokens to the request. The tool_result block returned here follows the same message structure as the basic request, with a messages array that keeps alternating roles.