Skip to main content
Messages API models tool workflows through content blocks rather than tool_calls arrays. Use this page when your app already depends on Anthropic-style tool semantics.

Define Tools

Assistant Tool Use Block

Return Tool Results

Tool results go back in a user message with tool_result blocks.
Keep the assistant tool_use block in the replayed history before you send the tool_result block. Some reasoning-capable models also return thinking blocks alongside tool_use. If you want continuity across turns, replay those blocks unchanged, including signature, before the later tool_result block. See Messages Thinking Blocks.

Streaming Behavior

When streaming is enabled:
  • the tool-use block begins with content_block_start
  • argument deltas arrive as content_block_delta with type: input_json_delta
  • tool-oriented turns usually end with message_delta.stop_reason: "tool_use"

Caveats

  • assistant messages can include tool_use blocks but not tool_result blocks
  • user messages can include tool_result blocks but not tool_use blocks
  • tool_choice: {"type":"any"} maps to required tool use semantics internally

Common mistakes

  • sending tool_result in an assistant message instead of a user message
  • losing the original tool_use block before sending the result back
  • trying to use Chat Completions or Responses tool payload shapes on this surface