# Why Do Tool Calls Fail After Switching a Coding Agent to Another Model? > Tool calls usually fail after a model switch because the replacement changes the protocol, tool schema expectations, argument serialization, streaming events, or conversation-state behavior. Treat the migration as a contract change, not a model-name change. A useful first test is smaller than a coding benchmark: ask the replacement model to call one read-only function with two required arguments. If that fails, the problem is below the planning layer. If it succeeds, add streaming, multiple tools, state, and write actions one at a time until the first contract break appears. Model switches expose assumptions that were hidden inside the old integration. A coding agent is not only a prompt plus a model. It is a state machine connecting model output, a stream parser, a tool registry, an executor, and a loop that returns tool results. Any boundary can become incompatible while ordinary text still looks healthy. ## Separate capability from protocol A model can be strong at coding yet unavailable through the protocol your client sends. Another may accept the request but not advertise tool use on that route. Check capability metadata before changing a model name. [Atlas Cloud's LLM protocol guide](https://www.atlascloud.ai/docs/llm-protocols?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=why-tool-calls-fail-after-switching-coding-agent-models) lists OpenAI Chat Completions, Responses, Anthropic Messages, Google Gemini, and other supported formats on one base URL. It also states that not every model speaks every protocol. Use each model's `supported_apis` and tool capability as the source of truth. | Layer | Migration question | Failure signal | |---|---|---| | Endpoint | Does the model accept this protocol? | 400 response or ignored fields | | Capability | Does this route advertise tools? | Text answer instead of a call | | Schema | Are names and JSON Schema valid? | Missing or malformed arguments | | Stream | Are argument deltas assembled correctly? | Truncated JSON | | Loop | Are tool results returned in the expected role? | Repeated call or stalled turn | ## Reduce the tool schema to one contract Start with a function that has a short name, two required strings, no unions, and no optional nesting. Complicated schemas combine model behavior with validator behavior, making diagnosis slow. ```json { "type": "function", "function": { "name": "read_file", "description": "Read a UTF-8 text file from the workspace.", "parameters": { "type": "object", "properties": { "path": {"type": "string"}, "max_chars": {"type": "integer", "minimum": 1} }, "required": ["path", "max_chars"], "additionalProperties": false } } } ``` Force this function if the protocol supports forced tool choice. A forced call distinguishes inability to call from a planning decision not to call. ## Test non-streaming before streaming Non-streaming responses show the final tool object in one payload. Streaming may deliver the name, call identifier, and JSON arguments in separate events. Parse arguments only after the protocol's final or done event. Never execute a tool because a partial buffer happens to parse as JSON. A later delta can still extend it. Store buffers by call identifier, reject duplicate finalization, and record the raw event sequence during migration tests. | Stream invariant | Required behavior | |---|---| | Stable call identity | All deltas map to one call buffer | | Ordered assembly | Argument fragments append in event order | | Explicit completion | Execution waits for the final event | | Single execution | A completed call runs at most once | ## Normalize the agent loop explicitly Do not spread provider-specific fields across the executor. Convert every response into an internal form such as `assistant_text`, `tool_calls`, `usage`, and `stop_reason`. Convert tool results back through a protocol adapter. Keep call IDs opaque. Preserve them exactly when the protocol requires correlation. Validate arguments before execution and return structured errors to the model instead of silently editing malformed JSON. ## Reset state during the first comparison Old conversation items can contain reasoning blocks, tool-result roles, state handles, or assistant messages that the replacement route does not accept. Start with a fresh conversation and the same system instructions. Then replay a short normalized history. State shortcuts are protocol-specific. For example, a previous-response handle does not imply that developer instructions are carried into the next request. Make instruction persistence an explicit test rather than an assumption. ## Build a migration ladder Run the same fixtures in this order: * Plain text response. * One forced read-only tool, non-streaming. * One automatic tool choice, non-streaming. * One forced tool with streaming. * Two independent tools. * One tool error and recovery. * A short multi-turn coding task. Stop at the first failure and inspect the wire data. Do not jump from a health check to an autonomous repository edit. ## Decide whether one adapter is enough A shared adapter is useful when differences are field names or event names. Separate adapters are safer when models require different protocols, history representations, or tool-result semantics. Atlas Cloud can simplify model experiments because one key and base URL expose multiple formats and a changing [LLM model catalog](https://www.atlascloud.ai/llm-models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=why-tool-calls-fail-after-switching-coding-agent-models). That convenience does not remove capability checks. Record the chosen model, protocol, schema version, streaming mode, and test result together. ## The bottom line Tool calls fail after a model switch when the integration treats a behavioral and protocol migration as a string replacement. Verify the route, reduce the schema, pass a non-streaming forced-call test, validate streamed assembly, and add conversation state last. If two models need materially different message or event semantics, keep separate adapters instead of hiding the difference. ## FAQ ### Why does the new model answer in text instead of calling a tool? The model may not support tools on the selected protocol, may require a different tool-choice setting, or may interpret the tool description differently. Verify capability metadata and test one forced call. ### Can two OpenAI-compatible models still return different tool-call shapes? Yes. Compatibility can cover the outer request while streamed deltas, call identifiers, argument completion, and finish reasons still differ. ### Should I reuse the old conversation after switching models? Only after confirming the new model and protocol accept the same history items. A safer migration test starts from a fresh conversation and then adds state back deliberately. ### What is the fastest diagnostic test? Force one deterministic read-only tool with a tiny JSON schema, run it without streaming, and log the raw request and response before testing a full agent loop. ### Does Atlas Cloud normalize every model into one identical tool interface? No. Atlas Cloud supports several protocols, and each model publishes supported APIs and capabilities. The client must choose a protocol the model actually supports. ### When should I keep separate adapters for two models? Keep adapters when their state objects, streaming events, tool-result messages, or error semantics cannot be represented safely by one normalized contract.