[ { "provider": "anthropic", "name": "Custom (user-defined) client tool", "type": "custom", "category": "client", "description": "Tool you define with name/description/input_schema (JSON Schema). Claude returns a tool_use block (id toolu_…, name, input, caller) with stop_reason tool_use; your code runs it and replies with a tool_result block. `type` may be omitted or set to \"custom\".", "compatible_models": [ "claude-fable-5-1", "claude-opus-5", "claude-sonnet-5", "claude-fable-5", "claude-opus-4-8", "claude-opus-4-7", "claude-sonnet-4-6", "claude-opus-4-6", "claude-opus-4-5-20251101", "claude-haiku-4-5-20251001", "claude-sonnet-4-5-20250929", "claude-mythos-5-1", "claude-mythos-5" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "name", "input_schema" ], "properties": { "type": { "enum": [ "custom" ], "description": "Optional; the only value is custom." }, "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,128}$", "description": "Unique within the request; must not collide with a toolset member family name (computer/browser) when that toolset is declared." }, "description": { "type": "string", "description": "Strongly recommended, 3-4+ sentences: what, when (and when not), parameter semantics, caveats." }, "input_schema": { "type": "object", "description": "JSON Schema, type must be object; properties/required. Strict mode uses the structured-outputs JSON Schema subset (additionalProperties:false etc.)." }, "eager_input_streaming": { "type": "boolean", "description": "true = fine-grained (unbuffered, unvalidated) input streaming for this tool. User-defined tools only. Replaces the legacy fine-grained-tool-streaming-2025-05-14 header." }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])." }, "input_examples": { "type": "array", "items": { "type": "object" }, "description": "Schema-validated example inputs (user-defined + Anthropic-schema client tools only; not toolsets/server tools)." } } }, "tool_choice_support": "auto/any/tool/none (tool_choice.type=tool may name this tool)", "parallel": "yes (several tool_use blocks per turn; one tool_result each, all in one user message)", "streaming_events": [ "content_block_start (tool_use, input: {})", "content_block_delta (input_json_delta.partial_json)", "content_block_stop", "message_delta (stop_reason: tool_use)" ], "result_shape": { "tool_use": { "type": "tool_use", "id": "toolu_01…", "name": "", "input": { "...": "object matching input_schema" }, "caller": { "type": "direct" } }, "tool_result (you send)": { "type": "tool_result", "tool_use_id": "toolu_01…", "content": "string | [text|image|document|search_result|tool_reference blocks]", "is_error": "optional bool", "cache_control": "optional" }, "live_note": "Every tool_use block returned live on 2026-09-18 carried caller:{type:direct} (haiku 4.5, sonnet 4.6, sonnet 5)." }, "billing": "Tokens only. Tool-use system prompt overhead per model (auto/none vs any/tool): {\"claude-opus-5\": [286, 406], \"claude-opus-4-8\": [290, 410], \"claude-opus-4-7\": [675, 804], \"claude-opus-4-6\": [497, 589], \"claude-opus-4-5-20251101\": [496, 588], \"claude-sonnet-5\": [354, 474], \"claude-sonnet-4-6\": [497, 589], \"claude-sonnet-4-5-20250929\": [496, 588], \"claude-haiku-4-5-20251001\": [496, 588]}. Live count_tokens on haiku 4.5: 11 tokens without tools, 581 with one small get_weather tool (auto), 673 with tool_choice any (+92). input_examples add ~20-200 tokens each.", "limitations": [ "Name regex ^[a-zA-Z0-9_-]{1,128}$", "tool_result blocks must be first in the next user message; text only after them (live 400 otherwise: 'tool_use ids were found without tool_result blocks immediately after')", "tool_choice any/tool: unsupported with manual extended thinking (thinking.type=enabled) and returns 400 on Claude Fable 5.1 / Mythos 5.1 (docs)", "strict:true incompatible with allowed_callers containing a code_execution caller (live 400)", "Circular $ref schemas cannot be enabled for programmatic calling (400 'Circular $ref detected')" ], "security": [ "Treat tool_result content as untrusted (indirect prompt injection); keep it inside tool_result, not system/user text.", "Do not put PHI in strict schemas (compiled grammars are cached up to 24h)." ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/tools/custom-tools/basic.sh", "python": "examples/anthropic/tools/custom-tools/basic.py", "typescript": "examples/anthropic/tools/custom-tools/basic.ts" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "a1_forced_tool..a10_input_examples, b1-b3 streaming, j1-j3 count_tokens on claude-haiku-4-5-20251001 (tmp-live/tools/)" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/strict-tool-use", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "tool_choice": { "auto": "default when tools present; may answer in text; disable_parallel_tool_use:true => at most one call (live verified)", "any": "must call some tool; disable_parallel_tool_use:true => exactly one call (live verified: haiku invented location '' when forced on 'Say hello')", "tool": "{type:tool, name} forces that tool (live verified); assistant prefilled so no text before tool_use", "none": "no tool calls (live verified; default when no tools)" }, "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Bash tool", "type": "bash_20250124", "category": "anthropic-defined-client", "description": "Schema-less client tool: Claude emits {command} or {restart:true}; you run it in a persistent bash session you own and return stdout+stderr as tool_result.", "compatible_models": [ "claude-fable-5-1", "claude-opus-5", "claude-sonnet-5", "claude-fable-5", "claude-opus-4-8", "claude-opus-4-7", "claude-sonnet-4-6", "claude-opus-4-6", "claude-opus-4-5-20251101", "claude-haiku-4-5-20251001", "claude-sonnet-4-5-20250929", "claude-mythos-5-1", "claude-mythos-5" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "bash_20250124" }, "name": { "const": "bash" }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])." }, "input_examples": { "type": "array", "items": { "type": "object" }, "description": "Schema-validated example inputs (user-defined + Anthropic-schema client tools only; not toolsets/server tools)." } }, "tool_use.input": { "command": { "type": "string", "description": "required unless restart" }, "restart": { "type": "boolean" } } }, "tool_choice_support": "auto/any/tool/none (tool_choice.type=tool may name this tool)", "parallel": "yes (several tool_use blocks per turn; one tool_result each, all in one user message)", "streaming_events": [ "content_block_start (tool_use, input: {})", "content_block_delta (input_json_delta.partial_json)", "content_block_stop", "message_delta (stop_reason: tool_use)" ], "result_shape": { "tool_use": { "type": "tool_use", "id": "toolu_…", "name": "bash", "input": { "command": "echo OK" }, "caller": { "type": "direct" } }, "tool_result": "string or text blocks; is_error:true on failure" }, "billing": "Definition adds ~325 input tokens (Opus 5/4.8/4.7) or ~244 (Opus 4.6, Sonnet 4.6 and earlier) + tool-use system prompt. Live count_tokens haiku 4.5: 751 tokens total for one short message + bash tool (vs 11 without tools).", "limitations": [ "No interactive commands, no GUI, no streaming of output; API does not truncate oversized results (request rejected) — truncate client-side.", "bash_20241022 (Sonnet 3.5 only, retired) needs anthropic-beta computer-use-2024-10-22." ], "security": [ "Run in an isolated container/VM as least-privileged user; allowlist commands; ulimit; log; redact secrets from output." ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/tools/bash/basic.sh", "python": "examples/anthropic/tools/bash/basic.py", "typescript": "examples/anthropic/tools/bash/basic.ts" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "h7_bash_20250124 (haiku) -> tool_use input {command:'echo OK'}; j4 count_tokens" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "name_constraint": "name must be exactly 'bash'", "versions": { "bash_20250124": "current, no beta header", "bash_20241022": "legacy, beta computer-use-2024-10-22, retired model only" }, "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Text editor tool (text_editor_20250728)", "type": "text_editor_20250728", "category": "anthropic-defined-client", "description": "Schema-less client tool for viewing/creating/editing files: commands view (path, view_range?), str_replace (path, old_str, new_str), create (path, file_text), insert (path, insert_line, insert_text). Current version for Claude 4+ (adds max_characters). Live: the only text_editor version accepted by claude-haiku-4-5 (20250124 and 20250429 -> 400 'does not support tool types').", "compatible_models": [ "claude-fable-5-1", "claude-opus-5", "claude-sonnet-5", "claude-fable-5", "claude-opus-4-8", "claude-opus-4-7", "claude-sonnet-4-6", "claude-opus-4-6", "claude-opus-4-5-20251101", "claude-haiku-4-5-20251001", "claude-sonnet-4-5-20250929", "claude-mythos-5-1", "claude-mythos-5" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "text_editor_20250728" }, "name": { "const": "str_replace_based_edit_tool" }, "max_characters": { "type": "integer", "description": "Truncation length for view (20250728+ only)" }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])." }, "input_examples": { "type": "array", "items": { "type": "object" }, "description": "Schema-validated example inputs (user-defined + Anthropic-schema client tools only; not toolsets/server tools)." } }, "tool_use.input": { "command": { "enum": [ "view", "str_replace", "create", "insert" ] }, "path": "string", "view_range": "[start,end] 1-indexed, -1 = EOF", "old_str": "string", "new_str": "string", "file_text": "string", "insert_line": "int (0 = top)", "insert_text": "string" } }, "tool_choice_support": "auto/any/tool/none (tool_choice.type=tool may name this tool)", "parallel": "yes (several tool_use blocks per turn; one tool_result each, all in one user message)", "streaming_events": [ "content_block_start (tool_use, input: {})", "content_block_delta (input_json_delta.partial_json)", "content_block_stop", "message_delta (stop_reason: tool_use)" ], "result_shape": { "tool_use": { "type": "tool_use", "id": "toolu_…", "name": "str_replace_based_edit_tool", "input": { "command": "view", "path": "/tmp" }, "caller": { "type": "direct" } }, "tool_result": "file contents (recommended with 'N: ' line numbers) / 'Successfully replaced text at exactly one location.' / errors with is_error:true" }, "billing": "~700 additional input tokens for the definition (docs figure for text_editor_20250429 on Claude 4.x). Live count_tokens haiku 4.5 with text_editor_20250728: 1252 tokens (vs 11 without tools).", "limitations": [ "Name is fixed (live 400: \"tools.0.text_editor_20250728.name: Input should be 'str_replace_based_edit_tool'\")", "str_replace must match exactly one location (your implementation enforces)." ], "security": [ "Validate paths (no traversal), backups, permission checks." ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/tools/text-editor/basic.sh", "python": "examples/anthropic/tools/text-editor/basic.py", "typescript": "examples/anthropic/tools/text-editor/basic.ts" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "h6_text_editor_20250728 (haiku) view /tmp; h9 wrong name 400; k15/k16 older versions 400 on haiku" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "name_constraint": "str_replace_based_edit_tool (20250429+) / str_replace_editor (20250124, 20241022)", "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Text editor tool (text_editor_20250429)", "type": "text_editor_20250429", "category": "anthropic-defined-client", "description": "Schema-less client tool for viewing/creating/editing files: commands view (path, view_range?), str_replace (path, old_str, new_str), create (path, file_text), insert (path, insert_line, insert_text). Claude 4 version (removed undo_edit). Rejected live by haiku 4.5; schema-accepted by the GA endpoint. Model list: docs only say 'Claude 4'.", "compatible_models": [], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "text_editor_20250429" }, "name": { "const": "str_replace_based_edit_tool" }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])." }, "input_examples": { "type": "array", "items": { "type": "object" }, "description": "Schema-validated example inputs (user-defined + Anthropic-schema client tools only; not toolsets/server tools)." } }, "tool_use.input": { "command": { "enum": [ "view", "str_replace", "create", "insert" ] }, "path": "string", "view_range": "[start,end] 1-indexed, -1 = EOF", "old_str": "string", "new_str": "string", "file_text": "string", "insert_line": "int (0 = top)", "insert_text": "string" } }, "tool_choice_support": "auto/any/tool/none (tool_choice.type=tool may name this tool)", "parallel": "yes (several tool_use blocks per turn; one tool_result each, all in one user message)", "streaming_events": [ "content_block_start (tool_use, input: {})", "content_block_delta (input_json_delta.partial_json)", "content_block_stop", "message_delta (stop_reason: tool_use)" ], "result_shape": { "tool_use": { "type": "tool_use", "id": "toolu_…", "name": "str_replace_based_edit_tool", "input": { "command": "view", "path": "/tmp" }, "caller": { "type": "direct" } }, "tool_result": "file contents (recommended with 'N: ' line numbers) / 'Successfully replaced text at exactly one location.' / errors with is_error:true" }, "billing": "~700 additional input tokens for the definition (docs figure for text_editor_20250429 on Claude 4.x). Live count_tokens haiku 4.5 with text_editor_20250728: 1252 tokens (vs 11 without tools).", "limitations": [ "Name is fixed (live 400: \"tools.0.text_editor_20250728.name: Input should be 'str_replace_based_edit_tool'\")", "str_replace must match exactly one location (your implementation enforces)." ], "security": [ "Validate paths (no traversal), backups, permission checks." ], "beta_header": null, "status": [ "DOCUMENTED", "LEGACY" ], "examples": { "curl": "examples/anthropic/tools/text-editor/basic.sh", "python": "examples/anthropic/tools/text-editor/basic.py", "typescript": "examples/anthropic/tools/text-editor/basic.ts" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "failure", "http_status": 400, "request_note": "k15/k16: haiku 4.5 rejects this version" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "name_constraint": "str_replace_based_edit_tool (20250429+) / str_replace_editor (20250124, 20241022)", "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Text editor tool (text_editor_20250124)", "type": "text_editor_20250124", "category": "anthropic-defined-client", "description": "Schema-less client tool for viewing/creating/editing files: commands view (path, view_range?), str_replace (path, old_str, new_str), create (path, file_text), insert (path, insert_line, insert_text), undo_edit. For earlier models (Claude Sonnet 3.7, retired). Rejected live by haiku 4.5. Includes undo_edit command.", "compatible_models": [], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "text_editor_20250124" }, "name": { "const": "str_replace_editor" }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])." }, "input_examples": { "type": "array", "items": { "type": "object" }, "description": "Schema-validated example inputs (user-defined + Anthropic-schema client tools only; not toolsets/server tools)." } }, "tool_use.input": { "command": { "enum": [ "view", "str_replace", "create", "insert", "undo_edit" ] }, "path": "string", "view_range": "[start,end] 1-indexed, -1 = EOF", "old_str": "string", "new_str": "string", "file_text": "string", "insert_line": "int (0 = top)", "insert_text": "string" } }, "tool_choice_support": "auto/any/tool/none (tool_choice.type=tool may name this tool)", "parallel": "yes (several tool_use blocks per turn; one tool_result each, all in one user message)", "streaming_events": [ "content_block_start (tool_use, input: {})", "content_block_delta (input_json_delta.partial_json)", "content_block_stop", "message_delta (stop_reason: tool_use)" ], "result_shape": { "tool_use": { "type": "tool_use", "id": "toolu_…", "name": "str_replace_based_edit_tool", "input": { "command": "view", "path": "/tmp" }, "caller": { "type": "direct" } }, "tool_result": "file contents (recommended with 'N: ' line numbers) / 'Successfully replaced text at exactly one location.' / errors with is_error:true" }, "billing": "~700 additional input tokens for the definition (docs figure for text_editor_20250429 on Claude 4.x). Live count_tokens haiku 4.5 with text_editor_20250728: 1252 tokens (vs 11 without tools).", "limitations": [ "Name is fixed (live 400: \"tools.0.text_editor_20250728.name: Input should be 'str_replace_based_edit_tool'\")", "str_replace must match exactly one location (your implementation enforces)." ], "security": [ "Validate paths (no traversal), backups, permission checks." ], "beta_header": null, "status": [ "DOCUMENTED", "LEGACY" ], "examples": { "curl": "examples/anthropic/tools/text-editor/basic.sh", "python": "examples/anthropic/tools/text-editor/basic.py", "typescript": "examples/anthropic/tools/text-editor/basic.ts" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "failure", "http_status": 400, "request_note": "k15/k16: haiku 4.5 rejects this version" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "name_constraint": "str_replace_based_edit_tool (20250429+) / str_replace_editor (20250124, 20241022)", "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Memory tool", "type": "memory_20250818", "category": "anthropic-defined-client", "description": "Client-side file-like memory under /memories. Commands: view (path, view_range?), create (path, file_text), str_replace (path, old_str, new_str?), insert (path, insert_line, insert_text), delete (path), rename (old_path, new_path). The API injects a memory protocol into the system prompt telling Claude to view /memories first.", "compatible_models": [ "claude-fable-5-1", "claude-opus-5", "claude-sonnet-5", "claude-fable-5", "claude-opus-4-8", "claude-opus-4-7", "claude-sonnet-4-6", "claude-opus-4-6", "claude-opus-4-5-20251101", "claude-haiku-4-5-20251001", "claude-sonnet-4-5-20250929", "claude-mythos-5-1", "claude-mythos-5" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "memory_20250818" }, "name": { "const": "memory" }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])." }, "input_examples": { "type": "array", "items": { "type": "object" }, "description": "Schema-validated example inputs (user-defined + Anthropic-schema client tools only; not toolsets/server tools)." } }, "tool_use.input": { "command": { "enum": [ "view", "create", "str_replace", "insert", "delete", "rename" ] }, "path": "string under /memories", "view_range": "[start,end]", "file_text": "string", "old_str": "string", "new_str": "string (optional for str_replace = delete)", "insert_line": "int", "insert_text": "string", "old_path": "string", "new_path": "string" } }, "tool_choice_support": "auto/any/tool/none (tool_choice.type=tool may name this tool)", "parallel": "yes (several tool_use blocks per turn; one tool_result each, all in one user message)", "streaming_events": [ "content_block_start (tool_use, input: {})", "content_block_delta (input_json_delta.partial_json)", "content_block_stop", "message_delta (stop_reason: tool_use)" ], "result_shape": { "tool_use": { "type": "tool_use", "id": "toolu_…", "name": "memory", "input": { "command": "view", "path": "/memories" }, "caller": { "type": "direct" } }, "tool_result strings (reference)": { "view dir": "Here're the files and directories up to 2 levels deep in {path}, excluding hidden items and node_modules:\\n{size}\\t{path}…", "view file": "Here's the content of {path} with line numbers:\\n{6-wide line no}\\t{content}", "create": "File created successfully at: {path}", "str_replace": "The memory file has been edited.", "insert": "The file {path} has been edited.", "delete": "Successfully deleted {path}", "rename": "Successfully renamed {old_path} to {new_path}" } }, "billing": "Tokens only. Live count_tokens haiku 4.5: 1576 tokens with the memory tool (vs 11 without) — includes injected memory protocol.", "limitations": [ "Client-side storage only; no beta header since 2026-02-17 (was beta context-management-2025-06-27 era)", "Files >999,999 lines should return an error; view truncates >16,000 chars per tool description" ], "security": [ "Path traversal protection mandatory (validate /memories prefix, canonicalize, reject ../ and %2e%2e%2f)", "Strip sensitive data before writing; cap file sizes; expire stale memories." ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/tools/memory/basic.sh", "python": "examples/anthropic/tools/memory/basic.py", "typescript": "examples/anthropic/tools/memory/basic.ts" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "h8_memory_20250818 (haiku) -> tool_use {command:view,path:/memories}; j6 count_tokens" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "name_constraint": "name must be exactly 'memory'", "sdk_helpers": "BetaLocalFilesystemMemoryTool / BetaAbstractMemoryTool (Python), betaMemoryTool (TS)", "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Computer use toolset (GA)", "type": "computer_toolset_20260801", "category": "anthropic-defined-client", "description": "Client toolset: one entry (no name) declares 17 member tools; Claude calls members as tool_use blocks with name= and toolset_name:'computer'; inputs have no action field. Coordinates are in the pixel space of the screenshots you return (no display_* params). Several member calls per turn = batch action: run in order, stop at first failure, answer skipped ones with is_error and the exact text 'Not executed: an earlier computer action in this turn failed.'", "compatible_models": [ "claude-fable-5-1", "claude-mythos-5-1", "claude-fable-5", "claude-mythos-5", "claude-opus-5", "claude-sonnet-5", "claude-opus-4-8" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "const": "computer_toolset_20260801" }, "configs": { "type": "object", "description": "member name -> {enabled?: bool (default true, incl. zoom), defer_loading?: bool}; unknown member or other fields rejected; disabling all members rejected" }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "allowed_callers": { "enum": [ [ "direct" ] ], "description": "only [\"direct\"]" } }, "rejected": [ "name", "display_width_px", "display_height_px", "display_number", "enable_zoom", "strict", "input_examples", "defer_loading on the entry", "tool_choice type tool naming it", "legacy fine-grained-tool-streaming-2025-05-14 header", "a second computer entry or another tool named computer" ], "members": [ "screenshot", "zoom", "left_click", "right_click", "middle_click", "double_click", "triple_click", "left_click_drag", "mouse_move", "left_mouse_down", "left_mouse_up", "cursor_position", "scroll", "type", "key", "hold_key", "wait" ], "member_inputs": { "screenshot": {}, "zoom": { "region": "[x0,y0,x1,y1]" }, "left_click": { "coordinate?": "[x,y]", "text?": "modifier keys shift|ctrl|alt|super joined with +" }, "right_click|middle_click|double_click|triple_click": "same as left_click", "left_click_drag": { "start_coordinate": "[x,y]", "coordinate": "[x,y]", "text?": "modifiers" }, "mouse_move": { "coordinate": "[x,y]" }, "left_mouse_down|left_mouse_up": {}, "cursor_position": {}, "scroll": { "scroll_direction": "up|down|left|right", "scroll_amount": "int clicks", "coordinate?": "[x,y]", "text?": "modifiers" }, "type": { "text": "string" }, "key": { "text": "key or chord e.g. Return, ctrl+s", "repeat?": "1-100 (toolset only)" }, "hold_key": { "text": "key", "duration": "seconds <=300" }, "wait": { "duration": "seconds <=300" } } }, "tool_choice_support": "auto/any/none; tool_choice type=tool naming the toolset or a member is rejected", "parallel": "batch actions: several member tool_use blocks per turn, executed sequentially in order; disable_parallel_tool_use:true limits to one", "streaming_events": [ "content_block_start tool_use (toolset_name present)", "each member input arrives as ONE complete input_json_delta", "content_block_stop" ], "result_shape": { "tool_use": { "type": "tool_use", "id": "toolu_…", "name": "screenshot", "toolset_name": "computer", "input": {}, "caller": { "type": "direct" } }, "tool_result": { "type": "tool_result", "tool_use_id": "toolu_…", "toolset_name": "computer (required echo)", "content": "[{type:image,…}] for screenshot/zoom; text such as 'OK' otherwise; only text and image blocks allowed" }, "live": "h4 on claude-sonnet-5: content = [thinking(empty, adaptive default), tool_use{name:screenshot,toolset_name:computer,input:{}}], input_tokens 4189 with zoom disabled" }, "billing": "~4,500 input tokens for the toolset definition + tool-use system prompt (≈4,520 on Fable 5/Mythos 5/Opus 5/Opus 4.8, ≈4,590 on Sonnet 5; disabling zoom saves ≈410). Screenshots billed as image input (~1,000-1,800 tokens each).", "limitations": [ "Not available in Managed Agents; Claude API + Google Cloud only (other platforms: earlier beta versions)", "Images must already fit the model image limits (2576 px long edge / 4784 visual tokens on Opus 4.7+); API does not downscale — oversized tool_result image rejected", ">20 images per request triggers stricter per-side limits", "Prompt-injection classifiers scan screenshots (opt-out via support)" ], "security": [ "Dedicated VM/container, no credentials, domain allowlist, human confirmation for consequential actions; screenshots are untrusted content" ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/computer-use/computer_toolset_20260801.sh", "python": "examples/anthropic/computer-use/computer_use_loop.py", "typescript": "examples/anthropic/computer-use/computer_use_loop.ts" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "h4_computer_toolset_20260801_sonnet5 (200, tool_use screenshot); h5 haiku 400 'does not support tool types: computer_toolset_20260801'; k22 name on toolset entry 400" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/release-notes/api", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "beta_history": "GA 2026-08-19 (release notes); successor of computer_20251124/computer_20250124", "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Computer use tool (beta, computer_20251124)", "type": "computer_20251124", "category": "anthropic-defined-client", "description": "Single schema-less tool named 'computer'; Claude emits input {action: , …}. Adds zoom (enable_zoom:true) over computer_20250124. Requires anthropic-beta: computer-use-2025-11-24 on every request (without it the GA schema rejects the type tag — live 400).", "compatible_models": [ "claude-fable-5-1", "claude-mythos-5-1", "claude-fable-5", "claude-mythos-5", "claude-opus-5", "claude-sonnet-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-4-6", "claude-opus-4-5-20251101" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name", "display_width_px", "display_height_px" ], "properties": { "type": { "const": "computer_20251124" }, "name": { "const": "computer" }, "display_width_px": { "type": "integer", "minimum": 1 }, "display_height_px": { "type": "integer", "minimum": 1 }, "display_number": { "type": "integer", "minimum": 0, "description": "X11 display number" }, "enable_zoom": { "type": "boolean", "default": false }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])." }, "input_examples": { "type": "array", "items": { "type": "object" }, "description": "Schema-validated example inputs (user-defined + Anthropic-schema client tools only; not toolsets/server tools)." } }, "actions": [ "key", "hold_key", "type", "cursor_position", "mouse_move", "left_mouse_down", "left_mouse_up", "left_click", "left_click_drag", "right_click", "middle_click", "double_click", "triple_click", "scroll", "wait", "screenshot", "zoom (when enable_zoom:true)" ], "action_inputs": { "screenshot": {}, "zoom": { "region": "[x0,y0,x1,y1]" }, "left_click": { "coordinate?": "[x,y]", "text?": "modifier keys shift|ctrl|alt|super joined with +" }, "right_click|middle_click|double_click|triple_click": "same as left_click", "left_click_drag": { "start_coordinate": "[x,y]", "coordinate": "[x,y]", "text?": "modifiers" }, "mouse_move": { "coordinate": "[x,y]" }, "left_mouse_down|left_mouse_up": {}, "cursor_position": {}, "scroll": { "scroll_direction": "up|down|left|right", "scroll_amount": "int clicks", "coordinate?": "[x,y]", "text?": "modifiers" }, "type": { "text": "string" }, "key": { "text": "key or chord e.g. Return, ctrl+s", "repeat?": "1-100 (toolset only)" }, "hold_key": { "text": "key", "duration": "seconds <=300" }, "wait": { "duration": "seconds <=300" } } }, "tool_choice_support": "auto/any/tool/none (tool_choice.type=tool may name this tool)", "parallel": "yes (several tool_use blocks per turn; one tool_result each, all in one user message)", "streaming_events": [ "content_block_start (tool_use, input: {})", "content_block_delta (input_json_delta.partial_json)", "content_block_stop", "message_delta (stop_reason: tool_use)" ], "result_shape": { "tool_use": { "type": "tool_use", "id": "toolu_…", "name": "computer", "input": { "action": "screenshot" }, "caller": { "type": "direct" } }, "tool_result": { "type": "tool_result", "tool_use_id": "toolu_…", "content": [ { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "…" } } ] } }, "billing": "System prompt overhead 466-499 tokens + ~735 tokens per tool definition (measured with computer_20250124). Live sonnet 4.6: input_tokens 1843 for 'Take a screenshot.'", "limitations": [ "Beta header required (k17b: sonnet 4.6 without header -> 400 unknown type tag)", "Haiku 4.5 / Sonnet 4.5 not supported (k17: 400 'does not support tool types: computer_20251124')", "API downscales? No: you should resize screenshots to model limits; coordinates scale accordingly" ], "security": [ "Same as toolset" ], "beta_header": "computer-use-2025-11-24", "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/computer-use/computer_20251124.sh", "python": "examples/anthropic/computer-use/computer_use_loop.py", "typescript": "examples/anthropic/computer-use/computer_use_loop.ts" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "h1 (sonnet 4.6, screenshot tool_use) + h2 (1x1 PNG tool_result -> text, stop max_tokens@50); k17 haiku 400; k17b no-header 400" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/messages/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Computer use tool (beta, computer_20250124)", "type": "computer_20250124", "category": "anthropic-defined-client", "description": "Earlier beta version for Claude Sonnet 4.5, Haiku 4.5 (and retired Opus 4.1/Sonnet 4/Opus 4). Requires anthropic-beta: computer-use-2025-01-24. Actions include hold_key, left_mouse_down/up, scroll, triple_click, wait (added 2025-01-24). No zoom.", "compatible_models": [ "claude-sonnet-4-5-20250929", "claude-haiku-4-5-20251001" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name", "display_width_px", "display_height_px" ], "properties": { "type": { "const": "computer_20250124" }, "name": { "const": "computer" }, "display_width_px": { "type": "integer", "minimum": 1 }, "display_height_px": { "type": "integer", "minimum": 1 }, "display_number": { "type": "integer", "minimum": 0 }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])." }, "input_examples": { "type": "array", "items": { "type": "object" }, "description": "Schema-validated example inputs (user-defined + Anthropic-schema client tools only; not toolsets/server tools)." } }, "actions": [ "key", "hold_key", "type", "cursor_position", "mouse_move", "left_mouse_down", "left_mouse_up", "left_click", "left_click_drag", "right_click", "middle_click", "double_click", "triple_click", "scroll", "wait", "screenshot" ] }, "tool_choice_support": "auto/any/tool/none (tool_choice.type=tool may name this tool)", "parallel": "yes (several tool_use blocks per turn; one tool_result each, all in one user message)", "streaming_events": [ "content_block_start (tool_use, input: {})", "content_block_delta (input_json_delta.partial_json)", "content_block_stop", "message_delta (stop_reason: tool_use)" ], "result_shape": { "tool_use": { "type": "tool_use", "id": "toolu_…", "name": "computer", "input": { "action": "screenshot" }, "caller": { "type": "direct" } } }, "billing": "~735 tokens per definition + 466-499 system prompt tokens (docs). Live count_tokens haiku 4.5: 1826 tokens for one short message + computer_20250124 (vs 11 without tools).", "limitations": [], "security": [], "beta_header": "computer-use-2025-01-24", "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/computer-use/computer_20250124_haiku.sh" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "h3_computer_20250124_haiku -> tool_use {action:screenshot}; j8 count_tokens 1826" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/messages/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/release-notes/api", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Computer use tool (legacy, computer_20241022)", "type": "computer_20241022", "category": "anthropic-defined-client", "description": "Original computer use tool for Claude Sonnet 3.5 (retired). Beta header computer-use-2024-10-22. Not accepted for current models.", "compatible_models": [], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "properties": { "type": { "const": "computer_20241022" }, "name": { "const": "computer" }, "display_width_px": "int", "display_height_px": "int", "display_number": "int" } }, "tool_choice_support": "auto/any/tool/none (tool_choice.type=tool may name this tool)", "parallel": "yes (several tool_use blocks per turn; one tool_result each, all in one user message)", "streaming_events": [ "content_block_start (tool_use, input: {})", "content_block_delta (input_json_delta.partial_json)", "content_block_stop", "message_delta (stop_reason: tool_use)" ], "result_shape": { "tool_use": { "name": "computer", "input": { "action": "…" } } }, "billing": "Standard input/output tokens (definition + tool_use + tool_result blocks) plus the per-model tool-use system prompt.", "limitations": [], "security": [], "beta_header": "computer-use-2024-10-22", "status": [ "DOCUMENTED", "LEGACY", "RETIRED" ], "examples": {}, "verification": { "method": "sdk_types", "verified_at": "2026-09-18", "result": "success", "http_status": null, "request_note": "type string present in sources/anthropic/openapi/{python,node}-sdk-api.md" }, "sources": [ { "url": "https://platform.claude.com/docs/en/release-notes/api", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Browser use toolset", "type": "browser_toolset_20260801", "category": "anthropic-defined-client", "description": "Client toolset (no name) with 31 member tools (27 enabled by default; javascript_exec, file_upload, read_console, read_network opt-in via configs). Members act on page structure (refs from read_page/find) or viewport coordinates. tool_use blocks carry toolset_name:'browser'. Results may include a browser_state block (tabs inventory + state_changes); tab-management members return exactly one browser_state block. Batch halt text: 'Not executed: an earlier action in this turn failed.'", "compatible_models": [ "claude-fable-5-1", "claude-mythos-5-1", "claude-fable-5", "claude-mythos-5", "claude-opus-5", "claude-sonnet-5", "claude-opus-4-8" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "const": "browser_toolset_20260801" }, "configs": { "type": "object", "description": "member -> {enabled?, defer_loading?}" }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "allowed_callers": { "enum": [ [ "direct" ] ] } }, "members": { "navigation_and_capture": [ "navigate(url, tab_id?)", "screenshot(tab_id?)", "zoom(region, tab_id?)" ], "pointer": [ "left_click(target, modifiers?, tab_id?)", "right_click", "middle_click", "double_click", "triple_click", "hover(target)", "left_click_drag(from, target)", "left_mouse_down(target)", "left_mouse_up(target)", "mouse_move(target)", "scroll(target, scroll_direction, scroll_amount?)", "scroll_to(target: RefTarget)" ], "keyboard_and_timing": [ "type(text)", "key(text, repeat?)", "hold_key(text, duration<=30)", "wait(duration<=30)" ], "page_reading": [ "read_page(filter?, depth?, ref?)", "find(query)", "get_page_text()" ], "forms_and_files": [ "form_input(target: RefTarget, value)", "file_upload(target, paths?, document_ids?) [disabled by default]" ], "diagnostics_and_scripting": [ "read_console() [disabled]", "read_network() [disabled]", "javascript_exec(text) [disabled]" ], "tab_management": [ "new_tab()", "list_tabs()", "switch_tab(tab_id)", "close_tab(tab_id)" ] }, "targets": { "Target": "CoordinateTarget {coordinate:[x,y]} | RefTarget {ref:'ref_N'}" } }, "tool_choice_support": "auto/any/none (type=tool naming toolset/member rejected)", "parallel": "batch actions, sequential execution", "streaming_events": [ "tool_use content_block_start with toolset_name; one complete input_json_delta per member" ], "result_shape": { "tool_use": { "type": "tool_use", "id": "toolu_…", "name": "navigate", "toolset_name": "browser", "input": { "url": "https://example.com" }, "caller": { "type": "direct" } }, "tool_result": { "type": "tool_result", "tool_use_id": "…", "toolset_name": "browser", "content": "[text | image | browser_state] only" }, "browser_state": { "type": "browser_state", "tabs": [ { "tab_id": "tab-1", "title": "…", "url": "…", "active": true } ], "state_changes": [ { "type": "tab_opened", "tab_id": "tab-2" }, { "type": "download_started|download_completed|download_failed", "…": "…" } ] }, "live": "k19 on claude-sonnet-5: [thinking, tool_use navigate{url}, tool_use screenshot{}] both toolset_name:browser; input_tokens 6689" }, "billing": "Toolset definition ≈6,000+ input tokens (live 6689 total for a one-line prompt on Sonnet 5); screenshots as image input.", "limitations": [ "Claude API + Google Cloud only; not on AWS/Bedrock/Foundry; not in Managed Agents", "browser_state limits: <=100 tabs, <=200 state_changes, strings <=4096 chars, no control chars; never on is_error results" ], "security": [ "Page content, tab titles/URLs and download metadata are prompt-injection surfaces; sanitize URLs; confirm consequential actions" ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/computer-use/browser_toolset_20260801.sh" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "k19_browser_toolset_sonnet5 -> navigate + screenshot member calls" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/release-notes/api", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Web search tool (web_search_20250305)", "type": "web_search_20250305", "category": "server", "description": "Basic web search executed by Anthropic. Citations always on. ZDR-eligible. No beta header (GA since 2026-02-17; launched 2025-05-07).", "compatible_models": [ "claude-fable-5-1", "claude-opus-5", "claude-sonnet-5", "claude-fable-5", "claude-opus-4-8", "claude-opus-4-7", "claude-sonnet-4-6", "claude-opus-4-6", "claude-opus-4-5-20251101", "claude-haiku-4-5-20251001", "claude-sonnet-4-5-20250929", "claude-mythos-5-1", "claude-mythos-5" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "web_search_20250305" }, "name": { "const": "web_search" }, "max_uses": { "type": "integer", "exclusiveMinimum": 0, "description": "Cap searches per request; exceeding -> max_uses_exceeded result error" }, "allowed_domains": { "type": "array", "items": { "type": "string" }, "description": "bare domains (+optional path); mutually exclusive with blocked_domains (live 400)" }, "blocked_domains": { "type": "array", "items": { "type": "string" } }, "user_location": { "type": "object", "properties": { "type": { "const": "approximate" }, "city": "string", "region": "string", "country": "ISO 3166-1 alpha-2 (live 400: 'String should have at most 2 characters')", "timezone": "IANA tz" } }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])." } } }, "tool_choice_support": "auto (server tool; tool_choice tool naming web_search not documented)", "parallel": "server-side loop, up to 10 iterations then stop_reason pause_turn; may be paired with client tools in one turn (server_tool_use without result until you return tool_result blocks)", "streaming_events": [ "content_block_start server_tool_use", "input_json_delta (query)", "content_block_stop", "content_block_start web_search_tool_result (whole block, no deltas)", "text deltas with citations_delta" ], "result_shape": { "server_tool_use": { "type": "server_tool_use", "id": "srvtoolu_…", "name": "web_search", "input": { "query": "…" } }, "web_search_tool_result": { "type": "web_search_tool_result", "tool_use_id": "srvtoolu_…", "content": "[{type:web_search_result,url,title,encrypted_content,page_age}] | {type:web_search_tool_result_error,error_code}" }, "citations": { "type": "web_search_result_location", "url": "…", "title": "…", "encrypted_index": "…", "cited_text": "<=150 chars" }, "usage": { "server_tool_use": { "web_search_requests": 1 } }, "error_codes": [ "too_many_requests", "invalid_tool_input", "max_uses_exceeded", "query_too_long", "request_too_large", "unavailable" ] }, "billing": "$10 per 1,000 searches (usage.server_tool_use.web_search_requests) + tokens for results in context (encrypted_content counts as input on later turns). Errors are not billed. Code execution used for dynamic filtering is free. Live c4: 10,491 input tokens for one search on haiku.", "limitations": [ "Org-level Console setting can disable web search (400 'web search is not enabled')", "Request-level allowed_domains must be a subset of org allowlist", "Wildcards only in path", "Not on Amazon Bedrock; Vertex + Foundry-on-Azure only basic version", "encrypted_content must be round-tripped unchanged (400 otherwise)" ], "security": [ "Search results are untrusted content; homograph domains bypass filters (use ASCII)" ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/web-search/web_search.sh", "python": "examples/anthropic/web-search/web_search.py", "typescript": "examples/anthropic/web-search/web_search.ts" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "c4_web_search_forced (haiku, max_uses 1): server_tool_use + web_search_tool_result[5 web_search_result] + text with web_search_result_location citations; usage.server_tool_use.web_search_requests=1; c1: model answered without searching (0 searches); c3 both domain lists 400" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/release-notes/api", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "name_constraint": "name must be 'web_search'", "zdr": "eligible only for web_search_20250305 or later versions with allowed_callers:[\"direct\"]", "dynamic_filtering_models": [], "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Web search tool (web_search_20260209)", "type": "web_search_20260209", "category": "server", "description": "Adds dynamic filtering: allowed_callers defaults to [\"code_execution_20260120\"] so Claude searches from inside an auto-provisioned code execution container and filters results before they enter context. Not ZDR-eligible unless allowed_callers:[\"direct\"]. Models without programmatic tool calling (Haiku 4.5) must set allowed_callers:[\"direct\"] (live 400 otherwise).", "compatible_models": [ "claude-fable-5-1", "claude-opus-5", "claude-sonnet-5", "claude-fable-5", "claude-opus-4-8", "claude-opus-4-7", "claude-sonnet-4-6", "claude-opus-4-6", "claude-opus-4-5-20251101", "claude-haiku-4-5-20251001", "claude-sonnet-4-5-20250929", "claude-mythos-5-1", "claude-mythos-5" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "web_search_20260209" }, "name": { "const": "web_search" }, "max_uses": { "type": "integer", "exclusiveMinimum": 0, "description": "Cap searches per request; exceeding -> max_uses_exceeded result error" }, "allowed_domains": { "type": "array", "items": { "type": "string" }, "description": "bare domains (+optional path); mutually exclusive with blocked_domains (live 400)" }, "blocked_domains": { "type": "array", "items": { "type": "string" } }, "user_location": { "type": "object", "properties": { "type": { "const": "approximate" }, "city": "string", "region": "string", "country": "ISO 3166-1 alpha-2 (live 400: 'String should have at most 2 characters')", "timezone": "IANA tz" } }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"]).", "default": [ "code_execution_20260120" ] } } }, "tool_choice_support": "auto (server tool; tool_choice tool naming web_search not documented)", "parallel": "server-side loop, up to 10 iterations then stop_reason pause_turn; may be paired with client tools in one turn (server_tool_use without result until you return tool_result blocks)", "streaming_events": [ "content_block_start server_tool_use", "input_json_delta (query)", "content_block_stop", "content_block_start web_search_tool_result (whole block, no deltas)", "text deltas with citations_delta" ], "result_shape": { "server_tool_use": { "type": "server_tool_use", "id": "srvtoolu_…", "name": "web_search", "input": { "query": "…" } }, "web_search_tool_result": { "type": "web_search_tool_result", "tool_use_id": "srvtoolu_…", "content": "[{type:web_search_result,url,title,encrypted_content,page_age}] | {type:web_search_tool_result_error,error_code}" }, "citations": { "type": "web_search_result_location", "url": "…", "title": "…", "encrypted_index": "…", "cited_text": "<=150 chars" }, "usage": { "server_tool_use": { "web_search_requests": 1 } }, "error_codes": [ "too_many_requests", "invalid_tool_input", "max_uses_exceeded", "query_too_long", "request_too_large", "unavailable" ] }, "billing": "$10 per 1,000 searches (usage.server_tool_use.web_search_requests) + tokens for results in context (encrypted_content counts as input on later turns). Errors are not billed. Code execution used for dynamic filtering is free. Live c4: 10,491 input tokens for one search on haiku.", "limitations": [ "Org-level Console setting can disable web search (400 'web search is not enabled')", "Request-level allowed_domains must be a subset of org allowlist", "Wildcards only in path", "Not on Amazon Bedrock; Vertex + Foundry-on-Azure only basic version", "encrypted_content must be round-tripped unchanged (400 otherwise)" ], "security": [ "Search results are untrusted content; homograph domains bypass filters (use ASCII)" ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/web-search/web_search.sh", "python": "examples/anthropic/web-search/web_search.py", "typescript": "examples/anthropic/web-search/web_search.ts" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "c2 haiku without allowed_callers -> 400 'does not support programmatic tool calling…set allowed_callers=[\"direct\"]'; c5 with [\"direct\"] -> 200" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/release-notes/api", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "name_constraint": "name must be 'web_search'", "zdr": "eligible only for web_search_20250305 or later versions with allowed_callers:[\"direct\"]", "dynamic_filtering_models": [ "claude-fable-5-1", "claude-mythos-5-1", "claude-fable-5", "claude-mythos-5", "claude-opus-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-opus-4-5-20251101", "claude-sonnet-5", "claude-sonnet-4-6", "claude-sonnet-4-5-20250929" ], "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Web search tool (web_search_20260318)", "type": "web_search_20260318", "category": "server", "description": "Adds response_inclusion control over web_search_20260209. Released 2026-06-11.", "compatible_models": [ "claude-fable-5-1", "claude-opus-5", "claude-sonnet-5", "claude-fable-5", "claude-opus-4-8", "claude-opus-4-7", "claude-sonnet-4-6", "claude-opus-4-6", "claude-opus-4-5-20251101", "claude-haiku-4-5-20251001", "claude-sonnet-4-5-20250929", "claude-mythos-5-1", "claude-mythos-5" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "web_search_20260318" }, "name": { "const": "web_search" }, "max_uses": { "type": "integer", "exclusiveMinimum": 0, "description": "Cap searches per request; exceeding -> max_uses_exceeded result error" }, "allowed_domains": { "type": "array", "items": { "type": "string" }, "description": "bare domains (+optional path); mutually exclusive with blocked_domains (live 400)" }, "blocked_domains": { "type": "array", "items": { "type": "string" } }, "user_location": { "type": "object", "properties": { "type": { "const": "approximate" }, "city": "string", "region": "string", "country": "ISO 3166-1 alpha-2 (live 400: 'String should have at most 2 characters')", "timezone": "IANA tz" } }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"]).", "default": [ "code_execution_20260120" ] }, "response_inclusion": { "enum": [ "full", "excluded" ], "default": "full", "description": "excluded drops nested server_tool_use/result pairs consumed by a completed code execution call" } } }, "tool_choice_support": "auto (server tool; tool_choice tool naming web_search not documented)", "parallel": "server-side loop, up to 10 iterations then stop_reason pause_turn; may be paired with client tools in one turn (server_tool_use without result until you return tool_result blocks)", "streaming_events": [ "content_block_start server_tool_use", "input_json_delta (query)", "content_block_stop", "content_block_start web_search_tool_result (whole block, no deltas)", "text deltas with citations_delta" ], "result_shape": { "server_tool_use": { "type": "server_tool_use", "id": "srvtoolu_…", "name": "web_search", "input": { "query": "…" } }, "web_search_tool_result": { "type": "web_search_tool_result", "tool_use_id": "srvtoolu_…", "content": "[{type:web_search_result,url,title,encrypted_content,page_age}] | {type:web_search_tool_result_error,error_code}" }, "citations": { "type": "web_search_result_location", "url": "…", "title": "…", "encrypted_index": "…", "cited_text": "<=150 chars" }, "usage": { "server_tool_use": { "web_search_requests": 1 } }, "error_codes": [ "too_many_requests", "invalid_tool_input", "max_uses_exceeded", "query_too_long", "request_too_large", "unavailable" ] }, "billing": "$10 per 1,000 searches (usage.server_tool_use.web_search_requests) + tokens for results in context (encrypted_content counts as input on later turns). Errors are not billed. Code execution used for dynamic filtering is free. Live c4: 10,491 input tokens for one search on haiku.", "limitations": [ "Org-level Console setting can disable web search (400 'web search is not enabled')", "Request-level allowed_domains must be a subset of org allowlist", "Wildcards only in path", "Not on Amazon Bedrock; Vertex + Foundry-on-Azure only basic version", "encrypted_content must be round-tripped unchanged (400 otherwise)" ], "security": [ "Search results are untrusted content; homograph domains bypass filters (use ASCII)" ], "beta_header": null, "status": [ "DOCUMENTED" ], "examples": { "curl": "examples/anthropic/web-search/web_search.sh", "python": "examples/anthropic/web-search/web_search.py", "typescript": "examples/anthropic/web-search/web_search.ts" }, "verification": { "method": "docs_only", "verified_at": "2026-09-18", "result": "success", "http_status": null, "request_note": "not exercised live in this run" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/release-notes/api", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "name_constraint": "name must be 'web_search'", "zdr": "eligible only for web_search_20250305 or later versions with allowed_callers:[\"direct\"]", "dynamic_filtering_models": [ "claude-fable-5-1", "claude-mythos-5-1", "claude-fable-5", "claude-mythos-5", "claude-opus-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-opus-4-5-20251101", "claude-sonnet-5", "claude-sonnet-4-6", "claude-sonnet-4-5-20250929" ], "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Web fetch tool (web_fetch_20250910)", "type": "web_fetch_20250910", "category": "server", "description": "Basic web fetch (text/HTML/PDF) executed by Anthropic. Only URLs already present in user messages, client tool results or prior search/fetch results can be fetched. ZDR-eligible. GA (no beta header) since 2026-02-17; launched in beta 2025-09-10 (web-fetch-2025-09-10).", "compatible_models": [ "claude-fable-5-1", "claude-opus-5", "claude-sonnet-5", "claude-fable-5", "claude-opus-4-8", "claude-opus-4-7", "claude-sonnet-4-6", "claude-opus-4-6", "claude-opus-4-5-20251101", "claude-haiku-4-5-20251001", "claude-sonnet-4-5-20250929", "claude-mythos-5-1", "claude-mythos-5" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "web_fetch_20250910" }, "name": { "const": "web_fetch" }, "max_uses": { "type": "integer", "exclusiveMinimum": 0, "description": "No default limit; failed fetches count" }, "allowed_domains": { "type": "array", "items": { "type": "string" }, "description": "domain-only matching (paths never match)" }, "blocked_domains": { "type": "array", "items": { "type": "string" } }, "citations": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false } } }, "max_content_tokens": { "type": "integer", "exclusiveMinimum": 0, "description": "approximate cap on text content (not PDFs); live 400 for 0" }, "url_sources": { "type": "object", "description": "Which sources make URLs fetchable: user_input: all|none; client_tool_results / server_tool_results: all|none|only{tools:[{type:tool_reference,name}]}|except{tools}" }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])." } } }, "tool_choice_support": "auto", "parallel": "server-side loop (pause_turn); mixed with client tools -> deferred until tool_result returned", "streaming_events": [ "content_block_start server_tool_use", "input_json_delta (url)", "content_block_start web_fetch_tool_result (whole)" ], "result_shape": { "server_tool_use": { "type": "server_tool_use", "id": "srvtoolu_…", "name": "web_fetch", "input": { "url": "https://…" } }, "web_fetch_tool_result": { "type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_…", "content": { "type": "web_fetch_result", "url": "…", "retrieved_at": "ISO-8601", "content": { "type": "document", "source": { "type": "text|base64", "media_type": "text/plain|application/pdf", "data": "…" }, "title": "…", "citations": { "enabled": true } } }, "caller": { "type": "direct" } }, "error": { "type": "web_fetch_tool_result", "tool_use_id": "…", "content": { "type": "web_fetch_tool_result_error", "error_code": "url_not_in_prior_context" }, "caller": { "type": "direct" } }, "citations": { "type": "char_location", "document_index": 0, "document_title": "…", "start_char_index": 0, "end_char_index": 0, "cited_text": "…" }, "usage": { "server_tool_use": { "web_search_requests": 0, "web_fetch_requests": 1 } }, "error_codes": [ "invalid_tool_input", "url_too_long (250 chars)", "url_not_allowed", "url_not_in_prior_context", "url_not_accessible", "too_many_requests", "unsupported_content_type", "max_uses_exceeded", "unavailable" ], "live_note": "d1/k21: the web_fetch_tool_result block carried caller:{type:direct} (not shown in docs example)" }, "billing": "No per-call charge; tokens of fetched content only (~2,500 tokens per 10 kB page; 500 kB PDF ≈125k tokens). usage.server_tool_use.web_fetch_requests counts fetches. Live d1: 3,319 input tokens for example.com.", "limitations": [ "No JavaScript rendering", "URL max 250 chars", "Only text, HTML, PDF", "Not on Bedrock/Vertex; Foundry-on-Azure only basic version", "Org-level domain settings apply" ], "security": [ "Data exfiltration risk: URLs only from prior context; restrict with allowed_domains/max_uses; publishers may log URL parameters" ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/web-fetch/web_fetch.sh", "python": "examples/anthropic/web-fetch/web_fetch.py", "typescript": "examples/anthropic/web-fetch/web_fetch.ts" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "d1 (haiku, example.com, citations enabled): server_tool_use + web_fetch_tool_result{web_fetch_result, document text/plain, title 'Example Domain', retrieved_at} + usage.server_tool_use.web_fetch_requests=1; k21: url_not_in_prior_context error block; k29 max_content_tokens 0 -> 400" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "name_constraint": "name must be 'web_fetch'", "dynamic_filtering_models": [], "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Web fetch tool (web_fetch_20260209)", "type": "web_fetch_20260209", "category": "server", "description": "Adds dynamic filtering (code execution provisioned automatically; allowed_callers default [\"code_execution_20260120\"]). Not ZDR-eligible by default.", "compatible_models": [ "claude-fable-5-1", "claude-opus-5", "claude-sonnet-5", "claude-fable-5", "claude-opus-4-8", "claude-opus-4-7", "claude-sonnet-4-6", "claude-opus-4-6", "claude-opus-4-5-20251101", "claude-haiku-4-5-20251001", "claude-sonnet-4-5-20250929", "claude-mythos-5-1", "claude-mythos-5" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "web_fetch_20260209" }, "name": { "const": "web_fetch" }, "max_uses": { "type": "integer", "exclusiveMinimum": 0, "description": "No default limit; failed fetches count" }, "allowed_domains": { "type": "array", "items": { "type": "string" }, "description": "domain-only matching (paths never match)" }, "blocked_domains": { "type": "array", "items": { "type": "string" } }, "citations": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false } } }, "max_content_tokens": { "type": "integer", "exclusiveMinimum": 0, "description": "approximate cap on text content (not PDFs); live 400 for 0" }, "url_sources": { "type": "object", "description": "Which sources make URLs fetchable: user_input: all|none; client_tool_results / server_tool_results: all|none|only{tools:[{type:tool_reference,name}]}|except{tools}" }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"]).", "default": [ "code_execution_20260120" ] } } }, "tool_choice_support": "auto", "parallel": "server-side loop (pause_turn); mixed with client tools -> deferred until tool_result returned", "streaming_events": [ "content_block_start server_tool_use", "input_json_delta (url)", "content_block_start web_fetch_tool_result (whole)" ], "result_shape": { "server_tool_use": { "type": "server_tool_use", "id": "srvtoolu_…", "name": "web_fetch", "input": { "url": "https://…" } }, "web_fetch_tool_result": { "type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_…", "content": { "type": "web_fetch_result", "url": "…", "retrieved_at": "ISO-8601", "content": { "type": "document", "source": { "type": "text|base64", "media_type": "text/plain|application/pdf", "data": "…" }, "title": "…", "citations": { "enabled": true } } }, "caller": { "type": "direct" } }, "error": { "type": "web_fetch_tool_result", "tool_use_id": "…", "content": { "type": "web_fetch_tool_result_error", "error_code": "url_not_in_prior_context" }, "caller": { "type": "direct" } }, "citations": { "type": "char_location", "document_index": 0, "document_title": "…", "start_char_index": 0, "end_char_index": 0, "cited_text": "…" }, "usage": { "server_tool_use": { "web_search_requests": 0, "web_fetch_requests": 1 } }, "error_codes": [ "invalid_tool_input", "url_too_long (250 chars)", "url_not_allowed", "url_not_in_prior_context", "url_not_accessible", "too_many_requests", "unsupported_content_type", "max_uses_exceeded", "unavailable" ], "live_note": "d1/k21: the web_fetch_tool_result block carried caller:{type:direct} (not shown in docs example)" }, "billing": "No per-call charge; tokens of fetched content only (~2,500 tokens per 10 kB page; 500 kB PDF ≈125k tokens). usage.server_tool_use.web_fetch_requests counts fetches. Live d1: 3,319 input tokens for example.com.", "limitations": [ "No JavaScript rendering", "URL max 250 chars", "Only text, HTML, PDF", "Not on Bedrock/Vertex; Foundry-on-Azure only basic version", "Org-level domain settings apply" ], "security": [ "Data exfiltration risk: URLs only from prior context; restrict with allowed_domains/max_uses; publishers may log URL parameters" ], "beta_header": null, "status": [ "DOCUMENTED" ], "examples": { "curl": "examples/anthropic/web-fetch/web_fetch.sh", "python": "examples/anthropic/web-fetch/web_fetch.py", "typescript": "examples/anthropic/web-fetch/web_fetch.ts" }, "verification": { "method": "docs_only", "verified_at": "2026-09-18", "result": "success", "http_status": null, "request_note": "not exercised live in this run" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "name_constraint": "name must be 'web_fetch'", "dynamic_filtering_models": [ "claude-fable-5-1", "claude-mythos-5-1", "claude-fable-5", "claude-mythos-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-5", "claude-sonnet-4-6" ], "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Web fetch tool (web_fetch_20260309)", "type": "web_fetch_20260309", "category": "server", "description": "Adds use_cache (cache bypass).", "compatible_models": [ "claude-fable-5-1", "claude-opus-5", "claude-sonnet-5", "claude-fable-5", "claude-opus-4-8", "claude-opus-4-7", "claude-sonnet-4-6", "claude-opus-4-6", "claude-opus-4-5-20251101", "claude-haiku-4-5-20251001", "claude-sonnet-4-5-20250929", "claude-mythos-5-1", "claude-mythos-5" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "web_fetch_20260309" }, "name": { "const": "web_fetch" }, "max_uses": { "type": "integer", "exclusiveMinimum": 0, "description": "No default limit; failed fetches count" }, "allowed_domains": { "type": "array", "items": { "type": "string" }, "description": "domain-only matching (paths never match)" }, "blocked_domains": { "type": "array", "items": { "type": "string" } }, "citations": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false } } }, "max_content_tokens": { "type": "integer", "exclusiveMinimum": 0, "description": "approximate cap on text content (not PDFs); live 400 for 0" }, "url_sources": { "type": "object", "description": "Which sources make URLs fetchable: user_input: all|none; client_tool_results / server_tool_results: all|none|only{tools:[{type:tool_reference,name}]}|except{tools}" }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"]).", "default": [ "code_execution_20260120" ] }, "use_cache": { "type": "boolean", "default": true, "description": "false bypasses the fetch cache (slower)" } } }, "tool_choice_support": "auto", "parallel": "server-side loop (pause_turn); mixed with client tools -> deferred until tool_result returned", "streaming_events": [ "content_block_start server_tool_use", "input_json_delta (url)", "content_block_start web_fetch_tool_result (whole)" ], "result_shape": { "server_tool_use": { "type": "server_tool_use", "id": "srvtoolu_…", "name": "web_fetch", "input": { "url": "https://…" } }, "web_fetch_tool_result": { "type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_…", "content": { "type": "web_fetch_result", "url": "…", "retrieved_at": "ISO-8601", "content": { "type": "document", "source": { "type": "text|base64", "media_type": "text/plain|application/pdf", "data": "…" }, "title": "…", "citations": { "enabled": true } } }, "caller": { "type": "direct" } }, "error": { "type": "web_fetch_tool_result", "tool_use_id": "…", "content": { "type": "web_fetch_tool_result_error", "error_code": "url_not_in_prior_context" }, "caller": { "type": "direct" } }, "citations": { "type": "char_location", "document_index": 0, "document_title": "…", "start_char_index": 0, "end_char_index": 0, "cited_text": "…" }, "usage": { "server_tool_use": { "web_search_requests": 0, "web_fetch_requests": 1 } }, "error_codes": [ "invalid_tool_input", "url_too_long (250 chars)", "url_not_allowed", "url_not_in_prior_context", "url_not_accessible", "too_many_requests", "unsupported_content_type", "max_uses_exceeded", "unavailable" ], "live_note": "d1/k21: the web_fetch_tool_result block carried caller:{type:direct} (not shown in docs example)" }, "billing": "No per-call charge; tokens of fetched content only (~2,500 tokens per 10 kB page; 500 kB PDF ≈125k tokens). usage.server_tool_use.web_fetch_requests counts fetches. Live d1: 3,319 input tokens for example.com.", "limitations": [ "No JavaScript rendering", "URL max 250 chars", "Only text, HTML, PDF", "Not on Bedrock/Vertex; Foundry-on-Azure only basic version", "Org-level domain settings apply" ], "security": [ "Data exfiltration risk: URLs only from prior context; restrict with allowed_domains/max_uses; publishers may log URL parameters" ], "beta_header": null, "status": [ "DOCUMENTED" ], "examples": { "curl": "examples/anthropic/web-fetch/web_fetch.sh", "python": "examples/anthropic/web-fetch/web_fetch.py", "typescript": "examples/anthropic/web-fetch/web_fetch.ts" }, "verification": { "method": "docs_only", "verified_at": "2026-09-18", "result": "success", "http_status": null, "request_note": "not exercised live in this run" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "name_constraint": "name must be 'web_fetch'", "dynamic_filtering_models": [ "claude-fable-5-1", "claude-mythos-5-1", "claude-fable-5", "claude-mythos-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-5", "claude-sonnet-4-6" ], "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Web fetch tool (web_fetch_20260318)", "type": "web_fetch_20260318", "category": "server", "description": "Adds response_inclusion. Released 2026-06-11. Live: accepted on haiku with allowed_callers:[\"direct\"], response_inclusion:excluded, use_cache:false (k30, 200).", "compatible_models": [ "claude-fable-5-1", "claude-opus-5", "claude-sonnet-5", "claude-fable-5", "claude-opus-4-8", "claude-opus-4-7", "claude-sonnet-4-6", "claude-opus-4-6", "claude-opus-4-5-20251101", "claude-haiku-4-5-20251001", "claude-sonnet-4-5-20250929", "claude-mythos-5-1", "claude-mythos-5" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "web_fetch_20260318" }, "name": { "const": "web_fetch" }, "max_uses": { "type": "integer", "exclusiveMinimum": 0, "description": "No default limit; failed fetches count" }, "allowed_domains": { "type": "array", "items": { "type": "string" }, "description": "domain-only matching (paths never match)" }, "blocked_domains": { "type": "array", "items": { "type": "string" } }, "citations": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false } } }, "max_content_tokens": { "type": "integer", "exclusiveMinimum": 0, "description": "approximate cap on text content (not PDFs); live 400 for 0" }, "url_sources": { "type": "object", "description": "Which sources make URLs fetchable: user_input: all|none; client_tool_results / server_tool_results: all|none|only{tools:[{type:tool_reference,name}]}|except{tools}" }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"]).", "default": [ "code_execution_20260120" ] }, "use_cache": { "type": "boolean", "default": true }, "response_inclusion": { "enum": [ "full", "excluded" ], "default": "full" } } }, "tool_choice_support": "auto", "parallel": "server-side loop (pause_turn); mixed with client tools -> deferred until tool_result returned", "streaming_events": [ "content_block_start server_tool_use", "input_json_delta (url)", "content_block_start web_fetch_tool_result (whole)" ], "result_shape": { "server_tool_use": { "type": "server_tool_use", "id": "srvtoolu_…", "name": "web_fetch", "input": { "url": "https://…" } }, "web_fetch_tool_result": { "type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_…", "content": { "type": "web_fetch_result", "url": "…", "retrieved_at": "ISO-8601", "content": { "type": "document", "source": { "type": "text|base64", "media_type": "text/plain|application/pdf", "data": "…" }, "title": "…", "citations": { "enabled": true } } }, "caller": { "type": "direct" } }, "error": { "type": "web_fetch_tool_result", "tool_use_id": "…", "content": { "type": "web_fetch_tool_result_error", "error_code": "url_not_in_prior_context" }, "caller": { "type": "direct" } }, "citations": { "type": "char_location", "document_index": 0, "document_title": "…", "start_char_index": 0, "end_char_index": 0, "cited_text": "…" }, "usage": { "server_tool_use": { "web_search_requests": 0, "web_fetch_requests": 1 } }, "error_codes": [ "invalid_tool_input", "url_too_long (250 chars)", "url_not_allowed", "url_not_in_prior_context", "url_not_accessible", "too_many_requests", "unsupported_content_type", "max_uses_exceeded", "unavailable" ], "live_note": "d1/k21: the web_fetch_tool_result block carried caller:{type:direct} (not shown in docs example)" }, "billing": "No per-call charge; tokens of fetched content only (~2,500 tokens per 10 kB page; 500 kB PDF ≈125k tokens). usage.server_tool_use.web_fetch_requests counts fetches. Live d1: 3,319 input tokens for example.com.", "limitations": [ "No JavaScript rendering", "URL max 250 chars", "Only text, HTML, PDF", "Not on Bedrock/Vertex; Foundry-on-Azure only basic version", "Org-level domain settings apply" ], "security": [ "Data exfiltration risk: URLs only from prior context; restrict with allowed_domains/max_uses; publishers may log URL parameters" ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/web-fetch/web_fetch.sh", "python": "examples/anthropic/web-fetch/web_fetch.py", "typescript": "examples/anthropic/web-fetch/web_fetch.ts" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "k30_web_fetch_20260318_direct_haiku 200 (no fetch performed)" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "name_constraint": "name must be 'web_fetch'", "dynamic_filtering_models": [ "claude-fable-5-1", "claude-mythos-5-1", "claude-fable-5", "claude-mythos-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-5", "claude-sonnet-4-6" ], "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Code execution tool (code_execution_20250825)", "type": "code_execution_20250825", "category": "server", "description": "Sandboxed container (Python 3.11, Linux x86_64, 1 CPU, 5 GiB RAM, 5 GiB disk, no internet). Exposes sub-tools bash_code_execution and text_editor_code_execution. Files in via container_upload blocks (Files API), out via $OUTPUT_DIR -> file_id entries. Container reuse via top-level `container`; 30-day expiry, checkpoint after ~5 min idle. No beta header (GA 2026-02-17; legacy header code-execution-2025-08-25 still accepted).", "compatible_models": [ "claude-fable-5-1", "claude-mythos-5-1", "claude-fable-5", "claude-mythos-5", "claude-opus-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-opus-4-5-20251101", "claude-sonnet-5", "claude-sonnet-4-6", "claude-sonnet-4-5-20250929", "claude-haiku-4-5-20251001" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "code_execution_20250825" }, "name": { "const": "code_execution" }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])." } }, "request_level": { "container": "string container id | {id?, skills?: [{type: anthropic|custom, skill_id, version}] (max 20 skills)}", "messages[].content[] container_upload": { "type": "container_upload", "file_id": "file_… (Files API)" } } }, "tool_choice_support": "auto", "parallel": "server-side loop; pause_turn possible; mixed with client tools -> result deferred", "streaming_events": [ "content_block_start server_tool_use (bash_code_execution / text_editor_code_execution / code_execution)", "input_json_delta", "result block arrives whole in one content_block_start" ], "result_shape": { "server_tool_use (bash)": { "type": "server_tool_use", "id": "srvtoolu_…", "name": "bash_code_execution", "input": { "command": "python3 -c \"print(2+2)\"" } }, "bash_code_execution_tool_result": { "type": "bash_code_execution_tool_result", "tool_use_id": "srvtoolu_…", "content": { "type": "bash_code_execution_result", "stdout": "4\n", "stderr": "", "return_code": 0, "content": [ { "type": "code_execution_output", "file_id": "file_…" } ] } }, "server_tool_use (editor)": { "type": "server_tool_use", "name": "text_editor_code_execution", "input": { "command": "view|create|str_replace", "path": "…", "file_text": "…", "old_str": "…", "new_str": "…" } }, "text_editor_code_execution_tool_result": { "content": "text_editor_code_execution_view_result{file_type,content,num_lines,start_line,total_lines} | text_editor_code_execution_create_result{is_file_update} | text_editor_code_execution_str_replace_result{old_start,old_lines,new_start,new_lines,lines[]}" }, "server_tool_use (PTC python cell)": { "type": "server_tool_use", "name": "code_execution", "input": { "code": "python source" } }, "code_execution_tool_result": { "type": "code_execution_tool_result", "tool_use_id": "srvtoolu_…", "content": { "type": "code_execution_result", "stdout": "…", "stderr": "…", "return_code": 0, "content": [], "abort_reason": null } }, "errors": { "type": "*_tool_result_error", "error_code": [ "unavailable", "execution_time_exceeded", "invalid_tool_input", "too_many_requests", "output_file_too_large (bash)", "file_not_found (text_editor)" ] }, "top_level container": { "id": "container_…", "expires_at": "ISO-8601 (rolling, ~5h ahead live)", "skills": "[…] when skills loaded" }, "live_note": "e1/e2/e3 (haiku): usage.server_tool_use had web_search_requests/web_fetch_requests only — no code_execution_requests field despite docs; g2 (sonnet 4.6 PTC): code_execution_result carried undocumented abort_reason:null" }, "billing": "Free when web_search_20260209+/web_fetch_20260209+ is in the request. Otherwise billed per container-hour: 5-minute minimum per session, 1,550 free hours/org/month, then $0.05/hour/container; files preloaded bill time even if the tool is not called. Tokens as usual (live e1: 4,611 input tokens on haiku for a one-line prompt).", "limitations": [ "No internet in the sandbox; only pre-installed libs (pandas, numpy, scipy, sklearn, statsmodels, matplotlib, seaborn, pyarrow, openpyxl, pillow, python-docx/pptx, pypdf, sympy…)", "Not on Bedrock/Vertex; Foundry requires Hosted-on-Anthropic", "Not ZDR-eligible; container data retained up to 30 days", "Haiku 4.5: no PTC / REPL persistence" ], "security": [ "Isolated container; outputs (files) carry C2PA credentials for media", "Distinguish from client bash tool in system prompt (separate environments)" ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/code-execution/code_execution.sh", "python": "examples/anthropic/code-execution/code_execution.py", "typescript": "examples/anthropic/code-execution/code_execution.ts" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "e1 (haiku): bash_code_execution + bash_code_execution_tool_result stdout '4', container{id,expires_at}; e2 reused same container id (expires_at advanced); k25 name 'code' -> 400 \"Input should be 'code_execution'\"" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/build-with-claude/skills-guide", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/release-notes/api", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "name_constraint": "name must be 'code_execution'", "sub_tools": [ "bash_code_execution", "text_editor_code_execution", "code_execution (PTC Python cell, 20260120+)" ], "internal_type_ids_seen_live": [ "bash_code_execution_20250825", "text_editor_code_execution_20250825", "python_with_tools_code_execution_20250825", "python_with_tools_code_execution_20260120", "python_with_tools_code_execution_20260521" ], "internal_type_ids_note": "Listed in the per-model 'Did you mean' 400 message (h5/k15/k17) but rejected as request tool types by the schema (k11/k12/k12b 400) — internal identifiers only. LIVE_DISCOVERED.", "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Code execution tool (code_execution_20260120)", "type": "code_execution_20260120", "category": "server", "description": "Same runtime + REPL state persistence across container reuse + programmatic tool calling (allowed_callers on other tools; Python cells as server_tool_use name code_execution with input.code). Required minimum for web_search/web_fetch _20260209+. On Haiku 4.5 behaves like 20250825.", "compatible_models": [ "claude-fable-5-1", "claude-mythos-5-1", "claude-fable-5", "claude-mythos-5", "claude-opus-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-opus-4-5-20251101", "claude-sonnet-5", "claude-sonnet-4-6", "claude-sonnet-4-5-20250929", "claude-haiku-4-5-20251001" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "code_execution_20260120" }, "name": { "const": "code_execution" }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])." } }, "request_level": { "container": "string container id | {id?, skills?: [{type: anthropic|custom, skill_id, version}] (max 20 skills)}", "messages[].content[] container_upload": { "type": "container_upload", "file_id": "file_… (Files API)" } } }, "tool_choice_support": "auto", "parallel": "server-side loop; pause_turn possible; mixed with client tools -> result deferred", "streaming_events": [ "content_block_start server_tool_use (bash_code_execution / text_editor_code_execution / code_execution)", "input_json_delta", "result block arrives whole in one content_block_start" ], "result_shape": { "server_tool_use (bash)": { "type": "server_tool_use", "id": "srvtoolu_…", "name": "bash_code_execution", "input": { "command": "python3 -c \"print(2+2)\"" } }, "bash_code_execution_tool_result": { "type": "bash_code_execution_tool_result", "tool_use_id": "srvtoolu_…", "content": { "type": "bash_code_execution_result", "stdout": "4\n", "stderr": "", "return_code": 0, "content": [ { "type": "code_execution_output", "file_id": "file_…" } ] } }, "server_tool_use (editor)": { "type": "server_tool_use", "name": "text_editor_code_execution", "input": { "command": "view|create|str_replace", "path": "…", "file_text": "…", "old_str": "…", "new_str": "…" } }, "text_editor_code_execution_tool_result": { "content": "text_editor_code_execution_view_result{file_type,content,num_lines,start_line,total_lines} | text_editor_code_execution_create_result{is_file_update} | text_editor_code_execution_str_replace_result{old_start,old_lines,new_start,new_lines,lines[]}" }, "server_tool_use (PTC python cell)": { "type": "server_tool_use", "name": "code_execution", "input": { "code": "python source" } }, "code_execution_tool_result": { "type": "code_execution_tool_result", "tool_use_id": "srvtoolu_…", "content": { "type": "code_execution_result", "stdout": "…", "stderr": "…", "return_code": 0, "content": [], "abort_reason": null } }, "errors": { "type": "*_tool_result_error", "error_code": [ "unavailable", "execution_time_exceeded", "invalid_tool_input", "too_many_requests", "output_file_too_large (bash)", "file_not_found (text_editor)" ] }, "top_level container": { "id": "container_…", "expires_at": "ISO-8601 (rolling, ~5h ahead live)", "skills": "[…] when skills loaded" }, "live_note": "e1/e2/e3 (haiku): usage.server_tool_use had web_search_requests/web_fetch_requests only — no code_execution_requests field despite docs; g2 (sonnet 4.6 PTC): code_execution_result carried undocumented abort_reason:null" }, "billing": "Free when web_search_20260209+/web_fetch_20260209+ is in the request. Otherwise billed per container-hour: 5-minute minimum per session, 1,550 free hours/org/month, then $0.05/hour/container; files preloaded bill time even if the tool is not called. Tokens as usual (live e1: 4,611 input tokens on haiku for a one-line prompt).", "limitations": [ "No internet in the sandbox; only pre-installed libs (pandas, numpy, scipy, sklearn, statsmodels, matplotlib, seaborn, pyarrow, openpyxl, pillow, python-docx/pptx, pypdf, sympy…)", "Not on Bedrock/Vertex; Foundry requires Hosted-on-Anthropic", "Not ZDR-eligible; container data retained up to 30 days", "Haiku 4.5: no PTC / REPL persistence" ], "security": [ "Isolated container; outputs (files) carry C2PA credentials for media", "Distinguish from client bash tool in system prompt (separate environments)" ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/code-execution/code_execution.sh", "python": "examples/anthropic/code-execution/code_execution.py", "typescript": "examples/anthropic/code-execution/code_execution.ts" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "g1/g2 on claude-sonnet-4-6: server_tool_use{name:code_execution,input:{code}} + tool_use{caller:{type:code_execution_20260120,tool_id}} -> after tool_result: code_execution_tool_result{code_execution_result stdout}" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/build-with-claude/skills-guide", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/release-notes/api", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "name_constraint": "name must be 'code_execution'", "sub_tools": [ "bash_code_execution", "text_editor_code_execution", "code_execution (PTC Python cell, 20260120+)" ], "internal_type_ids_seen_live": [ "bash_code_execution_20250825", "text_editor_code_execution_20250825", "python_with_tools_code_execution_20250825", "python_with_tools_code_execution_20260120", "python_with_tools_code_execution_20260521" ], "internal_type_ids_note": "Listed in the per-model 'Did you mean' 400 message (h5/k15/k17) but rejected as request tool types by the schema (k11/k12/k12b 400) — internal identifiers only. LIVE_DISCOVERED.", "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Code execution tool (code_execution_20260521)", "type": "code_execution_20260521", "category": "server", "description": "Same runtime as 20260120; tool description discloses the 90 s wall-clock limit per Python cell (detection_timeout status in output). Released 2026-06-11.", "compatible_models": [ "claude-fable-5-1", "claude-mythos-5-1", "claude-fable-5", "claude-mythos-5", "claude-opus-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-opus-4-5-20251101", "claude-sonnet-5", "claude-sonnet-4-6", "claude-sonnet-4-5-20250929", "claude-haiku-4-5-20251001" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "code_execution_20260521" }, "name": { "const": "code_execution" }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])." } }, "request_level": { "container": "string container id | {id?, skills?: [{type: anthropic|custom, skill_id, version}] (max 20 skills)}", "messages[].content[] container_upload": { "type": "container_upload", "file_id": "file_… (Files API)" } } }, "tool_choice_support": "auto", "parallel": "server-side loop; pause_turn possible; mixed with client tools -> result deferred", "streaming_events": [ "content_block_start server_tool_use (bash_code_execution / text_editor_code_execution / code_execution)", "input_json_delta", "result block arrives whole in one content_block_start" ], "result_shape": { "server_tool_use (bash)": { "type": "server_tool_use", "id": "srvtoolu_…", "name": "bash_code_execution", "input": { "command": "python3 -c \"print(2+2)\"" } }, "bash_code_execution_tool_result": { "type": "bash_code_execution_tool_result", "tool_use_id": "srvtoolu_…", "content": { "type": "bash_code_execution_result", "stdout": "4\n", "stderr": "", "return_code": 0, "content": [ { "type": "code_execution_output", "file_id": "file_…" } ] } }, "server_tool_use (editor)": { "type": "server_tool_use", "name": "text_editor_code_execution", "input": { "command": "view|create|str_replace", "path": "…", "file_text": "…", "old_str": "…", "new_str": "…" } }, "text_editor_code_execution_tool_result": { "content": "text_editor_code_execution_view_result{file_type,content,num_lines,start_line,total_lines} | text_editor_code_execution_create_result{is_file_update} | text_editor_code_execution_str_replace_result{old_start,old_lines,new_start,new_lines,lines[]}" }, "server_tool_use (PTC python cell)": { "type": "server_tool_use", "name": "code_execution", "input": { "code": "python source" } }, "code_execution_tool_result": { "type": "code_execution_tool_result", "tool_use_id": "srvtoolu_…", "content": { "type": "code_execution_result", "stdout": "…", "stderr": "…", "return_code": 0, "content": [], "abort_reason": null } }, "errors": { "type": "*_tool_result_error", "error_code": [ "unavailable", "execution_time_exceeded", "invalid_tool_input", "too_many_requests", "output_file_too_large (bash)", "file_not_found (text_editor)" ] }, "top_level container": { "id": "container_…", "expires_at": "ISO-8601 (rolling, ~5h ahead live)", "skills": "[…] when skills loaded" }, "live_note": "e1/e2/e3 (haiku): usage.server_tool_use had web_search_requests/web_fetch_requests only — no code_execution_requests field despite docs; g2 (sonnet 4.6 PTC): code_execution_result carried undocumented abort_reason:null" }, "billing": "Free when web_search_20260209+/web_fetch_20260209+ is in the request. Otherwise billed per container-hour: 5-minute minimum per session, 1,550 free hours/org/month, then $0.05/hour/container; files preloaded bill time even if the tool is not called. Tokens as usual (live e1: 4,611 input tokens on haiku for a one-line prompt).", "limitations": [ "No internet in the sandbox; only pre-installed libs (pandas, numpy, scipy, sklearn, statsmodels, matplotlib, seaborn, pyarrow, openpyxl, pillow, python-docx/pptx, pypdf, sympy…)", "Not on Bedrock/Vertex; Foundry requires Hosted-on-Anthropic", "Not ZDR-eligible; container data retained up to 30 days", "Haiku 4.5: no PTC / REPL persistence" ], "security": [ "Isolated container; outputs (files) carry C2PA credentials for media", "Distinguish from client bash tool in system prompt (separate environments)" ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/code-execution/code_execution.sh", "python": "examples/anthropic/code-execution/code_execution.py", "typescript": "examples/anthropic/code-execution/code_execution.ts" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "e3 (haiku): accepted; bash_code_execution ran print(3*3) -> '9'" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/build-with-claude/skills-guide", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/release-notes/api", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "name_constraint": "name must be 'code_execution'", "sub_tools": [ "bash_code_execution", "text_editor_code_execution", "code_execution (PTC Python cell, 20260120+)" ], "internal_type_ids_seen_live": [ "bash_code_execution_20250825", "text_editor_code_execution_20250825", "python_with_tools_code_execution_20250825", "python_with_tools_code_execution_20260120", "python_with_tools_code_execution_20260521" ], "internal_type_ids_note": "Listed in the per-model 'Did you mean' 400 message (h5/k15/k17) but rejected as request tool types by the schema (k11/k12/k12b 400) — internal identifiers only. LIVE_DISCOVERED.", "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Code execution tool (code_execution_20250522)", "type": "code_execution_20250522", "category": "server", "description": "Legacy Python-only version (beta header code-execution-2025-05-22); result type code_execution_result. Still accepted by the GA schema (live tag list) but docs say migrate.", "compatible_models": [ "claude-fable-5-1", "claude-mythos-5-1", "claude-fable-5", "claude-mythos-5", "claude-opus-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-opus-4-5-20251101", "claude-sonnet-5", "claude-sonnet-4-6", "claude-sonnet-4-5-20250929", "claude-haiku-4-5-20251001" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "const": "code_execution_20250522" }, "name": { "const": "code_execution" }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])." } }, "request_level": { "container": "string container id | {id?, skills?: [{type: anthropic|custom, skill_id, version}] (max 20 skills)}", "messages[].content[] container_upload": { "type": "container_upload", "file_id": "file_… (Files API)" } } }, "tool_choice_support": "auto", "parallel": "server-side loop; pause_turn possible; mixed with client tools -> result deferred", "streaming_events": [ "content_block_start server_tool_use (bash_code_execution / text_editor_code_execution / code_execution)", "input_json_delta", "result block arrives whole in one content_block_start" ], "result_shape": { "server_tool_use (bash)": { "type": "server_tool_use", "id": "srvtoolu_…", "name": "bash_code_execution", "input": { "command": "python3 -c \"print(2+2)\"" } }, "bash_code_execution_tool_result": { "type": "bash_code_execution_tool_result", "tool_use_id": "srvtoolu_…", "content": { "type": "bash_code_execution_result", "stdout": "4\n", "stderr": "", "return_code": 0, "content": [ { "type": "code_execution_output", "file_id": "file_…" } ] } }, "server_tool_use (editor)": { "type": "server_tool_use", "name": "text_editor_code_execution", "input": { "command": "view|create|str_replace", "path": "…", "file_text": "…", "old_str": "…", "new_str": "…" } }, "text_editor_code_execution_tool_result": { "content": "text_editor_code_execution_view_result{file_type,content,num_lines,start_line,total_lines} | text_editor_code_execution_create_result{is_file_update} | text_editor_code_execution_str_replace_result{old_start,old_lines,new_start,new_lines,lines[]}" }, "server_tool_use (PTC python cell)": { "type": "server_tool_use", "name": "code_execution", "input": { "code": "python source" } }, "code_execution_tool_result": { "type": "code_execution_tool_result", "tool_use_id": "srvtoolu_…", "content": { "type": "code_execution_result", "stdout": "…", "stderr": "…", "return_code": 0, "content": [], "abort_reason": null } }, "errors": { "type": "*_tool_result_error", "error_code": [ "unavailable", "execution_time_exceeded", "invalid_tool_input", "too_many_requests", "output_file_too_large (bash)", "file_not_found (text_editor)" ] }, "top_level container": { "id": "container_…", "expires_at": "ISO-8601 (rolling, ~5h ahead live)", "skills": "[…] when skills loaded" }, "live_note": "e1/e2/e3 (haiku): usage.server_tool_use had web_search_requests/web_fetch_requests only — no code_execution_requests field despite docs; g2 (sonnet 4.6 PTC): code_execution_result carried undocumented abort_reason:null" }, "billing": "Free when web_search_20260209+/web_fetch_20260209+ is in the request. Otherwise billed per container-hour: 5-minute minimum per session, 1,550 free hours/org/month, then $0.05/hour/container; files preloaded bill time even if the tool is not called. Tokens as usual (live e1: 4,611 input tokens on haiku for a one-line prompt).", "limitations": [ "No internet in the sandbox; only pre-installed libs (pandas, numpy, scipy, sklearn, statsmodels, matplotlib, seaborn, pyarrow, openpyxl, pillow, python-docx/pptx, pypdf, sympy…)", "Not on Bedrock/Vertex; Foundry requires Hosted-on-Anthropic", "Not ZDR-eligible; container data retained up to 30 days", "Haiku 4.5: no PTC / REPL persistence" ], "security": [ "Isolated container; outputs (files) carry C2PA credentials for media", "Distinguish from client bash tool in system prompt (separate environments)" ], "beta_header": null, "status": [ "DOCUMENTED", "LEGACY" ], "examples": { "curl": "examples/anthropic/code-execution/code_execution.sh", "python": "examples/anthropic/code-execution/code_execution.py", "typescript": "examples/anthropic/code-execution/code_execution.ts" }, "verification": { "method": "sdk_types", "verified_at": "2026-09-18", "result": "success", "http_status": null, "request_note": "type string present in sources/anthropic/openapi/{python,node}-sdk-api.md" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/build-with-claude/skills-guide", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/release-notes/api", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "name_constraint": "name must be 'code_execution'", "sub_tools": [ "bash_code_execution", "text_editor_code_execution", "code_execution (PTC Python cell, 20260120+)" ], "internal_type_ids_seen_live": [ "bash_code_execution_20250825", "text_editor_code_execution_20250825", "python_with_tools_code_execution_20250825", "python_with_tools_code_execution_20260120", "python_with_tools_code_execution_20260521" ], "internal_type_ids_note": "Listed in the per-model 'Did you mean' 400 message (h5/k15/k17) but rejected as request tool types by the schema (k11/k12/k12b 400) — internal identifiers only. LIVE_DISCOVERED.", "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Tool search tool (tool_search_tool_regex)", "type": "tool_search_tool_regex_20251119", "category": "server", "description": "Server tool that discovers deferred tools (defer_loading:true) and expands them inline as tool_reference blocks (prompt cache preserved). Claude writes Python re.search() patterns (case-insensitive, <=200 chars) over tool names/descriptions/argument names+descriptions. Default 5 results, Claude may set limit 1-10,000. Undated alias `tool_search_tool_regex` accepted as type (live f3, 200). GA since 2026-02-17 (beta 2025-11-24, header advanced-tool-use-2025-11-20).", "compatible_models": [ "claude-fable-5-1", "claude-mythos-5-1", "claude-fable-5", "claude-mythos-5", "claude-opus-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-4-6", "claude-opus-4-5-20251101", "claude-sonnet-4-5-20250929", "claude-haiku-4-5-20251001" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "enum": [ "tool_search_tool_regex_20251119", "tool_search_tool_regex" ] }, "name": { "const": "tool_search_tool_regex" }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])." } }, "constraints": [ "never set defer_loading:true on the search tool itself (400 'At least one tool must have defer_loading=false')", "deferred tool + cache_control -> 400 (live k23)", "max 10,000 deferred tools" ] }, "tool_choice_support": "auto", "parallel": "server-side; results expand automatically", "streaming_events": [ "server_tool_use start + input_json_delta (pattern/query/limit)", "tool_search_tool_result whole block" ], "result_shape": { "server_tool_use": { "type": "server_tool_use", "id": "srvtoolu_…", "name": "tool_search_tool_regex", "input": { "pattern": "weather", "limit": 10 } }, "tool_search_tool_result": { "type": "tool_search_tool_result", "tool_use_id": "srvtoolu_…", "content": { "type": "tool_search_tool_search_result", "tool_references": [ { "type": "tool_reference", "tool_name": "get_weather" } ] } }, "error": { "content": { "type": "tool_search_tool_result_error", "error_code": "invalid_tool_input|unavailable|too_many_requests|execution_time_exceeded", "error_message": "…" } }, "then": "tool_use for the discovered tool (execute + tool_result as usual). Never send a tool_result for the srvtoolu_ id (live k24: 400 'unexpected tool_use_id found in tool_result blocks').", "custom_search": { "type": "tool_result", "tool_use_id": "toolu_…", "content": [ { "type": "tool_reference", "tool_name": "…" } ] } }, "billing": "Not metered as a server tool (no usage.server_tool_use field); loaded definitions count as input tokens. Live f1: 1,635 input tokens with 6 deferred tools + search tool (vs 581 for one plain tool).", "limitations": [ "Sonnet 5 absent from the docs compatibility table (probably an omission — release notes say Sonnet 5 supports the same tools as Sonnet 4.6); Opus 4.1 and earlier unsupported", "Bedrock: InvokeModel only" ], "security": [], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/tools/tool-search/basic.sh", "python": "examples/anthropic/tools/tool-search/basic.py", "typescript": "examples/anthropic/tools/tool-search/basic.ts" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "f1 (haiku): pattern 'weather', limit 10 -> tool_reference get_weather -> tool_use get_weather" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "name_constraint": "name must be 'tool_search_tool_regex'", "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Tool search tool (tool_search_tool_bm25)", "type": "tool_search_tool_bm25_20251119", "category": "server", "description": "Server tool that discovers deferred tools (defer_loading:true) and expands them inline as tool_reference blocks (prompt cache preserved). Claude writes natural-language queries (<=500 chars); BM25 ranking. Default 5 results, Claude may set limit 1-10,000. Undated alias `tool_search_tool_bm25` accepted as type (live f3, 200). GA since 2026-02-17 (beta 2025-11-24, header advanced-tool-use-2025-11-20).", "compatible_models": [ "claude-fable-5-1", "claude-mythos-5-1", "claude-fable-5", "claude-mythos-5", "claude-opus-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-4-6", "claude-opus-4-5-20251101", "claude-sonnet-4-5-20250929", "claude-haiku-4-5-20251001" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "enum": [ "tool_search_tool_bm25_20251119", "tool_search_tool_bm25" ] }, "name": { "const": "tool_search_tool_bm25" }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])." } }, "constraints": [ "never set defer_loading:true on the search tool itself (400 'At least one tool must have defer_loading=false')", "deferred tool + cache_control -> 400 (live k23)", "max 10,000 deferred tools" ] }, "tool_choice_support": "auto", "parallel": "server-side; results expand automatically", "streaming_events": [ "server_tool_use start + input_json_delta (pattern/query/limit)", "tool_search_tool_result whole block" ], "result_shape": { "server_tool_use": { "type": "server_tool_use", "id": "srvtoolu_…", "name": "tool_search_tool_regex", "input": { "pattern": "weather", "limit": 10 } }, "tool_search_tool_result": { "type": "tool_search_tool_result", "tool_use_id": "srvtoolu_…", "content": { "type": "tool_search_tool_search_result", "tool_references": [ { "type": "tool_reference", "tool_name": "get_weather" } ] } }, "error": { "content": { "type": "tool_search_tool_result_error", "error_code": "invalid_tool_input|unavailable|too_many_requests|execution_time_exceeded", "error_message": "…" } }, "then": "tool_use for the discovered tool (execute + tool_result as usual). Never send a tool_result for the srvtoolu_ id (live k24: 400 'unexpected tool_use_id found in tool_result blocks').", "custom_search": { "type": "tool_result", "tool_use_id": "toolu_…", "content": [ { "type": "tool_reference", "tool_name": "…" } ] } }, "billing": "Not metered as a server tool (no usage.server_tool_use field); loaded definitions count as input tokens. Live f1: 1,635 input tokens with 6 deferred tools + search tool (vs 581 for one plain tool).", "limitations": [ "Sonnet 5 absent from the docs compatibility table (probably an omission — release notes say Sonnet 5 supports the same tools as Sonnet 4.6); Opus 4.1 and earlier unsupported", "Bedrock: InvokeModel only" ], "security": [], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/tools/tool-search/basic.sh", "python": "examples/anthropic/tools/tool-search/basic.py", "typescript": "examples/anthropic/tools/tool-search/basic.ts" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "f2 (haiku): query 'stock price AAPL Apple' -> tool_reference get_stock_price -> tool_use" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/messages/create", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "name_constraint": "name must be 'tool_search_tool_bm25'", "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Advisor tool (beta)", "type": "advisor_20260301", "category": "server", "description": "Executor model consults a higher-capability advisor model mid-generation: executor emits server_tool_use{name:advisor,input:{}}; Anthropic runs a separate inference on `model`; result comes back as advisor_tool_result (advisor_result{text} for most advisors, advisor_redacted_result{encrypted_content} for Fable/Mythos/Opus 5 advisors). Requires anthropic-beta: advisor-tool-2026-03-01 (live 400 without: unknown type tag). Beta since 2026-04-09.", "compatible_models": [ "claude-haiku-4-5-20251001", "claude-sonnet-4-6", "claude-sonnet-5", "claude-opus-4-6", "claude-opus-4-7", "claude-opus-4-8", "claude-opus-5", "claude-fable-5", "claude-mythos-5", "claude-fable-5-1", "claude-mythos-5-1" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "name", "model" ], "properties": { "type": { "const": "advisor_20260301" }, "name": { "const": "advisor" }, "model": { "type": "string", "description": "advisor model id; must be >= Sonnet 4.6 and at least as capable as the executor (see pairs)" }, "max_uses": { "type": "integer", "description": "per-request cap -> advisor_tool_result_error max_uses_exceeded" }, "max_tokens": { "type": "integer", "minimum": 1024, "description": "caps advisor output (thinking+text) per call; adds stop_reason to result" }, "caching": { "type": [ "object", "null" ], "description": "{type: ephemeral, ttl: 5m|1h} on/off switch for advisor-side caching" }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." }, "strict": { "type": "boolean", "description": "Grammar-constrained schema validation of the tool name and input. Not on mcp_toolset / computer_toolset / browser_toolset; not with code_execution callers (live 400)." }, "defer_loading": { "type": "boolean", "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request." }, "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])." }, "input_examples": { "type": "array", "items": { "type": "object" }, "description": "Schema-validated example inputs (user-defined + Anthropic-schema client tools only; not toolsets/server tools)." } }, "executor_advisor_pairs": { "claude-haiku-4-5-20251001": [ "claude-mythos-5-1", "claude-fable-5-1", "claude-mythos-5", "claude-fable-5", "claude-opus-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-5", "claude-sonnet-4-6" ], "claude-sonnet-4-6": [ "claude-mythos-5-1", "claude-fable-5-1", "claude-mythos-5", "claude-fable-5", "claude-opus-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-5", "claude-sonnet-4-6" ], "claude-sonnet-5": [ "claude-mythos-5-1", "claude-fable-5-1", "claude-mythos-5", "claude-fable-5", "claude-opus-5", "claude-opus-4-8", "claude-opus-4-7", "claude-sonnet-5" ], "claude-opus-4-6": [ "claude-mythos-5-1", "claude-fable-5-1", "claude-mythos-5", "claude-fable-5", "claude-opus-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-5" ], "claude-opus-4-7": [ "claude-mythos-5-1", "claude-fable-5-1", "claude-mythos-5", "claude-fable-5", "claude-opus-5", "claude-opus-4-8", "claude-opus-4-7" ], "claude-opus-4-8": [ "claude-mythos-5-1", "claude-fable-5-1", "claude-mythos-5", "claude-fable-5", "claude-opus-5", "claude-opus-4-8", "claude-opus-4-7" ], "claude-opus-5": [ "claude-mythos-5-1", "claude-fable-5-1", "claude-mythos-5", "claude-fable-5", "claude-opus-5" ], "claude-fable-5": [ "claude-mythos-5-1", "claude-fable-5-1", "claude-mythos-5", "claude-fable-5", "claude-opus-5" ], "claude-mythos-5": [ "claude-mythos-5-1", "claude-fable-5-1", "claude-mythos-5", "claude-fable-5", "claude-opus-5" ], "claude-fable-5-1": [ "claude-mythos-5-1", "claude-fable-5-1" ], "claude-mythos-5-1": [ "claude-mythos-5-1", "claude-fable-5-1" ] } }, "tool_choice_support": "auto", "parallel": "server-side; pause_turn possible while advisor pending", "streaming_events": [ "server_tool_use start/stop then quiet (ping every ~30 s) until advisor_tool_result arrives whole in one content_block_start", "message_delta with usage.iterations" ], "result_shape": { "server_tool_use": { "type": "server_tool_use", "id": "srvtoolu_…", "name": "advisor", "input": {} }, "advisor_tool_result": { "type": "advisor_tool_result", "tool_use_id": "srvtoolu_…", "content": "{type:advisor_result,text,stop_reason?} | {type:advisor_redacted_result,encrypted_content,stop_reason?} | {type:advisor_tool_result_error,error_code}" }, "error_codes": [ "max_uses_exceeded", "too_many_requests", "overloaded", "prompt_too_long", "execution_time_exceeded", "model_not_found", "unavailable" ], "usage.iterations": [ { "type": "message", "input_tokens": 0, "output_tokens": 0 }, { "type": "advisor_message", "model": "claude-opus-5", "input_tokens": 0, "output_tokens": 0 } ], "live_note": "k18 (haiku executor, sonnet 4.6 advisor, 'Reply with OK'): 200, no advisor call, usage.iterations present with one message iteration" }, "billing": "Advisor sub-inference billed at the advisor model's rates, reported in usage.iterations[] (type advisor_message); top-level usage = executor only; top-level max_tokens does not bound the advisor.", "limitations": [ "Claude API + Claude Platform on AWS only (beta)", "Invalid executor/advisor pair -> 400", "count_tokens covers only the executor's first sampling call" ], "security": [], "beta_header": "advisor-tool-2026-03-01", "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/tools/advisor/basic.sh" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "k18_advisor_haiku_exec 200; k18b without header 400" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/release-notes/api", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/build-with-claude/token-counting", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "MCP connector toolset (beta)", "type": "mcp_toolset", "category": "mcp", "description": "Connects the Messages API to a remote MCP server (Streamable HTTP or SSE, https only, tool calls only). Two parts: request-level mcp_servers[] {type:url,url,name,authorization_token?} and a tools[] entry {type:mcp_toolset, mcp_server_name, default_config?, configs?, cache_control?}. Claude's calls appear as mcp_tool_use blocks (id mcptoolu_…, server_name) followed by mcp_tool_result blocks executed by Anthropic. Requires anthropic-beta: mcp-client-2025-11-20 (deprecated mcp-client-2025-04-04 with mcp_servers[].tool_configuration still works live). Not date-versioned; versioning via header.", "compatible_models": [ "claude-fable-5-1", "claude-opus-5", "claude-sonnet-5", "claude-fable-5", "claude-opus-4-8", "claude-opus-4-7", "claude-sonnet-4-6", "claude-opus-4-6", "claude-opus-4-5-20251101", "claude-haiku-4-5-20251001", "claude-sonnet-4-5-20250929", "claude-mythos-5-1", "claude-mythos-5" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "type": "object", "required": [ "type", "mcp_server_name" ], "properties": { "type": { "const": "mcp_toolset" }, "mcp_server_name": { "type": "string", "description": "must match exactly one mcp_servers[].name; each server referenced by exactly one toolset" }, "default_config": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true }, "defer_loading": { "type": "boolean", "default": false } } }, "configs": { "type": "object", "description": "tool name -> {enabled?, defer_loading?} overrides (unknown names: warning only)" }, "cache_control": { "type": "object", "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)." } }, "mcp_servers[]": { "type": { "const": "url" }, "url": "https://… (Streamable HTTP or SSE)", "name": "unique id", "authorization_token": "OAuth bearer token obtained by you", "tool_configuration": "DEPRECATED (2025-04-04 header): {enabled?, allowed_tools?[]}" }, "limits": { "mcp_servers maxItems": 20 } }, "tool_choice_support": "auto", "parallel": "server-executed; an mcp_tool_use without result in a tool_use-stop response is deferred like server_tool_use", "streaming_events": [ "content_block_start mcp_tool_use + input_json_delta", "mcp_tool_result whole block" ], "result_shape": { "mcp_tool_use": { "type": "mcp_tool_use", "id": "mcptoolu_…", "name": "read_wiki_structure", "server_name": "deepwiki", "input": { "repoName": "…" } }, "mcp_tool_result": { "type": "mcp_tool_result", "tool_use_id": "mcptoolu_…", "is_error": false, "content": [ { "type": "text", "text": "…" } ] }, "live_note": "i1 (haiku, https://mcp.deepwiki.com/mcp): mcp_tool_use had no caller field; i2 without header -> 400 'mcp_servers: this parameter requires anthropic-beta: mcp-client-2026-09-15 (or mcp-client-2025-11-20)' but k13 sending mcp-client-2026-09-15 -> 400 'Unexpected value(s)…for the anthropic-beta header' (header advertised yet not accepted, 2026-09-18)" }, "billing": "Tokens only (tool definitions fetched from the server count as input; Batches priced the same). Live i1: 2,367 input tokens.", "limitations": [ "Remote HTTP servers only (no stdio); OAuth flow is your responsibility", "Not ZDR-eligible", "MCP tools cannot be called programmatically (PTC) and mcp_toolset does not accept strict/allowed_callers", "count_tokens rejects requests with mcp_servers", "Not on Bedrock/Vertex" ], "security": [ "Only connect to trusted servers; tool results are untrusted content" ], "beta_header": "mcp-client-2025-11-20", "status": [ "DOCUMENTED", "BETA", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/mcp/mcp_connector.sh", "python": "examples/anthropic/mcp/mcp_connector.py", "typescript": "examples/anthropic/mcp/mcp_connector.ts", "server": "examples/anthropic/mcp/mini-mcp-server.ts" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "i1_mcp_connector_deepwiki 200 (mcp_tool_use + mcp_tool_result); i2 no header 400; k13b legacy header 200; k13 2026-09-15 header 400" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/mcp-connector", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta/messages/create", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/api/beta-headers", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "beta_history": { "mcp-client-2025-04-04": "deprecated (tool_configuration on server def)", "mcp-client-2025-11-20": "current", "mcp-client-2026-09-15": "LIVE_DISCOVERED in an error message; not accepted on 2026-09-18" }, "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "anthropic", "name": "Programmatic tool calling (allowed_callers / caller)", "type": "allowed_callers:code_execution_20260120", "category": "programmatic", "description": "Not a tool type but a mode: any custom (or Anthropic-schema client) tool with allowed_callers containing code_execution_20260120 (or code_execution_20260521, interchangeable) becomes an async Python function inside the code_execution_20260120+ sandbox. Claude writes a cell (server_tool_use name code_execution, input.code); when the cell calls your tool the API pauses with stop_reason tool_use and a tool_use block whose caller is {type:code_execution_20260120, tool_id:}. You reply with ONLY tool_result blocks (string/text content), the same tools array and the top-level container id; the cell resumes and eventually a code_execution_tool_result arrives.", "compatible_models": [ "claude-fable-5-1", "claude-mythos-5-1", "claude-fable-5", "claude-mythos-5", "claude-opus-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-opus-4-5-20251101", "claude-sonnet-5", "claude-sonnet-4-6", "claude-sonnet-4-5-20250929" ], "compatible_endpoints": [ "POST /v1/messages", "POST /v1/messages/batches" ], "parameters_schema": { "allowed_callers": { "type": "array", "items": { "enum": [ "direct", "code_execution_20250825", "code_execution_20260120", "code_execution_20260521" ] }, "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])." }, "requires": "tools[] includes {type: code_execution_20260120|code_execution_20260521, name: code_execution}", "container": "required on continuation requests while a programmatic call is pending" }, "tool_choice_support": "tool_choice may not name a tool whose allowed_callers omits direct (live 400)", "parallel": "disable_parallel_tool_use:true unsupported with PTC; several programmatic calls may be pending at once (answer all in one user message)", "streaming_events": [ "server_tool_use code_execution start + input_json_delta(code)", "tool_use with caller", "later: code_execution_tool_result whole block" ], "result_shape": { "tool_use (programmatic)": { "type": "tool_use", "id": "toolu_…", "name": "query_database", "input": { "sql": "SELECT 1 AS one" }, "caller": { "type": "code_execution_20260120", "tool_id": "srvtoolu_…" } }, "tool_use (direct)": { "caller": { "type": "direct" } }, "completion": { "type": "code_execution_tool_result", "tool_use_id": "srvtoolu_…", "content": { "type": "code_execution_result", "stdout": "[{'one': 1}]\n", "stderr": "", "return_code": 0, "content": [], "abort_reason": null } }, "timeout": "TimeoutError in stderr after ~270 s waiting for your result; idle containers reclaimed after ~5 min" }, "billing": "Code execution pricing (free with web_search/web_fetch _20260209+). Programmatic tool results are NOT counted as input/output tokens; only the final code output and Claude's text are. Live g1+g2 on sonnet 4.6: 3,147 + 3,262 input tokens.", "limitations": [ "Haiku 4.5 unsupported (live 400 naming the tools)", "strict:true tools cannot have code_execution callers (live 400)", "No MCP tools, no computer/browser toolsets", "Recursive $ref schemas rejected", "tool_result content must be string/text only; no text after tool_results", "Not on Bedrock/Vertex; Foundry Hosted-on-Anthropic only; not ZDR" ], "security": [ "allowed_callers is guidance, not a hard block: still handle direct tool_use for every tool", "Tool results are strings that Claude's code may parse/exec — beware injection" ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/anthropic/tools/programmatic-tool-calling/basic.sh", "python": "examples/anthropic/tools/programmatic-tool-calling/basic.py", "typescript": "examples/anthropic/tools/programmatic-tool-calling/basic.ts" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "g1/g2 claude-sonnet-4-6 full round trip; g3 haiku 400; g4 tool_choice 400; k28 strict 400" }, "sources": [ { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools", "retrieved_at": "2026-09-18" }, { "url": "https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "release_history": "beta 2025-11-24 (advanced-tool-use-2025-11-20) -> GA 2026-02-17; code_execution_20260120 SDK support 2026-06-18", "_fragment": "generated/fragments/tools/anthropic-tools.json" }, { "provider": "gemini", "name": "Function calling (custom client tools)", "type": "functionDeclarations", "category": "client", "description": "User-defined functions declared in `tools[].functionDeclarations[]` (name, description, OpenAPI-subset `parameters` Schema or full JSON Schema `parametersJsonSchema`, optional `response`/`responseJsonSchema`, Live-only `behavior`). The model never executes them: it returns `functionCall` parts {name,args,id} (Gemini 3 always sets `id`); you run the code and reply with `functionResponse` parts {name,response,id} in a `user` (or `function`) role content. Supports parallel calls (several functionCall parts in one turn), compositional/sequential calls (multi-step), multimodal function responses (Gemini 3: `parts[].inlineData` image/png|jpeg|webp, application/pdf, text/plain, referenced from `response` via {\"$ref\": display_name}), combination with built-in tools on Gemini 3 (tool context circulation, `toolConfig.includeServerSideToolInvocations=true`) and with structured outputs (Gemini 3). Gemini 3 models require thought signatures (`thoughtSignature` on the first functionCall part of every step) to be echoed back; omission = HTTP 400 `MISSING_THOUGHT_SIGNATURE`. Max 512 declarations per request (SDK type docstring). `gemini-3.1-pro-preview-customtools` is a variant endpoint tuned for bash + custom tools.", "compatible_models": [ "gemini-3.8-flash", "gemini-3.7-flash", "gemini-3.6-flash", "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-3.1-pro-preview", "gemini-3.1-pro-preview-customtools", "gemini-3.1-flash-lite", "gemini-3.1-flash-lite-preview", "gemini-3-flash-preview", "gemini-3-pro-preview", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-lite", "gemini-robotics-er-2-preview", "gemini-robotics-er-1.6-preview", "gemini-3.8-live", "gemini-3.8-live-extended-thinking", "gemini-3.1-flash-live-preview", "gemini-2.5-flash-native-audio-preview-12-2025", "gemini-robotics-er-2-streaming-preview" ], "compatible_endpoints": [ "POST /v1beta/models/{model}:generateContent", "POST /v1beta/models/{model}:streamGenerateContent", "POST /v1beta/models/{model}:countTokens (tools counted)", "POST /v1beta/models/{model}:batchGenerateContent (same request schema)", "WSS /ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent (setup.tools; toolCall/toolResponse messages; behavior NON_BLOCKING)", "POST /v1beta/interactions (as `{\"type\":\"function\",name,description,parameters}` + `generation_config.tool_choice`)" ], "parameters_schema": { "type": "object", "description": "tools[].functionDeclarations[] item", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Required. a-z A-Z 0-9 underscore colon dot dash; max 128 chars (discovery). SDK docstring: must start with a letter or underscore. Guide: no spaces/periods/dashes for best results." }, "description": { "type": "string", "description": "Required per REST reference (discovery marks the whole object optional). Purpose of the function; crucial for tool selection." }, "parameters": { "type": "object", "description": "Schema (OpenAPI 3.03 subset: type, properties, required, enum, description, items, format, nullable, anyOf, propertyOrdering, minimum/maximum, minItems/maxItems, minLength/maxLength, pattern, default, example, title, minProperties/maxProperties). Type names may be upper-case (OBJECT/STRING) or lower-case. Mutually exclusive with parametersJsonSchema. Parameter names ≤64 chars, start with letter/underscore (SDK docstring)." }, "parametersJsonSchema": { "type": "object", "description": "Full JSON Schema object describing the parameters object (supports additionalProperties, propertyOrdering...). Mutually exclusive with `parameters`." }, "response": { "type": "object", "description": "Schema of the function's return value (OpenAPI subset). Mutually exclusive with responseJsonSchema." }, "responseJsonSchema": { "type": "object", "description": "JSON Schema of the return value. Mutually exclusive with `response`." }, "behavior": { "type": "string", "enum": [ "UNSPECIFIED", "BLOCKING", "NON_BLOCKING" ], "description": "Live API (BidiGenerateContent) only. BLOCKING (default) waits for the functionResponse; NON_BLOCKING lets the conversation continue (async function calling). gemini-3.8-live defaults to NON_BLOCKING; gemini-3.8-live-extended-thinking accepts only NON_BLOCKING; gemini-3.1-flash-live-preview is synchronous only." } }, "toolConfig.functionCallingConfig": { "mode": { "enum": [ "MODE_UNSPECIFIED", "AUTO", "ANY", "NONE", "VALIDATED" ], "default": "AUTO (VALIDATED when built-in tools or structured outputs are also enabled / when includeServerSideToolInvocations=true)" }, "allowedFunctionNames": { "type": "array", "description": "Only with mode ANY or VALIDATED" } } }, "tool_choice_support": "toolConfig.functionCallingConfig.mode = AUTO (default; model picks call or text) | ANY (forced function call, constrained decoding; may reject very large/deeply nested schemas) | NONE (never call; same as omitting declarations) | VALIDATED (call or text, but calls are schema-validated with constrained decoding; default and only mode when combining with built-in tools — AUTO unsupported with includeServerSideToolInvocations). allowedFunctionNames[] restricts ANY/VALIDATED. Interactions API twin: generation_config.tool_choice {auto|any|none|validated} / allowed_tools.", "parallel": "yes — multiple functionCall parts in one model content; functionResponse parts may be returned in any order (matched by id/name) but must follow ALL functionCall parts of that step (interleaving FC1,FR1,FC2,FR2 → 400). Thought signature only on the FIRST functionCall part of a parallel batch.", "streaming_events": [ "streamGenerateContent: GenerateContentResponse chunks whose candidates[0].content.parts[] contain functionCall parts (args arrive complete per part; SDK accumulates); thoughtSignature may arrive in an empty-text part when no FC — read until finishReason", "Live API server messages: toolCall {functionCalls[{id,name,args}]}, toolCallCancellation {ids[]}; client sends toolResponse {functionResponses[]}", "finishReason values to check: STOP, MALFORMED_FUNCTION_CALL, UNEXPECTED_TOOL_CALL, TOO_MANY_TOOL_CALLS, MISSING_THOUGHT_SIGNATURE" ], "result_shape": { "model part": { "functionCall": { "name": "get_weather", "args": { "city": "Paris" }, "id": "m4q8z1v6" }, "thoughtSignature": "" }, "your reply part (role user)": { "functionResponse": { "name": "get_weather", "id": "m4q8z1v6", "response": { "result": "..." }, "parts": [ { "inlineData": { "mimeType": "image/png", "data": "" } } ], "scheduling": "SILENT|WHEN_IDLE|INTERRUPT (Live NON_BLOCKING only)", "willContinue": "bool (Live NON_BLOCKING only)" } }, "multimodal ref": "response: {\"image\": {\"$ref\": \"\"}} (Gemini 3)", "Live": { "server": { "toolCall": { "functionCalls": [ { "id": "...", "name": "...", "args": {} } ] } }, "client": { "toolResponse": { "functionResponses": [ { "id": "...", "name": "...", "response": { "result": "ok", "scheduling": "INTERRUPT" } } ] } } } }, "billing": "No tool fee. Declarations (descriptions + schemas) count as input tokens; functionCall/functionResponse parts and echoed toolCall/toolResponse parts count toward promptTokenCount on the next request. Parallel/compositional calls = extra turns billed as normal tokens.", "limitations": [ "Only a subset of OpenAPI 3.03 Schema is supported in `parameters`; use parametersJsonSchema for full JSON Schema", "ANY mode may reject very large or deeply nested schemas (simplify names/nesting/count)", "Keep active set to ~10-20 tools (best practice); max 512 declarations (SDK docstring)", "Gemini 3: thought signature on first functionCall of every step of the current turn is mandatory (400 otherwise); dummy values `skip_thought_signature_validator` / `context_engineering_is_the_way_to_go` bypass validation for injected history", "Do not merge/split parts carrying signatures; do not interleave parallel FC/FR", "Automatic function calling is Python SDK only (JS SDK: AFC for mcpToTool/callable tools); Live API has no automatic tool response handling", "Pre-tool structured text (XML before a call) can cause MALFORMED_FUNCTION_CALL — wrap notes in an `update()` function instead", "`behavior` only honored by BidiGenerateContent", "Combining with built-in tools: Gemini 3 only, Preview, requires includeServerSideToolInvocations=true, VALIDATED mode only, all returned parts (toolCall/toolResponse/id/thoughtSignature) must be echoed", "When parts mix functionCall/toolCall/toolResponse do not assume functionCall is last — iterate parts" ], "security": "Validate calls before executing; confirm high-impact actions with the user; authenticate external APIs; avoid leaking sensitive data in args; treat model-provided args as untrusted input.", "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "curl -s \"https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash-lite:generateContent\" \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"contents\": [{\"role\": \"user\", \"parts\": [{\"text\": \"Weather in Paris?\"}]}], \"tools\": [{\"functionDeclarations\": [{\"name\": \"get_weather\", \"description\": \"Gets the current weather for a city.\", \"parameters\": {\"type\": \"object\", \"properties\": {\"city\": {\"type\": \"string\"}}, \"required\": [\"city\"]}}]}], \"toolConfig\": {\"functionCallingConfig\": {\"mode\": \"AUTO\"}}}'", "python": "from google import genai\nfrom google.genai import types\nclient = genai.Client() # reads GEMINI_API_KEY\nresp = client.models.generate_content(\n model='gemini-3.5-flash-lite',\n contents=\"Reply with OK.\",\n config=types.GenerateContentConfig(tools=[types.Tool(function_declarations=[types.FunctionDeclaration(name='get_weather', description='Gets the weather for a city.', parameters_json_schema={'type':'object','properties':{'city':{'type':'string'}},'required':['city']})])],\n tool_config=types.ToolConfig(function_calling_config=types.FunctionCallingConfig(mode='AUTO'))),\n)\nprint(resp.candidates[0].content.parts)", "typescript": "import { GoogleGenAI } from '@google/genai';\nconst ai = new GoogleGenAI({}); // GEMINI_API_KEY from env\nconst resp = await ai.models.generateContent({\n model: \"gemini-3.5-flash-lite\",\n contents: 'Reply with OK.',\n config: { tools: [{ functionDeclarations: [{ name: 'get_weather', description: 'Gets the weather for a city.', parametersJsonSchema: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] } }] }] },\n});\nconsole.log(JSON.stringify(resp.candidates?.[0]?.content?.parts, null, 2));" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "a1 mode ANY+allowedFunctionNames → functionCall{name,args,id:call_…}+thoughtSignature; a2 functionResponse → text; a2b WITHOUT thoughtSignature → 400 'Function call is missing a thought_signature'; a3 parallel: 2 calls, signature on the first only; a4 parametersJsonSchema OK; a5 NONE OK; a6 mode VALIDATED accepted (200, functionCall); a7 behavior NON_BLOCKING → 400 'only supported by the BidiGenerateContent method'; Live j5: toolCall{functionCalls[{name,args,id:function-call-…}]} (tmp-live/gemini-tools/a*.json, j5_ws_toolcall.json)" }, "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/function-calling", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/generate-content/function-calling", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/thought-signatures", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/generate-content/thought-signatures", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content#Tool", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content#FunctionDeclaration", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content#FunctionCallingConfig", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/live-tools", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/tool-combination", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/tools/gemini-tools.json" }, { "provider": "gemini", "name": "Grounding with Google Search", "type": "googleSearch", "category": "server", "description": "Google-executed web search grounding. The model decides whether to search, generates one or more queries, reads results and answers with citations. Response carries candidates[].groundingMetadata {webSearchQueries, searchEntryPoint.renderedContent (mandatory Search Suggestions widget), groundingChunks[].web{uri,title}, groundingSupports[]{segment, groundingChunkIndices, confidenceScores}}. Optional sub-config: `searchTypes.webSearch {}` (default) and `searchTypes.imageSearch {}` (image bytes returned; image-generation models — Nano Banana 2; groundingChunks[].image{imageUri,sourceUri,title,domain}, imageSearchQueries[]) and `timeRangeFilter {startTime,endTime}` (both required together; RFC 3339). Works with URL context, code execution, Google Maps (3.5 Flash+), function calling (Gemini 3, tool combination) and structured outputs (Gemini 3). Available in the Live API. Replaces the legacy googleSearchRetrieval tool.", "compatible_models": [ "gemini-3.8-flash", "gemini-3.7-flash", "gemini-3.6-flash", "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-3.1-pro-preview", "gemini-3.1-pro-preview-customtools", "gemini-3.1-flash-lite", "gemini-3.1-flash-lite-preview", "gemini-3-flash-preview", "gemini-3-pro-preview", "gemini-3.1-flash-image", "gemini-3.1-flash-image-preview", "gemini-3-pro-image", "gemini-3-pro-image-preview", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-lite", "gemini-robotics-er-2-preview", "gemini-robotics-er-1.6-preview", "gemini-3.8-live", "gemini-3.8-live-extended-thinking", "gemini-3.1-flash-live-preview", "gemini-2.5-flash-native-audio-preview-12-2025", "gemini-robotics-er-2-streaming-preview", "gemini-2.0-flash (RETIRED 2026-06-01)" ], "compatible_endpoints": [ "POST /v1beta/models/{model}:generateContent", "POST /v1beta/models/{model}:streamGenerateContent", "WSS /ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent (setup.tools[{googleSearch:{}}])", "POST /v1beta/interactions (as `{\"type\":\"google_search\"}`; search_types: [\"web_search\",\"image_search\"])", "POST /v1beta/models/{model}:batchGenerateContent" ], "parameters_schema": { "type": "object", "description": "tools[].googleSearch", "properties": { "timeRangeFilter": { "type": "object", "properties": { "startTime": { "type": "string (RFC 3339 timestamp)", "description": "Inclusive start" }, "endTime": { "type": "string (RFC 3339 timestamp)", "description": "Exclusive end" } }, "description": "Filter results to a time range; if one bound is set the other must be too. (Discovery/REST reference only; SDK type says not supported in Vertex AI.)" }, "searchTypes": { "type": "object", "properties": { "webSearch": { "type": "object (empty)", "description": "Enables web search; text results only. Default when searchTypes unset." }, "imageSearch": { "type": "object (empty)", "description": "Enables image search; image bytes returned. Documented for gemini-3.1-flash-image (Nano Banana 2); cannot be used to search for people." } } } }, "toolConfig.retrievalConfig": { "latLng": { "latitude": "number", "longitude": "number" }, "languageCode": "string (BCP-47)" } }, "tool_choice_support": "None (server decides whether to search). Not affected by functionCallingConfig. Legacy dynamic retrieval threshold only exists on googleSearchRetrieval.", "parallel": "Model may run several search queries per request (each billed on Gemini 3). Combinable in the same request with urlContext, codeExecution, googleMaps (3.5 Flash+), functionDeclarations (Gemini 3 + includeServerSideToolInvocations).", "streaming_events": [ "streamGenerateContent: groundingMetadata arrives on candidates; groundingChunks in a chunk contain only chunks not yet sent — client must accumulate; groundingChunkIndices index the accumulated list", "With includeServerSideToolInvocations=true: toolCall {toolType:GOOGLE_SEARCH_WEB|GOOGLE_SEARCH_IMAGE, args:{queries[]}, id} and toolResponse {response:{search_suggestions}} parts appear in model content", "Live API: same googleSearch tool; grounding metadata in serverContent" ], "result_shape": { "candidates[].groundingMetadata": { "webSearchQueries": [ "..." ], "imageSearchQueries": [ "..." ], "searchEntryPoint": { "renderedContent": "", "sdkBlob": "base64 JSON [[term,url],...]" }, "groundingChunks": [ { "web": { "uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/...", "title": "example.com" } }, { "image": { "imageUri": "...", "sourceUri": "...", "title": "...", "domain": "example.com" } } ], "groundingSupports": [ { "segment": { "partIndex": 0, "startIndex": 0, "endIndex": 85, "text": "..." }, "groundingChunkIndices": [ 0 ], "confidenceScores": [ 0.9 ], "renderedParts": [ 0 ] } ], "retrievalMetadata": { "googleSearchDynamicRetrievalScore": "only with legacy dynamic retrieval" } }, "usageMetadata": { "toolUsePromptTokenCount": "tokens injected by tools" } }, "billing": { "gemini_3_models": "5,000 free search requests per month (shared across all Gemini 3.x models), then $14 per 1,000 requests; billed per search QUERY the model executes (multiple queries in one prompt = multiple billable uses; empty queries ignored). Billing for Gemini 3 started 2026-01-05.", "gemini_2_5_models": "Paid tier: 1,500 RPD free (shared Flash/Flash-Lite), then $35 per 1,000 grounded PROMPTS (billed per prompt).", "free_tier": "500 RPD free (shared Flash and Flash-Lite); not available for Pro.", "tokens": "Search-retrieved content is NOT double-charged as tokens (search has its own query-level price); the model's own input/output tokens are billed normally.", "image_search": "Same $14 per 1,000 requests for text and image-based grounding (Nano Banana 2 pricing table)." }, "limitations": [ "Must display searchEntryPoint.renderedContent (Search Suggestions) per Terms of Service", "Cannot be combined with fileSearch (File Search guide: not combinable with other tools)", "Legacy 1.5/2.0 models used googleSearchRetrieval; 2.0 models were shut down 2026-06-01", "Live API: only tool alongside function calling; Maps/URL context/code execution unsupported there", "Image search cannot be used to search for people", "timeRangeFilter: start and end must both be set", "Built-in tools depend on location/time context — conflicting system_instruction can degrade tool combination" ], "security": "Display Search Suggestions (searchEntryPoint) as required by the grounding terms; redirect URIs (vertexaisearch.cloud.google.com/grounding-api-redirect/...) are Google proxies; treat retrieved web content as untrusted.", "beta_header": null, "status": [ "DOCUMENTED", "ACCOUNT_RESTRICTED" ], "examples": { "curl": "curl -s \"https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash-lite:generateContent\" \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"contents\": [{\"parts\": [{\"text\": \"Who won Euro 2024? Reply briefly.\"}]}], \"tools\": [{\"googleSearch\": {}}]}'", "python": "from google import genai\nfrom google.genai import types\nclient = genai.Client() # reads GEMINI_API_KEY\nresp = client.models.generate_content(\n model='gemini-3.5-flash-lite',\n contents=\"Reply with OK.\",\n config=types.GenerateContentConfig(tools=[types.Tool(google_search=types.GoogleSearch())]),\n)\nprint(resp.candidates[0].content.parts)", "typescript": "import { GoogleGenAI } from '@google/genai';\nconst ai = new GoogleGenAI({}); // GEMINI_API_KEY from env\nconst resp = await ai.models.generateContent({\n model: \"gemini-3.5-flash-lite\",\n contents: 'Reply with OK.',\n config: { tools: [{ googleSearch: {} }] },\n});\nconsole.log(JSON.stringify(resp.candidates?.[0]?.content?.parts, null, 2));" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "restricted", "http_status": 429, "request_note": "b/b2: tools:[{googleSearch:{}}] on gemini-3.5-flash-lite AND gemini-3.5-flash → 429 RESOURCE_EXHAUSTED 'You exceeded your current quota' (no per-metric detail); Interactions {type: google_search} → 429 too_many_requests. Consistent with the pricing page 'Not available' on the free tier; the project appears to be on the free tier (computer-use quota message: generate_content_free_tier_input_token_count limit 0) (tmp-live/gemini-tools/b_google_search.json)" }, "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/google-search", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/generate-content/google-search", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content#GoogleSearch", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content#GroundingMetadata", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/pricing", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/generate-content/image-generation", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/live-tools", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/tool-combination", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/tools/gemini-tools.json" }, { "provider": "gemini", "name": "Grounding with Google Image Search (searchTypes.imageSearch)", "type": "googleSearch.searchTypes.imageSearch", "category": "server", "description": "Not a top-level tools[] key: `imageSearch {}` is a sub-object of `tools[].googleSearch.searchTypes` (alongside `webSearch {}`). Lets the model retrieve web images via Google Search as visual context (documented for image generation with gemini-3.1-flash-image / Nano Banana 2; can run independently or with webSearch). Response: groundingMetadata.imageSearchQueries[] and groundingChunks[].image{imageUri,sourceUri,title,domain}; with tool context circulation toolCall.toolType=GOOGLE_SEARCH_IMAGE. Cannot be used to search for people.", "compatible_models": [ "gemini-3.1-flash-image", "gemini-3.1-flash-image-preview" ], "compatible_endpoints": [ "POST /v1beta/models/{model}:generateContent", "POST /v1beta/models/{model}:streamGenerateContent", "POST /v1beta/interactions (search_types: [\"image_search\"])" ], "parameters_schema": { "type": "object", "properties": { "searchTypes": { "webSearch": {}, "imageSearch": {} } } }, "tool_choice_support": "none", "parallel": "combinable with webSearch in the same googleSearch tool", "streaming_events": [ "groundingMetadata with image chunks on candidates" ], "result_shape": { "groundingChunks[].image": { "imageUri": "string", "sourceUri": "string", "title": "string", "domain": "string" }, "imageSearchQueries": [ "string" ] }, "billing": "5,000 free search requests/month (shared across Gemini 3.x), then $14 per 1,000 requests for text and image-based grounding.", "limitations": [ "Documented only for the Nano Banana 2 image model on 2026-09-18 — support on text models UNVERIFIED", "No people search" ], "security": "Same display/attribution obligations as web grounding.", "beta_header": null, "status": [ "DOCUMENTED" ], "examples": { "curl": "curl -s \"https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image:generateContent\" \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"contents\": [{\"parts\": [{\"text\": \"A painting of a Timareta butterfly on a flower\"}]}], \"generationConfig\": {\"responseModalities\": [\"IMAGE\"]}, \"tools\": [{\"googleSearch\": {\"searchTypes\": {\"webSearch\": {}, \"imageSearch\": {}}}}]}'", "python": "tools=[types.Tool(google_search=types.GoogleSearch(search_types=types.SearchTypes(web_search=types.WebSearch(), image_search=types.ImageSearch())))]", "typescript": "tools: [{ googleSearch: { searchTypes: { webSearch: {}, imageSearch: {} } } }]" }, "verification": { "method": "docs_only", "verified_at": "2026-09-18", "result": "not_tested", "http_status": null, "request_note": "not exercised in the 2026-09-18 run (docs only)" }, "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/generate-content/image-generation", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content#SearchTypes", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/models/gemini-3.1-flash-image", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/pricing", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/tools/gemini-tools.json" }, { "provider": "gemini", "name": "Google Search retrieval (legacy dynamic retrieval)", "type": "googleSearchRetrieval", "category": "server", "description": "LEGACY predecessor of googleSearch used by Gemini 1.5 and 2.0 models. `dynamicRetrievalConfig {mode: MODE_UNSPECIFIED (always retrieve) | MODE_DYNAMIC (retrieve only when the predictor score ≥ dynamicThreshold), dynamicThreshold: number (system default if unset)}`. Response adds groundingMetadata.retrievalMetadata.googleSearchDynamicRetrievalScore [0,1]. Still present in the v1beta discovery schema and REST reference, but the guide says: 'Older models use a google_search_retrieval tool. For all current models, use the google_search tool.' All Gemini 2.0 models were shut down 2026-06-01 and no 1.5 model is listed by ListModels, so no live model documented to accept it remains.", "compatible_models": [ "gemini-2.0-flash (RETIRED 2026-06-01)", "gemini-2.0-flash-lite (RETIRED 2026-06-01; search grounding 'Not supported' on its model page)", "gemini-1.5-* (RETIRED; not in models list)" ], "compatible_endpoints": [ "POST /v1beta/models/{model}:generateContent", "POST /v1beta/models/{model}:streamGenerateContent" ], "parameters_schema": { "type": "object", "properties": { "dynamicRetrievalConfig": { "type": "object", "properties": { "mode": { "enum": [ "MODE_UNSPECIFIED", "MODE_DYNAMIC" ] }, "dynamicThreshold": { "type": "number", "description": "threshold in [0,1]; default system value" } } } } }, "tool_choice_support": "dynamic retrieval threshold only", "parallel": null, "streaming_events": [ "groundingMetadata on candidates (same shape as googleSearch) + retrievalMetadata.googleSearchDynamicRetrievalScore" ], "result_shape": { "groundingMetadata.retrievalMetadata": { "googleSearchDynamicRetrievalScore": 0.73 } }, "billing": "Historically per grounded prompt ($35 / 1,000 grounded prompts, 1,500 RPD free on 2.5-era pricing). No current price line.", "limitations": [ "Not supported on Gemini 2.5/3.x — use googleSearch", "No live model in the 2026-09-18 ListModels output is documented to accept it" ], "security": "Same as googleSearch.", "beta_header": null, "status": [ "DOCUMENTED", "LEGACY", "DEPRECATED" ], "examples": { "curl": "curl -s \"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent\" \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"contents\": [{\"parts\": [{\"text\": \"Reply with OK.\"}]}], \"tools\": [{\"googleSearchRetrieval\": {\"dynamicRetrievalConfig\": {\"mode\": \"MODE_DYNAMIC\", \"dynamicThreshold\": 0.7}}}]}'", "python": "types.Tool(google_search_retrieval=types.GoogleSearchRetrieval(dynamic_retrieval_config=types.DynamicRetrievalConfig(mode='MODE_DYNAMIC', dynamic_threshold=0.7)))", "typescript": "{ googleSearchRetrieval: { dynamicRetrievalConfig: { mode: 'MODE_DYNAMIC', dynamicThreshold: 0.7 } } }" }, "verification": { "method": "docs_only", "verified_at": "2026-09-18", "result": "not_tested", "http_status": null, "request_note": "not exercised in the 2026-09-18 run (docs only)" }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#GoogleSearchRetrieval", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content#DynamicRetrievalConfig", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/google-search", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/deprecations", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/changelog", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/tools/gemini-tools.json" }, { "provider": "gemini", "name": "Grounding with Google Maps", "type": "googleMaps", "category": "server", "description": "Google-executed geospatial grounding over 250M+ places. Enable with `tools:[{googleMaps:{}}]`; optionally pass the user location in `toolConfig.retrievalConfig.latLng {latitude,longitude}` (and `languageCode`). `googleMaps.enableWidget: true` returns `groundingMetadata.googleMapsWidgetContextToken` for the PlacesContextElement widget (the experimental 'GMP Contextual View' fixed interface shuts down 2026-06-15 per changelog). Response: groundingChunks[].maps {uri, title, placeId (places/...), text, placeAnswerSources.reviewSnippets[{reviewId,googleMapsUri,title}]}, groundingSupports[], webSearchQueries[]. Textual tool: local queries ('near me') use the coordinates. GA since 2025 (changelog), Gemini 3 support added later.", "compatible_models": [ "gemini-3.8-flash", "gemini-3.7-flash", "gemini-3.6-flash", "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-3.1-pro-preview", "gemini-3.1-flash-lite", "gemini-3.1-flash-lite-preview", "gemini-3-flash-preview", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-lite", "gemini-robotics-er-2-preview", "gemini-robotics-er-1.6-preview", "gemini-2.0-flash (RETIRED 2026-06-01)" ], "compatible_endpoints": [ "POST /v1beta/models/{model}:generateContent", "POST /v1beta/models/{model}:streamGenerateContent", "POST /v1beta/interactions (as `{\"type\":\"google_maps\"}`)" ], "parameters_schema": { "type": "object", "properties": { "enableWidget": { "type": "boolean", "description": "Return googleMapsWidgetContextToken in groundingMetadata to render a Google Maps widget." } }, "toolConfig.retrievalConfig": { "latLng": { "latitude": "number [-90,90]", "longitude": "number [-180,180]" }, "languageCode": "string BCP-47" } }, "tool_choice_support": "none (off by default; enable only for geo queries)", "parallel": "combinable with googleSearch on Gemini 3.5 Flash and later; with function calling on Gemini 3 (tool combination); multiple Maps queries in one request count as one request for rate limits", "streaming_events": [ "groundingMetadata on candidates", "toolCall {toolType:GOOGLE_MAPS,args:{queries[]}} / toolResponse {response:{places, google_maps_widget_context_token}} with includeServerSideToolInvocations" ], "result_shape": { "groundingMetadata": { "groundingChunks": [ { "maps": { "uri": "https://maps.google.com/?cid=...", "title": "Place name", "placeId": "places/ChIJ...", "text": "...", "placeAnswerSources": { "reviewSnippets": [ { "reviewId": "...", "googleMapsUri": "...", "title": "..." } ] } } } ], "groundingSupports": [ { "segment": { "startIndex": 0, "endIndex": 79, "text": "..." }, "groundingChunkIndices": [ 0 ] } ], "webSearchQueries": [ "restaurants near me" ], "googleMapsWidgetContextToken": "only when enableWidget=true" } }, "billing": { "pricing_page_tools_table": "Free tier 500 RPD (not available for Pro). Paid: 1,500 RPD free (shared Flash/Flash-Lite), 10,000 RPD free for Pro, then $25 / 1,000 grounded prompts.", "pricing_page_gemini_3_model_tables": "5,000 prompts per month (free, shared across Gemini 3), then $14 / 1,000 search queries.", "maps_guide": "$25 / 1K grounded prompts; free tier up to 500 requests per day; a request counts only when the prompt returns ≥1 Google Maps grounded result; multiple Maps queries in one request = one request.", "note": "Documentation is inconsistent ($25/1K prompts vs $14/1K queries for Gemini 3) — DOCUMENTATION_INCOMPLETE; parent agent to verify billing dashboard if needed." }, "limitations": [ "Text only (no multimodal inputs/outputs beyond text)", "Off by default", "Not available in the Live API", "Not combinable with fileSearch", "Prohibited: high-risk activities incl. emergency response; distribution in Google Maps Platform Prohibited Territories", "Gemini 3 Pro Preview page: Maps 'Not supported'" ], "security": "Service usage requirements: inform users Google Maps sources are used; sources must immediately follow the grounded content and be viewable in one interaction; link each groundingChunk/reviewSnippet with the provided uri/googleMapsUri and 'Google Maps' text attribution (Roboto, 12-16sp, not translated/modified, translate=\"no\"); placeId/reviewId may be cached/stored/exported (caching restrictions do not apply to them).", "beta_header": null, "status": [ "DOCUMENTED", "GA", "LIVE_VERIFIED" ], "examples": { "curl": "curl -s \"https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash-lite:generateContent\" \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"contents\": [{\"parts\": [{\"text\": \"Coffee shops near here? One line.\"}]}], \"tools\": [{\"googleMaps\": {}}], \"toolConfig\": {\"retrievalConfig\": {\"latLng\": {\"latitude\": 45.5017, \"longitude\": -73.5673}}}}'", "python": "from google import genai\nfrom google.genai import types\nclient = genai.Client() # reads GEMINI_API_KEY\nresp = client.models.generate_content(\n model='gemini-3.5-flash-lite',\n contents=\"Reply with OK.\",\n config=types.GenerateContentConfig(tools=[types.Tool(google_maps=types.GoogleMaps())],\n tool_config=types.ToolConfig(retrieval_config=types.RetrievalConfig(lat_lng=types.LatLng(latitude=45.5017, longitude=-73.5673)))),\n)\nprint(resp.candidates[0].content.parts)", "typescript": "import { GoogleGenAI } from '@google/genai';\nconst ai = new GoogleGenAI({}); // GEMINI_API_KEY from env\nconst resp = await ai.models.generateContent({\n model: \"gemini-3.5-flash-lite\",\n contents: 'Reply with OK.',\n config: { tools: [{ googleMaps: {} }], toolConfig: { retrievalConfig: { latLng: { latitude: 45.5017, longitude: -73.5673 } } } },\n});\nconsole.log(JSON.stringify(resp.candidates?.[0]?.content?.parts, null, 2));" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "e: tools:[{googleMaps:{}}] + toolConfig.retrievalConfig.latLng (Toronto) → groundingMetadata {webSearchQueries, groundingChunks[{maps:{uri,title,text,placeId}}], groundingSupports}; e2 enableWidget:true → 200 but no googleMapsWidgetContextToken on gemini-3.5-flash-lite (tmp-live/gemini-tools/e_google_maps.json)" }, "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/maps-grounding", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/generate-content/maps-grounding", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content#GoogleMaps", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content#Maps", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/pricing", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/changelog", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/tools/gemini-tools.json" }, { "provider": "gemini", "name": "URL context", "type": "urlContext", "category": "server", "description": "Google-executed fetch of URLs mentioned in the prompt (up to 20 per request). Two-step retrieval: internal index cache first, then live fetch. Enable with `tools:[{urlContext:{}}]` (no fields). Response: candidates[].urlContextMetadata.urlMetadata[{retrievedUrl, urlRetrievalStatus: URL_RETRIEVAL_STATUS_SUCCESS|ERROR|PAYWALL|UNSAFE}]. Retrieved content is billed as input tokens and reported in usageMetadata.toolUsePromptTokenCount. GA since 2025-05 (changelog). Combinable with googleSearch (search then read pages) and, on Gemini 3, with function calling and structured outputs.", "compatible_models": [ "gemini-3.8-flash", "gemini-3.7-flash", "gemini-3.6-flash", "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-3.1-pro-preview", "gemini-3.1-pro-preview-customtools", "gemini-3.1-flash-lite", "gemini-3.1-flash-lite-preview", "gemini-3-flash-preview", "gemini-3-pro-preview", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-lite", "gemini-robotics-er-2-preview", "gemini-robotics-er-1.6-preview" ], "compatible_endpoints": [ "POST /v1beta/models/{model}:generateContent", "POST /v1beta/models/{model}:streamGenerateContent", "POST /v1beta/interactions (as `{\"type\":\"url_context\"}`)" ], "parameters_schema": { "type": "object", "description": "tools[].urlContext — empty object, no configurable fields", "properties": {} }, "tool_choice_support": "none", "parallel": "up to 20 URLs per request; combinable with googleSearch, codeExecution, functionDeclarations (Gemini 3)", "streaming_events": [ "urlContextMetadata on candidates", "toolCall {toolType:URL_CONTEXT,args:{urls[]}} / toolResponse {response:{urls_metadata:[{retrieved_url,url_retrieval_status}]}} with includeServerSideToolInvocations" ], "result_shape": { "candidates[].urlContextMetadata": { "urlMetadata": [ { "retrievedUrl": "https://...", "urlRetrievalStatus": "URL_RETRIEVAL_STATUS_SUCCESS" } ] }, "usageMetadata": { "toolUsePromptTokenCount": 10309, "toolUsePromptTokensDetails": [ { "modality": "TEXT", "tokenCount": 10309 } ] } }, "billing": "Free tier: free of charge. Paid: retrieved content charged as INPUT tokens at the model's rate (visible as toolUsePromptTokenCount). No per-call fee.", "limitations": [ "Max 20 URLs per request", "Max 34 MB of content per URL", "URLs must be public: no localhost/private networks/tunnels (ngrok, pinggy), no paywalls or logins", "Supported content: text/html, application/json, text/plain, text/xml, text/css, text/javascript, text/csv, text/rtf; images image/png|jpeg|bmp|webp; application/pdf", "Unsupported: paywalled content, YouTube videos, Google Workspace files (Docs/Sheets), video and audio files", "Only the given URLs are read (no nested links)", "Guide 'Limitations' still says tool use with function calling is unsupported — superseded for Gemini 3 by the tool-combination feature (Preview); UNVERIFIED for 2.5", "Not combinable with fileSearch; not available in the Live API" ], "security": "Content moderation check on each URL; unsafe URLs return URL_RETRIEVAL_STATUS_UNSAFE. Treat fetched content as untrusted (prompt-injection risk).", "beta_header": null, "status": [ "DOCUMENTED", "GA", "LIVE_VERIFIED" ], "examples": { "curl": "curl -s \"https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash-lite:generateContent\" \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"contents\": [{\"parts\": [{\"text\": \"Summarize https://ai.google.dev/gemini-api/docs/url-context in one sentence.\"}]}], \"tools\": [{\"urlContext\": {}}]}'", "python": "from google import genai\nfrom google.genai import types\nclient = genai.Client() # reads GEMINI_API_KEY\nresp = client.models.generate_content(\n model='gemini-3.5-flash-lite',\n contents=\"Reply with OK.\",\n config=types.GenerateContentConfig(tools=[types.Tool(url_context=types.UrlContext())]),\n)\nprint(resp.candidates[0].content.parts)", "typescript": "import { GoogleGenAI } from '@google/genai';\nconst ai = new GoogleGenAI({}); // GEMINI_API_KEY from env\nconst resp = await ai.models.generateContent({\n model: \"gemini-3.5-flash-lite\",\n contents: 'Reply with OK.',\n config: { tools: [{ urlContext: {} }] },\n});\nconsole.log(JSON.stringify(resp.candidates?.[0]?.content?.parts, null, 2));" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "c: candidate.urlContextMetadata.urlMetadata[{retrievedUrl, urlRetrievalStatus: URL_RETRIEVAL_STATUS_ERROR}] for https://example.com; usageMetadata.toolUsePromptTokenCount 130 (tmp-live/gemini-tools/c_url_context.json)" }, "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/url-context", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/generate-content/url-context", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content#UrlContext", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content#UrlContextMetadata", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/pricing", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/changelog", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/tools/gemini-tools.json" }, { "provider": "gemini", "name": "Code execution", "type": "codeExecution", "category": "server", "description": "Google-executed Python sandbox. The model writes code, the API runs it and feeds the result back, iterating (up to 5 regenerations on error) until a final answer. Response parts: `executableCode {language: PYTHON, code, id?}` then `codeExecutionResult {outcome: OUTCOME_OK|OUTCOME_FAILED|OUTCOME_DEADLINE_EXCEEDED, output, id?}`, plus `text` and, for matplotlib graphs / image manipulation, `inlineData` image parts. File input via part.inlineData or part.fileData (Files API); best with text/CSV. 'Code execution with images' (crop/zoom/annotate) on Gemini 3 Flash with thinking enabled. Combinable with googleSearch, with function calling on Gemini 3 (echo id + thoughtSignature), and with structured outputs (Gemini 3).", "compatible_models": [ "gemini-3.8-flash", "gemini-3.7-flash", "gemini-3.6-flash", "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-3.1-pro-preview", "gemini-3.1-pro-preview-customtools", "gemini-3.1-flash-lite", "gemini-3.1-flash-lite-preview", "gemini-3-flash-preview", "gemini-3-pro-preview", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-lite", "gemini-robotics-er-2-preview", "gemini-robotics-er-1.6-preview", "gemini-2.0-flash (RETIRED 2026-06-01)" ], "compatible_endpoints": [ "POST /v1beta/models/{model}:generateContent", "POST /v1beta/models/{model}:streamGenerateContent", "POST /v1beta/interactions (as `{\"type\":\"code_execution\"}`)", "POST /v1beta/models/{model}:batchGenerateContent" ], "parameters_schema": { "type": "object", "description": "tools[].codeExecution — empty object, no configurable fields", "properties": {} }, "tool_choice_support": "none (model decides). Prompt explicitly ('write code to ...') for non-obvious uses.", "parallel": "iterative: several executableCode/codeExecutionResult pairs per response; combinable with googleSearch and (Gemini 3) function calling", "streaming_events": [ "streamGenerateContent chunks carry executableCode, codeExecutionResult, inlineData (image/png) and text parts as they are produced", "In multi-turn use, echo executableCode/codeExecutionResult parts (with id and thoughtSignature) back in history" ], "result_shape": { "parts": [ { "executableCode": { "language": "PYTHON", "code": "print(sum(range(1,51)))", "id": "opt" }, "thoughtSignature": "..." }, { "codeExecutionResult": { "outcome": "OUTCOME_OK", "output": "1275\n", "id": "opt" } }, { "inlineData": { "mimeType": "image/png", "data": "" } }, { "text": "The sum is 1275." } ] }, "billing": "No additional charge; standard model token rates. Generated code + execution output + thinking + summary are OUTPUT tokens when created; the prompt, code and results become 'intermediate' INPUT tokens when the model re-reads them (intermediate token count is reported in usageMetadata). No charge for session runtime. Free tier: free of charge.", "limitations": [ "Python only (≥3.10); other languages can be generated but not run", "Max runtime 30 s per execution; up to 5 automatic retries on error", "Fixed library set; cannot pip install: attrs, chess, contourpy, fpdf, geopandas, imageio, jinja2, joblib, jsonschema, jsonschema-specifications, lxml, matplotlib, mpmath, numpy, opencv-python, openpyxl, packaging, pandas, pillow, protobuf, pylatex, pyparsing, PyPDF2, python-dateutil, python-docx, python-pptx, reportlab, scikit-learn, scipy, seaborn, six, striprtf, sympy, tabulate, tensorflow, toolz, xlrd", "Only matplotlib renders graphs; output files always returned as part.inlineData", "Input file size bounded by the model context window (AI Studio: ~1M tokens ≈ 2 MB text)", "Cannot return other artifacts (media files) beyond images", "May regress other output quality (e.g. creative writing); model-dependent reliability", "Not supported in the Live API; not combinable with fileSearch" ], "security": "Code runs in Google's sandbox, not on your machine; no network/library installation. Treat outputs as model-generated.", "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "curl -s \"https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash-lite:generateContent\" \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"contents\": [{\"parts\": [{\"text\": \"Compute the sum of the first 50 integers using code.\"}]}], \"tools\": [{\"codeExecution\": {}}]}'", "python": "from google import genai\nfrom google.genai import types\nclient = genai.Client() # reads GEMINI_API_KEY\nresp = client.models.generate_content(\n model='gemini-3.5-flash-lite',\n contents=\"Reply with OK.\",\n config=types.GenerateContentConfig(tools=[types.Tool(code_execution=types.ToolCodeExecution())]),\n)\nprint(resp.candidates[0].content.parts)", "typescript": "import { GoogleGenAI } from '@google/genai';\nconst ai = new GoogleGenAI({}); // GEMINI_API_KEY from env\nconst resp = await ai.models.generateContent({\n model: \"gemini-3.5-flash-lite\",\n contents: 'Reply with OK.',\n config: { tools: [{ codeExecution: {} }] },\n});\nconsole.log(JSON.stringify(resp.candidates?.[0]?.content?.parts, null, 2));" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "d: parts executableCode{language:PYTHON,code,id} → codeExecutionResult{outcome:OUTCOME_OK,output:'4\\n',id} → text; toolUsePromptTokenCount 34 (tmp-live/gemini-tools/d_code_execution.json)" }, "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/code-execution", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/generate-content/code-execution", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content#CodeExecution", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content#ExecutableCode", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content#CodeExecutionResult", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/pricing", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/tools/gemini-tools.json" }, { "provider": "gemini", "name": "Computer Use (Preview)", "type": "computerUse", "category": "client", "description": "Agentic UI control: `tools:[{computerUse:{environment: ENVIRONMENT_BROWSER|ENVIRONMENT_MOBILE|ENVIRONMENT_DESKTOP, excludedPredefinedFunctions[], enablePromptInjectionDetection, disabledSafetyPolicies[]}}]` auto-populates a catalogue of predefined function declarations. You send a screenshot (+ prompt); the model returns `functionCall` parts naming an action (Gemini 3.x: click, type, scroll, navigate, ... with normalized 0-999 x/y coordinates and an `intent` string; legacy 2.5: open_web_browser, click_at, type_text_at, scroll_document, ...). Your client executes it (e.g. Playwright), captures a new screenshot and returns it in a functionResponse (screenshot inlineData + {url}). `args.safety_decision {decision: require_confirmation|..., explanation}` requires user confirmation → reply with `safety_acknowledgement: true`. Custom FunctionDeclarations can be added and predefined ones excluded (HITL yield_to_user pattern). Client-side execution; context circulation via functionCall/functionResponse.", "compatible_models": [ "gemini-3.8-flash (recommended)", "gemini-3.7-flash", "gemini-3.6-flash (model page: Supported (Preview))", "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-3-flash-preview", "gemini-2.5-computer-use-preview-10-2025 (legacy, browser only)", "gemini-robotics-er-2-preview", "gemini-robotics-er-1.6-preview" ], "compatible_endpoints": [ "POST /v1beta/models/{model}:generateContent", "POST /v1beta/models/{model}:streamGenerateContent", "POST /v1beta/interactions (as `{\"type\":\"computer_use\"}`)" ], "parameters_schema": { "type": "object", "required": [ "environment" ], "properties": { "environment": { "type": "string", "enum": [ "ENVIRONMENT_UNSPECIFIED", "ENVIRONMENT_BROWSER", "ENVIRONMENT_MOBILE", "ENVIRONMENT_DESKTOP" ], "description": "Required. UNSPECIFIED defaults to browser. Mobile/desktop: Gemini 3.x only." }, "excludedPredefinedFunctions": { "type": "array", "description": "Predefined action names to drop (restrict action space or override with your own declaration)." }, "enablePromptInjectionDetection": { "type": "boolean", "default": false, "description": "Gemini 3.5 Flash+: scan screenshots for hidden adversarial instructions and block execution when detected." }, "disabledSafetyPolicies": { "type": "array", "enum": [ "FINANCIAL_TRANSACTIONS", "SENSITIVE_DATA_MODIFICATION", "COMMUNICATION_TOOL", "ACCOUNT_CREATION", "DATA_MODIFICATION", "USER_CONSENT_MANAGEMENT", "LEGAL_TERMS_AND_AGREEMENTS" ], "description": "Gemini 3.x safety policy categories to disable (overrides are preferences; require_confirmation may still be returned)." } }, "companion": "Add extra tools[].functionDeclarations for custom actions; generationConfig.thinkingConfig.thinkingLevel to trade speed vs accuracy (Gemini 3.x)." }, "tool_choice_support": "Predefined functions behave like function declarations; functionCallingConfig applies (not documented specifically). excludedPredefinedFunctions restricts the set.", "parallel": "Typically one action per step; the loop repeats until the task ends. Multiple functionCall parts may occur.", "streaming_events": [ "functionCall parts in generateContent/streamGenerateContent chunks (Gemini 3.x args include intent; may include safety_decision)", "Client returns functionResponse with screenshot (inlineData image/png) + current url" ], "result_shape": { "gemini_3x": { "functionCall": { "name": "click", "args": { "x": 450, "y": 120, "intent": "Click the search box" } } }, "legacy_2_5": { "functionCall": { "name": "type_text_at", "args": { "x": 371, "y": 470, "text": "...", "press_enter": true } } }, "safety": { "functionCall": { "name": "click_at", "args": { "x": 60, "y": 100, "safety_decision": { "decision": "require_confirmation", "explanation": "Must check check-box" } } } }, "functionResponse (you)": { "name": "click", "id": "", "response": { "url": "https://...", "safety_acknowledgement": true }, "parts": [ { "inlineData": { "mimeType": "image/png", "data": "" } } ] }, "action_catalogue": { "browser": [ "click", "double_click", "triple_click", "middle_click", "right_click", "mouse_down", "mouse_up", "move", "type", "drag_and_drop", "wait", "press_key", "key_down", "key_up", "hotkey", "take_screenshot", "scroll", "go_back", "navigate", "go_forward" ], "mobile": [ "open_app", "click", "list_apps", "wait", "go_back", "type", "drag_and_drop", "long_press", "press_key", "take_screenshot" ], "desktop": [ "click", "double_click", "triple_click", "middle_click", "right_click", "mouse_down", "mouse_up", "move", "type", "drag_and_drop", "wait", "press_key", "key_down", "key_up", "hotkey", "take_screenshot", "scroll" ], "legacy_2_5": [ "open_web_browser", "wait_5_seconds", "go_back", "go_forward", "search", "navigate", "click_at", "hover_at", "type_text_at", "key_combination", "scroll_document", "scroll_at", "drag_and_drop" ] } }, "billing": "No tool fee: charged as regular tokens at the model's price (screenshots are image input tokens). Free tier: not available. Legacy gemini-2.5-computer-use-preview-10-2025 has its own pricing table.", "limitations": [ "Preview: may contain errors and security vulnerabilities; avoid critical decisions/sensitive data", "Coordinates normalized 0-999 — client must scale to viewport; no need to send display size", "Legacy 2.5 model: browser only, 128k input / 64k output, image+text input", "gemini-3-pro-preview model page: Computer use 'Not supported' (changelog 2025 said launched) — conflicting docs", "Not in Live API", "Safety overrides are preferences; always implement safety_decision handling" ], "security": "Run in a sandboxed VM/container (reference Docker sandbox: github.com/google/computer-use-preview); enforce human-in-the-loop on require_confirmation; custom system-instruction safety boundaries; enablePromptInjectionDetection (3.5 Flash+); safety policy categories: FINANCIAL_TRANSACTIONS, SENSITIVE_DATA_MODIFICATION, COMMUNICATION_TOOL, ACCOUNT_CREATION, DATA_MODIFICATION, USER_CONSENT_MANAGEMENT, LEGAL_TERMS_AND_AGREEMENTS.", "beta_header": null, "status": [ "DOCUMENTED", "PREVIEW", "ACCOUNT_RESTRICTED" ], "examples": { "curl": "curl -s \"https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash-lite:generateContent\" \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"contents\": [{\"parts\": [{\"text\": \"Search for 'Gemini API' on Google.\"}]}], \"tools\": [{\"computerUse\": {\"environment\": \"ENVIRONMENT_BROWSER\"}}]}'", "python": "from google import genai\nfrom google.genai import types\nclient = genai.Client() # reads GEMINI_API_KEY\nresp = client.models.generate_content(\n model='gemini-3.5-flash-lite',\n contents=\"Reply with OK.\",\n config=types.GenerateContentConfig(tools=[types.Tool(computer_use=types.ComputerUse(environment=types.Environment.ENVIRONMENT_BROWSER))]),\n)\nprint(resp.candidates[0].content.parts)", "typescript": "import { GoogleGenAI } from '@google/genai';\nconst ai = new GoogleGenAI({}); // GEMINI_API_KEY from env\nconst resp = await ai.models.generateContent({\n model: \"gemini-3.5-flash-lite\",\n contents: 'Reply with OK.',\n config: { tools: [{ computerUse: { environment: 'ENVIRONMENT_BROWSER' } }] },\n});\nconsole.log(JSON.stringify(resp.candidates?.[0]?.content?.parts, null, 2));" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "restricted", "http_status": 429, "request_note": "f: generateContent computerUse{environment:ENVIRONMENT_BROWSER} on gemini-2.5-computer-use-preview-10-2025 → 429 'Quota exceeded for metric generate_content_free_tier_input_token_count, limit: 0, model: computer-use-preview'; f2: Interactions tools:[{type:computer_use, environment:browser}] on gemini-3.5-flash-lite → 200 completed (model replied DONE without acting) (tmp-live/gemini-tools/f*_computer_use*.json)" }, "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/computer-use", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/generate-content/computer-use", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content#ComputerUse", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/models/gemini-2.5-computer-use-preview-10-2025", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/pricing", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/changelog", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/tools/gemini-tools.json" }, { "provider": "gemini", "name": "File Search (managed RAG)", "type": "fileSearch", "category": "server", "description": "Google-hosted retrieval over your own documents. Create a FileSearchStore (POST /v1beta/fileSearchStores, optional embeddingModel models/gemini-embedding-2 for multimodal/image search), ingest with `media.uploadToFileSearchStore` (multipart/resumable upload, chunked + embedded server-side; LRO) or `fileSearchStores.importFile` (from a Files API file), then query with `tools:[{fileSearch:{fileSearchStoreNames:[...], metadataFilter?: 'author = \"X\"' (AIP-160 list-filter syntax), topK?}}]`. Response: groundingMetadata.groundingChunks[].retrievedContext {title, uri, text, fileSearchStore, pageNumber, mediaId (image chunks; download via GET /v1beta/{mediaId}), customMetadata[]} + groundingSupports[]. Embeddings persist until deleted (no TTL); Files API objects expire after 48 h. Public preview since 2025-11 (changelog); Gemini 3 supports fileSearch + structured outputs.", "compatible_models": [ "gemini-3.8-flash", "gemini-3.7-flash", "gemini-3.6-flash", "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-3.1-pro-preview (model page: 'Supported (AI Studio only)')", "gemini-3.1-flash-lite", "gemini-3.1-flash-lite-preview", "gemini-3-flash-preview", "gemini-3-pro-preview (model page)", "gemini-2.5-pro", "gemini-2.5-flash-lite", "gemini-2.5-flash (model page: Supported; absent from the File Search guide table)", "gemini-robotics-er-2-preview", "gemini-robotics-er-1.6-preview" ], "compatible_endpoints": [ "POST /v1beta/models/{model}:generateContent", "POST /v1beta/models/{model}:streamGenerateContent", "POST /v1beta/interactions (as `{\"type\":\"file_search\",\"file_search_store_names\":[...]}`; also a Deep Research agent tool)", "Store management: POST/GET /v1beta/fileSearchStores, GET/DELETE /v1beta/fileSearchStores/{id}, POST /upload/v1beta/fileSearchStores/{id}:uploadToFileSearchStore, POST /v1beta/fileSearchStores/{id}:importFile, GET/DELETE …/documents[/{doc}], GET …/operations/{op}, GET …/upload/operations/{op}, GET /v1beta/fileSearchStores/{id}/media/{blob} (download)" ], "parameters_schema": { "type": "object", "required": [ "fileSearchStoreNames" ], "properties": { "fileSearchStoreNames": { "type": "array", "description": "Store resource names, e.g. fileSearchStores/my-store-123a456b789c" }, "metadataFilter": { "type": "string", "description": "AIP-160 filter over document/chunk custom metadata, e.g. author = \"Robert Graves\" or year > 1930 (strings quoted; numeric comparisons; string_list INCLUDES/EXCLUDES)." }, "topK": { "type": "integer", "description": "Number of semantic retrieval chunks to retrieve (REST reference/discovery only; not in the guide)." } } }, "tool_choice_support": "none (server decides when to retrieve)", "parallel": "multiple stores per request; NOT combinable with other built-in tools (Google Search, URL context...) — Gemini 3 tool-combination page nevertheless lists File Search as circulation-supported and the guide says combinable with function calling on Gemini 3", "streaming_events": [ "groundingMetadata on candidates (retrievedContext chunks; accumulate across stream chunks)", "toolCall {toolType:FILE_SEARCH} / toolResponse parts with includeServerSideToolInvocations (no user-visible args)" ], "result_shape": { "groundingMetadata": { "groundingChunks": [ { "retrievedContext": { "title": "sample.txt", "uri": "...", "text": "chunk text", "fileSearchStore": "fileSearchStores/my-store-123", "pageNumber": 3, "mediaId": "fileSearchStores/my-store-123/media/BlobId-456", "customMetadata": [ { "key": "author", "stringValue": "Robert Graves" }, { "key": "year", "numericValue": 1934 } ] } } ], "groundingSupports": [ { "segment": { "startIndex": 0, "endIndex": 50, "text": "..." }, "groundingChunkIndices": [ 0 ] } ] } }, "billing": "Indexing: embeddings charged once at indexing time — pricing tools table: $0.15 / 1M tokens (gemini-embedding-2 standard text input is listed at $0.20 / 1M on the same page — DOCUMENTATION_INCOMPLETE). Storage: free. Query-time embeddings: free. Retrieved document tokens: billed as regular input/context tokens of the generating model. Free tier: free of charge.", "limitations": [ "Max 100 MB per file/document (discovery mediaUpload maxSize 104857600)", "Total store size per project by tier: Free 1 GB, Tier 1 10 GB, Tier 2 100 GB, Tier 3 1 TB (backend size ≈ 3× input incl. embeddings); keep each store < 20 GB for latency", "Not supported in the Live API", "Cannot be combined with Google Search, URL context, etc. (guide)", "Audio/video not supported; images (PNG/JPEG ≤ 4K×4K) only with embeddingModel models/gemini-embedding-2 set at store creation", "Max 20 customMetadata per Document; displayName ≤ 512 chars; store id ≤ 40 chars derived from displayName + 12-char suffix; store names are globally scoped", "Chunking: whiteSpaceConfig.maxTokensPerChunk (words; ≤ 512 recommended) / maxOverlapTokens", "Delete a store/document containing documents/chunks requires ?force=true (else FAILED_PRECONDITION)" ], "security": "Data stays until you delete it; Files API temp objects auto-delete after 48 h. Custom metadata is echoed to callers via grounding chunks. Uploads accept any MIME (*/*) but only listed text/application types are indexed.", "beta_header": null, "status": [ "DOCUMENTED", "PREVIEW", "LIVE_VERIFIED" ], "examples": { "curl": "curl -s \"https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash-lite:generateContent\" \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"contents\": [{\"parts\": [{\"text\": \"What does the uploaded doc say? One sentence.\"}]}], \"tools\": [{\"fileSearch\": {\"fileSearchStoreNames\": [\"fileSearchStores/STORE_ID\"], \"metadataFilter\": \"author = \\\"Robert Graves\\\"\"}}]}'", "python": "from google import genai\nfrom google.genai import types\nclient = genai.Client() # reads GEMINI_API_KEY\nresp = client.models.generate_content(\n model='gemini-3.5-flash-lite',\n contents=\"Reply with OK.\",\n config=types.GenerateContentConfig(tools=[types.Tool(file_search=types.FileSearch(file_search_store_names=['fileSearchStores/STORE_ID']))]),\n)\nprint(resp.candidates[0].content.parts)", "typescript": "import { GoogleGenAI } from '@google/genai';\nconst ai = new GoogleGenAI({}); // GEMINI_API_KEY from env\nconst resp = await ai.models.generateContent({\n model: \"gemini-3.5-flash-lite\",\n contents: 'Reply with OK.',\n config: { tools: [{ fileSearch: { fileSearchStoreNames: ['fileSearchStores/STORE_ID'] } }] },\n});\nconsole.log(JSON.stringify(resp.candidates?.[0]?.content?.parts, null, 2));" }, "verification": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "g6: tools:[{fileSearch:{fileSearchStoreNames:[…], metadataFilter:'kind=probe'}}] → correct answer from a 200-byte txt; groundingMetadata.groundingChunks[{retrievedContext{title,text,fileSearchStore}}] + groundingSupports present in 2 of 3 runs, absent once; toolUsePromptTokenCount 834–985 (tmp-live/gemini-tools/g6_file_search_query.json)" }, "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/file-search", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/generate-content/file-search", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/file-search/file-search-stores", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/file-search/documents", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content#FileSearch", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content#RetrievedContext", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/pricing", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/changelog", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/tools/gemini-tools.json" }, { "provider": "gemini", "name": "Remote MCP servers (server-side, tools[].mcpServers)", "type": "mcpServers", "category": "mcp", "description": "Present in the v1beta discovery `Tool` schema and REST reference: `tools[].mcpServers[] {name, streamableHttpTransport {url, headers{}, timeout ('3.5s'), sseReadTimeout, terminateOnClose}}` — 'MCP Servers to connect to'. The generateContent guides do NOT document it (the google-genai README uses Tool.mcp_servers only for the 'Gemini Enterprise Agent Platform' and the SDK type says 'not supported in Vertex AI'). Server-side remote MCP IS documented for the Interactions API (`tools:[{type:'mcp_server', name, url, headers, allowed_tools}]`; Streamable HTTP only, no SSE; server names without '-') and as a Deep Research agent tool. Whether generateContent honors tools[].mcpServers on the Gemini Developer API is UNVERIFIED (parent agent may probe).", "compatible_models": "UNVERIFIED for generateContent; Interactions API mcp_server: Gemini 3 models (examples use gemini-3.8-flash) and deep-research-* agents", "compatible_endpoints": [ "POST /v1beta/models/{model}:generateContent (schema only — UNVERIFIED)", "POST /v1beta/interactions (documented: type mcp_server)" ], "parameters_schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "streamableHttpTransport": { "type": "object", "properties": { "url": { "type": "string", "description": "Full MCP endpoint URL, e.g. https://api.example.com/mcp" }, "headers": { "type": "object (map)", "description": "auth headers etc." }, "timeout": { "type": "string (duration, e.g. '3.5s')" }, "sseReadTimeout": { "type": "string (duration)" }, "terminateOnClose": { "type": "boolean" } } } } }, "interactions_twin": { "type": "mcp_server", "name": "string (no '-')", "url": "string", "headers": "object", "allowed_tools": "array" } }, "tool_choice_support": "UNVERIFIED", "parallel": "UNVERIFIED", "streaming_events": [ "UNVERIFIED for generateContent; Interactions API returns mcp tool call/result steps" ], "result_shape": "UNVERIFIED (Interactions: function_call/function_result-style steps for MCP tools)", "billing": "Not documented (tokens of tool schemas/results presumably billed as input; UNVERIFIED).", "limitations": [ "Streamable HTTP transport only (no SSE) — Interactions docs", "Server names must not contain '-'", "No generateContent guide coverage" ], "security": "Remote servers receive your headers (tokens) from Google's side; only connect to trusted servers.", "beta_header": null, "status": [ "DOCUMENTED", "DOCUMENTATION_INCOMPLETE", "UNVERIFIED" ], "examples": { "curl": "curl -s \"https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash-lite:generateContent\" \\\n -H \"x-goog-api-key: $GEMINI_API_KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"contents\": [{\"parts\": [{\"text\": \"Check the weather in San Francisco.\"}]}], \"tools\": [{\"mcpServers\": [{\"name\": \"weather\", \"streamableHttpTransport\": {\"url\": \"https://gemini-api-demos.uc.r.appspot.com/mcp\"}}]}]}'", "python": "types.Tool(mcp_servers=[types.McpServer(name='weather', streamable_http_transport=types.StreamableHttpTransport(url='https://example.com/mcp'))]) # UNVERIFIED on generateContent", "typescript": "// Interactions API (documented): tools: [{ type: 'mcp_server', name: 'weather', url: 'https://example.com/mcp' }]" }, "verification": { "method": "docs_only", "verified_at": "2026-09-18", "result": "not_tested", "http_status": null, "request_note": "not exercised in the 2026-09-18 run (docs only)" }, "sources": [ { "url": "https://ai.google.dev/api/generate-content#McpServer", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/api/generate-content#StreamableHttpTransport", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/function-calling", "retrieved_at": "2026-09-18" }, { "url": "https://ai.google.dev/gemini-api/docs/deep-research", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/googleapis/python-genai (README: MCP for Gemini Enterprise Agent Platform)", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/tools/gemini-tools.json" }, { "provider": "gemini", "name": "MCP via SDK (client-side automatic tool calling)", "type": "mcp (SDK-side)", "category": "mcp", "description": "Experimental built-in MCP support in google-genai (Python) and @google/genai (JS/TS): pass a connected MCP `ClientSession` directly in `config.tools` (Python) or `mcpToTool(mcpClient)` (JS). The SDK lists the server's tools, converts them to functionDeclarations, and — with automatic function calling enabled (default) — executes model functionCalls against the MCP server and loops until no more calls (max 10 remote calls by default, `automatic_function_calling.maximum_remote_calls`). Disable with `automatic_function_calling: {disable: true}` / `automaticFunctionCalling: {disable: true}` to handle calls manually. Requires the `mcp` package (pip install mcp / @modelcontextprotocol/sdk). Nothing MCP-specific goes over the wire: the API sees ordinary functionDeclarations.", "compatible_models": "Any model with function calling (examples use gemini-3.8-flash / gemini-2.5-flash).", "compatible_endpoints": [ "POST /v1beta/models/{model}:generateContent (SDK wraps it)", "POST /v1beta/models/{model}:streamGenerateContent (stream variants)", "SDK Chats (AFC is moving to Chats in the next major SDK version per README)" ], "parameters_schema": { "python": { "config.tools": "[ClientSession, ...] or python callables", "config.automatic_function_calling": { "disable": "bool", "maximum_remote_calls": "int (default 10)", "ignore_call_history": "bool" } }, "javascript": { "config.tools": "[mcpToTool(client, ...)]", "config.automaticFunctionCalling": { "disable": "bool", "maximumRemoteCalls": "int" } } }, "tool_choice_support": "functionCallingConfig applies as for any declarations (AFC also runs in ANY mode; disable to stop the loop).", "parallel": "AFC executes parallel functionCalls sequentially/asynchronously per SDK; response.automatic_function_calling_history keeps the trace (Python).", "streaming_events": [ "SDK-level only; stream variants supported by AFC in current versions (README warns this moves to Chats)" ], "result_shape": "Final GenerateContentResponse.text after the loop; Python: response.automatic_function_calling_history[] with the intermediate Content objects.", "billing": "Ordinary token billing per model turn; each AFC round trip is a new generateContent request.", "limitations": [ "Experimental; breaking changes possible", "Only MCP tools (no resources, no prompts)", "Python and JS/TS SDKs only", "Python AFC 'currently doesn't parse argument descriptions' into property descriptions — whole docstring becomes the function description (for callables)", "Live API: no automatic tool response handling" ], "security": "The MCP server runs where your SDK runs (stdio/local or remote transport you choose); credentials never reach Google.", "beta_header": null, "status": [ "DOCUMENTED", "BETA" ], "examples": { "curl": "n/a — SDK-only feature (wire format is plain functionDeclarations)", "python": "import asyncio\nfrom mcp import ClientSession, StdioServerParameters\nfrom mcp.client.stdio import stdio_client\nfrom google import genai\nclient = genai.Client()\nasync def main():\n params = StdioServerParameters(command='npx', args=['-y', '@philschmid/weather-mcp'])\n async with stdio_client(params) as (r, w):\n async with ClientSession(r, w) as session:\n await session.initialize()\n resp = await client.aio.models.generate_content(\n model='gemini-3.5-flash-lite', contents='Weather in London today?',\n config=genai.types.GenerateContentConfig(tools=[session]))\n print(resp.text)\nasyncio.run(main())", "typescript": "import { GoogleGenAI, mcpToTool } from '@google/genai';\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js';\nimport { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';\nconst mcp = new Client({ name: 'demo', version: '1.0.0' });\nawait mcp.connect(new StdioClientTransport({ command: 'npx', args: ['-y', '@philschmid/weather-mcp'] }));\nconst ai = new GoogleGenAI({});\nconst resp = await ai.models.generateContent({ model: 'gemini-3.5-flash-lite', contents: 'Weather in London today?', config: { tools: [mcpToTool(mcp)] } });\nconsole.log(resp.text);\nawait mcp.close();" }, "verification": { "method": "docs_only", "verified_at": "2026-09-18", "result": "not_tested", "http_status": null, "request_note": "not exercised in the 2026-09-18 run (docs only)" }, "sources": [ { "url": "https://ai.google.dev/gemini-api/docs/generate-content/function-calling", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/googleapis/python-genai", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/googleapis/js-genai", "retrieved_at": "2026-09-18" } ], "_fragment": "generated/fragments/tools/gemini-tools.json" }, { "provider": "openai", "name": "Function calling (custom function tool)", "type": "function", "category": "client", "description": "Developer-defined function described by a JSON Schema. The model emits a `function_call` item (name + JSON `arguments`); the application executes it and returns a `function_call_output` item. Supports `strict` schemas (structured outputs), `async: true` (GPT-6 Astra+), `defer_loading` (tool search), `allowed_callers` (programmatic tool calling), `output_schema`, and grouping in `namespace` tools.", "compatible_models": [ "chat-latest", "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "gpt-4o", "gpt-4o-mini", "gpt-5", "gpt-5-chat-latest", "gpt-5-codex", "gpt-5-mini", "gpt-5-nano", "gpt-5-pro", "gpt-5.1", "gpt-5.1-chat-latest", "gpt-5.1-codex", "gpt-5.1-codex-max", "gpt-5.1-codex-mini", "gpt-5.2", "gpt-5.2-chat-latest", "gpt-5.2-codex", "gpt-5.2-pro", "gpt-5.3-chat-latest", "gpt-5.3-codex", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.4-pro", "gpt-5.5", "gpt-5.5-pro", "gpt-audio-mini", "gpt-oss-120b", "gpt-oss-20b", "o1", "o1-pro", "o3", "o3-mini", "o3-pro", "o4-mini" ], "compatible_endpoints": [ "POST /v1/responses", "POST /v1/chat/completions", "POST /v1/realtime (session.tools)", "Agents API (agent tool config)" ], "parameters_schema": { "properties": { "type": { "type": "string", "enum": [ "function" ], "description": "The type of the function tool. Always `function`.", "default": "function", "x-stainless-const": true }, "name": { "type": "string", "description": "The name of the function to call." }, "async": { "type": "boolean" }, "description": { "anyOf": [ { "type": "string", "description": "A description of the function. Used by the model to determine whether or not to call the function." }, { "type": "null" } ] }, "parameters": { "anyOf": [ { "additionalProperties": {}, "type": "object", "description": "A JSON schema object describing the parameters of the function." }, { "type": "null" } ] }, "output_schema": { "anyOf": [ { "additionalProperties": {}, "type": "object", "description": "A JSON schema object describing the JSON value encoded in string outputs for this function." }, { "type": "null" } ] }, "strict": { "anyOf": [ { "type": "boolean", "description": "Whether strict parameter validation is enforced for this function tool." }, { "type": "null" } ] }, "defer_loading": { "type": "boolean", "description": "Whether this function is deferred and loaded via tool search." }, "allowed_callers": { "anyOf": [ { "items": { "type": "string", "enum": [ "direct", "programmatic" ] }, "type": "array", "description": "The tool invocation context(s)." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "name", "strict", "parameters" ], "title": "Function", "description": "Defines a function in your own code the model can choose to call. Learn more about [function calling](https://developers.openai.com/api/docs/guides/function-calling)." }, "tool_choice_support": { "modes": [ "none", "auto", "required" ], "allowed_tools": { "type": "allowed_tools", "mode": "auto|required", "tools": [ "{type,name,...}" ] }, "specific": { "type": "function", "name": "" }, "chat_completions": { "type": "function", "function": { "name": "" } } }, "parallel": { "supported": true, "parameter": "parallel_tool_calls (default true)", "notes": "Built-in tools cannot be included in a parallel function-call batch (GPT-5+). Fine-tuned models: strict mode disabled when several functions are called in one turn." }, "streaming_events": [ "response.output_item.added", "response.function_call_arguments.delta", "response.function_call_arguments.done", "response.output_item.done" ], "result_shape": { "items": [ { "schema_name": "FunctionToolCall", "type": "function_call", "schema": { "type": "object", "title": "Function tool call", "description": "A tool call to run a function. See the\n[function calling guide](https://developers.openai.com/api/docs/guides/function-calling) for more information.\n", "properties": { "id": { "type": "string", "description": "The unique ID of the function tool call.\n" }, "type": { "type": "string", "enum": [ "function_call" ], "description": "The type of the function tool call. Always `function_call`.\n", "x-stainless-const": true }, "call_id": { "type": "string", "description": "The unique ID of the function tool call generated by the model.\n" }, "caller": { "anyOf": [ { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "direct" ], "default": "direct", "x-stainless-const": true } }, "type": "object", "required": [ "type" ] }, { "properties": { "type": { "type": "string", "enum": [ "program" ], "default": "program", "x-stainless-const": true }, "caller_id": { "type": "string", "description": "The call ID of the program item that produced this tool call." } }, "type": "object", "required": [ "type", "caller_id" ] } ], "description": "The execution context that produced this tool call.", "discriminator": { "propertyName": "type" } }, { "type": "null" } ] }, "namespace": { "type": "string", "description": "The namespace of the function to run.\n" }, "name": { "type": "string", "description": "The name of the function to run.\n" }, "arguments": { "type": "string", "description": "A JSON string of the arguments to pass to the function.\n" }, "status": { "type": "string", "description": "The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.\n", "enum": [ "in_progress", "completed", "incomplete" ] }, "async": { "type": "boolean", "description": "Whether the function tool call runs asynchronously.\n" } }, "required": [ "type", "call_id", "name", "arguments" ] } }, { "schema_name": "FunctionCallOutputItemParam", "type": "function_call_output", "schema": { "properties": { "id": { "anyOf": [ { "type": "string", "description": "The unique ID of the function tool call output. Populated when this item is returned via API.", "example": "fc_123" }, { "type": "null" } ] }, "call_id": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1, "description": "The unique ID of the function tool call generated by the model." }, { "type": "null" } ] }, "type": { "type": "string", "enum": [ "function_call_output" ], "description": "The type of the function tool call output. Always `function_call_output`.", "default": "function_call_output", "x-stainless-const": true }, "output": { "oneOf": [ { "type": "string", "maxLength": 10485760, "description": "A JSON string of the output of the function tool call." }, { "items": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "input_text" ], "description": "The type of the input item. Always `input_text`.", "default": "input_text", "x-stainless-const": true }, "text": { "type": "string", "maxLength": 10485760, "description": "The text input to the model." }, "prompt_cache_breakpoint": { "anyOf": [ { "properties": { "mode": { "$comment": "depth-limited" } }, "type": "object", "required": [ { "$comment": "depth-limited" } ], "title": "Prompt cache breakpoint", "description": "Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "text" ], "title": "Input text", "description": "A text input to the model." }, { "properties": { "type": { "type": "string", "enum": [ "input_image" ], "description": "The type of the input item. Always `input_image`.", "default": "input_image", "x-stainless-const": true }, "image_url": { "anyOf": [ { "type": "string", "maxLength": 20971520, "format": "uri", "description": "The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL." }, { "type": "null" } ] }, "file_id": { "anyOf": [ { "type": "string", "description": "The ID of the file to be sent to the model.", "example": "file-123" }, { "type": "null" } ] }, "detail": { "anyOf": [ { "type": "string", "enum": [ { "$comment": "depth-limited" }, { "$comment": "depth-limited" }, { "$comment": "depth-limited" }, { "$comment": "depth-limited" } ] }, { "type": "null" } ] }, "prompt_cache_breakpoint": { "anyOf": [ { "properties": { "mode": { "$comment": "depth-limited" } }, "type": "object", "required": [ { "$comment": "depth-limited" } ], "title": "Prompt cache breakpoint", "description": "Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block." }, { "type": "null" } ] } }, "type": "object", "required": [ "type" ], "title": "Input image", "description": "An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision)" }, { "properties": { "type": { "type": "string", "enum": [ "input_file" ], "description": "The type of the input item. Always `input_file`.", "default": "input_file", "x-stainless-const": true }, "file_id": { "anyOf": [ { "type": "string", "description": "The ID of the file to be sent to the model.", "example": "file-123" }, { "type": "null" } ] }, "filename": { "anyOf": [ { "type": "string", "description": "The name of the file to be sent to the model." }, { "type": "null" } ] }, "file_data": { "anyOf": [ { "type": "string", "maxLength": 73400320, "description": "The base64-encoded data of the file to be sent to the model." }, { "type": "null" } ] }, "file_url": { "anyOf": [ { "type": "string", "format": "uri", "description": "The URL of the file to be sent to the model." }, { "type": "null" } ] }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] }, "prompt_cache_breakpoint": { "anyOf": [ { "properties": { "mode": { "$comment": "depth-limited" } }, "type": "object", "required": [ { "$comment": "depth-limited" } ], "title": "Prompt cache breakpoint", "description": "Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block." }, { "type": "null" } ] } }, "type": "object", "required": [ "type" ], "title": "Input file", "description": "A file input to the model." } ], "description": "A piece of message content, such as text, an image, or a file.", "discriminator": { "propertyName": "type" } }, "type": "array", "description": "An array of content outputs (text, image, file) for the function tool call." } ], "description": "Text, image, or file output of the function tool call." }, "name": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "description": "The name of the tool that produced the output." }, { "type": "null" } ] }, "namespace": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$", "description": "The namespace of the tool that produced the output." }, { "type": "null" } ] }, "caller": { "anyOf": [ { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "direct" ], "description": "The caller type. Always `direct`.", "default": "direct", "x-stainless-const": true } }, "type": "object", "required": [ "type" ] }, { "properties": { "type": { "type": "string", "enum": [ "program" ], "description": "The caller type. Always `program`.", "default": "program", "x-stainless-const": true }, "caller_id": { "type": "string", "maxLength": 64, "minLength": 1, "description": "The call ID of the program item that produced this tool call." } }, "type": "object", "required": [ "type", "caller_id" ] } ], "description": "The execution context that produced this tool call.", "discriminator": { "propertyName": "type" } }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ] }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "output" ], "title": "Function tool call output", "description": "The output of a function tool call." } } ], "summary": "Output item `function_call` {id, call_id, name, arguments (JSON string), status, namespace?, caller?, async?}; reply with input item `function_call_output` {call_id, output: string | content array}." }, "billing": { "model": "Function definitions are injected into the system message and billed as input tokens; call arguments are output tokens.", "per_call": null, "source": "https://developers.openai.com/api/docs/pricing#built-in-tools" }, "limitations": [ "Strict mode requires all properties in `required`, `additionalProperties: false`, supported JSON Schema subset; strict schemas are cached and not eligible for ZDR.", "Soft guidance: < 20 functions available at the start of a turn.", "Chat Completions: `strict` defaults to false; Responses: omitted `strict` = best effort strict.", "GPT-6 Astra requires the Responses API for tool calling." ], "security": [ "Validate arguments server-side (schema/regex) before executing; the model can be prompt-injected by tool outputs.", "Reasoning items returned alongside tool calls must be passed back with the outputs (reasoning models)." ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/openai/tools/function-calling/function_calling.sh", "python": "examples/openai/tools/function-calling/function_calling.py", "typescript": "examples/openai/tools/function-calling/function_calling.ts" }, "verification": { "forced_call": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "gpt-5.4-nano: tool_choice {type:function,name:get_weather} -> function_call item, then function_call_output round trip via previous_response_id -> message" }, "streaming": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "response.output_item.added -> response.function_call_arguments.delta x N -> response.function_call_arguments.done -> response.output_item.done" }, "strict_invalid_schema": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 400, "request_note": "missing additionalProperties:false -> 400 invalid_request_error code=invalid_function_parameters param=tools[0].parameters" }, "allowed_tools": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "tool_choice {type:allowed_tools, mode:required, tools:[{type:function,name:get_weather}]} + parallel_tool_calls:false -> function_call" }, "chat_completions": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "gpt-4.1-nano chat.completions tool_choice forced -> choices[0].message.tool_calls[0].function" } }, "sources": [ { "url": "https://developers.openai.com/api/docs/guides/function-calling", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/docs/guides/async-tool-calling", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/tools/openai-tools.json" }, { "provider": "openai", "name": "Custom tool (free-form text or CFG grammar)", "type": "custom", "category": "client", "description": "Like a function but the model emits an arbitrary string (`custom_tool_call.input`) instead of JSON arguments. `format` is `{type: text}` (default) or `{type: grammar, syntax: lark|regex, definition}` constraining sampling (LLGuidance; Rust regex syntax).", "compatible_models": [ "chat-latest", "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "gpt-4o", "gpt-4o-mini", "gpt-5", "gpt-5-chat-latest", "gpt-5-codex", "gpt-5-mini", "gpt-5-nano", "gpt-5-pro", "gpt-5.1", "gpt-5.1-chat-latest", "gpt-5.1-codex", "gpt-5.1-codex-max", "gpt-5.1-codex-mini", "gpt-5.2", "gpt-5.2-chat-latest", "gpt-5.2-codex", "gpt-5.2-pro", "gpt-5.3-chat-latest", "gpt-5.3-codex", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.4-pro", "gpt-5.5", "gpt-5.5-pro", "gpt-audio-mini", "gpt-oss-120b", "gpt-oss-20b", "o1", "o1-pro", "o3", "o3-mini", "o3-pro", "o4-mini" ], "compatible_endpoints": [ "POST /v1/responses", "POST /v1/chat/completions" ], "parameters_schema": { "properties": { "type": { "type": "string", "enum": [ "custom" ], "description": "The type of the custom tool. Always `custom`.", "default": "custom", "x-stainless-const": true }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls." }, "async": { "type": "boolean", "description": "Whether the tool response can be returned asynchronously versus immediately returned on next response creation." }, "description": { "type": "string", "description": "Optional description of the custom tool, used to provide more context." }, "format": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Unconstrained text format. Always `text`.", "default": "text", "x-stainless-const": true } }, "type": "object", "required": [ "type" ], "title": "Text format", "description": "Unconstrained free-form text." }, { "properties": { "type": { "type": "string", "enum": [ "grammar" ], "description": "Grammar format. Always `grammar`.", "default": "grammar", "x-stainless-const": true }, "syntax": { "type": "string", "enum": [ "lark", "regex" ] }, "definition": { "type": "string", "description": "The grammar definition." } }, "type": "object", "required": [ "type", "syntax", "definition" ], "title": "Grammar format", "description": "A grammar defined by the user." } ], "description": "The input format for the custom tool. Default is unconstrained text.", "discriminator": { "propertyName": "type" } }, "defer_loading": { "type": "boolean", "description": "Whether this tool should be deferred and discovered via tool search." }, "allowed_callers": { "anyOf": [ { "items": { "type": "string", "enum": [ "direct", "programmatic" ] }, "type": "array", "minItems": 1, "description": "The tool invocation context(s)." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "name" ], "title": "Custom tool", "description": "A custom tool that processes input using a specified format. Learn more about [custom tools](https://developers.openai.com/api/docs/guides/function-calling#custom-tools)" }, "tool_choice_support": { "modes": [ "none", "auto", "required" ], "allowed_tools": { "type": "allowed_tools", "mode": "auto|required", "tools": [ "{type,name,...}" ] }, "specific": { "type": "custom", "name": "" }, "chat_completions": { "type": "custom", "custom": { "name": "" } } }, "parallel": { "supported": true, "parameter": "parallel_tool_calls" }, "streaming_events": [ "response.output_item.added", "response.custom_tool_call_input.delta", "response.custom_tool_call_input.done", "response.output_item.done" ], "result_shape": { "items": [ { "schema_name": "CustomToolCall", "type": "custom_tool_call", "schema": { "type": "object", "title": "Custom tool call", "description": "A call to a custom tool created by the model.\n", "properties": { "type": { "type": "string", "enum": [ "custom_tool_call" ], "x-stainless-const": true, "description": "The type of the custom tool call. Always `custom_tool_call`.\n" }, "id": { "type": "string", "description": "The unique ID of the custom tool call in the OpenAI platform.\n" }, "call_id": { "type": "string", "description": "An identifier used to map this custom tool call to a tool call output.\n" }, "caller": { "anyOf": [ { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "direct" ], "default": "direct", "x-stainless-const": true } }, "type": "object", "required": [ "type" ] }, { "properties": { "type": { "type": "string", "enum": [ "program" ], "default": "program", "x-stainless-const": true }, "caller_id": { "type": "string", "description": "The call ID of the program item that produced this tool call." } }, "type": "object", "required": [ "type", "caller_id" ] } ], "description": "The execution context that produced this tool call.", "discriminator": { "propertyName": "type" } }, { "type": "null" } ] }, "namespace": { "type": "string", "description": "The namespace of the custom tool being called.\n" }, "name": { "type": "string", "description": "The name of the custom tool being called.\n" }, "input": { "type": "string", "description": "The input for the custom tool call generated by the model.\n" }, "async": { "type": "boolean", "description": "Whether the custom tool call runs asynchronously.\n" } }, "required": [ "type", "call_id", "name", "input" ] } }, { "schema_name": "CustomToolCallOutput", "type": "custom_tool_call_output", "schema": { "type": "object", "title": "Custom tool call output", "description": "The output of a custom tool call from your code, being sent back to the model.\n", "properties": { "type": { "type": "string", "enum": [ "custom_tool_call_output" ], "x-stainless-const": true, "description": "The type of the custom tool call output. Always `custom_tool_call_output`.\n" }, "id": { "type": "string", "description": "The unique ID of the custom tool call output in the OpenAI platform.\n" }, "call_id": { "type": "string", "description": "The call ID, used to map this custom tool call output to a custom tool call.\n" }, "caller": { "anyOf": [ { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "direct" ], "description": "The caller type. Always `direct`.", "default": "direct", "x-stainless-const": true } }, "type": "object", "required": [ "type" ] }, { "properties": { "type": { "type": "string", "enum": [ "program" ], "description": "The caller type. Always `program`.", "default": "program", "x-stainless-const": true }, "caller_id": { "type": "string", "maxLength": 64, "minLength": 1, "description": "The call ID of the program item that produced this tool call." } }, "type": "object", "required": [ "type", "caller_id" ] } ], "description": "The execution context that produced this tool call.", "discriminator": { "propertyName": "type" } }, { "type": "null" } ] }, "output": { "description": "The output from the custom tool call generated by your code.\nCan be a string or an list of output content.\n", "oneOf": [ { "type": "string", "description": "A string of the output of the custom tool call.\n", "title": "string output" }, { "type": "array", "items": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "input_text" ], "description": "The type of the input item. Always `input_text`.", "default": "input_text", "x-stainless-const": true }, "text": { "type": "string", "description": "The text input to the model." }, "prompt_cache_breakpoint": { "properties": { "mode": { "type": { "$comment": "depth-limited" }, "enum": { "$comment": "depth-limited" }, "description": { "$comment": "depth-limited" }, "default": { "$comment": "depth-limited" }, "x-stainless-const": { "$comment": "depth-limited" } } }, "type": "object", "required": [ "mode" ], "title": "Prompt cache breakpoint", "description": "Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block." } }, "type": "object", "required": [ "type", "text" ], "title": "Input text", "description": "A text input to the model." }, { "properties": { "type": { "type": "string", "enum": [ "input_image" ], "description": "The type of the input item. Always `input_image`.", "default": "input_image", "x-stainless-const": true }, "image_url": { "anyOf": [ { "type": "string", "format": "uri", "description": "The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL." }, { "type": "null" } ] }, "file_id": { "anyOf": [ { "type": "string", "description": "The ID of the file to be sent to the model." }, { "type": "null" } ] }, "detail": { "type": "string", "enum": [ "low", "high", "auto", "original" ] }, "prompt_cache_breakpoint": { "properties": { "mode": { "type": { "$comment": "depth-limited" }, "enum": { "$comment": "depth-limited" }, "description": { "$comment": "depth-limited" }, "default": { "$comment": "depth-limited" }, "x-stainless-const": { "$comment": "depth-limited" } } }, "type": "object", "required": [ "mode" ], "title": "Prompt cache breakpoint", "description": "Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block." } }, "type": "object", "required": [ "type", "detail" ], "title": "Input image", "description": "An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision)." }, { "properties": { "type": { "type": "string", "enum": [ "input_file" ], "description": "The type of the input item. Always `input_file`.", "default": "input_file", "x-stainless-const": true }, "file_id": { "anyOf": [ { "type": "string", "description": "The ID of the file to be sent to the model." }, { "type": "null" } ] }, "filename": { "type": "string", "description": "The name of the file to be sent to the model." }, "file_data": { "type": "string", "description": "The content of the file to be sent to the model.\n" }, "prompt_cache_breakpoint": { "properties": { "mode": { "type": { "$comment": "depth-limited" }, "enum": { "$comment": "depth-limited" }, "description": { "$comment": "depth-limited" }, "default": { "$comment": "depth-limited" }, "x-stainless-const": { "$comment": "depth-limited" } } }, "type": "object", "required": [ "mode" ], "title": "Prompt cache breakpoint", "description": "Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block." }, "file_url": { "type": "string", "format": "uri", "description": "The URL of the file to be sent to the model." }, "detail": { "type": "string", "enum": [ "auto", "low", "high" ] } }, "type": "object", "required": [ "type" ], "title": "Input file", "description": "A file input to the model." } ], "discriminator": { "propertyName": "type" } }, "title": "output content list", "description": "Text, image, or file output of the custom tool call.\n" } ] } }, "required": [ "type", "call_id", "output" ] } } ], "summary": "Output item `custom_tool_call` {id, call_id, name, input: string, status}; reply with `custom_tool_call_output` {call_id, output}." }, "billing": { "model": "Token billing only.", "source": "https://developers.openai.com/api/docs/pricing#built-in-tools" }, "limitations": [ "Grammar too complex -> API error; keep terminals bounded; no verbose regex mode; Lark subset only.", "Chat Completions shape differs: {type: custom, custom: {name, description, format: {type: grammar, grammar: {syntax, definition}}}}." ], "security": [ "Grammar constrains syntax, not semantics — still validate the input before acting on it." ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/openai/tools/custom-tools/custom_tools.sh", "python": "examples/openai/tools/custom-tools/custom_tools.py", "typescript": "examples/openai/tools/custom-tools/custom_tools.ts" }, "verification": { "regex_grammar": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "gpt-5.4-nano: format grammar regex ^(yes|no)$ forced -> custom_tool_call input='yes'" }, "text_format": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "gpt-5.4-nano: default text format, tool_choice required -> custom_tool_call" }, "streaming": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "response.custom_tool_call_input.delta -> .done" } }, "sources": [ { "url": "https://developers.openai.com/api/docs/guides/function-calling#custom-tools", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/tools/openai-tools.json" }, { "provider": "openai", "name": "Namespace (group of function/custom tools)", "type": "namespace", "category": "client", "description": "Groups function/custom tools under a shared namespace with its own description. Calls come back as `function_call`/`custom_tool_call` items carrying a `namespace` field. Namespaces are the recommended unit for deferred loading with `tool_search`.", "compatible_models": [ "chat-latest", "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "gpt-4o", "gpt-4o-mini", "gpt-5", "gpt-5-chat-latest", "gpt-5-codex", "gpt-5-mini", "gpt-5-nano", "gpt-5-pro", "gpt-5.1", "gpt-5.1-chat-latest", "gpt-5.1-codex", "gpt-5.1-codex-max", "gpt-5.1-codex-mini", "gpt-5.2", "gpt-5.2-chat-latest", "gpt-5.2-codex", "gpt-5.2-pro", "gpt-5.3-chat-latest", "gpt-5.3-codex", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.4-pro", "gpt-5.5", "gpt-5.5-pro", "gpt-audio-mini", "gpt-oss-120b", "gpt-oss-20b", "o1", "o1-pro", "o3", "o3-mini", "o3-pro", "o4-mini" ], "compatible_endpoints": [ "POST /v1/responses" ], "parameters_schema": { "properties": { "type": { "type": "string", "enum": [ "namespace" ], "description": "The type of the tool. Always `namespace`.", "default": "namespace", "x-stainless-const": true }, "name": { "type": "string", "minLength": 1, "description": "The namespace name used in tool calls (for example, `crm`)." }, "description": { "type": "string", "description": "A description of the namespace shown to the model." }, "tools": { "items": { "oneOf": [ { "properties": { "name": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "parameters": { "anyOf": [ { "properties": {}, "type": "object", "required": [] }, { "type": "null" } ] }, "strict": { "anyOf": [ { "type": "boolean", "description": "Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise." }, { "type": "null" } ] }, "type": { "type": "string", "enum": [ "function" ], "default": "function", "x-stainless-const": true }, "async": { "type": "boolean", "description": "Whether the tool response can be returned asynchronously versus immediately returned on next response creation." }, "output_schema": { "anyOf": [ { "additionalProperties": {}, "type": "object", "description": "A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs." }, { "type": "null" } ] }, "defer_loading": { "type": "boolean", "description": "Whether this function should be deferred and discovered via tool search." }, "allowed_callers": { "anyOf": [ { "items": { "type": "string", "enum": [ "direct", "programmatic" ] }, "type": "array", "minItems": 1, "description": "The tool invocation context(s)." }, { "type": "null" } ] } }, "type": "object", "required": [ "name", "type" ] }, { "properties": { "type": { "type": "string", "enum": [ "custom" ], "description": "The type of the custom tool. Always `custom`.", "default": "custom", "x-stainless-const": true }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls." }, "async": { "type": "boolean", "description": "Whether the tool response can be returned asynchronously versus immediately returned on next response creation." }, "description": { "type": "string", "description": "Optional description of the custom tool, used to provide more context." }, "format": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ { "$comment": "depth-limited" } ], "description": "Unconstrained text format. Always `text`.", "default": "text", "x-stainless-const": true } }, "type": "object", "required": [ "type" ], "title": "Text format", "description": "Unconstrained free-form text." }, { "properties": { "type": { "type": "string", "enum": [ { "$comment": "depth-limited" } ], "description": "Grammar format. Always `grammar`.", "default": "grammar", "x-stainless-const": true }, "syntax": { "type": { "$comment": "depth-limited" }, "enum": { "$comment": "depth-limited" } }, "definition": { "type": "string", "description": "The grammar definition." } }, "type": "object", "required": [ "type", "syntax", "definition" ], "title": "Grammar format", "description": "A grammar defined by the user." } ], "description": "The input format for the custom tool. Default is unconstrained text.", "discriminator": { "propertyName": "type" } }, "defer_loading": { "type": "boolean", "description": "Whether this tool should be deferred and discovered via tool search." }, "allowed_callers": { "anyOf": [ { "items": { "type": "string", "enum": [ "direct", "programmatic" ] }, "type": "array", "minItems": 1, "description": "The tool invocation context(s)." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "name" ], "title": "Custom tool", "description": "A custom tool that processes input using a specified format. Learn more about [custom tools](https://developers.openai.com/api/docs/guides/function-calling#custom-tools)" } ], "description": "A function or custom tool that belongs to a namespace.", "discriminator": { "propertyName": "type" } }, "type": "array", "minItems": 1, "description": "The function/custom tools available inside this namespace." } }, "type": "object", "required": [ "type", "name", "description", "tools" ], "title": "Namespace", "description": "Groups function/custom tools under a shared namespace." }, "tool_choice_support": { "modes": [ "none", "auto", "required" ], "allowed_tools": { "type": "allowed_tools", "mode": "auto|required", "tools": [ "{type,name,...}" ] }, "note": "tool_choice targets the inner tool by name" }, "parallel": { "supported": true, "parameter": "parallel_tool_calls" }, "streaming_events": [ "response.output_item.added", "response.function_call_arguments.delta", "response.function_call_arguments.done", "response.output_item.done" ], "result_shape": { "items": [ { "schema_name": "FunctionToolCall", "type": "function_call", "schema": { "type": "object", "title": "Function tool call", "description": "A tool call to run a function. See the\n[function calling guide](https://developers.openai.com/api/docs/guides/function-calling) for more information.\n", "properties": { "id": { "type": "string", "description": "The unique ID of the function tool call.\n" }, "type": { "type": "string", "enum": [ "function_call" ], "description": "The type of the function tool call. Always `function_call`.\n", "x-stainless-const": true }, "call_id": { "type": "string", "description": "The unique ID of the function tool call generated by the model.\n" }, "caller": { "anyOf": [ { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "direct" ], "default": "direct", "x-stainless-const": true } }, "type": "object", "required": [ "type" ] }, { "properties": { "type": { "type": "string", "enum": [ "program" ], "default": "program", "x-stainless-const": true }, "caller_id": { "type": "string", "description": "The call ID of the program item that produced this tool call." } }, "type": "object", "required": [ "type", "caller_id" ] } ], "description": "The execution context that produced this tool call.", "discriminator": { "propertyName": "type" } }, { "type": "null" } ] }, "namespace": { "type": "string", "description": "The namespace of the function to run.\n" }, "name": { "type": "string", "description": "The name of the function to run.\n" }, "arguments": { "type": "string", "description": "A JSON string of the arguments to pass to the function.\n" }, "status": { "type": "string", "description": "The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.\n", "enum": [ "in_progress", "completed", "incomplete" ] }, "async": { "type": "boolean", "description": "Whether the function tool call runs asynchronously.\n" } }, "required": [ "type", "call_id", "name", "arguments" ] } }, { "schema_name": "CustomToolCall", "type": "custom_tool_call", "schema": { "type": "object", "title": "Custom tool call", "description": "A call to a custom tool created by the model.\n", "properties": { "type": { "type": "string", "enum": [ "custom_tool_call" ], "x-stainless-const": true, "description": "The type of the custom tool call. Always `custom_tool_call`.\n" }, "id": { "type": "string", "description": "The unique ID of the custom tool call in the OpenAI platform.\n" }, "call_id": { "type": "string", "description": "An identifier used to map this custom tool call to a tool call output.\n" }, "caller": { "anyOf": [ { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "direct" ], "default": "direct", "x-stainless-const": true } }, "type": "object", "required": [ "type" ] }, { "properties": { "type": { "type": "string", "enum": [ "program" ], "default": "program", "x-stainless-const": true }, "caller_id": { "type": "string", "description": "The call ID of the program item that produced this tool call." } }, "type": "object", "required": [ "type", "caller_id" ] } ], "description": "The execution context that produced this tool call.", "discriminator": { "propertyName": "type" } }, { "type": "null" } ] }, "namespace": { "type": "string", "description": "The namespace of the custom tool being called.\n" }, "name": { "type": "string", "description": "The name of the custom tool being called.\n" }, "input": { "type": "string", "description": "The input for the custom tool call generated by the model.\n" }, "async": { "type": "boolean", "description": "Whether the custom tool call runs asynchronously.\n" } }, "required": [ "type", "call_id", "name", "input" ] } } ], "summary": "Inner tool call items gain `namespace: `; `function_call_output` may echo `namespace`." }, "billing": { "model": "Token billing only.", "source": "https://developers.openai.com/api/docs/pricing#built-in-tools" }, "limitations": [ "`defer_loading` applies to the tools inside the namespace, not the namespace object.", "Model pages do not list `namespace` separately; availability follows function calling (verified on gpt-5.4-nano)." ], "security": [ "Same as function calling." ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/openai/tools/function-calling/function_calling.sh", "python": "examples/openai/tools/function-calling/function_calling.py", "typescript": "examples/openai/tools/function-calling/function_calling.ts" }, "verification": { "namespace_call": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "gpt-5.4-nano: namespace 'weather' wrapping get_weather, tool_choice required -> function_call with namespace='weather'" } }, "sources": [ { "url": "https://developers.openai.com/api/docs/guides/function-calling#namespaces", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/docs/guides/tools-tool-search", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/tools/openai-tools.json" }, { "provider": "openai", "name": "Tool search (deferred tool loading)", "type": "tool_search", "category": "hosted", "description": "Lets the model discover tools marked `defer_loading: true` (functions, namespaces, MCP servers) on demand. `execution: server` (hosted, default) emits `tool_search_call` + `tool_search_output` items automatically; `execution: client` stops after `tool_search_call` and the app returns a `tool_search_output` item with tool definitions. Deferred tools are loaded at the end of context to preserve prompt caching.", "compatible_models": [ "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-pro", "gpt-5.5", "gpt-5.6-cyber", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-6-astra", "gpt-daybreak-blue-latest", "gpt-daybreak-red-latest" ], "compatible_endpoints": [ "POST /v1/responses", "Agents API (session tools)" ], "parameters_schema": { "properties": { "type": { "type": "string", "enum": [ "tool_search" ], "description": "The type of the tool. Always `tool_search`.", "default": "tool_search", "x-stainless-const": true }, "execution": { "type": "string", "enum": [ "server", "client" ] }, "description": { "anyOf": [ { "type": "string", "description": "Description shown to the model for a client-executed tool search tool." }, { "type": "null" } ] }, "parameters": { "anyOf": [ { "properties": {}, "type": "object", "required": [] }, { "type": "null" } ] } }, "type": "object", "required": [ "type" ], "title": "Tool search tool", "description": "Hosted or BYOT tool search configuration for deferred tools." }, "tool_choice_support": { "modes": [ "auto", "required", "none" ], "note": "tool_choice applies to the tools currently callable in the turn" }, "parallel": { "supported": false, "notes": "Search happens before the eventual function call." }, "streaming_events": [ "response.output_item.added", "response.output_item.done" ], "result_shape": { "items": [ { "schema_name": "ToolSearchCall", "type": "tool_search_call", "schema": { "properties": { "type": { "type": "string", "enum": [ "tool_search_call" ], "description": "The type of the item. Always `tool_search_call`.", "default": "tool_search_call", "x-stainless-const": true }, "id": { "type": "string", "description": "The unique ID of the tool search call item." }, "call_id": { "anyOf": [ { "type": "string", "description": "The unique ID of the tool search call generated by the model." }, { "type": "null" } ] }, "execution": { "type": "string", "enum": [ "server", "client" ] }, "arguments": { "description": "Arguments used for the tool search call." }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ] }, "created_by": { "type": "string", "description": "The identifier of the actor that created the item." } }, "type": "object", "required": [ "type", "id", "call_id", "execution", "arguments", "status" ] } }, { "schema_name": "ToolSearchOutput", "type": "tool_search_output", "schema": { "properties": { "type": { "type": "string", "enum": [ "tool_search_output" ], "description": "The type of the item. Always `tool_search_output`.", "default": "tool_search_output", "x-stainless-const": true }, "id": { "type": "string", "description": "The unique ID of the tool search output item." }, "call_id": { "anyOf": [ { "type": "string", "description": "The unique ID of the tool search call generated by the model." }, { "type": "null" } ] }, "execution": { "type": "string", "enum": [ "server", "client" ] }, "tools": { "items": { "description": "A tool that can be used to generate a response.\n", "discriminator": { "propertyName": "type" }, "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "function" ], "description": "The type of the function tool. Always `function`.", "default": "function", "x-stainless-const": true }, "name": { "type": "string", "description": "The name of the function to call." }, "async": { "type": "boolean" }, "description": { "anyOf": [ { "type": "string", "description": "A description of the function. Used by the model to determine whether or not to call the function." }, { "type": "null" } ] }, "parameters": { "anyOf": [ { "additionalProperties": {}, "type": "object", "description": "A JSON schema object describing the parameters of the function." }, { "type": "null" } ] }, "output_schema": { "anyOf": [ { "additionalProperties": {}, "type": "object", "description": "A JSON schema object describing the JSON value encoded in string outputs for this function." }, { "type": "null" } ] }, "strict": { "anyOf": [ { "type": "boolean", "description": "Whether strict parameter validation is enforced for this function tool." }, { "type": "null" } ] }, "defer_loading": { "type": "boolean", "description": "Whether this function is deferred and loaded via tool search." }, "allowed_callers": { "anyOf": [ { "items": { "type": "string", "enum": [ { "$comment": "depth-limited" }, { "$comment": "depth-limited" } ] }, "type": "array", "description": "The tool invocation context(s)." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "name", "strict", "parameters" ], "title": "Function", "description": "Defines a function in your own code the model can choose to call. Learn more about [function calling](https://developers.openai.com/api/docs/guides/function-calling)." }, { "properties": { "type": { "type": "string", "enum": [ "file_search" ], "description": "The type of the file search tool. Always `file_search`.", "default": "file_search", "x-stainless-const": true }, "vector_store_ids": { "items": { "type": "string" }, "type": "array", "description": "The IDs of the vector stores to search." }, "max_num_results": { "type": "integer", "description": "The maximum number of results to return. This number should be between 1 and 50 inclusive." }, "ranking_options": { "properties": { "ranker": { "type": "string", "enum": [ { "$comment": "depth-limited" }, { "$comment": "depth-limited" } ] }, "score_threshold": { "type": "number", "description": "The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results." }, "hybrid_search": { "properties": { "embedding_weight": { "$comment": "depth-limited" }, "text_weight": { "$comment": "depth-limited" } }, "type": "object", "required": [ { "$comment": "depth-limited" }, { "$comment": "depth-limited" } ] } }, "type": "object", "required": [] }, "filters": { "anyOf": [ { "anyOf": [ { "$comment": "depth-limited" }, { "$comment": "depth-limited" } ] }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "vector_store_ids" ], "title": "File search", "description": "A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://developers.openai.com/api/docs/guides/tools-file-search)." }, { "properties": { "type": { "type": "string", "enum": [ "computer" ], "description": "The type of the computer tool. Always `computer`.", "default": "computer", "x-stainless-const": true } }, "type": "object", "required": [ "type" ], "title": "Computer", "description": "A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use)." }, { "properties": { "type": { "type": "string", "enum": [ "computer_use_preview" ], "description": "The type of the computer use tool. Always `computer_use_preview`.", "default": "computer_use_preview", "x-stainless-const": true }, "environment": { "type": "string", "enum": [ "windows", "mac", "linux", "ubuntu", "browser" ] }, "display_width": { "type": "integer", "description": "The width of the computer display." }, "display_height": { "type": "integer", "description": "The height of the computer display." } }, "type": "object", "required": [ "type", "environment", "display_width", "display_height" ], "title": "Computer use preview", "description": "A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use)." }, { "type": "object", "title": "Web search", "description": "Search the Internet for sources related to the prompt. Learn more about the\n[web search tool](https://developers.openai.com/api/docs/guides/tools-web-search).\n", "properties": { "type": { "type": "string", "enum": [ "web_search", "web_search_2025_08_26" ], "description": "The type of the web search tool. One of `web_search` or `web_search_2025_08_26`.", "default": "web_search" }, "external_web_access": { "type": "boolean", "default": true, "description": "Allow live internet access for web search. Defaults to true when omitted. When false, the web search tool runs in offline/cache-only mode and will not fetch new external content." }, "filters": { "anyOf": [ { "type": "object", "description": "Filters for the search.\n", "properties": { "allowed_domains": { "anyOf": [ { "$comment": "depth-limited" }, { "$comment": "depth-limited" } ] } } }, { "type": "null" } ] }, "user_location": { "anyOf": [ { "type": "object", "title": "Web search approximate location", "description": "The approximate location of the user.\n", "properties": { "type": { "type": { "$comment": "depth-limited" }, "enum": { "$comment": "depth-limited" }, "description": { "$comment": "depth-limited" }, "default": { "$comment": "depth-limited" }, "x-stainless-const": { "$comment": "depth-limited" } }, "country": { "anyOf": { "$comment": "depth-limited" } }, "region": { "anyOf": { "$comment": "depth-limited" } }, "city": { "anyOf": { "$comment": "depth-limited" } }, "timezone": { "anyOf": { "$comment": "depth-limited" } } } }, { "type": "null" } ] }, "search_context_size": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium", "description": "High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default." } }, "required": [ "type" ] }, { "type": "object", "title": "MCP tool", "description": "Give the model access to additional tools via remote Model Context Protocol\n(MCP) servers. [Learn more about MCP](https://developers.openai.com/api/docs/guides/tools-connectors-mcp).\n", "properties": { "type": { "type": "string", "enum": [ "mcp" ], "description": "The type of the MCP tool. Always `mcp`.", "x-stainless-const": true }, "server_label": { "type": "string", "description": "A label for this MCP server, used to identify it in tool calls.\n" }, "server_url": { "type": "string", "format": "uri", "description": "The URL for the MCP server. One of `server_url`, `connector_id`, or\n`tunnel_id` must be provided.\n" }, "connector_id": { "type": "string", "deprecated": true, "enum": [ "connector_dropbox", "connector_gmail", "connector_googlecalendar", "connector_googledrive", "connector_microsoftteams", "connector_outlookcalendar", "connector_outlookemail", "connector_sharepoint" ], "description": "Identifier for service connectors, like those available in ChatGPT. One of\n`server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more\nabout service connectors [here](https://developers.openai.com/api/docs/guides/tools-connectors-mcp#connectors).\n\nThis field is deprecated for models released after September 1, 2026.\nUse `server_url` to connect to a remote MCP server, or `tunnel_id` to\nconnect through a Secure MCP Tunnel.\n\nCurrently supported `connector_id` values are:\n\n- Dropbox: `connector_dropbox`\n- Gmail: `connector_gmail`\n- Google Calendar: `connector_googlecalendar`\n- Google Drive: `connector_googledrive`\n- Microsoft Teams: `connector_microsoftteams`\n- Outlook Calendar: `connector_outlookcalendar`\n- Outlook Email: `connector_outlookemail`\n- SharePoint: `connector_sharepoint`\n" }, "tunnel_id": { "type": "string", "pattern": "^tunnel_[a-z0-9]{32}$", "description": "The Secure MCP Tunnel ID to use instead of a direct server URL. One of\n`server_url`, `connector_id`, or `tunnel_id` must be provided.\n" }, "authorization": { "type": "string", "description": "An OAuth access token that can be used with a remote MCP server, either\nwith a custom MCP server URL or a service connector. Your application\nmust handle the OAuth authorization flow and provide the token here.\n" }, "server_description": { "type": "string", "description": "Optional description of the MCP server, used to provide more context.\n" }, "headers": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional HTTP headers to send to the MCP server. Use for authentication\nor other purposes.\n" }, { "type": "null" } ] }, "allowed_tools": { "anyOf": [ { "description": "List of allowed tool names or a filter object.\n", "oneOf": [ { "type": "array", "title": "MCP allowed tools", "description": "A string array of allowed tool names", "items": { "type": { "$comment": "depth-limited" } } }, { "type": { "$comment": "depth-limited" }, "title": { "$comment": "depth-limited" }, "description": { "$comment": "depth-limited" }, "properties": { "$comment": "depth-limited" }, "required": { "$comment": "depth-limited" }, "additionalProperties": { "$comment": "depth-limited" } } ] }, { "type": "null" } ] }, "allowed_callers": { "anyOf": [ { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ { "$comment": "depth-limited" }, { "$comment": "depth-limited" } ] }, "description": "The tool invocation context(s)." }, { "type": "null" } ] }, "require_approval": { "anyOf": [ { "description": "Specify which of the MCP server's tools require approval.", "oneOf": [ { "type": "object", "title": "MCP tool approval filter", "description": "Specify which of the MCP server's tools require approval. Can be\n`always`, `never`, or a filter object associated with tools\nthat require approval.\n", "properties": { "always": { "$comment": "depth-limited" }, "never": { "$comment": "depth-limited" } }, "additionalProperties": false }, { "type": "string", "title": "MCP tool approval setting", "description": "Specify a single approval policy for all tools. One of `always` or\n`never`. When set to `always`, all tools will require approval. When\nset to `never`, all tools will not require approval.\n", "enum": [ { "$comment": "depth-limited" }, { "$comment": "depth-limited" } ] } ], "default": "always" }, { "type": "null" } ] }, "defer_loading": { "type": "boolean", "description": "Whether this MCP tool is deferred and discovered via tool search.\n" } }, "required": [ "type", "server_label" ] }, { "type": "object", "title": "Code interpreter", "description": "A tool that runs Python code to help generate a response to a prompt.\n", "properties": { "type": { "type": "string", "enum": [ "code_interpreter" ], "description": "The type of the code interpreter tool. Always `code_interpreter`.\n", "x-stainless-const": true }, "container": { "description": "The code interpreter container. Can be a container ID or an object that\nspecifies uploaded file IDs to make available to your code, along with an\noptional `memory_limit` setting.\n", "oneOf": [ { "type": "string", "description": "The container ID." }, { "properties": { "type": { "type": { "$comment": "depth-limited" }, "enum": { "$comment": "depth-limited" }, "description": { "$comment": "depth-limited" }, "default": { "$comment": "depth-limited" }, "x-stainless-const": { "$comment": "depth-limited" } }, "file_ids": { "items": { "$comment": "depth-limited" }, "type": { "$comment": "depth-limited" }, "maxItems": { "$comment": "depth-limited" }, "description": { "$comment": "depth-limited" } }, "memory_limit": { "anyOf": { "$comment": "depth-limited" } }, "network_policy": { "oneOf": { "$comment": "depth-limited" }, "description": { "$comment": "depth-limited" }, "discriminator": { "$comment": "depth-limited" } } }, "type": "object", "required": [ "type" ], "title": "CodeInterpreterToolAuto", "description": "Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on." } ] }, "allowed_callers": { "anyOf": [ { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ { "$comment": "depth-limited" }, { "$comment": "depth-limited" } ] }, "description": "The tool invocation context(s)." }, { "type": "null" } ] } }, "required": [ "type", "container" ] }, { "properties": { "type": { "type": "string", "enum": [ "programmatic_tool_calling" ], "description": "The type of the tool. Always `programmatic_tool_calling`.", "default": "programmatic_tool_calling", "x-stainless-const": true } }, "type": "object", "required": [ "type" ] }, { "type": "object", "title": "Image generation tool", "description": "A tool that generates images using the GPT image models.\n", "properties": { "type": { "type": "string", "enum": [ "image_generation" ], "description": "The type of the image generation tool. Always `image_generation`.\n", "x-stainless-const": true }, "model": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "gpt-image-1", "gpt-image-1-mini", "gpt-image-1.5", "gpt-image-2", "gpt-image-2-2026-04-21", "gpt-image-2.5-sunburst", "gpt-image-2.5-sunburst-2026-09-08", "gpt-image-2.5-flare", "gpt-image-2.5-flare-2026-09-08" ], "description": "The image generation model to use. One of `gpt-image-1`,\n`gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`,\n`gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`,\n`gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`,\n`gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`. Default:\n`gpt-image-1`.\n", "default": "gpt-image-1" } ] }, "quality": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max", "auto" ], "description": "The quality of the generated image. The GPT image models support `low`,\n`medium`, and `high`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`,\nincluding their `2026-09-08` snapshots, also support `xhigh` and `max`.\nDefault: `auto`.\n", "default": "auto" }, "size": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "1024x1024", "1024x1536", "1536x1024", "auto" ] } ], "description": "The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`.", "default": "auto" }, "output_format": { "type": "string", "enum": [ "png", "webp", "jpeg" ], "description": "The output format of the generated image. One of `png`, `webp`, or\n`jpeg`. Default: `png`.\n", "default": "png" }, "output_compression": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Compression level for the output image. Default: 100.\n", "default": 100 }, "moderation": { "type": "string", "enum": [ "auto", "low" ], "description": "Moderation level for the generated image. Default: `auto`.\n", "default": "auto" }, "background": { "type": "string", "enum": [ "transparent", "opaque", "auto" ], "description": "Set the background of the generated image. One of `transparent`, `opaque`,\nor `auto`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including\ntheir `2026-09-08` snapshots, support `opaque` and `transparent`\nbackgrounds. Transparent backgrounds are available for supported GPT Image\nmodels. For `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in\npreview. When using `transparent`, set the output format to `png` or `webp`.\nDefault: `auto`.\n", "default": "auto" }, "input_fidelity": { "anyOf": [ { "type": "string", "enum": [ "high", "low" ], "description": "Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`." }, { "type": "null" } ] }, "input_image_mask": { "type": "object", "description": "Optional mask for inpainting. Contains `image_url`\n(string, optional) and `file_id` (string, optional).\n", "properties": { "image_url": { "type": "string", "description": "Base64-encoded mask image.\n" }, "file_id": { "type": "string", "description": "File ID for the mask image.\n" } }, "required": [], "additionalProperties": false }, "partial_images": { "type": "integer", "minimum": 0, "maximum": 3, "description": "Number of partial images to generate in streaming mode, from 0 (default value) to 3.\n", "default": 0 }, "action": { "type": "string", "enum": [ "generate", "edit", "auto" ] } }, "required": [ "type" ] }, { "properties": { "type": { "type": "string", "enum": [ "local_shell" ], "description": "The type of the local shell tool. Always `local_shell`.", "default": "local_shell", "x-stainless-const": true } }, "type": "object", "required": [ "type" ], "title": "Local shell tool", "description": "A tool that allows the model to execute shell commands in a local environment." }, { "properties": { "type": { "type": "string", "enum": [ "shell" ], "description": "The type of the shell tool. Always `shell`.", "default": "shell", "x-stainless-const": true }, "environment": { "anyOf": [ { "oneOf": [ { "properties": { "$comment": "depth-limited" }, "type": { "$comment": "depth-limited" }, "required": { "$comment": "depth-limited" } }, { "properties": { "$comment": "depth-limited" }, "type": { "$comment": "depth-limited" }, "required": { "$comment": "depth-limited" } }, { "properties": { "$comment": "depth-limited" }, "type": { "$comment": "depth-limited" }, "required": { "$comment": "depth-limited" } } ], "discriminator": { "propertyName": "type" } }, { "type": "null" } ] }, "allowed_callers": { "anyOf": [ { "items": { "type": "string", "enum": [ { "$comment": "depth-limited" }, { "$comment": "depth-limited" } ] }, "type": "array", "minItems": 1, "description": "The tool invocation context(s)." }, { "type": "null" } ] } }, "type": "object", "required": [ "type" ], "title": "Shell tool", "description": "A tool that allows the model to execute shell commands." }, { "properties": { "type": { "type": "string", "enum": [ "custom" ], "description": "The type of the custom tool. Always `custom`.", "default": "custom", "x-stainless-const": true }, "name": { "type": "string", "description": "The name of the custom tool, used to identify it in tool calls." }, "async": { "type": "boolean", "description": "Whether the tool response can be returned asynchronously versus immediately returned on next response creation." }, "description": { "type": "string", "description": "Optional description of the custom tool, used to provide more context." }, "format": { "oneOf": [ { "properties": { "type": { "type": { "$comment": "depth-limited" }, "enum": { "$comment": "depth-limited" }, "description": { "$comment": "depth-limited" }, "default": { "$comment": "depth-limited" }, "x-stainless-const": { "$comment": "depth-limited" } } }, "type": "object", "required": [ "type" ], "title": "Text format", "description": "Unconstrained free-form text." }, { "properties": { "type": { "type": { "$comment": "depth-limited" }, "enum": { "$comment": "depth-limited" }, "description": { "$comment": "depth-limited" }, "default": { "$comment": "depth-limited" }, "x-stainless-const": { "$comment": "depth-limited" } }, "syntax": { "$comment": "depth-limited" }, "definition": { "type": { "$comment": "depth-limited" }, "description": { "$comment": "depth-limited" } } }, "type": "object", "required": [ "type", "syntax", "definition" ], "title": "Grammar format", "description": "A grammar defined by the user." } ], "description": "The input format for the custom tool. Default is unconstrained text.", "discriminator": { "propertyName": "type" } }, "defer_loading": { "type": "boolean", "description": "Whether this tool should be deferred and discovered via tool search." }, "allowed_callers": { "anyOf": [ { "items": { "type": "string", "enum": [ { "$comment": "depth-limited" }, { "$comment": "depth-limited" } ] }, "type": "array", "minItems": 1, "description": "The tool invocation context(s)." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "name" ], "title": "Custom tool", "description": "A custom tool that processes input using a specified format. Learn more about [custom tools](https://developers.openai.com/api/docs/guides/function-calling#custom-tools)" }, { "properties": { "type": { "type": "string", "enum": [ "namespace" ], "description": "The type of the tool. Always `namespace`.", "default": "namespace", "x-stainless-const": true }, "name": { "type": "string", "minLength": 1, "description": "The namespace name used in tool calls (for example, `crm`)." }, "description": { "type": "string", "description": "A description of the namespace shown to the model." }, "tools": { "items": { "oneOf": [ { "properties": { "name": { "$comment": "depth-limited" }, "description": { "$comment": "depth-limited" }, "parameters": { "$comment": "depth-limited" }, "strict": { "$comment": "depth-limited" }, "type": { "$comment": "depth-limited" }, "async": { "$comment": "depth-limited" }, "output_schema": { "$comment": "depth-limited" }, "defer_loading": { "$comment": "depth-limited" }, "allowed_callers": { "$comment": "depth-limited" } }, "type": "object", "required": [ { "$comment": "depth-limited" }, { "$comment": "depth-limited" } ] }, { "properties": { "type": { "$comment": "depth-limited" }, "name": { "$comment": "depth-limited" }, "async": { "$comment": "depth-limited" }, "description": { "$comment": "depth-limited" }, "format": { "$comment": "depth-limited" }, "defer_loading": { "$comment": "depth-limited" }, "allowed_callers": { "$comment": "depth-limited" } }, "type": "object", "required": [ { "$comment": "depth-limited" }, { "$comment": "depth-limited" } ], "title": "Custom tool", "description": "A custom tool that processes input using a specified format. Learn more about [custom tools](https://developers.openai.com/api/docs/guides/function-calling#custom-tools)" } ], "description": "A function or custom tool that belongs to a namespace.", "discriminator": { "propertyName": "type" } }, "type": "array", "minItems": 1, "description": "The function/custom tools available inside this namespace." } }, "type": "object", "required": [ "type", "name", "description", "tools" ], "title": "Namespace", "description": "Groups function/custom tools under a shared namespace." }, { "properties": { "type": { "type": "string", "enum": [ "tool_search" ], "description": "The type of the tool. Always `tool_search`.", "default": "tool_search", "x-stainless-const": true }, "execution": { "type": "string", "enum": [ "server", "client" ] }, "description": { "anyOf": [ { "type": "string", "description": "Description shown to the model for a client-executed tool search tool." }, { "type": "null" } ] }, "parameters": { "anyOf": [ { "properties": {}, "type": "object", "required": [] }, { "type": "null" } ] } }, "type": "object", "required": [ "type" ], "title": "Tool search tool", "description": "Hosted or BYOT tool search configuration for deferred tools." }, { "properties": { "type": { "type": "string", "enum": [ "web_search_preview", "web_search_preview_2025_03_11" ], "description": "The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`.", "default": "web_search_preview", "x-stainless-const": true }, "user_location": { "anyOf": [ { "properties": { "type": { "type": { "$comment": "depth-limited" }, "enum": { "$comment": "depth-limited" }, "description": { "$comment": "depth-limited" }, "default": { "$comment": "depth-limited" }, "x-stainless-const": { "$comment": "depth-limited" } }, "country": { "anyOf": { "$comment": "depth-limited" } }, "region": { "anyOf": { "$comment": "depth-limited" } }, "city": { "anyOf": { "$comment": "depth-limited" } }, "timezone": { "anyOf": { "$comment": "depth-limited" } } }, "type": "object", "required": [ "type" ] }, { "type": "null" } ] }, "search_context_size": { "type": "string", "enum": [ "low", "medium", "high" ] }, "search_content_types": { "items": { "type": "string", "enum": [ "text", "image" ] }, "type": "array" } }, "type": "object", "required": [ "type" ], "title": "Web search preview", "description": "This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search)." }, { "properties": { "type": { "type": "string", "enum": [ "apply_patch" ], "description": "The type of the tool. Always `apply_patch`.", "default": "apply_patch", "x-stainless-const": true }, "allowed_callers": { "anyOf": [ { "items": { "type": "string", "enum": [ { "$comment": "depth-limited" }, { "$comment": "depth-limited" } ] }, "type": "array", "minItems": 1, "description": "The tool invocation context(s)." }, { "type": "null" } ] } }, "type": "object", "required": [ "type" ], "title": "Apply patch tool", "description": "Allows the assistant to create, delete, or update files using unified diffs." } ] }, "type": "array", "description": "The loaded tool definitions returned by tool search." }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ] }, "created_by": { "type": "string", "description": "The identifier of the actor that created the item." } }, "type": "object", "required": [ "type", "id", "call_id", "execution", "tools", "status" ] } } ], "summary": "Output items `tool_search_call` {id, call_id|null, execution, arguments: {paths: [...]}, status} then `tool_search_output` {id, call_id, execution, tools: [tool definitions], status}, then normal tool calls." }, "billing": { "model": "Token billing only; saves input tokens by not sending deferred definitions up front.", "source": "https://developers.openai.com/api/docs/pricing#built-in-tools" }, "limitations": [ "Responses API: only gpt-5.4 and later models (gpt-5.4-nano page does not list tool_search).", "`additional_tools` input item can inject tools mid-conversation." ], "security": [ "Client-executed search lets the app decide which tools exist per turn — keep an allowlist." ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/openai/tools/tool-search/tool_search.sh", "python": "examples/openai/tools/tool-search/tool_search.py", "typescript": "examples/openai/tools/tool-search/tool_search.ts" }, "verification": { "hosted": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "gpt-5.4-mini: tool_search + namespace with deferred get_weather -> tool_search_call{arguments:{paths:['weather']}} , tool_search_output{tools:[namespace]}, function_call{namespace:'weather'}" } }, "sources": [ { "url": "https://developers.openai.com/api/docs/guides/tools-tool-search", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/tools/openai-tools.json" }, { "provider": "openai", "name": "Programmatic Tool Calling", "type": "programmatic_tool_calling", "category": "hosted", "description": "Hosted tool letting the model write JavaScript (isolated V8, no Node/network) that orchestrates other tools. Eligible tools opt in with `allowed_callers: [\"programmatic\"]` (function, custom, mcp, apply_patch, shell, code_interpreter). Tool calls emitted from the program carry `caller: {type: program, caller_id}`.", "compatible_models": [], "compatible_endpoints": [ "POST /v1/responses", "Agents API (enabled by default)" ], "parameters_schema": { "properties": { "type": { "type": "string", "enum": [ "programmatic_tool_calling" ], "description": "The type of the tool. Always `programmatic_tool_calling`.", "default": "programmatic_tool_calling", "x-stainless-const": true } }, "type": "object", "required": [ "type" ] }, "tool_choice_support": { "modes": [ "auto", "required", "none" ], "specific": { "type": "programmatic_tool_calling" } }, "parallel": { "supported": true, "notes": "Program can call tools in parallel inside the runtime." }, "streaming_events": [ "response.output_item.added", "response.output_item.done" ], "result_shape": { "items": [ { "schema_name": "FunctionToolCall", "type": "function_call", "schema": { "type": "object", "title": "Function tool call", "description": "A tool call to run a function. See the\n[function calling guide](https://developers.openai.com/api/docs/guides/function-calling) for more information.\n", "properties": { "id": { "type": "string", "description": "The unique ID of the function tool call.\n" }, "type": { "type": "string", "enum": [ "function_call" ], "description": "The type of the function tool call. Always `function_call`.\n", "x-stainless-const": true }, "call_id": { "type": "string", "description": "The unique ID of the function tool call generated by the model.\n" }, "caller": { "anyOf": [ { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "direct" ], "default": "direct", "x-stainless-const": true } }, "type": "object", "required": [ "type" ] }, { "properties": { "type": { "type": "string", "enum": [ "program" ], "default": "program", "x-stainless-const": true }, "caller_id": { "type": "string", "description": "The call ID of the program item that produced this tool call." } }, "type": "object", "required": [ "type", "caller_id" ] } ], "description": "The execution context that produced this tool call.", "discriminator": { "propertyName": "type" } }, { "type": "null" } ] }, "namespace": { "type": "string", "description": "The namespace of the function to run.\n" }, "name": { "type": "string", "description": "The name of the function to run.\n" }, "arguments": { "type": "string", "description": "A JSON string of the arguments to pass to the function.\n" }, "status": { "type": "string", "description": "The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.\n", "enum": [ "in_progress", "completed", "incomplete" ] }, "async": { "type": "boolean", "description": "Whether the function tool call runs asynchronously.\n" } }, "required": [ "type", "call_id", "name", "arguments" ] } } ], "summary": "Standard Responses object; nested `function_call` items with caller.type = program; results returned as `function_call_output` with the same caller." }, "billing": { "model": "Token billing only.", "source": "https://developers.openai.com/api/docs/pricing#built-in-tools" }, "limitations": [ "Check the model page before enabling; not listed on gpt-5.4-nano.", "Supports ZDR without a persistent container.", "Not live-tested (no cheap eligible model identified)." ], "security": [ "Require application-level approval for high-impact actions regardless of caller; MCP `require_approval` can pause the program." ], "beta_header": null, "status": [ "DOCUMENTED", "UNVERIFIED" ], "examples": {}, "verification": { "docs": { "method": "docs_only", "verified_at": "2026-09-18", "result": "success", "http_status": 0, "request_note": "not called" } }, "sources": [ { "url": "https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/tools/openai-tools.json" }, { "provider": "openai", "name": "Web search (hosted)", "type": "web_search", "category": "hosted", "description": "Hosted web search. Actions `search` (with `queries`, `sources` when `include: [web_search_call.action.sources]`), `open_page` and `find_in_page` (reasoning models). Citations come back as `url_citation` annotations on the message. Live fields echoed by the API but absent from the OpenAPI spec: `return_token_budget` (default|unlimited), `filters.blocked_domains`, `search_content_types` ([text, image]).", "compatible_models": [ "chat-latest", "gpt-4.1", "gpt-4.1-mini", "gpt-4o", "gpt-4o-mini", "gpt-4o-mini-audio-preview", "gpt-5", "gpt-5-chat-latest", "gpt-5-codex", "gpt-5-mini", "gpt-5-nano", "gpt-5-pro", "gpt-5.1", "gpt-5.1-chat-latest", "gpt-5.1-codex", "gpt-5.1-codex-max", "gpt-5.1-codex-mini", "gpt-5.2", "gpt-5.2-chat-latest", "gpt-5.2-codex", "gpt-5.2-pro", "gpt-5.3-chat-latest", "gpt-5.3-codex", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.4-pro", "gpt-5.5", "gpt-5.5-pro", "gpt-5.6-cyber", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-6-astra", "gpt-daybreak-blue-latest", "gpt-daybreak-red-latest", "gpt-oss-120b", "gpt-oss-20b", "o3", "o3-deep-research", "o3-pro", "o4-mini", "o4-mini-deep-research" ], "compatible_endpoints": [ "POST /v1/responses", "Realtime/Live (web_search tool in Live sessions)", "Agents API" ], "parameters_schema": { "type": "object", "title": "Web search", "description": "Search the Internet for sources related to the prompt. Learn more about the\n[web search tool](https://developers.openai.com/api/docs/guides/tools-web-search).\n", "properties": { "type": { "type": "string", "enum": [ "web_search", "web_search_2025_08_26" ], "description": "The type of the web search tool. One of `web_search` or `web_search_2025_08_26`.", "default": "web_search" }, "external_web_access": { "type": "boolean", "default": true, "description": "Allow live internet access for web search. Defaults to true when omitted. When false, the web search tool runs in offline/cache-only mode and will not fetch new external content." }, "filters": { "anyOf": [ { "type": "object", "description": "Filters for the search.\n", "properties": { "allowed_domains": { "anyOf": [ { "type": "array", "title": "Allowed domains for the search.", "description": "Allowed domains for the search. If not provided, all domains are allowed.\nSubdomains of the provided domains are allowed as well.\n\nExample: `[\"pubmed.ncbi.nlm.nih.gov\"]`\n", "items": { "type": "string", "description": "Allowed domain for the search." }, "default": [] }, { "type": "null" } ] } } }, { "type": "null" } ] }, "user_location": { "anyOf": [ { "type": "object", "title": "Web search approximate location", "description": "The approximate location of the user.\n", "properties": { "type": { "type": "string", "enum": [ "approximate" ], "description": "The type of location approximation. Always `approximate`.", "default": "approximate", "x-stainless-const": true }, "country": { "anyOf": [ { "type": "string", "description": "The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`." }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string", "description": "Free text input for the region of the user, e.g. `California`." }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "description": "Free text input for the city of the user, e.g. `San Francisco`." }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string", "description": "The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`." }, { "type": "null" } ] } } }, { "type": "null" } ] }, "search_context_size": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium", "description": "High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default." } }, "required": [ "type" ] }, "tool_choice_support": { "modes": [ "none", "auto", "required" ], "allowed_tools": { "type": "allowed_tools", "mode": "auto|required", "tools": [ "{type,name,...}" ] }, "specific": { "type": "web_search" }, "note": "Live: tool_choice {type: web_search} accepted and echoed back as {type: web_search_preview}; spec ToolChoiceTypes enum only lists web_search_preview." }, "parallel": { "supported": false, "notes": "Built-in tools are not batched with parallel function calls." }, "streaming_events": [ "response.output_item.added", "response.web_search_call.in_progress", "response.web_search_call.searching", "response.web_search_call.completed", "response.output_item.done", "response.output_text.annotation.added" ], "result_shape": { "items": [ { "schema_name": "WebSearchToolCall", "type": "web_search_call", "schema": { "type": "object", "title": "Web search tool call", "description": "The results of a web search tool call. See the\n[web search guide](https://developers.openai.com/api/docs/guides/tools-web-search) for more information.\n", "properties": { "id": { "type": "string", "description": "The unique ID of the web search tool call.\n" }, "type": { "type": "string", "enum": [ "web_search_call" ], "description": "The type of the web search tool call. Always `web_search_call`.\n", "x-stainless-const": true }, "status": { "type": "string", "enum": [ "in_progress", "searching", "completed", "failed", "incomplete" ] }, "action": { "type": "object", "description": "An object describing the specific action taken in this web search call.\nIncludes details on how the model used the web (search, open_page, find_in_page).\n", "oneOf": [ { "type": "object", "title": "Search action", "description": "Action type \"search\" - Performs a web search query.\n", "properties": { "type": { "type": "string", "enum": [ "search" ], "description": "The action type.\n", "x-stainless-const": true }, "query": { "type": "string", "deprecated": true, "description": "The search query.\n" }, "queries": { "type": "array", "title": "Search queries", "description": "The search queries.\n", "items": { "type": "string", "description": "A search query.\n" } }, "sources": { "type": "array", "title": "Web search sources", "description": "The sources used in the search.\n", "items": { "type": "object", "title": "Web search source", "description": "A source used in the search.\n", "properties": { "type": { "type": "string", "enum": [ "url" ], "description": "The type of source. Always `url`.\n", "x-stainless-const": true }, "url": { "type": "string", "format": "uri", "description": "The URL of the source.\n" } }, "required": [ "type", "url" ] } } }, "required": [ "type" ] }, { "type": "object", "title": "Open page action", "description": "Action type \"open_page\" - Opens a specific URL from search results.\n", "properties": { "type": { "type": "string", "enum": [ "open_page" ], "description": "The action type.\n", "x-stainless-const": true }, "url": { "description": "The URL opened by the model.\n", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "type" ] }, { "type": "object", "title": "Find action", "description": "Action type \"find_in_page\": Searches for a pattern within a loaded page.\n", "properties": { "type": { "type": "string", "enum": [ "find_in_page" ], "description": "The action type.\n", "x-stainless-const": true }, "url": { "type": "string", "format": "uri", "description": "The URL of the page searched for the pattern.\n" }, "pattern": { "type": "string", "description": "The pattern or text to search for within the page.\n" } }, "required": [ "type", "url", "pattern" ] } ], "discriminator": { "propertyName": "type" } } }, "required": [ "id", "type", "status", "action" ] } } ], "summary": "Output item `web_search_call` {id, status, action: {type: search|open_page|find_in_page, query, queries, sources: [{type: url, url} | {type: api, name: oai-time|oai-weather|oai-sports|oai-finance}]}}; message annotations `url_citation` {url, title, start_index, end_index}." }, "billing": { "per_call": "$10.00 / 1k calls (web_search, all models; image web search same) + search content tokens billed at model rates", "preview": "$10/1k (reasoning models) or $25/1k with free content tokens (non-reasoning)", "source": "https://developers.openai.com/api/docs/pricing#built-in-tools" }, "limitations": [ "Search context window limited to 128k even on 1M models.", "Not supported with gpt-5 `minimal` reasoning; gpt-5.4 reasoning `none` may degrade quality.", "Up to 100 allowed_domains / 100 blocked_domains.", "Rate limits = underlying model tiered limits.", "`web_search_preview` ignores `external_web_access`, no `filters`/`return_token_budget`." ], "security": [ "Treat page content as untrusted (prompt injection); prefer `filters.allowed_domains` for sensitive workflows.", "`external_web_access: false` runs cache-only." ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/openai/tools/web-search/web_search.sh", "python": "examples/openai/tools/web-search/web_search.py", "typescript": "examples/openai/tools/web-search/web_search.ts" }, "verification": { "forced_search": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "gpt-5.4-nano: tool_choice {type:web_search}, search_context_size low, include web_search_call.action.sources -> web_search_call action.type=search, sources=[{type:'api',name:'oai-time'}] (non-URL source shape not in spec); answer 'Saturday, September 19, 2026 Toronto'; usage 4671 in / 329 out" }, "auto_no_search": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "same prompt with tool_choice auto -> model answered without calling the tool (search is optional under auto)" }, "max_output_tokens_64": { "method": "live_api", "verified_at": "2026-09-18", "result": "failure", "http_status": 200, "request_note": "first attempt with max_output_tokens 64 ended status=incomplete (reason max_output_tokens) before any tool call — leave >= 300 tokens for reasoning+search" }, "streaming": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "response.web_search_call.in_progress -> searching -> completed" } }, "sources": [ { "url": "https://developers.openai.com/api/docs/guides/tools-web-search", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/docs/pricing#built-in-tools", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/tools/openai-tools.json" }, { "provider": "openai", "name": "Web search (dated snapshot 2025-08-26)", "type": "web_search_2025_08_26", "category": "hosted", "description": "Dated alias of `web_search` (same schema, WebSearchTool).", "compatible_models": [ "chat-latest", "gpt-4.1", "gpt-4.1-mini", "gpt-4o", "gpt-4o-mini", "gpt-4o-mini-audio-preview", "gpt-5", "gpt-5-chat-latest", "gpt-5-codex", "gpt-5-mini", "gpt-5-nano", "gpt-5-pro", "gpt-5.1", "gpt-5.1-chat-latest", "gpt-5.1-codex", "gpt-5.1-codex-max", "gpt-5.1-codex-mini", "gpt-5.2", "gpt-5.2-chat-latest", "gpt-5.2-codex", "gpt-5.2-pro", "gpt-5.3-chat-latest", "gpt-5.3-codex", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.4-pro", "gpt-5.5", "gpt-5.5-pro", "gpt-5.6-cyber", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-6-astra", "gpt-daybreak-blue-latest", "gpt-daybreak-red-latest", "gpt-oss-120b", "gpt-oss-20b", "o3", "o3-deep-research", "o3-pro", "o4-mini", "o4-mini-deep-research" ], "compatible_endpoints": [ "POST /v1/responses" ], "parameters_schema": { "type": "object", "title": "Web search", "description": "Search the Internet for sources related to the prompt. Learn more about the\n[web search tool](https://developers.openai.com/api/docs/guides/tools-web-search).\n", "properties": { "type": { "type": "string", "enum": [ "web_search", "web_search_2025_08_26" ], "description": "The type of the web search tool. One of `web_search` or `web_search_2025_08_26`.", "default": "web_search" }, "external_web_access": { "type": "boolean", "default": true, "description": "Allow live internet access for web search. Defaults to true when omitted. When false, the web search tool runs in offline/cache-only mode and will not fetch new external content." }, "filters": { "anyOf": [ { "type": "object", "description": "Filters for the search.\n", "properties": { "allowed_domains": { "anyOf": [ { "type": "array", "title": "Allowed domains for the search.", "description": "Allowed domains for the search. If not provided, all domains are allowed.\nSubdomains of the provided domains are allowed as well.\n\nExample: `[\"pubmed.ncbi.nlm.nih.gov\"]`\n", "items": { "type": "string", "description": "Allowed domain for the search." }, "default": [] }, { "type": "null" } ] } } }, { "type": "null" } ] }, "user_location": { "anyOf": [ { "type": "object", "title": "Web search approximate location", "description": "The approximate location of the user.\n", "properties": { "type": { "type": "string", "enum": [ "approximate" ], "description": "The type of location approximation. Always `approximate`.", "default": "approximate", "x-stainless-const": true }, "country": { "anyOf": [ { "type": "string", "description": "The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`." }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string", "description": "Free text input for the region of the user, e.g. `California`." }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "description": "Free text input for the city of the user, e.g. `San Francisco`." }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string", "description": "The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`." }, { "type": "null" } ] } } }, { "type": "null" } ] }, "search_context_size": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium", "description": "High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default." } }, "required": [ "type" ] }, "tool_choice_support": { "modes": [ "none", "auto", "required" ], "allowed_tools": { "type": "allowed_tools", "mode": "auto|required", "tools": [ "{type,name,...}" ] } }, "parallel": { "supported": false }, "streaming_events": [], "result_shape": { "items": [ { "schema_name": "WebSearchToolCall", "type": "web_search_call", "schema": { "type": "object", "title": "Web search tool call", "description": "The results of a web search tool call. See the\n[web search guide](https://developers.openai.com/api/docs/guides/tools-web-search) for more information.\n", "properties": { "id": { "type": "string", "description": "The unique ID of the web search tool call.\n" }, "type": { "type": "string", "enum": [ "web_search_call" ], "description": "The type of the web search tool call. Always `web_search_call`.\n", "x-stainless-const": true }, "status": { "type": "string", "enum": [ "in_progress", "searching", "completed", "failed", "incomplete" ] }, "action": { "type": "object", "description": "An object describing the specific action taken in this web search call.\nIncludes details on how the model used the web (search, open_page, find_in_page).\n", "oneOf": [ { "type": "object", "title": "Search action", "description": "Action type \"search\" - Performs a web search query.\n", "properties": { "type": { "type": "string", "enum": [ "search" ], "description": "The action type.\n", "x-stainless-const": true }, "query": { "type": "string", "deprecated": true, "description": "The search query.\n" }, "queries": { "type": "array", "title": "Search queries", "description": "The search queries.\n", "items": { "type": "string", "description": "A search query.\n" } }, "sources": { "type": "array", "title": "Web search sources", "description": "The sources used in the search.\n", "items": { "type": "object", "title": "Web search source", "description": "A source used in the search.\n", "properties": { "type": { "type": "string", "enum": [ "url" ], "description": "The type of source. Always `url`.\n", "x-stainless-const": true }, "url": { "type": "string", "format": "uri", "description": "The URL of the source.\n" } }, "required": [ "type", "url" ] } } }, "required": [ "type" ] }, { "type": "object", "title": "Open page action", "description": "Action type \"open_page\" - Opens a specific URL from search results.\n", "properties": { "type": { "type": "string", "enum": [ "open_page" ], "description": "The action type.\n", "x-stainless-const": true }, "url": { "description": "The URL opened by the model.\n", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "type" ] }, { "type": "object", "title": "Find action", "description": "Action type \"find_in_page\": Searches for a pattern within a loaded page.\n", "properties": { "type": { "type": "string", "enum": [ "find_in_page" ], "description": "The action type.\n", "x-stainless-const": true }, "url": { "type": "string", "format": "uri", "description": "The URL of the page searched for the pattern.\n" }, "pattern": { "type": "string", "description": "The pattern or text to search for within the page.\n" } }, "required": [ "type", "url", "pattern" ] } ], "discriminator": { "propertyName": "type" } } }, "required": [ "id", "type", "status", "action" ] } } ], "summary": "Same as web_search." }, "billing": { "per_call": "$10.00 / 1k calls (web_search, all models; image web search same) + search content tokens billed at model rates", "preview": "$10/1k (reasoning models) or $25/1k with free content tokens (non-reasoning)", "source": "https://developers.openai.com/api/docs/pricing#built-in-tools" }, "limitations": [ "Search context window limited to 128k even on 1M models.", "Not supported with gpt-5 `minimal` reasoning; gpt-5.4 reasoning `none` may degrade quality.", "Up to 100 allowed_domains / 100 blocked_domains.", "Rate limits = underlying model tiered limits.", "`web_search_preview` ignores `external_web_access`, no `filters`/`return_token_budget`." ], "security": [ "Treat page content as untrusted (prompt injection); prefer `filters.allowed_domains` for sensitive workflows.", "`external_web_access: false` runs cache-only." ], "beta_header": null, "status": [ "DOCUMENTED", "UNVERIFIED" ], "examples": { "curl": "examples/openai/tools/web-search/web_search.sh", "python": "examples/openai/tools/web-search/web_search.py", "typescript": "examples/openai/tools/web-search/web_search.ts" }, "verification": { "docs": { "method": "docs_only", "verified_at": "2026-09-18", "result": "success", "http_status": 0, "request_note": "alias not called" } }, "sources": [ { "url": "https://developers.openai.com/api/docs/guides/tools-web-search", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/tools/openai-tools.json" }, { "provider": "openai", "name": "Web search preview (legacy)", "type": "web_search_preview", "category": "hosted", "description": "Earlier hosted web search tool kept for legacy integrations. Supports `user_location`, `search_context_size`, `search_content_types`; does not support `filters`, `external_web_access`, `return_token_budget`. Docs: migrate to `web_search`.", "compatible_models": [ "chat-latest", "gpt-4.1", "gpt-4.1-mini", "gpt-4o", "gpt-4o-mini", "gpt-4o-mini-audio-preview", "gpt-5", "gpt-5-chat-latest", "gpt-5-codex", "gpt-5-mini", "gpt-5-nano", "gpt-5-pro", "gpt-5.1", "gpt-5.1-chat-latest", "gpt-5.1-codex", "gpt-5.1-codex-max", "gpt-5.1-codex-mini", "gpt-5.2", "gpt-5.2-chat-latest", "gpt-5.2-codex", "gpt-5.2-pro", "gpt-5.3-chat-latest", "gpt-5.3-codex", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.4-pro", "gpt-5.5", "gpt-5.5-pro", "gpt-5.6-cyber", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-6-astra", "gpt-daybreak-blue-latest", "gpt-daybreak-red-latest", "gpt-oss-120b", "gpt-oss-20b", "o3", "o3-deep-research", "o3-pro", "o4-mini", "o4-mini-deep-research" ], "compatible_endpoints": [ "POST /v1/responses" ], "parameters_schema": { "properties": { "type": { "type": "string", "enum": [ "web_search_preview", "web_search_preview_2025_03_11" ], "description": "The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`.", "default": "web_search_preview", "x-stainless-const": true }, "user_location": { "anyOf": [ { "properties": { "type": { "type": "string", "enum": [ "approximate" ], "description": "The type of location approximation. Always `approximate`.", "default": "approximate", "x-stainless-const": true }, "country": { "anyOf": [ { "type": "string", "description": "The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`." }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string", "description": "Free text input for the region of the user, e.g. `California`." }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "description": "Free text input for the city of the user, e.g. `San Francisco`." }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string", "description": "The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`." }, { "type": "null" } ] } }, "type": "object", "required": [ "type" ] }, { "type": "null" } ] }, "search_context_size": { "type": "string", "enum": [ "low", "medium", "high" ] }, "search_content_types": { "items": { "type": "string", "enum": [ "text", "image" ] }, "type": "array" } }, "type": "object", "required": [ "type" ], "title": "Web search preview", "description": "This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search)." }, "tool_choice_support": { "modes": [ "none", "auto", "required" ], "allowed_tools": { "type": "allowed_tools", "mode": "auto|required", "tools": [ "{type,name,...}" ] }, "specific": { "type": "web_search_preview" } }, "parallel": { "supported": false }, "streaming_events": [], "result_shape": { "items": [ { "schema_name": "WebSearchToolCall", "type": "web_search_call", "schema": { "type": "object", "title": "Web search tool call", "description": "The results of a web search tool call. See the\n[web search guide](https://developers.openai.com/api/docs/guides/tools-web-search) for more information.\n", "properties": { "id": { "type": "string", "description": "The unique ID of the web search tool call.\n" }, "type": { "type": "string", "enum": [ "web_search_call" ], "description": "The type of the web search tool call. Always `web_search_call`.\n", "x-stainless-const": true }, "status": { "type": "string", "enum": [ "in_progress", "searching", "completed", "failed", "incomplete" ] }, "action": { "type": "object", "description": "An object describing the specific action taken in this web search call.\nIncludes details on how the model used the web (search, open_page, find_in_page).\n", "oneOf": [ { "type": "object", "title": "Search action", "description": "Action type \"search\" - Performs a web search query.\n", "properties": { "type": { "type": "string", "enum": [ "search" ], "description": "The action type.\n", "x-stainless-const": true }, "query": { "type": "string", "deprecated": true, "description": "The search query.\n" }, "queries": { "type": "array", "title": "Search queries", "description": "The search queries.\n", "items": { "type": "string", "description": "A search query.\n" } }, "sources": { "type": "array", "title": "Web search sources", "description": "The sources used in the search.\n", "items": { "type": "object", "title": "Web search source", "description": "A source used in the search.\n", "properties": { "type": { "type": "string", "enum": [ "url" ], "description": "The type of source. Always `url`.\n", "x-stainless-const": true }, "url": { "type": "string", "format": "uri", "description": "The URL of the source.\n" } }, "required": [ "type", "url" ] } } }, "required": [ "type" ] }, { "type": "object", "title": "Open page action", "description": "Action type \"open_page\" - Opens a specific URL from search results.\n", "properties": { "type": { "type": "string", "enum": [ "open_page" ], "description": "The action type.\n", "x-stainless-const": true }, "url": { "description": "The URL opened by the model.\n", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "type" ] }, { "type": "object", "title": "Find action", "description": "Action type \"find_in_page\": Searches for a pattern within a loaded page.\n", "properties": { "type": { "type": "string", "enum": [ "find_in_page" ], "description": "The action type.\n", "x-stainless-const": true }, "url": { "type": "string", "format": "uri", "description": "The URL of the page searched for the pattern.\n" }, "pattern": { "type": "string", "description": "The pattern or text to search for within the page.\n" } }, "required": [ "type", "url", "pattern" ] } ], "discriminator": { "propertyName": "type" } } }, "required": [ "id", "type", "status", "action" ] } } ], "summary": "Same `web_search_call` item." }, "billing": { "per_call": "$10.00 / 1k calls (web_search, all models; image web search same) + search content tokens billed at model rates", "preview": "$10/1k (reasoning models) or $25/1k with free content tokens (non-reasoning)", "source": "https://developers.openai.com/api/docs/pricing#built-in-tools" }, "limitations": [ "Search context window limited to 128k even on 1M models.", "Not supported with gpt-5 `minimal` reasoning; gpt-5.4 reasoning `none` may degrade quality.", "Up to 100 allowed_domains / 100 blocked_domains.", "Rate limits = underlying model tiered limits.", "`web_search_preview` ignores `external_web_access`, no `filters`/`return_token_budget`.", "Docs recommend migrating to web_search." ], "security": [ "Treat page content as untrusted (prompt injection); prefer `filters.allowed_domains` for sensitive workflows.", "`external_web_access: false` runs cache-only." ], "beta_header": null, "status": [ "DOCUMENTED", "LEGACY", "UNVERIFIED" ], "examples": { "curl": "examples/openai/tools/web-search/web_search.sh", "python": "examples/openai/tools/web-search/web_search.py", "typescript": "examples/openai/tools/web-search/web_search.ts" }, "verification": { "docs": { "method": "docs_only", "verified_at": "2026-09-18", "result": "success", "http_status": 0, "request_note": "not called (legacy)" } }, "sources": [ { "url": "https://developers.openai.com/api/docs/guides/tools-web-search", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/tools/openai-tools.json" }, { "provider": "openai", "name": "Web search preview (dated snapshot 2025-03-11)", "type": "web_search_preview_2025_03_11", "category": "hosted", "description": "Dated alias of `web_search_preview`.", "compatible_models": [ "chat-latest", "gpt-4.1", "gpt-4.1-mini", "gpt-4o", "gpt-4o-mini", "gpt-4o-mini-audio-preview", "gpt-5", "gpt-5-chat-latest", "gpt-5-codex", "gpt-5-mini", "gpt-5-nano", "gpt-5-pro", "gpt-5.1", "gpt-5.1-chat-latest", "gpt-5.1-codex", "gpt-5.1-codex-max", "gpt-5.1-codex-mini", "gpt-5.2", "gpt-5.2-chat-latest", "gpt-5.2-codex", "gpt-5.2-pro", "gpt-5.3-chat-latest", "gpt-5.3-codex", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.4-pro", "gpt-5.5", "gpt-5.5-pro", "gpt-5.6-cyber", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-6-astra", "gpt-daybreak-blue-latest", "gpt-daybreak-red-latest", "gpt-oss-120b", "gpt-oss-20b", "o3", "o3-deep-research", "o3-pro", "o4-mini", "o4-mini-deep-research" ], "compatible_endpoints": [ "POST /v1/responses" ], "parameters_schema": { "properties": { "type": { "type": "string", "enum": [ "web_search_preview", "web_search_preview_2025_03_11" ], "description": "The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`.", "default": "web_search_preview", "x-stainless-const": true }, "user_location": { "anyOf": [ { "properties": { "type": { "type": "string", "enum": [ "approximate" ], "description": "The type of location approximation. Always `approximate`.", "default": "approximate", "x-stainless-const": true }, "country": { "anyOf": [ { "type": "string", "description": "The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`." }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string", "description": "Free text input for the region of the user, e.g. `California`." }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "description": "Free text input for the city of the user, e.g. `San Francisco`." }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string", "description": "The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`." }, { "type": "null" } ] } }, "type": "object", "required": [ "type" ] }, { "type": "null" } ] }, "search_context_size": { "type": "string", "enum": [ "low", "medium", "high" ] }, "search_content_types": { "items": { "type": "string", "enum": [ "text", "image" ] }, "type": "array" } }, "type": "object", "required": [ "type" ], "title": "Web search preview", "description": "This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search)." }, "tool_choice_support": { "modes": [ "none", "auto", "required" ], "allowed_tools": { "type": "allowed_tools", "mode": "auto|required", "tools": [ "{type,name,...}" ] }, "specific": { "type": "web_search_preview_2025_03_11" } }, "parallel": { "supported": false }, "streaming_events": [], "result_shape": { "items": [ { "schema_name": "WebSearchToolCall", "type": "web_search_call", "schema": { "type": "object", "title": "Web search tool call", "description": "The results of a web search tool call. See the\n[web search guide](https://developers.openai.com/api/docs/guides/tools-web-search) for more information.\n", "properties": { "id": { "type": "string", "description": "The unique ID of the web search tool call.\n" }, "type": { "type": "string", "enum": [ "web_search_call" ], "description": "The type of the web search tool call. Always `web_search_call`.\n", "x-stainless-const": true }, "status": { "type": "string", "enum": [ "in_progress", "searching", "completed", "failed", "incomplete" ] }, "action": { "type": "object", "description": "An object describing the specific action taken in this web search call.\nIncludes details on how the model used the web (search, open_page, find_in_page).\n", "oneOf": [ { "type": "object", "title": "Search action", "description": "Action type \"search\" - Performs a web search query.\n", "properties": { "type": { "type": "string", "enum": [ "search" ], "description": "The action type.\n", "x-stainless-const": true }, "query": { "type": "string", "deprecated": true, "description": "The search query.\n" }, "queries": { "type": "array", "title": "Search queries", "description": "The search queries.\n", "items": { "type": "string", "description": "A search query.\n" } }, "sources": { "type": "array", "title": "Web search sources", "description": "The sources used in the search.\n", "items": { "type": "object", "title": "Web search source", "description": "A source used in the search.\n", "properties": { "type": { "type": "string", "enum": [ "url" ], "description": "The type of source. Always `url`.\n", "x-stainless-const": true }, "url": { "type": "string", "format": "uri", "description": "The URL of the source.\n" } }, "required": [ "type", "url" ] } } }, "required": [ "type" ] }, { "type": "object", "title": "Open page action", "description": "Action type \"open_page\" - Opens a specific URL from search results.\n", "properties": { "type": { "type": "string", "enum": [ "open_page" ], "description": "The action type.\n", "x-stainless-const": true }, "url": { "description": "The URL opened by the model.\n", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "type" ] }, { "type": "object", "title": "Find action", "description": "Action type \"find_in_page\": Searches for a pattern within a loaded page.\n", "properties": { "type": { "type": "string", "enum": [ "find_in_page" ], "description": "The action type.\n", "x-stainless-const": true }, "url": { "type": "string", "format": "uri", "description": "The URL of the page searched for the pattern.\n" }, "pattern": { "type": "string", "description": "The pattern or text to search for within the page.\n" } }, "required": [ "type", "url", "pattern" ] } ], "discriminator": { "propertyName": "type" } } }, "required": [ "id", "type", "status", "action" ] } } ], "summary": "Same `web_search_call` item." }, "billing": { "per_call": "$10.00 / 1k calls (web_search, all models; image web search same) + search content tokens billed at model rates", "preview": "$10/1k (reasoning models) or $25/1k with free content tokens (non-reasoning)", "source": "https://developers.openai.com/api/docs/pricing#built-in-tools" }, "limitations": [ "Search context window limited to 128k even on 1M models.", "Not supported with gpt-5 `minimal` reasoning; gpt-5.4 reasoning `none` may degrade quality.", "Up to 100 allowed_domains / 100 blocked_domains.", "Rate limits = underlying model tiered limits.", "`web_search_preview` ignores `external_web_access`, no `filters`/`return_token_budget`." ], "security": [ "Treat page content as untrusted (prompt injection); prefer `filters.allowed_domains` for sensitive workflows.", "`external_web_access: false` runs cache-only." ], "beta_header": null, "status": [ "DOCUMENTED", "LEGACY", "UNVERIFIED" ], "examples": { "curl": "examples/openai/tools/web-search/web_search.sh", "python": "examples/openai/tools/web-search/web_search.py", "typescript": "examples/openai/tools/web-search/web_search.ts" }, "verification": { "docs": { "method": "docs_only", "verified_at": "2026-09-18", "result": "success", "http_status": 0, "request_note": "not called" } }, "sources": [ { "url": "https://developers.openai.com/api/docs/guides/tools-web-search", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/tools/openai-tools.json" }, { "provider": "openai", "name": "File search (vector stores)", "type": "file_search", "category": "hosted", "description": "Semantic + keyword (hybrid) retrieval over vector stores. Configure `vector_store_ids`, `max_num_results` (1-50), `filters` (comparison/compound on file attributes), `ranking_options` {ranker, score_threshold, hybrid_search}. Results are hidden unless `include: [file_search_call.results]`; citations are `file_citation` annotations.", "compatible_models": [ "chat-latest", "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "gpt-4o", "gpt-4o-mini", "gpt-4o-mini-audio-preview", "gpt-5", "gpt-5-chat-latest", "gpt-5-mini", "gpt-5-nano", "gpt-5-pro", "gpt-5.1", "gpt-5.1-chat-latest", "gpt-5.2", "gpt-5.2-chat-latest", "gpt-5.2-pro", "gpt-5.3-chat-latest", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.4-pro", "gpt-5.5", "gpt-5.5-pro", "gpt-5.6-cyber", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-6-astra", "gpt-daybreak-blue-latest", "gpt-daybreak-red-latest", "o1", "o1-mini", "o1-pro", "o3", "o3-mini", "o3-pro", "o4-mini" ], "compatible_endpoints": [ "POST /v1/responses", "Assistants API (legacy)" ], "parameters_schema": { "properties": { "type": { "type": "string", "enum": [ "file_search" ], "description": "The type of the file search tool. Always `file_search`.", "default": "file_search", "x-stainless-const": true }, "vector_store_ids": { "items": { "type": "string" }, "type": "array", "description": "The IDs of the vector stores to search." }, "max_num_results": { "type": "integer", "description": "The maximum number of results to return. This number should be between 1 and 50 inclusive." }, "ranking_options": { "properties": { "ranker": { "type": "string", "enum": [ "auto", "default-2024-11-15" ] }, "score_threshold": { "type": "number", "description": "The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results." }, "hybrid_search": { "properties": { "embedding_weight": { "type": "number", "description": "The weight of the embedding in the reciprocal ranking fusion." }, "text_weight": { "type": "number", "description": "The weight of the text in the reciprocal ranking fusion." } }, "type": "object", "required": [ "embedding_weight", "text_weight" ] } }, "type": "object", "required": [] }, "filters": { "anyOf": [ { "anyOf": [ { "type": "object", "additionalProperties": false, "title": "Comparison Filter", "description": "A filter used to compare a specified attribute key to a given value using a defined comparison operation.\n", "properties": { "type": { "type": "string", "default": "eq", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte", "in", "nin" ], "description": "Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`.\n- `eq`: equals\n- `ne`: not equal\n- `gt`: greater than\n- `gte`: greater than or equal\n- `lt`: less than\n- `lte`: less than or equal\n- `in`: in\n- `nin`: not in\n" }, "key": { "type": "string", "description": "The key to compare against the value." }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "oneOf": [ { "$comment": "depth-limited" }, { "$comment": "depth-limited" } ] } } ], "description": "The value to compare against the attribute key; supports string, number, or boolean types." } }, "required": [ "type", "key", "value" ] }, { "$recursiveAnchor": true, "type": "object", "additionalProperties": false, "title": "Compound Filter", "description": "Combine multiple filters using `and` or `or`.", "properties": { "type": { "type": "string", "description": "Type of operation: `and` or `or`.", "enum": [ "and", "or" ] }, "filters": { "type": "array", "description": "Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`.", "items": { "oneOf": [ { "type": { "$comment": "depth-limited" }, "additionalProperties": { "$comment": "depth-limited" }, "title": { "$comment": "depth-limited" }, "description": { "$comment": "depth-limited" }, "properties": { "$comment": "depth-limited" }, "required": { "$comment": "depth-limited" } }, { "$recursiveRef": "#" } ], "discriminator": { "propertyName": "type" } } } }, "required": [ "type", "filters" ] } ] }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "vector_store_ids" ], "title": "File search", "description": "A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://developers.openai.com/api/docs/guides/tools-file-search)." }, "tool_choice_support": { "modes": [ "none", "auto", "required" ], "allowed_tools": { "type": "allowed_tools", "mode": "auto|required", "tools": [ "{type,name,...}" ] }, "specific": { "type": "file_search" } }, "parallel": { "supported": false }, "streaming_events": [ "response.output_item.added", "response.file_search_call.in_progress", "response.file_search_call.searching", "response.file_search_call.completed", "response.output_item.done", "response.output_text.annotation.added" ], "result_shape": { "items": [ { "schema_name": "FileSearchToolCall", "type": "file_search_call", "schema": { "type": "object", "title": "File search tool call", "description": "The results of a file search tool call. See the\n[file search guide](https://developers.openai.com/api/docs/guides/tools-file-search) for more information.\n", "properties": { "id": { "type": "string", "description": "The unique ID of the file search tool call.\n" }, "type": { "type": "string", "enum": [ "file_search_call" ], "description": "The type of the file search tool call. Always `file_search_call`.\n", "x-stainless-const": true }, "status": { "type": "string", "description": "The status of the file search tool call. One of `in_progress`,\n`searching`, `incomplete` or `failed`,\n", "enum": [ "in_progress", "searching", "completed", "incomplete", "failed" ] }, "queries": { "type": "array", "items": { "type": "string" }, "description": "The queries used to search for files.\n" }, "results": { "anyOf": [ { "type": "array", "description": "The results of the file search tool call.\n", "items": { "type": "object", "properties": { "file_id": { "type": "string", "description": "The unique ID of the file.\n" }, "text": { "type": "string", "description": "The text that was retrieved from the file.\n" }, "filename": { "type": "string", "description": "The name of the file.\n" }, "attributes": { "anyOf": [ { "type": "object", "description": "Set of 16 key-value pairs that can be attached to an object. This can be\nuseful for storing additional information about the object in a structured\nformat, and querying for objects via API or the dashboard. Keys are strings\nwith a maximum length of 64 characters. Values are strings with a maximum\nlength of 512 characters, booleans, or numbers.\n", "maxProperties": 16, "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "oneOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" } ] } }, { "type": "null" } ] }, "score": { "type": "number", "format": "float", "description": "The relevance score of the file - a value between 0 and 1.\n" } } } }, { "type": "null" } ] } }, "required": [ "id", "type", "status", "queries" ] } } ], "summary": "Output item `file_search_call` {id, status, queries: [...], results: [{file_id, filename, score, text, attributes, vector_store_id}] | null} + message with `file_citation` annotations." }, "billing": { "per_call": "$2.50 / 1k calls", "storage": "$0.10 / GB / day (1 GB free)", "source": "https://developers.openai.com/api/docs/pricing#built-in-tools" }, "limitations": [ "max_num_results 1-50.", "Deep research models support only `type` and `vector_store_ids`.", "Vector store CRUD is documented in the vector-stores fragment (other agent)." ], "security": [ "Only upload trusted files: retrieved text is model input (prompt injection)." ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/openai/tools/file-search/file_search.sh", "python": "examples/openai/tools/file-search/file_search.py", "typescript": "examples/openai/tools/file-search/file_search.ts" }, "verification": { "search": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "gpt-5.4-nano: vector store 'atlas-tools-agent' + 1 txt file, include file_search_call.results -> file_search_call queries=[3 rewrites], results[0].score=0.7626, text returned; answer PELICAN-42; results[0].vector_store_id was '' (empty string, spec says string)" }, "max_output_tokens_32": { "method": "live_api", "verified_at": "2026-09-18", "result": "failure", "http_status": 200, "request_note": "with max_output_tokens 32 the response was incomplete and file_search_call.status='incomplete'" }, "streaming": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "response.file_search_call.in_progress -> searching -> completed" } }, "sources": [ { "url": "https://developers.openai.com/api/docs/guides/tools-file-search", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/docs/pricing#built-in-tools", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/tools/openai-tools.json" }, { "provider": "openai", "name": "Code interpreter (Python sandbox container)", "type": "code_interpreter", "category": "hosted", "description": "Runs Python in a sandboxed container. `container` is either a container id (explicit mode, created via POST /v1/containers) or `{type: auto, file_ids?, memory_limit?: 1g|4g|16g|64g, network_policy?}`. Generated files are cited as `container_file_citation` annotations; outputs (`logs`, `image`) are returned only with `include: [code_interpreter_call.outputs]`.", "compatible_models": [ "chat-latest", "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "gpt-4o", "gpt-4o-mini", "gpt-4o-mini-audio-preview", "gpt-5", "gpt-5-chat-latest", "gpt-5-mini", "gpt-5-nano", "gpt-5.1", "gpt-5.1-chat-latest", "gpt-5.2", "gpt-5.2-chat-latest", "gpt-5.3-chat-latest", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.5", "gpt-5.5-pro", "gpt-5.6-cyber", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-6-astra", "gpt-daybreak-blue-latest", "gpt-daybreak-red-latest", "gpt-oss-120b", "gpt-oss-20b", "o1-mini", "o3", "o3-deep-research", "o3-mini", "o4-mini", "o4-mini-deep-research" ], "compatible_endpoints": [ "POST /v1/responses", "Assistants API (legacy)" ], "parameters_schema": { "type": "object", "title": "Code interpreter", "description": "A tool that runs Python code to help generate a response to a prompt.\n", "properties": { "type": { "type": "string", "enum": [ "code_interpreter" ], "description": "The type of the code interpreter tool. Always `code_interpreter`.\n", "x-stainless-const": true }, "container": { "description": "The code interpreter container. Can be a container ID or an object that\nspecifies uploaded file IDs to make available to your code, along with an\noptional `memory_limit` setting.\n", "oneOf": [ { "type": "string", "description": "The container ID." }, { "properties": { "type": { "type": "string", "enum": [ "auto" ], "description": "Always `auto`.", "default": "auto", "x-stainless-const": true }, "file_ids": { "items": { "type": "string", "example": "file-123" }, "type": "array", "maxItems": 50, "description": "An optional list of uploaded files to make available to your code." }, "memory_limit": { "anyOf": [ { "type": "string", "enum": [ "1g", "4g", "16g", "64g" ] }, { "type": "null" } ] }, "network_policy": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "disabled" ], "description": "Disable outbound network access. Always `disabled`.", "default": "disabled", "x-stainless-const": true } }, "type": "object", "required": [ "type" ] }, { "properties": { "type": { "type": "string", "enum": [ "allowlist" ], "description": "Allow outbound network access only to specified domains. Always `allowlist`.", "default": "allowlist", "x-stainless-const": true }, "allowed_domains": { "items": { "type": "string" }, "type": "array", "minItems": 1, "description": "A list of allowed domains when type is `allowlist`." }, "domain_secrets": { "items": { "properties": { "$comment": "depth-limited" }, "type": { "$comment": "depth-limited" }, "required": { "$comment": "depth-limited" } }, "type": "array", "minItems": 1, "description": "Optional domain-scoped secrets for allowlisted domains." } }, "type": "object", "required": [ "type", "allowed_domains" ] } ], "description": "Network access policy for the container.", "discriminator": { "propertyName": "type" } } }, "type": "object", "required": [ "type" ], "title": "CodeInterpreterToolAuto", "description": "Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on." } ] }, "allowed_callers": { "anyOf": [ { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "direct", "programmatic" ] }, "description": "The tool invocation context(s)." }, { "type": "null" } ] } }, "required": [ "type", "container" ] }, "tool_choice_support": { "modes": [ "none", "auto", "required" ], "allowed_tools": { "type": "allowed_tools", "mode": "auto|required", "tools": [ "{type,name,...}" ] }, "specific": { "type": "code_interpreter" } }, "parallel": { "supported": false }, "streaming_events": [ "response.output_item.added", "response.code_interpreter_call.in_progress", "response.code_interpreter_call_code.delta", "response.code_interpreter_call_code.done", "response.code_interpreter_call.interpreting", "response.code_interpreter_call.completed", "response.output_item.done", "response.output_text.annotation.added" ], "result_shape": { "items": [ { "schema_name": "CodeInterpreterToolCall", "type": "code_interpreter_call", "schema": { "type": "object", "title": "Code interpreter tool call", "description": "A tool call to run code.\n", "properties": { "type": { "type": "string", "enum": [ "code_interpreter_call" ], "default": "code_interpreter_call", "x-stainless-const": true, "description": "The type of the code interpreter tool call. Always `code_interpreter_call`.\n" }, "id": { "type": "string", "description": "The unique ID of the code interpreter tool call.\n" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "incomplete", "interpreting", "failed" ], "description": "The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`.\n" }, "container_id": { "type": "string", "description": "The ID of the container used to run the code.\n" }, "code": { "anyOf": [ { "type": "string", "description": "The code to run, or null if not available.\n" }, { "type": "null" } ] }, "outputs": { "anyOf": [ { "type": "array", "items": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "logs" ], "description": "The type of the output. Always `logs`.", "default": "logs", "x-stainless-const": true }, "logs": { "type": "string", "description": "The logs output from the code interpreter." } }, "type": "object", "required": [ "type", "logs" ], "title": "Code interpreter output logs", "description": "The logs output from the code interpreter." }, { "properties": { "type": { "type": "string", "enum": [ "image" ], "description": "The type of the output. Always `image`.", "default": "image", "x-stainless-const": true }, "url": { "type": "string", "format": "uri", "description": "The URL of the image output from the code interpreter." } }, "type": "object", "required": [ "type", "url" ], "title": "Code interpreter output image", "description": "The image output from the code interpreter." } ], "discriminator": { "propertyName": "type" } }, "discriminator": { "propertyName": "type" }, "description": "The outputs generated by the code interpreter, such as logs or images.\nCan be null if no outputs are available.\n" }, { "type": "null" } ] } }, "required": [ "type", "id", "status", "container_id", "code", "outputs" ] } } ], "summary": "Output item `code_interpreter_call` {id, status: in_progress|interpreting|completed|incomplete|failed, container_id, code, outputs: [{type: logs, logs} | {type: image, url}] | null}." }, "billing": { "per_session": "1 GB $0.03 · 4 GB $0.12 · 16 GB $0.48 · 64 GB $1.92 per 20-minute session per container (shared with hosted shell)", "source": "https://developers.openai.com/api/docs/pricing#built-in-tools" }, "limitations": [ "Container expires after 20 min of inactivity (auto containers: expires_after last_active_at 20 min); expired containers cannot be revived.", "No outbound network by default (network_policy allowlist/disabled; org allow-list applies).", "Model knows the tool as the 'python tool'." ], "security": [ "Network-enabled containers: prompt-injection driven exfiltration risk; only allowlist trusted domains; use domain_secrets instead of raw credentials." ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/openai/tools/code-interpreter/code_interpreter.sh", "python": "examples/openai/tools/code-interpreter/code_interpreter.py", "typescript": "examples/openai/tools/code-interpreter/code_interpreter.ts" }, "verification": { "auto_container": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 200, "request_note": "gpt-5.4-nano: container auto, include code_interpreter_call.outputs -> code 'print(2+2)', outputs [{type:logs, logs:'4\\n'}], container_id cntr_…; then GET/LIST/DELETE container 200 (see containers endpoints)" }, "streaming": { "method": "docs_only", "verified_at": "2026-09-18", "result": "success", "http_status": 0, "request_note": "not streamed live (cost); events from spec" } }, "sources": [ { "url": "https://developers.openai.com/api/docs/guides/tools-code-interpreter", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/reference/resources/containers", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/docs/pricing#built-in-tools", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/tools/openai-tools.json" }, { "provider": "openai", "name": "Computer use (preview tool + computer-use-preview model)", "type": "computer_use_preview", "category": "client", "description": "Model returns structured GUI actions (`computer_call` with action click/double_click/drag/keypress/move/screenshot/scroll/type/wait and `pending_safety_checks`); the app executes them and returns `computer_call_output` {call_id, output: {type: computer_screenshot, image_url|file_id}, acknowledged_safety_checks}. Requires `display_width`, `display_height`, `environment` (windows|mac|linux|ubuntu|browser). Historically paired with model `computer-use-preview`; newer docs recommend the `computer` tool or code-execution with GPT-6 Astra.", "compatible_models": [ "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-pro", "gpt-5.5", "gpt-5.6-cyber", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-6-astra", "gpt-daybreak-blue-latest", "gpt-daybreak-red-latest" ], "compatible_endpoints": [ "POST /v1/responses" ], "parameters_schema": { "properties": { "type": { "type": "string", "enum": [ "computer_use_preview" ], "description": "The type of the computer use tool. Always `computer_use_preview`.", "default": "computer_use_preview", "x-stainless-const": true }, "environment": { "type": "string", "enum": [ "windows", "mac", "linux", "ubuntu", "browser" ] }, "display_width": { "type": "integer", "description": "The width of the computer display." }, "display_height": { "type": "integer", "description": "The height of the computer display." } }, "type": "object", "required": [ "type", "environment", "display_width", "display_height" ], "title": "Computer use preview", "description": "A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use)." }, "tool_choice_support": { "modes": [ "none", "auto", "required" ], "allowed_tools": { "type": "allowed_tools", "mode": "auto|required", "tools": [ "{type,name,...}" ] }, "specific": { "type": "computer_use_preview" } }, "parallel": { "supported": false }, "streaming_events": [ "response.output_item.added", "response.output_item.done" ], "result_shape": { "items": [ { "schema_name": "ComputerToolCall", "type": "computer_call", "schema": { "type": "object", "title": "Computer tool call", "description": "A tool call to a computer use tool. See the\n[computer use guide](https://developers.openai.com/api/docs/guides/tools-computer-use) for more information.\n", "properties": { "type": { "type": "string", "description": "The type of the computer call. Always `computer_call`.", "enum": [ "computer_call" ], "default": "computer_call" }, "id": { "type": "string", "description": "The unique ID of the computer call." }, "call_id": { "type": "string", "description": "An identifier used when responding to the tool call with output.\n" }, "action": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "click" ], "description": "Specifies the event type. For a click action, this property is always `click`.", "default": "click", "x-stainless-const": true }, "button": { "type": "string", "enum": [ "left", "right", "wheel", "back", "forward" ] }, "x": { "type": "integer", "description": "The x-coordinate where the click occurred." }, "y": { "type": "integer", "description": "The y-coordinate where the click occurred." }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while clicking." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "button", "x", "y" ], "title": "Click", "description": "A click action." }, { "properties": { "type": { "type": "string", "enum": [ "double_click" ], "description": "Specifies the event type. For a double click action, this property is always set to `double_click`.", "default": "double_click", "x-stainless-const": true }, "x": { "type": "integer", "description": "The x-coordinate where the double click occurred." }, "y": { "type": "integer", "description": "The y-coordinate where the double click occurred." }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while double-clicking." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "x", "y", "keys" ], "title": "DoubleClick", "description": "A double click action." }, { "properties": { "type": { "type": "string", "enum": [ "drag" ], "description": "Specifies the event type. For a drag action, this property is always set to `drag`.", "default": "drag", "x-stainless-const": true }, "path": { "items": { "properties": { "x": { "type": "integer", "description": "The x-coordinate." }, "y": { "type": "integer", "description": "The y-coordinate." } }, "type": "object", "required": [ "x", "y" ], "title": "Coordinate", "description": "An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`." }, "type": "array", "description": "An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg\n```\n[\n { x: 100, y: 200 },\n { x: 200, y: 300 }\n]\n```" }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while dragging the mouse." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "path" ], "title": "Drag", "description": "A drag action." }, { "properties": { "type": { "type": "string", "enum": [ "keypress" ], "description": "Specifies the event type. For a keypress action, this property is always set to `keypress`.", "default": "keypress", "x-stainless-const": true }, "keys": { "items": { "type": "string", "description": "One of the keys the model is requesting to be pressed." }, "type": "array", "description": "The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key." } }, "type": "object", "required": [ "type", "keys" ], "title": "KeyPress", "description": "A collection of keypresses the model would like to perform." }, { "properties": { "type": { "type": "string", "enum": [ "move" ], "description": "Specifies the event type. For a move action, this property is always set to `move`.", "default": "move", "x-stainless-const": true }, "x": { "type": "integer", "description": "The x-coordinate to move to." }, "y": { "type": "integer", "description": "The y-coordinate to move to." }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while moving the mouse." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "x", "y" ], "title": "Move", "description": "A mouse move action." }, { "properties": { "type": { "type": "string", "enum": [ "screenshot" ], "description": "Specifies the event type. For a screenshot action, this property is always set to `screenshot`.", "default": "screenshot", "x-stainless-const": true } }, "type": "object", "required": [ "type" ], "title": "Screenshot", "description": "A screenshot action." }, { "properties": { "type": { "type": "string", "enum": [ "scroll" ], "description": "Specifies the event type. For a scroll action, this property is always set to `scroll`.", "default": "scroll", "x-stainless-const": true }, "x": { "type": "integer", "description": "The x-coordinate where the scroll occurred." }, "y": { "type": "integer", "description": "The y-coordinate where the scroll occurred." }, "scroll_x": { "type": "integer", "description": "The horizontal scroll distance." }, "scroll_y": { "type": "integer", "description": "The vertical scroll distance." }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while scrolling." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "x", "y", "scroll_x", "scroll_y" ], "title": "Scroll", "description": "A scroll action." }, { "properties": { "type": { "type": "string", "enum": [ "type" ], "description": "Specifies the event type. For a type action, this property is always set to `type`.", "default": "type", "x-stainless-const": true }, "text": { "type": "string", "description": "The text to type." } }, "type": "object", "required": [ "type", "text" ], "title": "Type", "description": "An action to type in text." }, { "properties": { "type": { "type": "string", "enum": [ "wait" ], "description": "Specifies the event type. For a wait action, this property is always set to `wait`.", "default": "wait", "x-stainless-const": true } }, "type": "object", "required": [ "type" ], "title": "Wait", "description": "A wait action." } ], "discriminator": { "propertyName": "type" } }, "actions": { "title": "Computer Action List", "type": "array", "description": "Flattened batched actions for `computer_use`. Each action includes an\n`type` discriminator and action-specific fields.\n", "items": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "click" ], "description": "Specifies the event type. For a click action, this property is always `click`.", "default": "click", "x-stainless-const": true }, "button": { "type": "string", "enum": [ "left", "right", "wheel", "back", "forward" ] }, "x": { "type": "integer", "description": "The x-coordinate where the click occurred." }, "y": { "type": "integer", "description": "The y-coordinate where the click occurred." }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while clicking." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "button", "x", "y" ], "title": "Click", "description": "A click action." }, { "properties": { "type": { "type": "string", "enum": [ "double_click" ], "description": "Specifies the event type. For a double click action, this property is always set to `double_click`.", "default": "double_click", "x-stainless-const": true }, "x": { "type": "integer", "description": "The x-coordinate where the double click occurred." }, "y": { "type": "integer", "description": "The y-coordinate where the double click occurred." }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while double-clicking." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "x", "y", "keys" ], "title": "DoubleClick", "description": "A double click action." }, { "properties": { "type": { "type": "string", "enum": [ "drag" ], "description": "Specifies the event type. For a drag action, this property is always set to `drag`.", "default": "drag", "x-stainless-const": true }, "path": { "items": { "properties": { "x": { "type": { "$comment": "depth-limited" }, "description": { "$comment": "depth-limited" } }, "y": { "type": { "$comment": "depth-limited" }, "description": { "$comment": "depth-limited" } } }, "type": "object", "required": [ "x", "y" ], "title": "Coordinate", "description": "An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`." }, "type": "array", "description": "An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg\n```\n[\n { x: 100, y: 200 },\n { x: 200, y: 300 }\n]\n```" }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while dragging the mouse." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "path" ], "title": "Drag", "description": "A drag action." }, { "properties": { "type": { "type": "string", "enum": [ "keypress" ], "description": "Specifies the event type. For a keypress action, this property is always set to `keypress`.", "default": "keypress", "x-stainless-const": true }, "keys": { "items": { "type": "string", "description": "One of the keys the model is requesting to be pressed." }, "type": "array", "description": "The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key." } }, "type": "object", "required": [ "type", "keys" ], "title": "KeyPress", "description": "A collection of keypresses the model would like to perform." }, { "properties": { "type": { "type": "string", "enum": [ "move" ], "description": "Specifies the event type. For a move action, this property is always set to `move`.", "default": "move", "x-stainless-const": true }, "x": { "type": "integer", "description": "The x-coordinate to move to." }, "y": { "type": "integer", "description": "The y-coordinate to move to." }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while moving the mouse." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "x", "y" ], "title": "Move", "description": "A mouse move action." }, { "properties": { "type": { "type": "string", "enum": [ "screenshot" ], "description": "Specifies the event type. For a screenshot action, this property is always set to `screenshot`.", "default": "screenshot", "x-stainless-const": true } }, "type": "object", "required": [ "type" ], "title": "Screenshot", "description": "A screenshot action." }, { "properties": { "type": { "type": "string", "enum": [ "scroll" ], "description": "Specifies the event type. For a scroll action, this property is always set to `scroll`.", "default": "scroll", "x-stainless-const": true }, "x": { "type": "integer", "description": "The x-coordinate where the scroll occurred." }, "y": { "type": "integer", "description": "The y-coordinate where the scroll occurred." }, "scroll_x": { "type": "integer", "description": "The horizontal scroll distance." }, "scroll_y": { "type": "integer", "description": "The vertical scroll distance." }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while scrolling." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "x", "y", "scroll_x", "scroll_y" ], "title": "Scroll", "description": "A scroll action." }, { "properties": { "type": { "type": "string", "enum": [ "type" ], "description": "Specifies the event type. For a type action, this property is always set to `type`.", "default": "type", "x-stainless-const": true }, "text": { "type": "string", "description": "The text to type." } }, "type": "object", "required": [ "type", "text" ], "title": "Type", "description": "An action to type in text." }, { "properties": { "type": { "type": "string", "enum": [ "wait" ], "description": "Specifies the event type. For a wait action, this property is always set to `wait`.", "default": "wait", "x-stainless-const": true } }, "type": "object", "required": [ "type" ], "title": "Wait", "description": "A wait action." } ], "discriminator": { "propertyName": "type" } } }, "pending_safety_checks": { "type": "array", "items": { "properties": { "id": { "type": "string", "description": "The ID of the pending safety check." }, "code": { "anyOf": [ { "type": "string", "description": "The type of the pending safety check." }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string", "description": "Details about the pending safety check." }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "description": "A pending safety check for the computer call." }, "description": "The pending safety checks for the computer call.\n" }, "status": { "type": "string", "description": "The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.\n", "enum": [ "in_progress", "completed", "incomplete" ] } }, "required": [ "type", "id", "call_id", "pending_safety_checks", "status" ] } }, { "schema_name": "ComputerToolCallOutput", "type": "computer_call_output", "schema": { "type": "object", "title": "Computer tool call output", "description": "The output of a computer tool call.\n", "properties": { "type": { "type": "string", "description": "The type of the computer tool call output. Always `computer_call_output`.\n", "enum": [ "computer_call_output" ], "default": "computer_call_output", "x-stainless-const": true }, "id": { "type": "string", "description": "The ID of the computer tool call output.\n" }, "call_id": { "type": "string", "description": "The ID of the computer tool call that produced the output.\n" }, "acknowledged_safety_checks": { "type": "array", "description": "The safety checks reported by the API that have been acknowledged by the\ndeveloper.\n", "items": { "properties": { "id": { "type": "string", "description": "The ID of the pending safety check." }, "code": { "anyOf": [ { "type": "string", "description": "The type of the pending safety check." }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string", "description": "Details about the pending safety check." }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "description": "A pending safety check for the computer call." } }, "output": { "type": "object", "description": "A computer screenshot image used with the computer use tool.\n", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ], "default": "computer_screenshot", "description": "Specifies the event type. For a computer screenshot, this property is \nalways set to `computer_screenshot`.\n", "x-stainless-const": true }, "image_url": { "type": "string", "format": "uri", "description": "The URL of the screenshot image." }, "file_id": { "type": "string", "description": "The identifier of an uploaded file that contains the screenshot." } }, "required": [ "type" ] }, "status": { "type": "string", "description": "The status of the message input. One of `in_progress`, `completed`, or\n`incomplete`. Populated when input items are returned via API.\n", "enum": [ "in_progress", "completed", "incomplete" ] } }, "required": [ "type", "call_id", "output" ] } } ], "summary": "`computer_call` {id, call_id, action, pending_safety_checks, status}; input `computer_call_output`; `include: [computer_call_output.output.image_url]` returns screenshot URLs in retrieved items." }, "billing": { "model": "computer-use-preview $3 / 1M input, $12 / 1M output (model page); newer models at their own rates", "source": "https://developers.openai.com/api/docs/models/computer-use-preview" }, "limitations": [ "Requires `truncation: auto` with computer-use-preview.", "Our key: model computer-use-preview -> 404 model_not_found (tiered/limited access)." ], "security": [ "Isolated browser/VM, site allow-list, treat screen content as untrusted, confirm at the point of risk, enforce step/time/cost limits, acknowledge `pending_safety_checks` explicitly." ], "beta_header": null, "status": [ "DOCUMENTED", "PREVIEW", "ACCOUNT_RESTRICTED" ], "examples": { "curl": "examples/openai/tools/computer-use/computer_use.sh", "python": "examples/openai/tools/computer-use/computer_use.py", "typescript": "examples/openai/tools/computer-use/computer_use.ts" }, "verification": { "computer_use_preview_model": { "method": "live_api", "verified_at": "2026-09-18", "result": "restricted", "http_status": 404, "request_note": "POST /v1/responses model=computer-use-preview with 1x1 PNG input_image + computer_use_preview tool -> 404 invalid_request_error code=model_not_found 'does not exist or you do not have access'" } }, "sources": [ { "url": "https://developers.openai.com/api/docs/guides/tools-computer-use", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/docs/guides/tools-computer-use-integration", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/docs/models/computer-use-preview", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/tools/openai-tools.json" }, { "provider": "openai", "name": "Computer tool (current)", "type": "computer", "category": "client", "description": "Current computer-use tool (`{type: computer}`, no display parameters in the spec). Same `computer_call`/`computer_call_output` loop; `computer_call.actions[]` carries flattened batched actions for `computer_use`. Listed as `computer_use` on gpt-5.4/5.4-mini/5.4-pro/5.5/5.6*/gpt-6-astra model pages.", "compatible_models": [ "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-pro", "gpt-5.5", "gpt-5.6-cyber", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-6-astra", "gpt-daybreak-blue-latest", "gpt-daybreak-red-latest" ], "compatible_endpoints": [ "POST /v1/responses" ], "parameters_schema": { "properties": { "type": { "type": "string", "enum": [ "computer" ], "description": "The type of the computer tool. Always `computer`.", "default": "computer", "x-stainless-const": true } }, "type": "object", "required": [ "type" ], "title": "Computer", "description": "A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use)." }, "tool_choice_support": { "modes": [ "none", "auto", "required" ], "allowed_tools": { "type": "allowed_tools", "mode": "auto|required", "tools": [ "{type,name,...}" ] }, "specific": [ { "type": "computer" }, { "type": "computer_use" } ] }, "parallel": { "supported": false }, "streaming_events": [ "response.output_item.added", "response.output_item.done" ], "result_shape": { "items": [ { "schema_name": "ComputerToolCall", "type": "computer_call", "schema": { "type": "object", "title": "Computer tool call", "description": "A tool call to a computer use tool. See the\n[computer use guide](https://developers.openai.com/api/docs/guides/tools-computer-use) for more information.\n", "properties": { "type": { "type": "string", "description": "The type of the computer call. Always `computer_call`.", "enum": [ "computer_call" ], "default": "computer_call" }, "id": { "type": "string", "description": "The unique ID of the computer call." }, "call_id": { "type": "string", "description": "An identifier used when responding to the tool call with output.\n" }, "action": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "click" ], "description": "Specifies the event type. For a click action, this property is always `click`.", "default": "click", "x-stainless-const": true }, "button": { "type": "string", "enum": [ "left", "right", "wheel", "back", "forward" ] }, "x": { "type": "integer", "description": "The x-coordinate where the click occurred." }, "y": { "type": "integer", "description": "The y-coordinate where the click occurred." }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while clicking." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "button", "x", "y" ], "title": "Click", "description": "A click action." }, { "properties": { "type": { "type": "string", "enum": [ "double_click" ], "description": "Specifies the event type. For a double click action, this property is always set to `double_click`.", "default": "double_click", "x-stainless-const": true }, "x": { "type": "integer", "description": "The x-coordinate where the double click occurred." }, "y": { "type": "integer", "description": "The y-coordinate where the double click occurred." }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while double-clicking." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "x", "y", "keys" ], "title": "DoubleClick", "description": "A double click action." }, { "properties": { "type": { "type": "string", "enum": [ "drag" ], "description": "Specifies the event type. For a drag action, this property is always set to `drag`.", "default": "drag", "x-stainless-const": true }, "path": { "items": { "properties": { "x": { "type": "integer", "description": "The x-coordinate." }, "y": { "type": "integer", "description": "The y-coordinate." } }, "type": "object", "required": [ "x", "y" ], "title": "Coordinate", "description": "An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`." }, "type": "array", "description": "An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg\n```\n[\n { x: 100, y: 200 },\n { x: 200, y: 300 }\n]\n```" }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while dragging the mouse." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "path" ], "title": "Drag", "description": "A drag action." }, { "properties": { "type": { "type": "string", "enum": [ "keypress" ], "description": "Specifies the event type. For a keypress action, this property is always set to `keypress`.", "default": "keypress", "x-stainless-const": true }, "keys": { "items": { "type": "string", "description": "One of the keys the model is requesting to be pressed." }, "type": "array", "description": "The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key." } }, "type": "object", "required": [ "type", "keys" ], "title": "KeyPress", "description": "A collection of keypresses the model would like to perform." }, { "properties": { "type": { "type": "string", "enum": [ "move" ], "description": "Specifies the event type. For a move action, this property is always set to `move`.", "default": "move", "x-stainless-const": true }, "x": { "type": "integer", "description": "The x-coordinate to move to." }, "y": { "type": "integer", "description": "The y-coordinate to move to." }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while moving the mouse." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "x", "y" ], "title": "Move", "description": "A mouse move action." }, { "properties": { "type": { "type": "string", "enum": [ "screenshot" ], "description": "Specifies the event type. For a screenshot action, this property is always set to `screenshot`.", "default": "screenshot", "x-stainless-const": true } }, "type": "object", "required": [ "type" ], "title": "Screenshot", "description": "A screenshot action." }, { "properties": { "type": { "type": "string", "enum": [ "scroll" ], "description": "Specifies the event type. For a scroll action, this property is always set to `scroll`.", "default": "scroll", "x-stainless-const": true }, "x": { "type": "integer", "description": "The x-coordinate where the scroll occurred." }, "y": { "type": "integer", "description": "The y-coordinate where the scroll occurred." }, "scroll_x": { "type": "integer", "description": "The horizontal scroll distance." }, "scroll_y": { "type": "integer", "description": "The vertical scroll distance." }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while scrolling." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "x", "y", "scroll_x", "scroll_y" ], "title": "Scroll", "description": "A scroll action." }, { "properties": { "type": { "type": "string", "enum": [ "type" ], "description": "Specifies the event type. For a type action, this property is always set to `type`.", "default": "type", "x-stainless-const": true }, "text": { "type": "string", "description": "The text to type." } }, "type": "object", "required": [ "type", "text" ], "title": "Type", "description": "An action to type in text." }, { "properties": { "type": { "type": "string", "enum": [ "wait" ], "description": "Specifies the event type. For a wait action, this property is always set to `wait`.", "default": "wait", "x-stainless-const": true } }, "type": "object", "required": [ "type" ], "title": "Wait", "description": "A wait action." } ], "discriminator": { "propertyName": "type" } }, "actions": { "title": "Computer Action List", "type": "array", "description": "Flattened batched actions for `computer_use`. Each action includes an\n`type` discriminator and action-specific fields.\n", "items": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "click" ], "description": "Specifies the event type. For a click action, this property is always `click`.", "default": "click", "x-stainless-const": true }, "button": { "type": "string", "enum": [ "left", "right", "wheel", "back", "forward" ] }, "x": { "type": "integer", "description": "The x-coordinate where the click occurred." }, "y": { "type": "integer", "description": "The y-coordinate where the click occurred." }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while clicking." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "button", "x", "y" ], "title": "Click", "description": "A click action." }, { "properties": { "type": { "type": "string", "enum": [ "double_click" ], "description": "Specifies the event type. For a double click action, this property is always set to `double_click`.", "default": "double_click", "x-stainless-const": true }, "x": { "type": "integer", "description": "The x-coordinate where the double click occurred." }, "y": { "type": "integer", "description": "The y-coordinate where the double click occurred." }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while double-clicking." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "x", "y", "keys" ], "title": "DoubleClick", "description": "A double click action." }, { "properties": { "type": { "type": "string", "enum": [ "drag" ], "description": "Specifies the event type. For a drag action, this property is always set to `drag`.", "default": "drag", "x-stainless-const": true }, "path": { "items": { "properties": { "x": { "type": { "$comment": "depth-limited" }, "description": { "$comment": "depth-limited" } }, "y": { "type": { "$comment": "depth-limited" }, "description": { "$comment": "depth-limited" } } }, "type": "object", "required": [ "x", "y" ], "title": "Coordinate", "description": "An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`." }, "type": "array", "description": "An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg\n```\n[\n { x: 100, y: 200 },\n { x: 200, y: 300 }\n]\n```" }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while dragging the mouse." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "path" ], "title": "Drag", "description": "A drag action." }, { "properties": { "type": { "type": "string", "enum": [ "keypress" ], "description": "Specifies the event type. For a keypress action, this property is always set to `keypress`.", "default": "keypress", "x-stainless-const": true }, "keys": { "items": { "type": "string", "description": "One of the keys the model is requesting to be pressed." }, "type": "array", "description": "The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key." } }, "type": "object", "required": [ "type", "keys" ], "title": "KeyPress", "description": "A collection of keypresses the model would like to perform." }, { "properties": { "type": { "type": "string", "enum": [ "move" ], "description": "Specifies the event type. For a move action, this property is always set to `move`.", "default": "move", "x-stainless-const": true }, "x": { "type": "integer", "description": "The x-coordinate to move to." }, "y": { "type": "integer", "description": "The y-coordinate to move to." }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while moving the mouse." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "x", "y" ], "title": "Move", "description": "A mouse move action." }, { "properties": { "type": { "type": "string", "enum": [ "screenshot" ], "description": "Specifies the event type. For a screenshot action, this property is always set to `screenshot`.", "default": "screenshot", "x-stainless-const": true } }, "type": "object", "required": [ "type" ], "title": "Screenshot", "description": "A screenshot action." }, { "properties": { "type": { "type": "string", "enum": [ "scroll" ], "description": "Specifies the event type. For a scroll action, this property is always set to `scroll`.", "default": "scroll", "x-stainless-const": true }, "x": { "type": "integer", "description": "The x-coordinate where the scroll occurred." }, "y": { "type": "integer", "description": "The y-coordinate where the scroll occurred." }, "scroll_x": { "type": "integer", "description": "The horizontal scroll distance." }, "scroll_y": { "type": "integer", "description": "The vertical scroll distance." }, "keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "description": "The keys being held while scrolling." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "x", "y", "scroll_x", "scroll_y" ], "title": "Scroll", "description": "A scroll action." }, { "properties": { "type": { "type": "string", "enum": [ "type" ], "description": "Specifies the event type. For a type action, this property is always set to `type`.", "default": "type", "x-stainless-const": true }, "text": { "type": "string", "description": "The text to type." } }, "type": "object", "required": [ "type", "text" ], "title": "Type", "description": "An action to type in text." }, { "properties": { "type": { "type": "string", "enum": [ "wait" ], "description": "Specifies the event type. For a wait action, this property is always set to `wait`.", "default": "wait", "x-stainless-const": true } }, "type": "object", "required": [ "type" ], "title": "Wait", "description": "A wait action." } ], "discriminator": { "propertyName": "type" } } }, "pending_safety_checks": { "type": "array", "items": { "properties": { "id": { "type": "string", "description": "The ID of the pending safety check." }, "code": { "anyOf": [ { "type": "string", "description": "The type of the pending safety check." }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string", "description": "Details about the pending safety check." }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "description": "A pending safety check for the computer call." }, "description": "The pending safety checks for the computer call.\n" }, "status": { "type": "string", "description": "The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.\n", "enum": [ "in_progress", "completed", "incomplete" ] } }, "required": [ "type", "id", "call_id", "pending_safety_checks", "status" ] } }, { "schema_name": "ComputerToolCallOutput", "type": "computer_call_output", "schema": { "type": "object", "title": "Computer tool call output", "description": "The output of a computer tool call.\n", "properties": { "type": { "type": "string", "description": "The type of the computer tool call output. Always `computer_call_output`.\n", "enum": [ "computer_call_output" ], "default": "computer_call_output", "x-stainless-const": true }, "id": { "type": "string", "description": "The ID of the computer tool call output.\n" }, "call_id": { "type": "string", "description": "The ID of the computer tool call that produced the output.\n" }, "acknowledged_safety_checks": { "type": "array", "description": "The safety checks reported by the API that have been acknowledged by the\ndeveloper.\n", "items": { "properties": { "id": { "type": "string", "description": "The ID of the pending safety check." }, "code": { "anyOf": [ { "type": "string", "description": "The type of the pending safety check." }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string", "description": "Details about the pending safety check." }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "description": "A pending safety check for the computer call." } }, "output": { "type": "object", "description": "A computer screenshot image used with the computer use tool.\n", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ], "default": "computer_screenshot", "description": "Specifies the event type. For a computer screenshot, this property is \nalways set to `computer_screenshot`.\n", "x-stainless-const": true }, "image_url": { "type": "string", "format": "uri", "description": "The URL of the screenshot image." }, "file_id": { "type": "string", "description": "The identifier of an uploaded file that contains the screenshot." } }, "required": [ "type" ] }, "status": { "type": "string", "description": "The status of the message input. One of `in_progress`, `completed`, or\n`incomplete`. Populated when input items are returned via API.\n", "enum": [ "in_progress", "completed", "incomplete" ] } }, "required": [ "type", "call_id", "output" ] } } ], "summary": "Same as computer_use_preview plus `actions[]` batches." }, "billing": { "model": "Token billing (images as input tokens)", "source": "https://developers.openai.com/api/docs/pricing#built-in-tools" }, "limitations": [ "Not live-tested (cost/safety); docs recommend code-execution integration for GPT-6 Astra." ], "security": [ "Isolated browser/VM, site allow-list, treat screen content as untrusted, confirm at the point of risk, enforce step/time/cost limits, acknowledge `pending_safety_checks` explicitly." ], "beta_header": null, "status": [ "DOCUMENTED", "UNVERIFIED" ], "examples": { "curl": "examples/openai/tools/computer-use/computer_use.sh", "python": "examples/openai/tools/computer-use/computer_use.py", "typescript": "examples/openai/tools/computer-use/computer_use.ts" }, "verification": { "docs": { "method": "docs_only", "verified_at": "2026-09-18", "result": "success", "http_status": 0, "request_note": "not called" } }, "sources": [ { "url": "https://developers.openai.com/api/docs/guides/tools-computer-use", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/docs/guides/tools-computer-use-integration", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/tools/openai-tools.json" }, { "provider": "openai", "name": "Image generation tool", "type": "image_generation", "category": "hosted", "description": "Lets a mainline model call GPT Image models (`model`: gpt-image-1, gpt-image-1-mini, gpt-image-1.5, gpt-image-2[-2026-04-21], gpt-image-2.5-sunburst|flare[-2026-09-08]). Parameters: size, quality (low|medium|high|xhigh|max|auto), background, output_format, output_compression, moderation, input_fidelity, input_image_mask, partial_images (0-3, streaming), action (generate|edit|auto). Result is base64 in `image_generation_call.result`.", "compatible_models": [ "chat-latest", "gpt-4.1", "gpt-4.1-nano", "gpt-4o", "gpt-4o-mini", "gpt-5", "gpt-5-chat-latest", "gpt-5-nano", "gpt-5-pro", "gpt-5.1", "gpt-5.1-chat-latest", "gpt-5.2", "gpt-5.2-chat-latest", "gpt-5.2-pro", "gpt-5.3-chat-latest", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.4-pro", "gpt-5.5", "gpt-5.5-pro", "gpt-5.6-cyber", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-6-astra", "gpt-daybreak-blue-latest", "gpt-daybreak-red-latest", "o3", "o3-mini", "o3-pro" ], "compatible_endpoints": [ "POST /v1/responses" ], "parameters_schema": { "type": "object", "title": "Image generation tool", "description": "A tool that generates images using the GPT image models.\n", "properties": { "type": { "type": "string", "enum": [ "image_generation" ], "description": "The type of the image generation tool. Always `image_generation`.\n", "x-stainless-const": true }, "model": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "gpt-image-1", "gpt-image-1-mini", "gpt-image-1.5", "gpt-image-2", "gpt-image-2-2026-04-21", "gpt-image-2.5-sunburst", "gpt-image-2.5-sunburst-2026-09-08", "gpt-image-2.5-flare", "gpt-image-2.5-flare-2026-09-08" ], "description": "The image generation model to use. One of `gpt-image-1`,\n`gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`,\n`gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`,\n`gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`,\n`gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`. Default:\n`gpt-image-1`.\n", "default": "gpt-image-1" } ] }, "quality": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max", "auto" ], "description": "The quality of the generated image. The GPT image models support `low`,\n`medium`, and `high`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`,\nincluding their `2026-09-08` snapshots, also support `xhigh` and `max`.\nDefault: `auto`.\n", "default": "auto" }, "size": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "1024x1024", "1024x1536", "1536x1024", "auto" ] } ], "description": "The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`.", "default": "auto" }, "output_format": { "type": "string", "enum": [ "png", "webp", "jpeg" ], "description": "The output format of the generated image. One of `png`, `webp`, or\n`jpeg`. Default: `png`.\n", "default": "png" }, "output_compression": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Compression level for the output image. Default: 100.\n", "default": 100 }, "moderation": { "type": "string", "enum": [ "auto", "low" ], "description": "Moderation level for the generated image. Default: `auto`.\n", "default": "auto" }, "background": { "type": "string", "enum": [ "transparent", "opaque", "auto" ], "description": "Set the background of the generated image. One of `transparent`, `opaque`,\nor `auto`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including\ntheir `2026-09-08` snapshots, support `opaque` and `transparent`\nbackgrounds. Transparent backgrounds are available for supported GPT Image\nmodels. For `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in\npreview. When using `transparent`, set the output format to `png` or `webp`.\nDefault: `auto`.\n", "default": "auto" }, "input_fidelity": { "anyOf": [ { "type": "string", "enum": [ "high", "low" ], "description": "Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`." }, { "type": "null" } ] }, "input_image_mask": { "type": "object", "description": "Optional mask for inpainting. Contains `image_url`\n(string, optional) and `file_id` (string, optional).\n", "properties": { "image_url": { "type": "string", "description": "Base64-encoded mask image.\n" }, "file_id": { "type": "string", "description": "File ID for the mask image.\n" } }, "required": [], "additionalProperties": false }, "partial_images": { "type": "integer", "minimum": 0, "maximum": 3, "description": "Number of partial images to generate in streaming mode, from 0 (default value) to 3.\n", "default": 0 }, "action": { "type": "string", "enum": [ "generate", "edit", "auto" ] } }, "required": [ "type" ] }, "tool_choice_support": { "modes": [ "none", "auto", "required" ], "allowed_tools": { "type": "allowed_tools", "mode": "auto|required", "tools": [ "{type,name,...}" ] }, "specific": { "type": "image_generation" } }, "parallel": { "supported": false }, "streaming_events": [ "response.output_item.added", "response.image_generation_call.in_progress", "response.image_generation_call.generating", "response.image_generation_call.partial_image", "response.image_generation_call.completed", "response.output_item.done" ], "result_shape": { "items": [ { "schema_name": "ImageGenToolCall", "type": "image_generation_call", "schema": { "properties": { "type": { "type": "string", "enum": [ "image_generation_call" ], "description": "The type of the image generation call. Always `image_generation_call`.", "x-stainless-const": true }, "id": { "type": "string", "description": "The unique ID of the image generation call." }, "status": { "type": "string", "enum": [ "in_progress", "completed", "generating", "failed" ], "description": "The status of the image generation call." }, "result": { "anyOf": [ { "type": "string", "description": "The generated image encoded in base64." }, { "type": "null" } ] }, "size": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "1024x1024", "1024x1536", "1536x1024" ] } ], "description": "The image dimensions as a `WIDTHxHEIGHT` string, for example `1536x864`." }, { "type": "null" } ] }, "quality": { "anyOf": [ { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max", "auto" ], "description": "The quality of the image generated by the image generation tool call. One of `low`, `medium`, `high`, `xhigh`, `max`, or `auto`." }, { "type": "null" } ] }, "action": { "anyOf": [ { "type": "string", "enum": [ "generate", "edit", "auto" ] }, { "type": "null" } ], "x-openai-go-optional-enum": true }, "background": { "anyOf": [ { "type": "string", "enum": [ "transparent", "opaque", "auto" ] }, { "type": "null" } ], "x-openai-go-optional-enum": true }, "output_format": { "anyOf": [ { "type": "string", "enum": [ "png", "webp", "jpeg" ] }, { "type": "null" } ], "x-openai-go-optional-enum": true }, "revised_prompt": { "anyOf": [ { "type": "string", "description": "The prompt that was used after any model prompt rewriting." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "id", "status", "result" ], "title": "Image generation call", "description": "An image generation request made by the model." } } ], "summary": "Output item `image_generation_call` {id, status: in_progress|generating|completed|failed, result: base64|null, revised_prompt, size, quality, background, output_format, action}." }, "billing": { "per_image": "Image model token pricing (see pricing fragment / image generation guide calculator); mainline model tokens billed separately", "source": "https://developers.openai.com/api/docs/pricing#image-generation" }, "limitations": [ "Guide model list: gpt-5.5, gpt-5.4-mini, gpt-5.4-nano, gpt-5.2, gpt-5, gpt-5-nano, o3, gpt-4.1(-mini/-nano), gpt-4o(-mini).", "Size must be divisible by 16 (live error).", "xhigh/max quality only on gpt-image-2.5-*." ], "security": [ "Moderation `low` relaxes filtering; images may be revised by the mainline model (revised_prompt)." ], "beta_header": null, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "examples": { "curl": "examples/openai/tools/image-generation/image_generation.sh", "python": "examples/openai/tools/image-generation/image_generation.py", "typescript": "examples/openai/tools/image-generation/image_generation.ts" }, "verification": { "invalid_size_error": { "method": "live_api", "verified_at": "2026-09-18", "result": "success", "http_status": 400, "request_note": "gpt-5.4-nano: size '1x1' -> 400 type=image_generation_user_error code=invalid_value param=tools 'Width and height must both be divisible by 16.' (generation itself skipped: RUN_IMAGE_TESTS)" } }, "sources": [ { "url": "https://developers.openai.com/api/docs/guides/tools-image-generation", "retrieved_at": "2026-09-18" }, { "url": "https://developers.openai.com/api/reference/resources/responses/methods/create", "retrieved_at": "2026-09-18" }, { "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)", "retrieved_at": "2026-09-18" } ], "last_verified": "2026-09-18", "_fragment": "generated/fragments/tools/openai-tools.json" }, { "provider": "openai", "name": "Remote MCP servers, connectors and Secure MCP Tunnel", "type": "mcp", "category": "mcp", "description": "Connects the model to a remote MCP server (`server_url`, Streamable HTTP or HTTP/SSE), a Secure MCP Tunnel (`tunnel_id`) or a legacy connector (`connector_id`, deprecated for models released after 2025-09-01). Auth via `authorization` (OAuth token, never stored/echoed) or `headers`. `allowed_tools` (list or {tool_names, read_only}), `require_approval` (always|never|{always:{...}, never:{...}}, default always), `defer_loading`, `allowed_callers`, `server_description`.", "compatible_models": [ "chat-latest", "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "gpt-4o", "gpt-4o-mini", "gpt-4o-mini-audio-preview", "gpt-5", "gpt-5-chat-latest", "gpt-5-mini", "gpt-5-nano", "gpt-5-pro", "gpt-5.1", "gpt-5.1-chat-latest", "gpt-5.2", "gpt-5.2-chat-latest", "gpt-5.2-pro", "gpt-5.3-chat-latest", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.4-pro", "gpt-5.5", "gpt-5.5-pro", "gpt-5.6-cyber", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-6-astra", "gpt-daybreak-blue-latest", "gpt-daybreak-red-latest", "gpt-oss-120b", "gpt-oss-20b", "o1", "o1-mini", "o1-pro", "o3", "o3-deep-research", "o3-mini", "o3-pro", "o4-mini", "o4-mini-deep-research" ], "compatible_endpoints": [ "POST /v1/responses", "POST /v1/realtime (mcp tool)", "Agents API (MCP connections)", "Deep research models" ], "parameters_schema": { "type": "object", "title": "MCP tool", "description": "Give the model access to additional tools via remote Model Context Protocol\n(MCP) servers. [Learn more about MCP](https://developers.openai.com/api/docs/guides/tools-connectors-mcp).\n", "properties": { "type": { "type": "string", "enum": [ "mcp" ], "description": "The type of the MCP tool. Always `mcp`.", "x-stainless-const": true }, "server_label": { "type": "string", "description": "A label for this MCP server, used to identify it in tool calls.\n" }, "server_url": { "type": "string", "format": "uri", "description": "The URL for the MCP server. One of `server_url`, `connector_id`, or\n`tunnel_id` must be provided.\n" }, "connector_id": { "type": "string", "deprecated": true, "enum": [ "connector_dropbox", "connector_gmail", "connector_googlecalendar", "connector_googledrive", "connector_microsoftteams", "connector_outlookcalendar", "connector_outlookemail", "connector_sharepoint" ], "description": "Identifier for service connectors, like those available in ChatGPT. One of\n`server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more\nabout service connectors [here](https://developers.openai.com/api/docs/guides/tools-connectors-mcp#connectors).\n\nThis field is deprecated for models released after September 1, 2026.\nUse `server_url` to connect to a remote MCP server, or `tunnel_id` to\nconnect through a Secure MCP Tunnel.\n\nCurrently supported `connector_id` values are:\n\n- Dropbox: `connector_dropbox`\n- Gmail: `connector_gmail`\n- Google Calendar: `connector_googlecalendar`\n- Google Drive: `connector_googledrive`\n- Microsoft Teams: `connector_microsoftteams`\n- Outlook Calendar: `connector_outlookcalendar`\n- Outlook Email: `connector_outlookemail`\n- SharePoint: `connector_sharepoint`\n" }, "tunnel_id": { "type": "string", "pattern": "^tunnel_[a-z0-9]{32}$", "description": "The Secure MCP Tunnel ID to use instead of a direct server URL. One of\n`server_url`, `connector_id`, or `tunnel_id` must be provided.\n" }, "authorization": { "type": "string", "description": "An OAuth access token that can be used with a remote MCP server, either\nwith a custom MCP server URL or a service connector. Your application\nmust handle the OAuth authorization flow and provide the token here.\n" }, "server_description": { "type": "string", "description": "Optional description of the MCP server, used to provide more context.\n" }, "headers": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional HTTP headers to send to the MCP server. Use for authentication\nor other purposes.\n" }, { "type": "null" } ] }, "allowed_tools": { "anyOf": [ { "description": "List of allowed tool names or a filter object.\n", "oneOf": [ { "type": "array", "title": "MCP allowed tools", "description": "A string array of allowed tool names", "items": { "type": "string" } }, { "type": "object", "title": "MCP tool filter", "description": "A filter object to specify which tools are allowed.\n", "properties": { "tool_names": { "type": "array", "title": "MCP allowed tools", "items": { "type": "string" }, "description": "List of allowed tool names." }, "read_only": { "type": "boolean", "description": "Indicates whether or not a tool modifies data or is read-only. If an\nMCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),\nit will match this filter.\n" } }, "required": [], "additionalProperties": false } ] }, { "type": "null" } ] }, "allowed_callers": { "anyOf": [ { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "direct", "programmatic" ] }, "description": "The tool invocation context(s)." }, { "type": "null" } ] }, "require_approval": { "anyOf": [ { "description": "Specify which of the MCP server's tools require approval.", "oneOf": [ { "type": "object", "title": "MCP tool approval filter", "description": "Specify which of the MCP server's tools require approval. Can be\n`always`, `never`, or a filter object associated with tools\nthat require approval.\n", "properties": { "always": { "type": "object", "title": "MCP tool filter", "description": "A filter object to specify which tools are allowed.\n", "properties": { "tool_names": { "type": "array", "title": "MCP allowed tools", "items": { "type": "string" }, "description": "List of allowed tool names." }, "read_only": { "type": "boolean", "description": "Indicates whether or not a tool modifies data or is read-only. If an\nMCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),\nit will match this filter.\n" } }, "required": [], "additionalProperties": false }, "never": { "type": "object", "title": "MCP tool filter", "description": "A filter object to specify which tools are allowed.\n", "properties": { "tool_names": { "type": "array", "title": "MCP allowed tools", "items": { "type": "string" }, "description": "List of allowed tool names." }, "read_only": { "type": "boolean", "description": "Indicates whether or not a tool modifies data or is read-only. If an\nMCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),\nit will match this filter.\n" } }, "required": [], "additionalProperties": false } }, "additionalProperties": false }, { "type": "string", "title": "MCP tool approval setting", "description": "Specify a single approval policy for all tools. One of `always` or\n`never`. When set to `always`, all tools will require approval. When\nset to `never`, all tools will not require approval.\n", "enum": [ "always", "never" ] } ], "default": "always" }, { "type": "null" } ] }, "defer_loading": { "type": "boolean", "description": "Whether this MCP tool is deferred and discovered via tool search.\n" } }, "required": [ "type", "server_label" ] }, "tool_choice_support": { "modes": [ "none", "auto", "required" ], "allowed_tools": { "type": "allowed_tools", "mode": "auto|required", "tools": [ "{type,name,...}" ] }, "specific": { "type": "mcp", "server_label": "