Use when an approved ai-architecture.md defines an Anthropic Claude capability whose model calls tools or takes side-effecting actions. Produces tool schemas, an auth-enforcing execution adapter, idempotency, audit logging, and failure tests. Not for schema-only output, RAG, or agent design.
Use when an approved ai-architecture.md defines an Anthropic Claude capability whose model calls tools or takes side-effecting actions. Produces tool schemas, an auth-enforcing execution adapter, idempotency, audit logging, and failure tests. Not for schema-only output, RAG, or agent design.
Anthropic Tool Use Runtime
When to use
Invoke when ai-architecture.md defines a capability whose model is allowed to
call tools (functions, side-effecting actions, external lookups) and the chosen
provider is Anthropic (Claude via the Messages API).
Do not use for free-form chat, schema-bound output without tool execution,
retrieval topology design, or agent control-flow and stop-condition design.
Inputs
Required:
Approved ai-architecture.md.
Capability name and model contract.
Approved tool surface: each tool's name, purpose, input schema, side-effect class, and authorization model.
Target application language and framework.
Optional:
Idempotency policy and idempotency-key source per tool.
Audit-logging requirements and retention rules.
Parallel-tool-use allowance and tool_choice policy from the architecture.
Whether any MCP connector tool is explicitly approved.
Prompt-cache strategy for the tool-definition prefix.
Latency, cost, and retry budgets.
Sample successful and failed tool-call traces.
Operating rules
Preserve the tool surface from ai-architecture.md. Do not add, widen, rename, or repurpose a tool, and do not relax a tool's input schema. If a tool, side-effect class, or authorization model is missing, raise an ADR candidate instead of inventing it.
Tool schemas are a contract surface. Each input_schema is exactly the approved schema; versioning and breaking-change policy apply as for any external API.
Authorization is enforced in the execution adapter, never delegated to the model. The model proposes a tool call; the adapter verifies the caller is permitted to run that tool with those arguments before any side effect. A model-proposed call is untrusted input.
Side-effecting tools are idempotent. Every mutating tool execution carries an idempotency key derived from a stable request property per the architecture's policy; a replayed tool_use does not double-apply.
tool_choice is a deliberate decision, stated explicitly: auto (model decides), any (must call some tool), {type: "tool", name} (force one tool), or none (suppress tools). The choice traces to the contract, never left to default by omission.
Parallel tool use is a decision. If the architecture allows the model to emit multiple tool_use blocks in one turn, the adapter executes them with explicit ordering/concurrency and authorization per call; if disallowed, parallel tool use is suppressed and asserted off.
MCP connector tools are used only where ai-architecture.md explicitly approves a named connector. An MCP tool is a remote side-effecting surface: same authorization, idempotency, and audit rules apply, plus the connector's trust boundary is documented.
Every tool execution is audited. The audit record captures tool name, authorization outcome, idempotency key, result class, and correlation id — never raw secrets or unredacted PII.
Prompt caching is a decision, not an accident. cache_control is placed only on the stable tool-definition prefix (system prompt + tool definitions), never on per-request content (tool_result, user input, retrieved data); cache placement never changes tool semantics, and a cache miss is never a correctness failure.
Extended thinking is handled, not ignored. If the capability uses extended thinking, thinking blocks are preserved or stripped per the architecture and the parser selects tool_use blocks while tolerating preceding thinking blocks; if unused, state N/A explicitly.
No sensitive data in telemetry. Tool name, authorization outcome, latency, tokens, cache outcome, and result class are logged; tool arguments, results, secrets, and PII are redacted unless the architecture explicitly permits a field.
Output contract
The implementation MUST conform to:
api-standards — each tool schema is an external contract surface; versioning and breaking-change policy apply.
security-standards — authorization enforced before side effects; no secrets or PII in prompts, tool arguments, results, logs, or audit records without redaction; Anthropic API credentials injected at deploy time, never committed.
observability-standards — structured logs and metrics for latency, input/output tokens, cache-read/write tokens, tool-call counts, authorization outcomes, tool failures, and model/prompt version; trace propagation through the tool loop.
deployment-standards — model id, prompt version, tool-cache strategy, and tool_choice policy are deploy-time configuration, not hardcoded.
Upstream contract: ai-architecture.md is the source of truth for the capability, tool surface, each tool's authorization model and side-effect class, idempotency policy, parallel-tool and tool_choice policy, any approved MCP connector, prompt-cache strategy, extended-thinking requirement, degradation behavior, and latency/cost budgets. If it is silent on any of these, this skill pauses and raises an ADR candidate rather than inventing the decision.
Progressive references
Read references/anthropic-tool-use-runtime-playbook.md when implementing any owned area or checking the anti-pattern list.
Read references/anthropic-tool-use-runtime-quality-rubric.md before declaring the integration complete.
Use assets/anthropic-tool-use-runtime.template.md as the request-shape, adapter, audit, telemetry, and test-matrix reference.
Process
Load ai-architecture.md and identify the capability, the approved tool surface, each tool's side-effect class and authorization model, idempotency policy, and prompt-cache strategy.
Verify the architecture names the model tier, the tool_choice and parallel-tool policy, any approved MCP connector, the extended-thinking requirement, and degradation behavior.
Define each tool with its approved name, description, and input_schema verbatim from the contract; record the tool_choice decision and why.
Implement the Messages API request: system prompt, messages, tool definitions, the chosen tool_choice, and explicit decoding settings.
Place cache_control on the stable tool-definition prefix per the architecture's cache strategy; confirm no breakpoint sits on tool_result or per-request content.
Implement the execution adapter: authorization check → argument validation against input_schema → idempotency-keyed execution → structured tool_result.
Implement the tool loop: feed tool_result back, handle multiple/parallel tool_use blocks per the policy, and bound the loop with a max-iteration limit.
If extended thinking is required, reconcile thinking blocks with tool_use parsing per the architecture's retention rule; otherwise mark N/A.
Add audit logging for every tool execution and telemetry for model id, prompt version, latency, tokens, cache outcome, tool-call counts, authorization outcomes, and tool failures.
Add tests for a valid tool call, an unauthorized call, a tool execution failure, idempotent replay, retry/loop-bound exhaustion, and a cache-miss path.
Document unresolved architecture gaps as ADR candidates instead of silently filling them in.
Outputs
Anthropic Messages API integration for the tool-use capability, including the bounded tool loop.
Tool definitions (name, description, input_schema) derived verbatim from the contract.
Tool execution adapter with authorization, argument validation, idempotency, and structured tool_result shaping.
Audit-logging integration for every tool execution.
Prompt or message template files with tool-prefix cache-breakpoint placement noted.
Tests for valid call, unauthorized call, tool failure, idempotent replay, loop-bound exhaustion, and cache miss.
Telemetry notes for tokens, cache outcomes, latency, tool-call counts, authorization outcomes, and model version.
Output rules:
The tool_choice and parallel-tool decisions are stated explicitly; never left implicit.
Authorization is enforced in the adapter before any side effect; a model-proposed call is never trusted.
Every mutating tool execution carries an idempotency key; replay does not double-apply.
cache_control appears only on the tool-definition prefix; never on tool_result or per-request content.
No Anthropic API key, MCP connector secret, or environment-specific endpoint committed to source.
Quality checks
The implementation consumes a named capability and tool surface from ai-architecture.md.
Each tool's input_schema matches the approved schema; no tool added, widened, or repurposed.
Authorization is enforced in the execution adapter before any side effect.
Every mutating tool carries an idempotency key; replay is proven not to double-apply.
tool_choice and parallel-tool-use policy are explicit and justified against the contract.
MCP connector tools appear only where the architecture explicitly approves them, with the same authz/idempotency/audit rules.
cache_control sits only on the tool-definition prefix and does not change tool semantics.
Extended-thinking interaction with tool_use parsing is handled per the architecture (or explicitly N/A).
Audit records and telemetry exclude unredacted secrets, tool arguments/results, and PII.
Tests cover valid call, unauthorized call, tool failure, idempotent replay, loop-bound exhaustion, and a cache-miss path.
Any missing tool, authorization, idempotency, cache, tool_choice, or degradation decision is documented as an ADR candidate.
