A Claude agent keeps inventing parameters, repeats the same action, or stalls after a tool call.
Start with one read-only tool and one low-risk action, close the full request–tool_use–execution–tool_result loop, then add strict inputs and structured final output. Do not connect a large MCP catalog before permissions, timeouts, idempotency, and human approval are working.
Who this runbook is for
This guide is for you if you are using the Claude Sonnet 5 API for a code agent, search workflow, or business automation backend.
It is also useful if you already have a Claude Tool Use project and need to review strict parameter handling, output validation, retries, or a remote Mac runtime.
Last updated: August 18, 2026. Model availability, supported API features, and preview limits should be rechecked against the Claude Sonnet 5 announcement, the current Claude model page, and the API release notes before deployment.
Deployment boundaries before the first request
The fastest way to create an unreliable agent is to expose every internal function on day one. A large tool list creates several problems that are easy to miss during a demo:
- Ambiguous selection: tools with similar names or descriptions give the model multiple plausible paths.
- Excess authority: a tool may technically accept a request that the current user should not be allowed to perform.
- Unclear failure ownership: developers often treat a model response as execution, even though the application must run the function and enforce policy.
- Unbounded data exposure: a search or file tool can return credentials, personal data, internal prompts, or oversized records.
- Duplicate side effects: a timeout can make the model or application repeat a payment, deployment, ticket update, or file operation.
- Poor diagnosis: without a call identifier, schema version, and executor log, you cannot tell whether the model selected the wrong tool or the backend executed it incorrectly.
Begin with a read-only operation such as search_records or get_build_status, then add a low-risk action such as create_draft. These names are examples, not a universal tool catalog. The important properties are narrow scope, predictable output, and a clear rollback path.
For each tool, write four boundaries before adding it to the API request:
- What business question does it answer?
- Which identity and permission does it require?
- What data may it read or change?
- What happens if the call is repeated, delayed, rejected, or partially completed?
A tool description should explain when the function is appropriate and when it must not be used. Avoid descriptions such as “handles customer tasks.” Use a bounded statement such as “Returns build status for a repository the authenticated user can access. Does not start, cancel, or modify a build.”
Your input Schema should represent the executor’s real contract. Required fields should be genuinely required. Enums should contain only accepted values. Free-form strings should have length and format checks in the application even when the model receives a schema.
For current field names and request behavior, use the official Tool Use overview rather than relying on an older SDK example.
The first Tool Use loop
A Claude Sonnet 5 API integration is not complete when the model returns a tool request. The first closed loop has four observable transitions:
- Your application sends the user message and the available tool definition.
- Claude returns an assistant response containing a
tool_useblock. - Your executor validates authorization and runs the selected function.
- Your application sends a
tool_resulttied to the original call identifier, allowing Claude to continue.
The official result-handling documentation describes the relationship between the tool-use request and the returned tool result: tool call result handling.
A minimal implementation should persist, at minimum:
- the request identifier from your own gateway;
- the model identifier and API version;
- the selected tool name;
- the tool-use identifier;
- a hash or version of the input Schema;
- the authorization decision;
- execution status and a redacted result;
- retry and approval state.
The application owns execution. Claude can propose create_draft, but it must not receive credentials or direct access to the function runner. The executor should independently check the authenticated principal, tenant, resource ownership, rate policy, and action risk.
A compact pseudocode flow looks like this:
response = claude.messages.create(
model="claude-sonnet-5",
messages=[{"role": "user", "content": user_text}],
tools=[search_tool, create_draft_tool],
)
for block in response.content:
if block.type == "tool_use":
authorize(block.name, block.input, user_context)
result = execute_with_policy(
name=block.name,
arguments=block.input,
idempotency_key=make_key(block.id, block.input),
)
messages.append({"role": "assistant", "content": response.content})
messages.append({
"role": "user",
"content": [{
"type": "tool_result",
"tool_use_id": block.id,
"content": serialize_for_model(result),
}],
})
Treat this as control-flow pseudocode, not a copy-and-paste production client. Your SDK version, model identifier, authentication layer, and error types must match the current API documentation.
The result sent back to the model should be useful but narrow. A successful build-status result might contain status, commit identifier, and the last safe diagnostic message. It should not contain an entire CI log by default. A failed operation should return a stable error category such as permission_denied, not_found, validation_failed, or temporary_unavailable. This gives the model a chance to explain the outcome without exposing internal stack traces.
Strict inputs and final output
Strict tool inputs and Structured Outputs address different failure modes.
Strict tool input validation protects the executor from arguments that do not match the declared contract. It does not decide whether the user is authorized, whether the action is safe, or whether the target resource exists.
Structured Outputs controls the shape of the assistant’s final response. It is useful when your application needs a predictable object such as:
{
"status": "needs_approval",
"summary": "Draft created but not published",
"next_action": "human_review",
"references": []
}
The Structured Outputs documentation should be your source for the supported models, request fields, schema limitations, and refusal behavior. Do not assume that a valid tool input guarantees a valid final object. The tool call and the final response pass through different stages and need separate validation.
Use this sequence:
- Validate the incoming user intent and session identity.
- Let Claude select from the narrow tool set.
- Validate the returned tool arguments again in your executor.
- Run authorization and risk checks.
- Execute the tool and return a bounded result.
- Ask Claude for the final response under the output schema.
- Validate the final object before your application uses it.
Keep an explicit exception branch for refusal or safety blocking. Keep another branch for a response that stops before the expected final object, including a length-related interruption. A third branch should handle schema rejection caused by excessive nesting, unsupported constructs, or an invalid deployment configuration.
Schema complexity has an operational cost. A deeply nested output may be technically expressive but harder to validate, version, and repair. Prefer a small set of stable fields, explicit status values, and an array of short references over a large object that mirrors your entire database.
Reliability controls for production
The happy path is not the deployment plan. Before you expose an action to real users, add controls around the executor rather than asking the model to behave perfectly.
Timeouts
Set a separate timeout for each tool. A read-only lookup can have a shorter limit than a code build or remote desktop operation. The timeout must be enforced by the executor, not merely described in the tool schema.
When a timeout occurs, mark the operation as uncertain if the remote system may have accepted the request. Do not automatically retry an unknown side effect. Return a status that lets the workflow choose between verification and human review.
Retries
Retry only errors classified as temporary, such as a connection reset before the request reached the service or a clearly documented transient response. Do not retry malformed input, permission denial, missing resources, or an action whose completion status is unknown.
Your retry record should include the original call identifier and the reason for the retry. This makes repeated model decisions distinguishable from infrastructure retries.
Idempotency
Every side-effecting tool needs an idempotency strategy. Derive a key from the workflow run, intended action, target resource, and an application-controlled attempt boundary. Store the key and final status before returning success.
If the same key appears again, return the stored result or an explicit “already processed” state. Never use the model’s natural-language explanation as the duplicate detector.
Human approval
Actions that publish code, delete records, change access, send external messages, or incur material cost should enter an approval state. The model can prepare the action and explain its impact. The executor should pause until an authorized person confirms the exact target and arguments.
A useful approval record contains the proposed tool name, normalized arguments, requesting identity, risk reason, expiration time, and final decision. If any of those values changes, require a new approval.
Direct tools versus MCP
MCP is an extension layer, not a replacement for the Tool Use execution loop. Direct tools are usually the better first deployment choice when one backend owns a small, stable set of functions.
Choose direct Claude Tool Use when:
- one agent controls the integration;
- the tool list is short and changes infrequently;
- authorization is tightly coupled to your application;
- you need simple local tests and rollback;
- the executor already has a reliable service boundary.
Consider MCP when:
- several clients need to discover and reuse the same tools;
- a separate team owns the tool server;
- you need a shared capability boundary across agents;
- the tool inventory changes independently from the model client.
The MCP Connector documentation explains the remote connection model and current constraints. It does not remove your responsibility for authorization, network controls, audit logs, or third-party data review.
MCP adds hidden operational surfaces: remote connectivity, authorization renewal, tool-list changes, server versioning, and data ownership. Capture the discovered tool name, server identity, schema version, and authorization scope in your logs. If a server changes its tool definition, fail closed until the change is reviewed.
Do not connect an MCP server merely because discovery feels convenient. For a single agent with two well-understood functions, the additional layer can make incident response harder.
A deployment decision guide
Use the following comparison before choosing your first architecture.
Choose direct tool definitions if your tools are owned by the same backend, your permission rules are local, and you can test every executor path in one repository. This gives you a smaller failure surface and a clearer rollback.
Choose an MCP layer if multiple clients need the same governed tools, the tools have an independent release cycle, and your team can monitor remote authorization and inventory changes. Require a server-level ownership contact before production access.
Delay both broad tool access and MCP if you have no call-level audit trail, no duplicate detection, no timeout policy, or no approval path for destructive actions. A larger catalog will not repair missing controls.
Use Structured Outputs only after you know what the final consumer needs. If the result is shown directly to a person, a concise textual answer may be enough. If another service consumes it, define a small schema and validate it at the application boundary.
For a code agent, this often means starting with repository status and draft patch generation, not unrestricted shell execution. For a search agent, start with a read-only query tool and a result normalizer. For business automation, begin with draft creation before adding send, publish, or delete operations.
Remote Mac acceptance
A remote Mac is useful when the agent must run Apple-specific build tools, signing workflows, simulator tasks, or a macOS-only development stack. It is not automatically a better execution target for every backend workload.
Before moving from a local test to a remotely hosted agent, verify these seven areas:
- Process supervision: the agent worker restarts after a crash and does not create duplicate workers.
- Environment variables: production secrets are injected through the approved mechanism, not committed to the repository or printed during startup.
- Network access: the machine can reach the API, tool services, package registries, and callback endpoints required by the workflow.
- Logs: request identifiers, tool-use identifiers, executor results, and approval decisions survive process restarts and can be retrieved without exposing secrets.
- Key rotation: API credentials can be replaced without rebuilding the entire image or manually editing a live process.
- Rollback: you can return to the prior agent version and prior tool Schema if a deployment changes behavior.
- Real-task evidence: record representative task runs, including failures, retries, approval pauses, and uncertain timeouts. Do not substitute unrepeatable performance claims for these records.
Use Macstripe to review a remote Mac configuration only after you know the runtime requirements of your agent. If you need help identifying the right environment boundary, the Macstripe Help Center is a better starting point than adding more tools to the model request.
A remote environment has its own hidden costs: network latency, disconnected sessions, missing local credentials, unmanaged background processes, and unclear ownership of logs. Treat those as acceptance criteria, not as problems to solve after launch.
Current backend versus a remote Mac
A conventional Linux or local backend may be the right long-term home when your tools are HTTP services, your workloads are stable, and no macOS-only dependency is involved. It becomes a poor fit when the agent must repeatedly access Apple build tooling, simulator workflows, signing identities, or a developer environment that cannot be reproduced cleanly elsewhere.
A local Mac gives you direct hardware and physical interfaces, but it also creates maintenance work, limited availability for distributed teams, and a higher chance that a developer’s machine becomes an undocumented production dependency. A generic cloud host simplifies elasticity, yet it may require extra work to reproduce macOS-specific tasks and can complicate interactive debugging.
Macstripe is a practical middle option for temporary validation, remote development, or a small production trial: you can keep the Agent control plane separate while testing the execution worker on a managed remote Mac environment. It is less suitable when you need permanent high-volume capacity, direct physical peripherals, or complete ownership of the host lifecycle.
After the tool loop passes real-task acceptance, compare the expected task duration, session persistence, secret handling, and rollback needs against the cost of maintaining your current setup. If the project only needs a short-lived macOS execution environment, renting a Mac through Macstripe can remove the need to turn a developer workstation into an always-on service. Start with a small validation cycle, retain the logs, and expand only when the failure and approval paths are as clear as the successful run.
Frequently Asked Questions
How does Claude Sonnet 5 call an external tool?
Your application first sends the available tool definition and the user request to the Claude Sonnet 5 API. Claude can return a tool_use block with a tool name, input object, and call identifier. Your executor, not the model, runs the function. You then send a tool_result containing that identifier and the execution result so Claude can continue or produce a final answer.
How should strict tool use be configured in Claude?
Start with a narrow input schema, explicit required fields, and bounded enums where they reflect real business rules. Enable the strictest supported input validation for the selected model and API version, but retain an error branch for rejected arguments. Strict validation protects the executor from malformed inputs; it does not approve the action or replace authorization checks.
How do you return a result after a Claude tool call?
Store the tool-use identifier, execute the requested operation, and return a tool_result linked to that exact identifier. Include a compact success payload or a structured error that the model can interpret. Never return credentials, unrestricted logs, or an unbounded raw response. The application should decide whether Claude receives the result, whether the call can be retried, and whether a human must review it.
Should Claude API and MCP be used together?
They can be combined, but they solve different problems. The Claude API provides the model interaction, while MCP can expose discoverable tools through a shared remote server. Add MCP when several clients need the same governed tool inventory. For one agent and a few stable functions, direct tool definitions are easier to inspect, authorize, test, and roll back.
What logs are needed for a Claude Agent deployment?
Record request and response timestamps, model identifier, tool name, call identifier, schema version, authorization decision, latency category, retry count, result status, and redacted error details. Also record deployment version, environment, and approval state for sensitive actions. Keep secrets and personal data out of routine logs. Retention and access rules should match your business and legal requirements.
