[DOCS] Incorrect stop_reason value in tool use response example

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview

Section/Topic

"Single tool example" section - the JSON response example after processing tool results

Current Documentation

The response example shows:

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-sonnet-4-5",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "The current weather in San Francisco is 15 degrees Celsius (59 degrees Fahrenheit). It's a cool day in the city by the bay!"
    }
  ]
}

What's Wrong or Missing?

The stop_reason value is incorrectly shown as "stop_sequence". This value is only returned when Claude encounters a custom stop sequence provided in the request's stop_sequences parameter.

In this example, Claude has finished its natural response after processing the tool result - it should show "end_turn" which indicates Claude completed its response naturally.

SDK Evidence:

From the Python SDK (anthropic-sdk-python), the StopReason type is defined as:

StopReason: TypeAlias = Literal["end_turn", "max_tokens", "stop_sequence", "tool_use", "pause_turn", "refusal"]

The stop_sequence value is specifically documented in handling-stop-reasons as: "Claude encountered one of your custom stop sequences."

Since no custom stop sequences were provided in the tool use example request, and Claude is naturally finishing its response with the weather information, the correct stop_reason should be "end_turn".

Suggested Improvement

Change the response example to use the correct stop_reason:

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-sonnet-4-5",
  "stop_reason": "end_turn",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "The current weather in San Francisco is 15 degrees Celsius (59 degrees Fahrenheit). It's a cool day in the city by the bay!"
    }
  ]
}

Impact

Medium - Makes feature difficult to understand

Additional Context

SDK File: src/anthropic/types/stop_reason.py (StopReason type definition)
SDK Commit: 9b5ab24ba17bcd5e762e5a5fd69bb3c17b100aaa

This discrepancy could confuse developers who are implementing proper stop_reason handling, as they may expect stop_sequence in their tool use workflows when they should actually be checking for end_turn.

Note: The old URL https://platform.claude.com/docs/en/build-with-claude/tool-use redirects (307) to this canonical URL.