Claude Tool Use API: How It Works and How to Call It

The Claude tool use API lets you give Claude a set of functions it can call — database lookups, calculators, search, internal APIs — and Claude decides when to invoke them based on the conversation. You define each tool with a JSON schema, send it alongside your messages, and Claude responds with a tool_use block instead of plain text when it needs that tool. You then execute the function yourself, send the result back as a tool_result, and Claude continues the conversation with that data in hand.

This is the mechanism behind most "agentic" Claude applications: coding assistants that run shell commands, support bots that query order status, research tools that hit a search API. The model itself never executes anything — it only requests a call and reads back the result. Everything else (auth, execution, sandboxing) is your responsibility. Below is what the request/response cycle actually looks like and where people get tripped up.

How tool use works, step by step

1. You define tools as JSON objects with a name, description, and input_schema (JSON Schema for parameters).
2. You send a message with those tools attached. Claude reads the conversation and decides whether a tool is needed.
3. Claude replies with stop_reason: "tool_use" and a content block containing the tool name and structured input.
4. You run the actual function in your own code — this is not sandboxed by Claude.
5. You send the result back as a tool_result block in a new user message, keeping the same tool_use_id.
6. Claude continues, either calling another tool or producing a final answer.

A minimal tool definition looks like this:

{
  "name": "get_weather",
  "description": "Get current weather for a city",
  "input_schema": {
    "type": "object",
    "properties": {
      "city": { "type": "string" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["city"]
  }
}

When Claude decides to use it, the response content includes something like:

{
  "type": "tool_use",
  "id": "toolu_01A2B3",
  "name": "get_weather",
  "input": { "city": "Lisbon", "unit": "celsius" }
}

Your code runs get_weather("Lisbon", "celsius"), then sends the output back:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01A2B3",
  "content": "18°C, partly cloudy"
}

Claude then produces a normal text reply using that result. The loop can repeat multiple times in a single turn if the model needs several tool calls to answer one question — that's normal and expected for agentic flows.

Common mistakes with the tool use API

• Vague tool descriptions. Claude picks tools based on the description field. If two tools sound similar, expect wrong calls. Be specific about when to use each one and what it returns.
• Loose schemas. Optional fields that should be required, missing enum constraints, or ambiguous types lead to malformed inputs you then have to defensively parse.
• Forgetting multi-step loops. Some tasks require Claude to call a tool, look at the result, then call another tool. Your integration needs to keep looping until stop_reason is no longer tool_use, not assume one call is final.
• Not validating tool inputs. Claude is good but not infallible — validate arguments server-side before executing anything with real side effects (payments, deletions, emails).
• Ignoring parallel tool calls. Claude can request multiple tools in one turn. If your code only handles the first tool_use block, you'll silently drop the rest.

Calling Claude's tool use API through SubToAPI

If you're already paying for Claude access and want to expose tool use through a stable HTTPS endpoint — for a backend service, a teammate's app, or a CI job — SubToAPI turns that access into an API with sub_live_... application keys. Tool use works the same way as calling Claude directly: define your tools, send the request, handle the tool_use block.

curl https://api.subtoapi.app/v1/messages \
  -H "Authorization: Bearer $SUBTOAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "input_schema": {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          },
          "required": ["city"]
        }
      }
    ],
    "messages": [
      { "role": "user", "content": "What is the weather in Lisbon?" }
    ]
  }'

The response format and tool loop are unchanged — you parse tool_use, execute your function, and send back tool_result exactly as described above. What you get on top is per-application API keys instead of sharing one account credential, streaming support, usage metadata per key so you can see which service is calling which tool, and team seats if more than one person needs access. See /docs/tools for the full request/response schema and /docs/streaming if you want tool calls to stream incrementally rather than wait for the full response.

Plans start at €9/month for solo use, €19/seat for teams, and €49/seat for Scale, with a free trial at /signup — full breakdown at /pricing. If you're new to the API shape in general, /docs/quickstart and /docs/messages cover the basics before you get into tool definitions.

Questions

Does Claude execute the tool code itself? No. Claude only decides when to call a tool and what arguments to pass. Your application executes the actual function — database query, API call, shell command — and sends the result back to Claude as a tool_result.

Can Claude call multiple tools in one turn? Yes. A single response can contain several tool_use blocks, and Claude may also chain tool calls across multiple turns if the task requires it. Your integration needs a loop, not a single request/response assumption.

Do I need a special SDK to use Claude's tool use API? No, it's a JSON-based HTTP API — you can call it with curl, fetch, or any HTTP client. An SDK just wraps the same request/response structure for convenience.