Agent SDK reference - Python changedagent-sdk/python
Nearest release: v2.1.251, published 6 hours before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+21added
Lines−16removed
From line
141
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits61to this page, all time
The whole hunk
from line 141, old and new numbered
/
from line 141
141141
142142#### `ToolAnnotations`
143143
144Re-exported from `mcp.types` (also available as `from claude_agent_sdk import ToolAnnotations`). All fields are optional hints; clients should not rely on them for security decisions.
144Behavioral hints for a tool, passed as the `annotations` argument of [`tool()`](#tool). `ToolAnnotations` extends the MCP SDK's `mcp.types.ToolAnnotations` with a `maxResultSizeChars` field, and you can write each hint in camelCase or snake\_case: `ToolAnnotations(readOnlyHint=True)` and `ToolAnnotations(read_only_hint=True)` are equivalent. You can also pass a plain `mcp.types.ToolAnnotations` wherever the SDK accepts annotations.
145145
146| Field | Type | Default | Description |
147| :---------------- | :------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
148| `title` | `str \| None` | `None` | Human-readable title for the tool |
149| `readOnlyHint` | `bool \| None` | `False` | If `True`, the tool does not modify its environment |
150| `destructiveHint` | `bool \| None` | `True` | If `True`, the tool may perform destructive updates (only meaningful when `readOnlyHint` is `False`) |
151| `idempotentHint` | `bool \| None` | `False` | If `True`, repeated calls with the same arguments have no additional effect (only meaningful when `readOnlyHint` is `False`) |
152| `openWorldHint` | `bool \| None` | `True` | If `True`, the tool interacts with external entities (for example, web search). If `False`, the tool's domain is closed (for example, a memory tool) |
146The snake\_case names and the typed `maxResultSizeChars` field require Python Agent SDK 0.2.140 or later. Versions 0.1.31 through 0.2.139 re-export `mcp.types.ToolAnnotations` unchanged. On versions 0.1.55 through 0.2.139 you can still pass `maxResultSizeChars` as a keyword argument: the MCP class accepts extra fields, and the SDK forwards the value to Claude Code.
153147
148All fields are optional. Clients shouldn't rely on the hints for security decisions.
149
150| Field | Type | Default | Description |
151| :------------------- | :------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
152| `title` | `str \| None` | `None` | Human-readable title for the tool |
153| `readOnlyHint` | `bool \| None` | `False` | If `True`, the tool does not modify its environment |
154| `destructiveHint` | `bool \| None` | `True` | If `True`, the tool may perform destructive updates (only meaningful when `readOnlyHint` is `False`) |
155| `idempotentHint` | `bool \| None` | `False` | If `True`, repeated calls with the same arguments have no additional effect (only meaningful when `readOnlyHint` is `False`) |
156| `openWorldHint` | `bool \| None` | `True` | If `True`, the tool interacts with external entities (for example, web search). If `False`, the tool's domain is closed (for example, a memory tool) |
157| `maxResultSizeChars` | `int \| None` | `None` | Number of characters up to which Claude Code keeps this tool's text result inline in the conversation instead of saving it to a file, up to 500,000. Results that contain images aren't affected. A Claude Code setting rather than an MCP hint: the SDK sends it in the tool's `_meta` as `anthropic/maxResultSizeChars`. See [Raise the limit for a specific tool](/docs/en/mcp#raise-the-limit-for-a-specific-tool) |
158
154159```python theme={null}
155160from claude_agent_sdk import tool, ToolAnnotations
156161from typing import Any
from line 687
682687 annotations: ToolAnnotations | None = None
683688```
684689
685| Property | Type | Description |
686| :------------- | :----------------------------------------- | :--------------------------------------------------------------------------------------------------------- |
687| `name` | `str` | Unique identifier for the tool |
688| `description` | `str` | Human-readable description |
689| `input_schema` | `type[T] \| dict[str, Any]` | Schema for input validation |
690| `handler` | `Callable[[T], Awaitable[dict[str, Any]]]` | Async function that handles tool execution |
691| `annotations` | `ToolAnnotations \| None` | Optional MCP tool annotations (e.g., `readOnlyHint`, `destructiveHint`, `openWorldHint`). From `mcp.types` |
690| Property | Type | Description |
691| :------------- | :---------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- |
692| `name` | `str` | Unique identifier for the tool |
693| `description` | `str` | Human-readable description |
694| `input_schema` | `type[T] \| dict[str, Any]` | Schema for input validation |
695| `handler` | `Callable[[T], Awaitable[dict[str, Any]]]` | Async function that handles tool execution |
696| `annotations` | [`ToolAnnotations`](#toolannotations)` \| None` | Optional tool annotations (for example `readOnlyHint`, `destructiveHint`, `openWorldHint`, `maxResultSizeChars`) |
692697
693698### `Transport`
694699
No line in this hunk matches that.