Claude + External APIs: A Safe Tool-Use Guide (2026)

01 / The story

How does Claude call an external API?

A custom tool describes an action using a name, description, and input schema. Claude can return a tool_use block naming that tool and its inputs. Your application reads the request, checks it, calls the allowed API, and sends back the result. The model does not gain unlimited network access just because you describe a tool.

Anthropic distinguishes client tools from provider-run server tools. This guide focuses on client tools for services you control or have permission to use. Do not confuse this pattern with giving a chat app a password or assuming every hosted tool follows your own execution policy.

02 / The story

Define one narrow read-only tool first

Start with something bounded, such as fetching the status of an order the signed-in user may see. Describe exactly what the tool returns and when it should be used. Prefer explicit fields to an arbitrary URL or free-form database query.

Validate the proposed arguments against your own schema after receiving them. Also check ownership, account scope, and permitted values. A valid JSON object is not evidence that the caller may access the named record.

{
  "name": "get_order_status",
  "description": "Read status for one order belonging to the signed-in user. No changes.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string"
      }
    },
    "required": [
      "order_id"
    ],
    "additionalProperties": false
  }
}

03 / The story

Keep the execution boundary outside the conversation

Load API credentials only in your trusted application service. Choose allowed hosts in code, enforce timeouts and response-size limits, and restrict which endpoints the tool can call. Never let model output select internal network addresses or a secret-bearing request destination.

External results are untrusted data. A support note or API response can contain malicious instructions. Return only the fields the task needs, strip unnecessary personal data, and never obey instructions from the result to change permissions or disclose credentials.

04 / The story

Return tool results in the correct message order

Anthropic’s handling guide requires the tool_result to carry the matching tool_use_id. Tool-result messages immediately follow the corresponding assistant tool-use message; tool results come before any ordinary text in the user message. Preserve the assistant content rather than replacing it with a summary.

Handle multiple proposed calls deliberately. Run only authorized calls, return appropriate errors when they fail, and continue the loop within a fixed budget. The guide supports marking an error result with is_error. Do not send stack traces, tokens, or private upstream responses back to the model.

• Inspect every proposed tool and its arguments.
• Authorize the current user against the target record.
• Execute only an allowed action with bounded time and size.
• Return the result with its matching identifier.
• Stop when the goal is met or the budget is exhausted.

05 / The story

Require review before consequential writes

For sending messages, changing records, or spending money, show the exact action for approval. Bind that approval to the final target and arguments so later model changes cannot quietly alter it. A vague earlier instruction to “handle this” is not enough for every future action.

Plan retries with the upstream API’s supported duplicate-prevention mechanism. A timed-out write may already have succeeded. Check the result before retrying, record an audit trail without secrets, and give an owner a way to stop the loop. API terms, data rights, and rate limits still apply.