Messages API Roles and Content Block Types Reference

Yes - content: "some text" is shorthand for content: [{"type": "text", "text": "some text"}]. Use the list form once you need more than one block or a non-text block type.

Claude produces text and tool_use blocks in assistant turns. image and tool_result blocks are things your application sends in user turns; Claude never generates them.

The tool_use_id field on the tool_result block must exactly match the id field Claude generated on the corresponding tool_use block.

Yes - Claude can request several tool calls in a single assistant turn. When that happens, return all the matching tool_result blocks together in a single user turn, not split across multiple turns.

It tells Claude the tool call failed rather than succeeded, so Claude reasons about the failure and can try a different approach instead of treating the error message as valid data.

No. system is a separate top-level request parameter, not a role or a content block inside messages. It has no block types of its own.

No - image blocks only appear in user turns, since they represent input you're providing to Claude, not something Claude generates.

base64 embeds the raw image bytes directly in the request; url instead points to a publicly reachable image URL that Claude fetches. Use base64 for local files and url when the image is already hosted.

Always parse it - input is delivered as a structured object matching your tool's schema, and relying on exact string formatting (like specific escaping) is fragile and can break across model versions.

Yes - content on a tool_result block can be a string, or a list of blocks (such as text and image) for richer results, like returning a generated chart image alongside a text summary.

Generally yes for readability and how Claude processes multi-block context - place explanatory text before or after the block it refers to consistently, though there's no strict alternation rule within one turn's content list the way there is across turns.