On this page
The Sonnet 5.5 forced tool use error requires a request change: replace tool_choice types any or tool with auto, then decide how your application handles a response that does not call a tool. Strict tool input can enforce the schema of a call; it does not guarantee that a call happens.
That distinction matters when a previous integration treated “the model must choose this function” as part of its business workflow. Removing the rejected field makes the request compatible, but the workflow still needs an explicit completion condition. The examples below use the direct Claude API contract checked on October 15, 2026. Local checks were executed; no Sonnet API request was made for this guide.
Identify the request that triggers the error
Anthropic's Sonnet 5.5 migration guide documents rejection of both forced forms, including on the token-counting endpoint. The accepted choices are auto and none. This is a model compatibility problem, so retrying the unchanged payload does not fix it.
| Request choice | Sonnet 5.5 contract | What the application should expect |
|---|---|---|
{"type":"any"} |
Unsupported | Replace the request field |
{"type":"tool","name":"lookup_invoice"} |
Unsupported | Replace the request field |
{"type":"auto"} |
Supported | Tool call or another response |
{"type":"none"} |
Supported | No tool call |
The model ID on the direct API is claude-sonnet-5-5. Record the provider and route alongside that ID. A compatibility gateway can reject a field itself or forward it to Claude; retaining the raw error and request ID helps distinguish those cases. Do not change the model name to an older version as an invisible workaround.
Look for forced tool choice in more than the final HTTP code. A framework may inject it when a helper requests structured output or selects a specific function. Inspect the serialized request after framework defaults have been applied, with credentials and private content removed. The field you intended to send and the field that reaches the API can differ.
Separate schema validity from business completion
Suppose an invoice assistant uses lookup_invoice to fetch the current status. The request should describe when to call the tool and the tool should have a narrow input schema. A returned invoice identifier is not proof that the invoice exists, belongs to the user or has been paid. Those facts come from the application-side lookup.
For the direct Claude API, the migration guide recommends auto with strict: true, and additionalProperties: false on schema objects. It also notes a platform exception: strict tool use is unavailable for Sonnet 5.5 on Amazon Bedrock. Verify the platform-specific contract before copying the direct-API example. Migration guide
Here is a documentary request skeleton. It has not been submitted to a provider:
INV-DEMO-42 is a synthetic identifier. A real lookup must authorize the invoice for the signed-in user. Keep the tool read-only while diagnosing request compatibility. Once lookup behavior is reliable, add write operations under their own authorization and idempotency rules.
If the task only needs a schema-shaped answer, inspect structured outputs as a separate option. If it needs a live lookup, a well-formed object cannot replace that lookup. Choose the interface from the required result, then test the full path that supplies it.
Handle the no-tool response explicitly
With auto, the model may answer without calling the tool. Your application should detect that outcome and avoid presenting an unverified status as a fetched fact.
For an invoice lookup, define success as an authorized tool call, an application result for the requested invoice, and a final answer grounded in that result. If the model asks for an invoice identifier, return a visible clarification state. If it gives an answer without fetching, show that the lookup is incomplete. Repeatedly prompting until a tool appears can create cost and inconsistent behavior; set a bounded retry policy for the task.
Do not execute a function merely because a text answer contains its name. Execute only recognized tool-use blocks with validated input. Validate the business fields even when strict schema enforcement is active: a string can be syntactically valid and still refer to an unauthorized record.
Keep the distinction visible in logs. Useful outcomes include request_rejected, clarification_needed, tool_requested, tool_denied, tool_failed and lookup_completed. A single “success” flag tends to hide the exact point where the application stopped making progress.
Run a local regression check before paying for inference
This fixture checks request choices and response handling without network access. Its blocks are synthetic, so it proves the local contract logic only.
These assertions were executed successfully. The last state deliberately hands off to authorization and lookup; it does not mark the task complete. Add fixtures for your actual schema, denied records, missing values and tool failures. Then run a live provider check with your own authorized test account and retain its receipt separately from the local result.
Check the nearby migration changes
Fixing forced tool choice can expose another rejected field that was already in the request. Sonnet 5.5's what's-new page documents thinking and sampling changes. For example, thinking.type: "disabled" moves to between_tools, and non-default sampling parameters are rejected. Verify these fields against the documentation rather than deleting every parameter at once.
Change one causal setting, retain the new response and compare it with the previous error. This makes a second failure interpretable. Keep the same test task and tool schema while validating the request; changing task, model, gateway and prompt together can make a successful response impossible to explain.
If the integration keeps conversation history, also inspect how tool-use blocks and results are replayed. A corrected first request is only the start of a tool loop. Preserve the provider's required block structure, match the result to its tool call, and verify the final answer instead of stopping at the first accepted HTTP response.
Build a migration review board with Atoms
Use Atoms to make a small review application for request variants and their receipts. The first version can accept manually pasted, sanitized records. This supports the team's migration work without claiming that Atoms provides native Sonnet 5.5 API access.
Ask for a board with task ID, provider, model, request version, tool-choice type, strict-schema setting, expected state, observed state and evidence link. Add separate checks for request acceptance, authorized tool execution and final answer correctness. Let a reviewer compare the old and new request side by side.
In the preview, import the synthetic text-only response and confirm it stays incomplete. Import the tool-use fixture and confirm that it asks for authorization and lookup evidence. Save a record, reload it, and verify persistence. If the board needs shared storage, use the Atoms Cloud guide and test reviewer permissions on both reads and edits.
Conclusion
Replace forced tool choice with the supported request contract, then make no-tool responses and business completion explicit. The compatible payload, the authorized lookup and the final answer are separate checks. Build the migration review board in Atoms to keep those checks and their receipts visible during rollout.
Frequently asked questions
01Q1: Does strict tool use force Sonnet 5.5 to call a tool?
No. Strict tool use constrains a call's input schema. With auto, the model can still respond without calling a tool.
02Q2: Why does token counting fail before generation starts?
The official migration guide says the forced-tool compatibility check also applies to token counting. Inspect the same tool_choice field in that request.
03Q3: Can I use the strict example on Bedrock unchanged?
The Sonnet 5.5 migration guide identifies a Bedrock limitation for strict tool use. Follow the current platform contract and validate input in your application.
04Q4: Was the provider error reproduced in this guide?
The error is documented by Anthropic. The executed tests cover local payload and response logic; they do not claim a live Sonnet invocation.
