Building with Claude Sonnet 5.5: choosing, migrating, tuning

At launch, Sonnet 5.5 kept Sonnet 5's per-token prices, so moving to it can look like a one-line change. Anthropic's guide to building with it, written by Addy Osmani, says otherwise. After changing the model ID to claude-sonnet-5-5, developers have to work through five breaking changes and one change to the shape of responses. Several of these turn requests that were valid on Sonnet 5 into HTTP 400 errors.

The biggest change involves thinking, the reasoning the model does before or during its answer. Thinking is now on by default, and a request that explicitly disables it returns a 400. The replacement is a setting called between_tools: it skips the upfront reasoning and lets the model think only between tool calls. It works at low, medium or high effort but returns a 400 at xhigh or max, rejects other thinking fields, and does not let effort change mid-conversation. Because a response can now begin with a thinking block, code that treats the first content block as the answer breaks, which is why the guide reads blocks by type. Notes longer than a sentence or two that the model writes between tool calls also now come back as thinking blocks, and under adaptive thinking those blocks are empty at the default display setting. That change throws no error, but a UI can quietly stop showing the notes.

The other changes affect specific features. Forcing tool use through tool_choice of type any or tool now returns a 400; the guide swaps in auto, marks the tool strict so its input matches the schema, and tells the model in the prompt when to use it. On the Claude API and Google Cloud, computer use must move to the new computer toolset, while Amazon Bedrock still accepts the older tool. With the advisor tool, a Sonnet 5.5 executor rejects Opus 4.8, Opus 4.7 and Sonnet 5 as advisors. Sonnet 5.5's thinking blocks are also tied to the model and the conversation: it can read Sonnet 5's blocks, so a conversation switched over midway keeps its reasoning, but no other model can read Sonnet 5.5's. Claude Code can apply the model ID swap and the breaking parameter changes across a codebase through its bundled Claude API skill.

After the migration comes tuning. Effort levels have been recalibrated, so a given level no longer produces the same amount of thinking it did on Sonnet 5, and old settings do not carry over. The default is high on the Claude API and medium in Claude Code. The guide suggests starting at medium for well-specified agentic coding and keeping xhigh or max for cases where evals show a quality gain. At those levels the model thinks longer and costs more, and the guide suggests Opus 5.5 may then be the better choice. The total bill still changes even though per-token prices matched at launch, because Sonnet 5.5 typically uses fewer tokens per task. Images are one thing to watch: Sonnet 5.5 uses a high-resolution image tier, and a 2000 by 1500 image takes about 2.5 times the tokens it did on Sonnet 4.6, Sonnet 4.5 or Haiku 4.5, so the guide suggests downscaling images that do not need the detail.