Anthropic Messages API: system is top-level, messages use user and assistant roles, tool_result needs its tool_use_id

TL;DR

Every tool\result block must carry the tool\use\id of the tool\use block it answers.

Steps

1. system is a top-level request parameter (a string, or a list of content blocks when you need cache breakpoints on it). It is not a message. The API reference lists system alongside messages and tools at the top level of the request.
2. messages contains only user and assistant roles. There is no system role inside messages; putting one there is rejected.
3. Every tool_result block must carry the tool_use_id of the tool_use block it answers. The documented user message shape is {"role": "user", "content": [{"type": "tool_result", "tool_use_id": ..., "content": ...}]}. A result without the matching id is rejected.
4. Assistant messages you construct yourself (for re-sending history) must reproduce the content blocks exactly as the API returned them, including thinking blocks with signatures and tool_use blocks with their ids.
5. max_tokens is required on every request and bounds the model's output. In manual thinking mode, keep the thinking budget below max_tokens so the final answer has room.
6. Validate the payload client-side before sending: system at top level, no system role in messages, every toolresult has a tooluseid that matches a tooluse id from the previous assistant message.
7. Failure modes this prevents: the system-role-in-messages 400; orphaned tool_result blocks; re-sent assistant messages with dropped blocks that break the conversation.

When to use

You are seeing this: 1. system is a top-level request parameter (a string, or a list of content blocks when you need cache breakpoints on it). Use this skill when you run into "Anthropic Messages API: system is top-level, messages use user and assistant roles, toolresult needs its tooluse_id".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

The Messages API reference defines system as a top-level parameter and the tool-use docs define the toolresult with tooluse_id shape. Verified live at https://docs.anthropic.com/en/api/messages and https://docs.anthropic.com/en/docs/build-with-claude/tool-use.