spb/doc-api

1[2 {3  "provider": "anthropic",4  "name": "Custom (user-defined) client tool",5  "type": "custom",6  "category": "client",7  "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\".",8  "compatible_models": [9   "claude-fable-5-1",10   "claude-opus-5",11   "claude-sonnet-5",12   "claude-fable-5",13   "claude-opus-4-8",14   "claude-opus-4-7",15   "claude-sonnet-4-6",16   "claude-opus-4-6",17   "claude-opus-4-5-20251101",18   "claude-haiku-4-5-20251001",19   "claude-sonnet-4-5-20250929",20   "claude-mythos-5-1",21   "claude-mythos-5"22  ],23  "compatible_endpoints": [24   "POST /v1/messages",25   "POST /v1/messages/batches"26  ],27  "parameters_schema": {28   "type": "object",29   "required": [30    "name",31    "input_schema"32   ],33   "properties": {34    "type": {35     "enum": [36      "custom"37     ],38     "description": "Optional; the only value is custom."39    },40    "name": {41     "type": "string",42     "pattern": "^[a-zA-Z0-9_-]{1,128}$",43     "description": "Unique within the request; must not collide with a toolset member family name (computer/browser) when that toolset is declared."44    },45    "description": {46     "type": "string",47     "description": "Strongly recommended, 3-4+ sentences: what, when (and when not), parameter semantics, caveats."48    },49    "input_schema": {50     "type": "object",51     "description": "JSON Schema, type must be object; properties/required. Strict mode uses the structured-outputs JSON Schema subset (additionalProperties:false etc.)."52    },53    "eager_input_streaming": {54     "type": "boolean",55     "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."56    },57    "cache_control": {58     "type": "object",59     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."60    },61    "strict": {62     "type": "boolean",63     "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)."64    },65    "defer_loading": {66     "type": "boolean",67     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."68    },69    "allowed_callers": {70     "type": "array",71     "items": {72      "enum": [73       "direct",74       "code_execution_20250825",75       "code_execution_20260120",76       "code_execution_20260521"77      ]78     },79     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])."80    },81    "input_examples": {82     "type": "array",83     "items": {84      "type": "object"85     },86     "description": "Schema-validated example inputs (user-defined + Anthropic-schema client tools only; not toolsets/server tools)."87    }88   }89  },90  "tool_choice_support": "auto/any/tool/none (tool_choice.type=tool may name this tool)",91  "parallel": "yes (several tool_use blocks per turn; one tool_result each, all in one user message)",92  "streaming_events": [93   "content_block_start (tool_use, input: {})",94   "content_block_delta (input_json_delta.partial_json)",95   "content_block_stop",96   "message_delta (stop_reason: tool_use)"97  ],98  "result_shape": {99   "tool_use": {100    "type": "tool_use",101    "id": "toolu_01…",102    "name": "<tool name>",103    "input": {104     "...": "object matching input_schema"105    },106    "caller": {107     "type": "direct"108    }109   },110   "tool_result (you send)": {111    "type": "tool_result",112    "tool_use_id": "toolu_01…",113    "content": "string | [text|image|document|search_result|tool_reference blocks]",114    "is_error": "optional bool",115    "cache_control": "optional"116   },117   "live_note": "Every tool_use block returned live on 2026-09-18 carried caller:{type:direct} (haiku 4.5, sonnet 4.6, sonnet 5)."118  },119  "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.",120  "limitations": [121   "Name regex ^[a-zA-Z0-9_-]{1,128}$",122   "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')",123   "tool_choice any/tool: unsupported with manual extended thinking (thinking.type=enabled) and returns 400 on Claude Fable 5.1 / Mythos 5.1 (docs)",124   "strict:true incompatible with allowed_callers containing a code_execution caller (live 400)",125   "Circular $ref schemas cannot be enabled for programmatic calling (400 'Circular $ref detected')"126  ],127  "security": [128   "Treat tool_result content as untrusted (indirect prompt injection); keep it inside tool_result, not system/user text.",129   "Do not put PHI in strict schemas (compiled grammars are cached up to 24h)."130  ],131  "beta_header": null,132  "status": [133   "DOCUMENTED",134   "LIVE_VERIFIED"135  ],136  "examples": {137   "curl": "examples/anthropic/tools/custom-tools/basic.sh",138   "python": "examples/anthropic/tools/custom-tools/basic.py",139   "typescript": "examples/anthropic/tools/custom-tools/basic.ts"140  },141  "verification": {142   "method": "live_api",143   "verified_at": "2026-09-18",144   "result": "success",145   "http_status": 200,146   "request_note": "a1_forced_tool..a10_input_examples, b1-b3 streaming, j1-j3 count_tokens on claude-haiku-4-5-20251001 (tmp-live/tools/)"147  },148  "sources": [149   {150    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools",151    "retrieved_at": "2026-09-18"152   },153   {154    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls",155    "retrieved_at": "2026-09-18"156   },157   {158    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use",159    "retrieved_at": "2026-09-18"160   },161   {162    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/strict-tool-use",163    "retrieved_at": "2026-09-18"164   },165   {166    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming",167    "retrieved_at": "2026-09-18"168   },169   {170    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview",171    "retrieved_at": "2026-09-18"172   },173   {174    "url": "https://platform.claude.com/docs/en/api/messages/create",175    "retrieved_at": "2026-09-18"176   }177  ],178  "last_verified": "2026-09-18",179  "tool_choice": {180   "auto": "default when tools present; may answer in text; disable_parallel_tool_use:true => at most one call (live verified)",181   "any": "must call some tool; disable_parallel_tool_use:true => exactly one call (live verified: haiku invented location '<UNKNOWN>' when forced on 'Say hello')",182   "tool": "{type:tool, name} forces that tool (live verified); assistant prefilled so no text before tool_use",183   "none": "no tool calls (live verified; default when no tools)"184  },185  "_fragment": "generated/fragments/tools/anthropic-tools.json"186 },187 {188  "provider": "anthropic",189  "name": "Bash tool",190  "type": "bash_20250124",191  "category": "anthropic-defined-client",192  "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.",193  "compatible_models": [194   "claude-fable-5-1",195   "claude-opus-5",196   "claude-sonnet-5",197   "claude-fable-5",198   "claude-opus-4-8",199   "claude-opus-4-7",200   "claude-sonnet-4-6",201   "claude-opus-4-6",202   "claude-opus-4-5-20251101",203   "claude-haiku-4-5-20251001",204   "claude-sonnet-4-5-20250929",205   "claude-mythos-5-1",206   "claude-mythos-5"207  ],208  "compatible_endpoints": [209   "POST /v1/messages",210   "POST /v1/messages/batches"211  ],212  "parameters_schema": {213   "type": "object",214   "required": [215    "type",216    "name"217   ],218   "properties": {219    "type": {220     "const": "bash_20250124"221    },222    "name": {223     "const": "bash"224    },225    "cache_control": {226     "type": "object",227     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."228    },229    "strict": {230     "type": "boolean",231     "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)."232    },233    "defer_loading": {234     "type": "boolean",235     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."236    },237    "allowed_callers": {238     "type": "array",239     "items": {240      "enum": [241       "direct",242       "code_execution_20250825",243       "code_execution_20260120",244       "code_execution_20260521"245      ]246     },247     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])."248    },249    "input_examples": {250     "type": "array",251     "items": {252      "type": "object"253     },254     "description": "Schema-validated example inputs (user-defined + Anthropic-schema client tools only; not toolsets/server tools)."255    }256   },257   "tool_use.input": {258    "command": {259     "type": "string",260     "description": "required unless restart"261    },262    "restart": {263     "type": "boolean"264    }265   }266  },267  "tool_choice_support": "auto/any/tool/none (tool_choice.type=tool may name this tool)",268  "parallel": "yes (several tool_use blocks per turn; one tool_result each, all in one user message)",269  "streaming_events": [270   "content_block_start (tool_use, input: {})",271   "content_block_delta (input_json_delta.partial_json)",272   "content_block_stop",273   "message_delta (stop_reason: tool_use)"274  ],275  "result_shape": {276   "tool_use": {277    "type": "tool_use",278    "id": "toolu_…",279    "name": "bash",280    "input": {281     "command": "echo OK"282    },283    "caller": {284     "type": "direct"285    }286   },287   "tool_result": "string or text blocks; is_error:true on failure"288  },289  "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).",290  "limitations": [291   "No interactive commands, no GUI, no streaming of output; API does not truncate oversized results (request rejected) — truncate client-side.",292   "bash_20241022 (Sonnet 3.5 only, retired) needs anthropic-beta computer-use-2024-10-22."293  ],294  "security": [295   "Run in an isolated container/VM as least-privileged user; allowlist commands; ulimit; log; redact secrets from output."296  ],297  "beta_header": null,298  "status": [299   "DOCUMENTED",300   "LIVE_VERIFIED"301  ],302  "examples": {303   "curl": "examples/anthropic/tools/bash/basic.sh",304   "python": "examples/anthropic/tools/bash/basic.py",305   "typescript": "examples/anthropic/tools/bash/basic.ts"306  },307  "verification": {308   "method": "live_api",309   "verified_at": "2026-09-18",310   "result": "success",311   "http_status": 200,312   "request_note": "h7_bash_20250124 (haiku) -> tool_use input {command:'echo OK'}; j4 count_tokens"313  },314  "sources": [315   {316    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool",317    "retrieved_at": "2026-09-18"318   },319   {320    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",321    "retrieved_at": "2026-09-18"322   },323   {324    "url": "https://platform.claude.com/docs/en/api/messages/create",325    "retrieved_at": "2026-09-18"326   }327  ],328  "last_verified": "2026-09-18",329  "name_constraint": "name must be exactly 'bash'",330  "versions": {331   "bash_20250124": "current, no beta header",332   "bash_20241022": "legacy, beta computer-use-2024-10-22, retired model only"333  },334  "_fragment": "generated/fragments/tools/anthropic-tools.json"335 },336 {337  "provider": "anthropic",338  "name": "Text editor tool (text_editor_20250728)",339  "type": "text_editor_20250728",340  "category": "anthropic-defined-client",341  "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').",342  "compatible_models": [343   "claude-fable-5-1",344   "claude-opus-5",345   "claude-sonnet-5",346   "claude-fable-5",347   "claude-opus-4-8",348   "claude-opus-4-7",349   "claude-sonnet-4-6",350   "claude-opus-4-6",351   "claude-opus-4-5-20251101",352   "claude-haiku-4-5-20251001",353   "claude-sonnet-4-5-20250929",354   "claude-mythos-5-1",355   "claude-mythos-5"356  ],357  "compatible_endpoints": [358   "POST /v1/messages",359   "POST /v1/messages/batches"360  ],361  "parameters_schema": {362   "type": "object",363   "required": [364    "type",365    "name"366   ],367   "properties": {368    "type": {369     "const": "text_editor_20250728"370    },371    "name": {372     "const": "str_replace_based_edit_tool"373    },374    "max_characters": {375     "type": "integer",376     "description": "Truncation length for view (20250728+ only)"377    },378    "cache_control": {379     "type": "object",380     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."381    },382    "strict": {383     "type": "boolean",384     "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)."385    },386    "defer_loading": {387     "type": "boolean",388     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."389    },390    "allowed_callers": {391     "type": "array",392     "items": {393      "enum": [394       "direct",395       "code_execution_20250825",396       "code_execution_20260120",397       "code_execution_20260521"398      ]399     },400     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])."401    },402    "input_examples": {403     "type": "array",404     "items": {405      "type": "object"406     },407     "description": "Schema-validated example inputs (user-defined + Anthropic-schema client tools only; not toolsets/server tools)."408    }409   },410   "tool_use.input": {411    "command": {412     "enum": [413      "view",414      "str_replace",415      "create",416      "insert"417     ]418    },419    "path": "string",420    "view_range": "[start,end] 1-indexed, -1 = EOF",421    "old_str": "string",422    "new_str": "string",423    "file_text": "string",424    "insert_line": "int (0 = top)",425    "insert_text": "string"426   }427  },428  "tool_choice_support": "auto/any/tool/none (tool_choice.type=tool may name this tool)",429  "parallel": "yes (several tool_use blocks per turn; one tool_result each, all in one user message)",430  "streaming_events": [431   "content_block_start (tool_use, input: {})",432   "content_block_delta (input_json_delta.partial_json)",433   "content_block_stop",434   "message_delta (stop_reason: tool_use)"435  ],436  "result_shape": {437   "tool_use": {438    "type": "tool_use",439    "id": "toolu_…",440    "name": "str_replace_based_edit_tool",441    "input": {442     "command": "view",443     "path": "/tmp"444    },445    "caller": {446     "type": "direct"447    }448   },449   "tool_result": "file contents (recommended with 'N: ' line numbers) / 'Successfully replaced text at exactly one location.' / errors with is_error:true"450  },451  "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).",452  "limitations": [453   "Name is fixed (live 400: \"tools.0.text_editor_20250728.name: Input should be 'str_replace_based_edit_tool'\")",454   "str_replace must match exactly one location (your implementation enforces)."455  ],456  "security": [457   "Validate paths (no traversal), backups, permission checks."458  ],459  "beta_header": null,460  "status": [461   "DOCUMENTED",462   "LIVE_VERIFIED"463  ],464  "examples": {465   "curl": "examples/anthropic/tools/text-editor/basic.sh",466   "python": "examples/anthropic/tools/text-editor/basic.py",467   "typescript": "examples/anthropic/tools/text-editor/basic.ts"468  },469  "verification": {470   "method": "live_api",471   "verified_at": "2026-09-18",472   "result": "success",473   "http_status": 200,474   "request_note": "h6_text_editor_20250728 (haiku) view /tmp; h9 wrong name 400; k15/k16 older versions 400 on haiku"475  },476  "sources": [477   {478    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool",479    "retrieved_at": "2026-09-18"480   },481   {482    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",483    "retrieved_at": "2026-09-18"484   },485   {486    "url": "https://platform.claude.com/docs/en/api/messages/create",487    "retrieved_at": "2026-09-18"488   }489  ],490  "last_verified": "2026-09-18",491  "name_constraint": "str_replace_based_edit_tool (20250429+) / str_replace_editor (20250124, 20241022)",492  "_fragment": "generated/fragments/tools/anthropic-tools.json"493 },494 {495  "provider": "anthropic",496  "name": "Text editor tool (text_editor_20250429)",497  "type": "text_editor_20250429",498  "category": "anthropic-defined-client",499  "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'.",500  "compatible_models": [],501  "compatible_endpoints": [502   "POST /v1/messages",503   "POST /v1/messages/batches"504  ],505  "parameters_schema": {506   "type": "object",507   "required": [508    "type",509    "name"510   ],511   "properties": {512    "type": {513     "const": "text_editor_20250429"514    },515    "name": {516     "const": "str_replace_based_edit_tool"517    },518    "cache_control": {519     "type": "object",520     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."521    },522    "strict": {523     "type": "boolean",524     "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)."525    },526    "defer_loading": {527     "type": "boolean",528     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."529    },530    "allowed_callers": {531     "type": "array",532     "items": {533      "enum": [534       "direct",535       "code_execution_20250825",536       "code_execution_20260120",537       "code_execution_20260521"538      ]539     },540     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])."541    },542    "input_examples": {543     "type": "array",544     "items": {545      "type": "object"546     },547     "description": "Schema-validated example inputs (user-defined + Anthropic-schema client tools only; not toolsets/server tools)."548    }549   },550   "tool_use.input": {551    "command": {552     "enum": [553      "view",554      "str_replace",555      "create",556      "insert"557     ]558    },559    "path": "string",560    "view_range": "[start,end] 1-indexed, -1 = EOF",561    "old_str": "string",562    "new_str": "string",563    "file_text": "string",564    "insert_line": "int (0 = top)",565    "insert_text": "string"566   }567  },568  "tool_choice_support": "auto/any/tool/none (tool_choice.type=tool may name this tool)",569  "parallel": "yes (several tool_use blocks per turn; one tool_result each, all in one user message)",570  "streaming_events": [571   "content_block_start (tool_use, input: {})",572   "content_block_delta (input_json_delta.partial_json)",573   "content_block_stop",574   "message_delta (stop_reason: tool_use)"575  ],576  "result_shape": {577   "tool_use": {578    "type": "tool_use",579    "id": "toolu_…",580    "name": "str_replace_based_edit_tool",581    "input": {582     "command": "view",583     "path": "/tmp"584    },585    "caller": {586     "type": "direct"587    }588   },589   "tool_result": "file contents (recommended with 'N: ' line numbers) / 'Successfully replaced text at exactly one location.' / errors with is_error:true"590  },591  "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).",592  "limitations": [593   "Name is fixed (live 400: \"tools.0.text_editor_20250728.name: Input should be 'str_replace_based_edit_tool'\")",594   "str_replace must match exactly one location (your implementation enforces)."595  ],596  "security": [597   "Validate paths (no traversal), backups, permission checks."598  ],599  "beta_header": null,600  "status": [601   "DOCUMENTED",602   "LEGACY"603  ],604  "examples": {605   "curl": "examples/anthropic/tools/text-editor/basic.sh",606   "python": "examples/anthropic/tools/text-editor/basic.py",607   "typescript": "examples/anthropic/tools/text-editor/basic.ts"608  },609  "verification": {610   "method": "live_api",611   "verified_at": "2026-09-18",612   "result": "failure",613   "http_status": 400,614   "request_note": "k15/k16: haiku 4.5 rejects this version"615  },616  "sources": [617   {618    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool",619    "retrieved_at": "2026-09-18"620   },621   {622    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",623    "retrieved_at": "2026-09-18"624   },625   {626    "url": "https://platform.claude.com/docs/en/api/messages/create",627    "retrieved_at": "2026-09-18"628   }629  ],630  "last_verified": "2026-09-18",631  "name_constraint": "str_replace_based_edit_tool (20250429+) / str_replace_editor (20250124, 20241022)",632  "_fragment": "generated/fragments/tools/anthropic-tools.json"633 },634 {635  "provider": "anthropic",636  "name": "Text editor tool (text_editor_20250124)",637  "type": "text_editor_20250124",638  "category": "anthropic-defined-client",639  "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.",640  "compatible_models": [],641  "compatible_endpoints": [642   "POST /v1/messages",643   "POST /v1/messages/batches"644  ],645  "parameters_schema": {646   "type": "object",647   "required": [648    "type",649    "name"650   ],651   "properties": {652    "type": {653     "const": "text_editor_20250124"654    },655    "name": {656     "const": "str_replace_editor"657    },658    "cache_control": {659     "type": "object",660     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."661    },662    "strict": {663     "type": "boolean",664     "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)."665    },666    "defer_loading": {667     "type": "boolean",668     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."669    },670    "allowed_callers": {671     "type": "array",672     "items": {673      "enum": [674       "direct",675       "code_execution_20250825",676       "code_execution_20260120",677       "code_execution_20260521"678      ]679     },680     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])."681    },682    "input_examples": {683     "type": "array",684     "items": {685      "type": "object"686     },687     "description": "Schema-validated example inputs (user-defined + Anthropic-schema client tools only; not toolsets/server tools)."688    }689   },690   "tool_use.input": {691    "command": {692     "enum": [693      "view",694      "str_replace",695      "create",696      "insert",697      "undo_edit"698     ]699    },700    "path": "string",701    "view_range": "[start,end] 1-indexed, -1 = EOF",702    "old_str": "string",703    "new_str": "string",704    "file_text": "string",705    "insert_line": "int (0 = top)",706    "insert_text": "string"707   }708  },709  "tool_choice_support": "auto/any/tool/none (tool_choice.type=tool may name this tool)",710  "parallel": "yes (several tool_use blocks per turn; one tool_result each, all in one user message)",711  "streaming_events": [712   "content_block_start (tool_use, input: {})",713   "content_block_delta (input_json_delta.partial_json)",714   "content_block_stop",715   "message_delta (stop_reason: tool_use)"716  ],717  "result_shape": {718   "tool_use": {719    "type": "tool_use",720    "id": "toolu_…",721    "name": "str_replace_based_edit_tool",722    "input": {723     "command": "view",724     "path": "/tmp"725    },726    "caller": {727     "type": "direct"728    }729   },730   "tool_result": "file contents (recommended with 'N: ' line numbers) / 'Successfully replaced text at exactly one location.' / errors with is_error:true"731  },732  "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).",733  "limitations": [734   "Name is fixed (live 400: \"tools.0.text_editor_20250728.name: Input should be 'str_replace_based_edit_tool'\")",735   "str_replace must match exactly one location (your implementation enforces)."736  ],737  "security": [738   "Validate paths (no traversal), backups, permission checks."739  ],740  "beta_header": null,741  "status": [742   "DOCUMENTED",743   "LEGACY"744  ],745  "examples": {746   "curl": "examples/anthropic/tools/text-editor/basic.sh",747   "python": "examples/anthropic/tools/text-editor/basic.py",748   "typescript": "examples/anthropic/tools/text-editor/basic.ts"749  },750  "verification": {751   "method": "live_api",752   "verified_at": "2026-09-18",753   "result": "failure",754   "http_status": 400,755   "request_note": "k15/k16: haiku 4.5 rejects this version"756  },757  "sources": [758   {759    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool",760    "retrieved_at": "2026-09-18"761   },762   {763    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",764    "retrieved_at": "2026-09-18"765   },766   {767    "url": "https://platform.claude.com/docs/en/api/messages/create",768    "retrieved_at": "2026-09-18"769   }770  ],771  "last_verified": "2026-09-18",772  "name_constraint": "str_replace_based_edit_tool (20250429+) / str_replace_editor (20250124, 20241022)",773  "_fragment": "generated/fragments/tools/anthropic-tools.json"774 },775 {776  "provider": "anthropic",777  "name": "Memory tool",778  "type": "memory_20250818",779  "category": "anthropic-defined-client",780  "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.",781  "compatible_models": [782   "claude-fable-5-1",783   "claude-opus-5",784   "claude-sonnet-5",785   "claude-fable-5",786   "claude-opus-4-8",787   "claude-opus-4-7",788   "claude-sonnet-4-6",789   "claude-opus-4-6",790   "claude-opus-4-5-20251101",791   "claude-haiku-4-5-20251001",792   "claude-sonnet-4-5-20250929",793   "claude-mythos-5-1",794   "claude-mythos-5"795  ],796  "compatible_endpoints": [797   "POST /v1/messages",798   "POST /v1/messages/batches"799  ],800  "parameters_schema": {801   "type": "object",802   "required": [803    "type",804    "name"805   ],806   "properties": {807    "type": {808     "const": "memory_20250818"809    },810    "name": {811     "const": "memory"812    },813    "cache_control": {814     "type": "object",815     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."816    },817    "strict": {818     "type": "boolean",819     "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)."820    },821    "defer_loading": {822     "type": "boolean",823     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."824    },825    "allowed_callers": {826     "type": "array",827     "items": {828      "enum": [829       "direct",830       "code_execution_20250825",831       "code_execution_20260120",832       "code_execution_20260521"833      ]834     },835     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])."836    },837    "input_examples": {838     "type": "array",839     "items": {840      "type": "object"841     },842     "description": "Schema-validated example inputs (user-defined + Anthropic-schema client tools only; not toolsets/server tools)."843    }844   },845   "tool_use.input": {846    "command": {847     "enum": [848      "view",849      "create",850      "str_replace",851      "insert",852      "delete",853      "rename"854     ]855    },856    "path": "string under /memories",857    "view_range": "[start,end]",858    "file_text": "string",859    "old_str": "string",860    "new_str": "string (optional for str_replace = delete)",861    "insert_line": "int",862    "insert_text": "string",863    "old_path": "string",864    "new_path": "string"865   }866  },867  "tool_choice_support": "auto/any/tool/none (tool_choice.type=tool may name this tool)",868  "parallel": "yes (several tool_use blocks per turn; one tool_result each, all in one user message)",869  "streaming_events": [870   "content_block_start (tool_use, input: {})",871   "content_block_delta (input_json_delta.partial_json)",872   "content_block_stop",873   "message_delta (stop_reason: tool_use)"874  ],875  "result_shape": {876   "tool_use": {877    "type": "tool_use",878    "id": "toolu_…",879    "name": "memory",880    "input": {881     "command": "view",882     "path": "/memories"883    },884    "caller": {885     "type": "direct"886    }887   },888   "tool_result strings (reference)": {889    "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}…",890    "view file": "Here's the content of {path} with line numbers:\\n{6-wide line no}\\t{content}",891    "create": "File created successfully at: {path}",892    "str_replace": "The memory file has been edited.",893    "insert": "The file {path} has been edited.",894    "delete": "Successfully deleted {path}",895    "rename": "Successfully renamed {old_path} to {new_path}"896   }897  },898  "billing": "Tokens only. Live count_tokens haiku 4.5: 1576 tokens with the memory tool (vs 11 without) — includes injected memory protocol.",899  "limitations": [900   "Client-side storage only; no beta header since 2026-02-17 (was beta context-management-2025-06-27 era)",901   "Files >999,999 lines should return an error; view truncates >16,000 chars per tool description"902  ],903  "security": [904   "Path traversal protection mandatory (validate /memories prefix, canonicalize, reject ../ and %2e%2e%2f)",905   "Strip sensitive data before writing; cap file sizes; expire stale memories."906  ],907  "beta_header": null,908  "status": [909   "DOCUMENTED",910   "LIVE_VERIFIED"911  ],912  "examples": {913   "curl": "examples/anthropic/tools/memory/basic.sh",914   "python": "examples/anthropic/tools/memory/basic.py",915   "typescript": "examples/anthropic/tools/memory/basic.ts"916  },917  "verification": {918   "method": "live_api",919   "verified_at": "2026-09-18",920   "result": "success",921   "http_status": 200,922   "request_note": "h8_memory_20250818 (haiku) -> tool_use {command:view,path:/memories}; j6 count_tokens"923  },924  "sources": [925   {926    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool",927    "retrieved_at": "2026-09-18"928   },929   {930    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",931    "retrieved_at": "2026-09-18"932   }933  ],934  "last_verified": "2026-09-18",935  "name_constraint": "name must be exactly 'memory'",936  "sdk_helpers": "BetaLocalFilesystemMemoryTool / BetaAbstractMemoryTool (Python), betaMemoryTool (TS)",937  "_fragment": "generated/fragments/tools/anthropic-tools.json"938 },939 {940  "provider": "anthropic",941  "name": "Computer use toolset (GA)",942  "type": "computer_toolset_20260801",943  "category": "anthropic-defined-client",944  "description": "Client toolset: one entry (no name) declares 17 member tools; Claude calls members as tool_use blocks with name=<member> 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.'",945  "compatible_models": [946   "claude-fable-5-1",947   "claude-mythos-5-1",948   "claude-fable-5",949   "claude-mythos-5",950   "claude-opus-5",951   "claude-sonnet-5",952   "claude-opus-4-8"953  ],954  "compatible_endpoints": [955   "POST /v1/messages",956   "POST /v1/messages/batches"957  ],958  "parameters_schema": {959   "type": "object",960   "required": [961    "type"962   ],963   "properties": {964    "type": {965     "const": "computer_toolset_20260801"966    },967    "configs": {968     "type": "object",969     "description": "member name -> {enabled?: bool (default true, incl. zoom), defer_loading?: bool}; unknown member or other fields rejected; disabling all members rejected"970    },971    "cache_control": {972     "type": "object",973     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."974    },975    "allowed_callers": {976     "enum": [977      [978       "direct"979      ]980     ],981     "description": "only [\"direct\"]"982    }983   },984   "rejected": [985    "name",986    "display_width_px",987    "display_height_px",988    "display_number",989    "enable_zoom",990    "strict",991    "input_examples",992    "defer_loading on the entry",993    "tool_choice type tool naming it",994    "legacy fine-grained-tool-streaming-2025-05-14 header",995    "a second computer entry or another tool named computer"996   ],997   "members": [998    "screenshot",999    "zoom",1000    "left_click",1001    "right_click",1002    "middle_click",1003    "double_click",1004    "triple_click",1005    "left_click_drag",1006    "mouse_move",1007    "left_mouse_down",1008    "left_mouse_up",1009    "cursor_position",1010    "scroll",1011    "type",1012    "key",1013    "hold_key",1014    "wait"1015   ],1016   "member_inputs": {1017    "screenshot": {},1018    "zoom": {1019     "region": "[x0,y0,x1,y1]"1020    },1021    "left_click": {1022     "coordinate?": "[x,y]",1023     "text?": "modifier keys shift|ctrl|alt|super joined with +"1024    },1025    "right_click|middle_click|double_click|triple_click": "same as left_click",1026    "left_click_drag": {1027     "start_coordinate": "[x,y]",1028     "coordinate": "[x,y]",1029     "text?": "modifiers"1030    },1031    "mouse_move": {1032     "coordinate": "[x,y]"1033    },1034    "left_mouse_down|left_mouse_up": {},1035    "cursor_position": {},1036    "scroll": {1037     "scroll_direction": "up|down|left|right",1038     "scroll_amount": "int clicks",1039     "coordinate?": "[x,y]",1040     "text?": "modifiers"1041    },1042    "type": {1043     "text": "string"1044    },1045    "key": {1046     "text": "key or chord e.g. Return, ctrl+s",1047     "repeat?": "1-100 (toolset only)"1048    },1049    "hold_key": {1050     "text": "key",1051     "duration": "seconds <=300"1052    },1053    "wait": {1054     "duration": "seconds <=300"1055    }1056   }1057  },1058  "tool_choice_support": "auto/any/none; tool_choice type=tool naming the toolset or a member is rejected",1059  "parallel": "batch actions: several member tool_use blocks per turn, executed sequentially in order; disable_parallel_tool_use:true limits to one",1060  "streaming_events": [1061   "content_block_start tool_use (toolset_name present)",1062   "each member input arrives as ONE complete input_json_delta",1063   "content_block_stop"1064  ],1065  "result_shape": {1066   "tool_use": {1067    "type": "tool_use",1068    "id": "toolu_…",1069    "name": "screenshot",1070    "toolset_name": "computer",1071    "input": {},1072    "caller": {1073     "type": "direct"1074    }1075   },1076   "tool_result": {1077    "type": "tool_result",1078    "tool_use_id": "toolu_…",1079    "toolset_name": "computer (required echo)",1080    "content": "[{type:image,…}] for screenshot/zoom; text such as 'OK' otherwise; only text and image blocks allowed"1081   },1082   "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"1083  },1084  "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).",1085  "limitations": [1086   "Not available in Managed Agents; Claude API + Google Cloud only (other platforms: earlier beta versions)",1087   "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",1088   ">20 images per request triggers stricter per-side limits",1089   "Prompt-injection classifiers scan screenshots (opt-out via support)"1090  ],1091  "security": [1092   "Dedicated VM/container, no credentials, domain allowlist, human confirmation for consequential actions; screenshots are untrusted content"1093  ],1094  "beta_header": null,1095  "status": [1096   "DOCUMENTED",1097   "LIVE_VERIFIED"1098  ],1099  "examples": {1100   "curl": "examples/anthropic/computer-use/computer_toolset_20260801.sh",1101   "python": "examples/anthropic/computer-use/computer_use_loop.py",1102   "typescript": "examples/anthropic/computer-use/computer_use_loop.ts"1103  },1104  "verification": {1105   "method": "live_api",1106   "verified_at": "2026-09-18",1107   "result": "success",1108   "http_status": 200,1109   "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"1110  },1111  "sources": [1112   {1113    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool",1114    "retrieved_at": "2026-09-18"1115   },1116   {1117    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",1118    "retrieved_at": "2026-09-18"1119   },1120   {1121    "url": "https://platform.claude.com/docs/en/release-notes/api",1122    "retrieved_at": "2026-09-18"1123   },1124   {1125    "url": "https://platform.claude.com/docs/en/api/messages/create",1126    "retrieved_at": "2026-09-18"1127   }1128  ],1129  "last_verified": "2026-09-18",1130  "beta_history": "GA 2026-08-19 (release notes); successor of computer_20251124/computer_20250124",1131  "_fragment": "generated/fragments/tools/anthropic-tools.json"1132 },1133 {1134  "provider": "anthropic",1135  "name": "Computer use tool (beta, computer_20251124)",1136  "type": "computer_20251124",1137  "category": "anthropic-defined-client",1138  "description": "Single schema-less tool named 'computer'; Claude emits input {action: <name>, …}. 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).",1139  "compatible_models": [1140   "claude-fable-5-1",1141   "claude-mythos-5-1",1142   "claude-fable-5",1143   "claude-mythos-5",1144   "claude-opus-5",1145   "claude-sonnet-5",1146   "claude-opus-4-8",1147   "claude-opus-4-7",1148   "claude-opus-4-6",1149   "claude-sonnet-4-6",1150   "claude-opus-4-5-20251101"1151  ],1152  "compatible_endpoints": [1153   "POST /v1/messages",1154   "POST /v1/messages/batches"1155  ],1156  "parameters_schema": {1157   "type": "object",1158   "required": [1159    "type",1160    "name",1161    "display_width_px",1162    "display_height_px"1163   ],1164   "properties": {1165    "type": {1166     "const": "computer_20251124"1167    },1168    "name": {1169     "const": "computer"1170    },1171    "display_width_px": {1172     "type": "integer",1173     "minimum": 11174    },1175    "display_height_px": {1176     "type": "integer",1177     "minimum": 11178    },1179    "display_number": {1180     "type": "integer",1181     "minimum": 0,1182     "description": "X11 display number"1183    },1184    "enable_zoom": {1185     "type": "boolean",1186     "default": false1187    },1188    "cache_control": {1189     "type": "object",1190     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."1191    },1192    "strict": {1193     "type": "boolean",1194     "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)."1195    },1196    "defer_loading": {1197     "type": "boolean",1198     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."1199    },1200    "allowed_callers": {1201     "type": "array",1202     "items": {1203      "enum": [1204       "direct",1205       "code_execution_20250825",1206       "code_execution_20260120",1207       "code_execution_20260521"1208      ]1209     },1210     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])."1211    },1212    "input_examples": {1213     "type": "array",1214     "items": {1215      "type": "object"1216     },1217     "description": "Schema-validated example inputs (user-defined + Anthropic-schema client tools only; not toolsets/server tools)."1218    }1219   },1220   "actions": [1221    "key",1222    "hold_key",1223    "type",1224    "cursor_position",1225    "mouse_move",1226    "left_mouse_down",1227    "left_mouse_up",1228    "left_click",1229    "left_click_drag",1230    "right_click",1231    "middle_click",1232    "double_click",1233    "triple_click",1234    "scroll",1235    "wait",1236    "screenshot",1237    "zoom (when enable_zoom:true)"1238   ],1239   "action_inputs": {1240    "screenshot": {},1241    "zoom": {1242     "region": "[x0,y0,x1,y1]"1243    },1244    "left_click": {1245     "coordinate?": "[x,y]",1246     "text?": "modifier keys shift|ctrl|alt|super joined with +"1247    },1248    "right_click|middle_click|double_click|triple_click": "same as left_click",1249    "left_click_drag": {1250     "start_coordinate": "[x,y]",1251     "coordinate": "[x,y]",1252     "text?": "modifiers"1253    },1254    "mouse_move": {1255     "coordinate": "[x,y]"1256    },1257    "left_mouse_down|left_mouse_up": {},1258    "cursor_position": {},1259    "scroll": {1260     "scroll_direction": "up|down|left|right",1261     "scroll_amount": "int clicks",1262     "coordinate?": "[x,y]",1263     "text?": "modifiers"1264    },1265    "type": {1266     "text": "string"1267    },1268    "key": {1269     "text": "key or chord e.g. Return, ctrl+s",1270     "repeat?": "1-100 (toolset only)"1271    },1272    "hold_key": {1273     "text": "key",1274     "duration": "seconds <=300"1275    },1276    "wait": {1277     "duration": "seconds <=300"1278    }1279   }1280  },1281  "tool_choice_support": "auto/any/tool/none (tool_choice.type=tool may name this tool)",1282  "parallel": "yes (several tool_use blocks per turn; one tool_result each, all in one user message)",1283  "streaming_events": [1284   "content_block_start (tool_use, input: {})",1285   "content_block_delta (input_json_delta.partial_json)",1286   "content_block_stop",1287   "message_delta (stop_reason: tool_use)"1288  ],1289  "result_shape": {1290   "tool_use": {1291    "type": "tool_use",1292    "id": "toolu_…",1293    "name": "computer",1294    "input": {1295     "action": "screenshot"1296    },1297    "caller": {1298     "type": "direct"1299    }1300   },1301   "tool_result": {1302    "type": "tool_result",1303    "tool_use_id": "toolu_…",1304    "content": [1305     {1306      "type": "image",1307      "source": {1308       "type": "base64",1309       "media_type": "image/png",1310       "data": "…"1311      }1312     }1313    ]1314   }1315  },1316  "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.'",1317  "limitations": [1318   "Beta header required (k17b: sonnet 4.6 without header -> 400 unknown type tag)",1319   "Haiku 4.5 / Sonnet 4.5 not supported (k17: 400 'does not support tool types: computer_20251124')",1320   "API downscales? No: you should resize screenshots to model limits; coordinates scale accordingly"1321  ],1322  "security": [1323   "Same as toolset"1324  ],1325  "beta_header": "computer-use-2025-11-24",1326  "status": [1327   "DOCUMENTED",1328   "BETA",1329   "LIVE_VERIFIED"1330  ],1331  "examples": {1332   "curl": "examples/anthropic/computer-use/computer_20251124.sh",1333   "python": "examples/anthropic/computer-use/computer_use_loop.py",1334   "typescript": "examples/anthropic/computer-use/computer_use_loop.ts"1335  },1336  "verification": {1337   "method": "live_api",1338   "verified_at": "2026-09-18",1339   "result": "success",1340   "http_status": 200,1341   "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"1342  },1343  "sources": [1344   {1345    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool",1346    "retrieved_at": "2026-09-18"1347   },1348   {1349    "url": "https://platform.claude.com/docs/en/api/beta/messages/create",1350    "retrieved_at": "2026-09-18"1351   },1352   {1353    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",1354    "retrieved_at": "2026-09-18"1355   }1356  ],1357  "last_verified": "2026-09-18",1358  "_fragment": "generated/fragments/tools/anthropic-tools.json"1359 },1360 {1361  "provider": "anthropic",1362  "name": "Computer use tool (beta, computer_20250124)",1363  "type": "computer_20250124",1364  "category": "anthropic-defined-client",1365  "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.",1366  "compatible_models": [1367   "claude-sonnet-4-5-20250929",1368   "claude-haiku-4-5-20251001"1369  ],1370  "compatible_endpoints": [1371   "POST /v1/messages",1372   "POST /v1/messages/batches"1373  ],1374  "parameters_schema": {1375   "type": "object",1376   "required": [1377    "type",1378    "name",1379    "display_width_px",1380    "display_height_px"1381   ],1382   "properties": {1383    "type": {1384     "const": "computer_20250124"1385    },1386    "name": {1387     "const": "computer"1388    },1389    "display_width_px": {1390     "type": "integer",1391     "minimum": 11392    },1393    "display_height_px": {1394     "type": "integer",1395     "minimum": 11396    },1397    "display_number": {1398     "type": "integer",1399     "minimum": 01400    },1401    "cache_control": {1402     "type": "object",1403     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."1404    },1405    "strict": {1406     "type": "boolean",1407     "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)."1408    },1409    "defer_loading": {1410     "type": "boolean",1411     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."1412    },1413    "allowed_callers": {1414     "type": "array",1415     "items": {1416      "enum": [1417       "direct",1418       "code_execution_20250825",1419       "code_execution_20260120",1420       "code_execution_20260521"1421      ]1422     },1423     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])."1424    },1425    "input_examples": {1426     "type": "array",1427     "items": {1428      "type": "object"1429     },1430     "description": "Schema-validated example inputs (user-defined + Anthropic-schema client tools only; not toolsets/server tools)."1431    }1432   },1433   "actions": [1434    "key",1435    "hold_key",1436    "type",1437    "cursor_position",1438    "mouse_move",1439    "left_mouse_down",1440    "left_mouse_up",1441    "left_click",1442    "left_click_drag",1443    "right_click",1444    "middle_click",1445    "double_click",1446    "triple_click",1447    "scroll",1448    "wait",1449    "screenshot"1450   ]1451  },1452  "tool_choice_support": "auto/any/tool/none (tool_choice.type=tool may name this tool)",1453  "parallel": "yes (several tool_use blocks per turn; one tool_result each, all in one user message)",1454  "streaming_events": [1455   "content_block_start (tool_use, input: {})",1456   "content_block_delta (input_json_delta.partial_json)",1457   "content_block_stop",1458   "message_delta (stop_reason: tool_use)"1459  ],1460  "result_shape": {1461   "tool_use": {1462    "type": "tool_use",1463    "id": "toolu_…",1464    "name": "computer",1465    "input": {1466     "action": "screenshot"1467    },1468    "caller": {1469     "type": "direct"1470    }1471   }1472  },1473  "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).",1474  "limitations": [],1475  "security": [],1476  "beta_header": "computer-use-2025-01-24",1477  "status": [1478   "DOCUMENTED",1479   "BETA",1480   "LIVE_VERIFIED"1481  ],1482  "examples": {1483   "curl": "examples/anthropic/computer-use/computer_20250124_haiku.sh"1484  },1485  "verification": {1486   "method": "live_api",1487   "verified_at": "2026-09-18",1488   "result": "success",1489   "http_status": 200,1490   "request_note": "h3_computer_20250124_haiku -> tool_use {action:screenshot}; j8 count_tokens 1826"1491  },1492  "sources": [1493   {1494    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool",1495    "retrieved_at": "2026-09-18"1496   },1497   {1498    "url": "https://platform.claude.com/docs/en/api/beta/messages/create",1499    "retrieved_at": "2026-09-18"1500   },1501   {1502    "url": "https://platform.claude.com/docs/en/release-notes/api",1503    "retrieved_at": "2026-09-18"1504   }1505  ],1506  "last_verified": "2026-09-18",1507  "_fragment": "generated/fragments/tools/anthropic-tools.json"1508 },1509 {1510  "provider": "anthropic",1511  "name": "Computer use tool (legacy, computer_20241022)",1512  "type": "computer_20241022",1513  "category": "anthropic-defined-client",1514  "description": "Original computer use tool for Claude Sonnet 3.5 (retired). Beta header computer-use-2024-10-22. Not accepted for current models.",1515  "compatible_models": [],1516  "compatible_endpoints": [1517   "POST /v1/messages",1518   "POST /v1/messages/batches"1519  ],1520  "parameters_schema": {1521   "type": "object",1522   "properties": {1523    "type": {1524     "const": "computer_20241022"1525    },1526    "name": {1527     "const": "computer"1528    },1529    "display_width_px": "int",1530    "display_height_px": "int",1531    "display_number": "int"1532   }1533  },1534  "tool_choice_support": "auto/any/tool/none (tool_choice.type=tool may name this tool)",1535  "parallel": "yes (several tool_use blocks per turn; one tool_result each, all in one user message)",1536  "streaming_events": [1537   "content_block_start (tool_use, input: {})",1538   "content_block_delta (input_json_delta.partial_json)",1539   "content_block_stop",1540   "message_delta (stop_reason: tool_use)"1541  ],1542  "result_shape": {1543   "tool_use": {1544    "name": "computer",1545    "input": {1546     "action": "…"1547    }1548   }1549  },1550  "billing": "Standard input/output tokens (definition + tool_use + tool_result blocks) plus the per-model tool-use system prompt.",1551  "limitations": [],1552  "security": [],1553  "beta_header": "computer-use-2024-10-22",1554  "status": [1555   "DOCUMENTED",1556   "LEGACY",1557   "RETIRED"1558  ],1559  "examples": {},1560  "verification": {1561   "method": "sdk_types",1562   "verified_at": "2026-09-18",1563   "result": "success",1564   "http_status": null,1565   "request_note": "type string present in sources/anthropic/openapi/{python,node}-sdk-api.md"1566  },1567  "sources": [1568   {1569    "url": "https://platform.claude.com/docs/en/release-notes/api",1570    "retrieved_at": "2026-09-18"1571   },1572   {1573    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",1574    "retrieved_at": "2026-09-18"1575   }1576  ],1577  "last_verified": "2026-09-18",1578  "_fragment": "generated/fragments/tools/anthropic-tools.json"1579 },1580 {1581  "provider": "anthropic",1582  "name": "Browser use toolset",1583  "type": "browser_toolset_20260801",1584  "category": "anthropic-defined-client",1585  "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.'",1586  "compatible_models": [1587   "claude-fable-5-1",1588   "claude-mythos-5-1",1589   "claude-fable-5",1590   "claude-mythos-5",1591   "claude-opus-5",1592   "claude-sonnet-5",1593   "claude-opus-4-8"1594  ],1595  "compatible_endpoints": [1596   "POST /v1/messages",1597   "POST /v1/messages/batches"1598  ],1599  "parameters_schema": {1600   "type": "object",1601   "required": [1602    "type"1603   ],1604   "properties": {1605    "type": {1606     "const": "browser_toolset_20260801"1607    },1608    "configs": {1609     "type": "object",1610     "description": "member -> {enabled?, defer_loading?}"1611    },1612    "cache_control": {1613     "type": "object",1614     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."1615    },1616    "allowed_callers": {1617     "enum": [1618      [1619       "direct"1620      ]1621     ]1622    }1623   },1624   "members": {1625    "navigation_and_capture": [1626     "navigate(url, tab_id?)",1627     "screenshot(tab_id?)",1628     "zoom(region, tab_id?)"1629    ],1630    "pointer": [1631     "left_click(target, modifiers?, tab_id?)",1632     "right_click",1633     "middle_click",1634     "double_click",1635     "triple_click",1636     "hover(target)",1637     "left_click_drag(from, target)",1638     "left_mouse_down(target)",1639     "left_mouse_up(target)",1640     "mouse_move(target)",1641     "scroll(target, scroll_direction, scroll_amount?)",1642     "scroll_to(target: RefTarget)"1643    ],1644    "keyboard_and_timing": [1645     "type(text)",1646     "key(text, repeat?)",1647     "hold_key(text, duration<=30)",1648     "wait(duration<=30)"1649    ],1650    "page_reading": [1651     "read_page(filter?, depth?, ref?)",1652     "find(query)",1653     "get_page_text()"1654    ],1655    "forms_and_files": [1656     "form_input(target: RefTarget, value)",1657     "file_upload(target, paths?, document_ids?) [disabled by default]"1658    ],1659    "diagnostics_and_scripting": [1660     "read_console() [disabled]",1661     "read_network() [disabled]",1662     "javascript_exec(text) [disabled]"1663    ],1664    "tab_management": [1665     "new_tab()",1666     "list_tabs()",1667     "switch_tab(tab_id)",1668     "close_tab(tab_id)"1669    ]1670   },1671   "targets": {1672    "Target": "CoordinateTarget {coordinate:[x,y]} | RefTarget {ref:'ref_N'}"1673   }1674  },1675  "tool_choice_support": "auto/any/none (type=tool naming toolset/member rejected)",1676  "parallel": "batch actions, sequential execution",1677  "streaming_events": [1678   "tool_use content_block_start with toolset_name; one complete input_json_delta per member"1679  ],1680  "result_shape": {1681   "tool_use": {1682    "type": "tool_use",1683    "id": "toolu_…",1684    "name": "navigate",1685    "toolset_name": "browser",1686    "input": {1687     "url": "https://example.com"1688    },1689    "caller": {1690     "type": "direct"1691    }1692   },1693   "tool_result": {1694    "type": "tool_result",1695    "tool_use_id": "…",1696    "toolset_name": "browser",1697    "content": "[text | image | browser_state] only"1698   },1699   "browser_state": {1700    "type": "browser_state",1701    "tabs": [1702     {1703      "tab_id": "tab-1",1704      "title": "…",1705      "url": "…",1706      "active": true1707     }1708    ],1709    "state_changes": [1710     {1711      "type": "tab_opened",1712      "tab_id": "tab-2"1713     },1714     {1715      "type": "download_started|download_completed|download_failed",1716      "…": "…"1717     }1718    ]1719   },1720   "live": "k19 on claude-sonnet-5: [thinking, tool_use navigate{url}, tool_use screenshot{}] both toolset_name:browser; input_tokens 6689"1721  },1722  "billing": "Toolset definition ≈6,000+ input tokens (live 6689 total for a one-line prompt on Sonnet 5); screenshots as image input.",1723  "limitations": [1724   "Claude API + Google Cloud only; not on AWS/Bedrock/Foundry; not in Managed Agents",1725   "browser_state limits: <=100 tabs, <=200 state_changes, strings <=4096 chars, no control chars; never on is_error results"1726  ],1727  "security": [1728   "Page content, tab titles/URLs and download metadata are prompt-injection surfaces; sanitize URLs; confirm consequential actions"1729  ],1730  "beta_header": null,1731  "status": [1732   "DOCUMENTED",1733   "LIVE_VERIFIED"1734  ],1735  "examples": {1736   "curl": "examples/anthropic/computer-use/browser_toolset_20260801.sh"1737  },1738  "verification": {1739   "method": "live_api",1740   "verified_at": "2026-09-18",1741   "result": "success",1742   "http_status": 200,1743   "request_note": "k19_browser_toolset_sonnet5 -> navigate + screenshot member calls"1744  },1745  "sources": [1746   {1747    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool",1748    "retrieved_at": "2026-09-18"1749   },1750   {1751    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",1752    "retrieved_at": "2026-09-18"1753   },1754   {1755    "url": "https://platform.claude.com/docs/en/release-notes/api",1756    "retrieved_at": "2026-09-18"1757   },1758   {1759    "url": "https://platform.claude.com/docs/en/api/messages/create",1760    "retrieved_at": "2026-09-18"1761   }1762  ],1763  "last_verified": "2026-09-18",1764  "_fragment": "generated/fragments/tools/anthropic-tools.json"1765 },1766 {1767  "provider": "anthropic",1768  "name": "Web search tool (web_search_20250305)",1769  "type": "web_search_20250305",1770  "category": "server",1771  "description": "Basic web search executed by Anthropic. Citations always on. ZDR-eligible. No beta header (GA since 2026-02-17; launched 2025-05-07).",1772  "compatible_models": [1773   "claude-fable-5-1",1774   "claude-opus-5",1775   "claude-sonnet-5",1776   "claude-fable-5",1777   "claude-opus-4-8",1778   "claude-opus-4-7",1779   "claude-sonnet-4-6",1780   "claude-opus-4-6",1781   "claude-opus-4-5-20251101",1782   "claude-haiku-4-5-20251001",1783   "claude-sonnet-4-5-20250929",1784   "claude-mythos-5-1",1785   "claude-mythos-5"1786  ],1787  "compatible_endpoints": [1788   "POST /v1/messages",1789   "POST /v1/messages/batches"1790  ],1791  "parameters_schema": {1792   "type": "object",1793   "required": [1794    "type",1795    "name"1796   ],1797   "properties": {1798    "type": {1799     "const": "web_search_20250305"1800    },1801    "name": {1802     "const": "web_search"1803    },1804    "max_uses": {1805     "type": "integer",1806     "exclusiveMinimum": 0,1807     "description": "Cap searches per request; exceeding -> max_uses_exceeded result error"1808    },1809    "allowed_domains": {1810     "type": "array",1811     "items": {1812      "type": "string"1813     },1814     "description": "bare domains (+optional path); mutually exclusive with blocked_domains (live 400)"1815    },1816    "blocked_domains": {1817     "type": "array",1818     "items": {1819      "type": "string"1820     }1821    },1822    "user_location": {1823     "type": "object",1824     "properties": {1825      "type": {1826       "const": "approximate"1827      },1828      "city": "string",1829      "region": "string",1830      "country": "ISO 3166-1 alpha-2 (live 400: 'String should have at most 2 characters')",1831      "timezone": "IANA tz"1832     }1833    },1834    "cache_control": {1835     "type": "object",1836     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."1837    },1838    "defer_loading": {1839     "type": "boolean",1840     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."1841    },1842    "strict": {1843     "type": "boolean",1844     "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)."1845    },1846    "allowed_callers": {1847     "type": "array",1848     "items": {1849      "enum": [1850       "direct",1851       "code_execution_20250825",1852       "code_execution_20260120",1853       "code_execution_20260521"1854      ]1855     },1856     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])."1857    }1858   }1859  },1860  "tool_choice_support": "auto (server tool; tool_choice tool naming web_search not documented)",1861  "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)",1862  "streaming_events": [1863   "content_block_start server_tool_use",1864   "input_json_delta (query)",1865   "content_block_stop",1866   "content_block_start web_search_tool_result (whole block, no deltas)",1867   "text deltas with citations_delta"1868  ],1869  "result_shape": {1870   "server_tool_use": {1871    "type": "server_tool_use",1872    "id": "srvtoolu_…",1873    "name": "web_search",1874    "input": {1875     "query": "…"1876    }1877   },1878   "web_search_tool_result": {1879    "type": "web_search_tool_result",1880    "tool_use_id": "srvtoolu_…",1881    "content": "[{type:web_search_result,url,title,encrypted_content,page_age}] | {type:web_search_tool_result_error,error_code}"1882   },1883   "citations": {1884    "type": "web_search_result_location",1885    "url": "…",1886    "title": "…",1887    "encrypted_index": "…",1888    "cited_text": "<=150 chars"1889   },1890   "usage": {1891    "server_tool_use": {1892     "web_search_requests": 11893    }1894   },1895   "error_codes": [1896    "too_many_requests",1897    "invalid_tool_input",1898    "max_uses_exceeded",1899    "query_too_long",1900    "request_too_large",1901    "unavailable"1902   ]1903  },1904  "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.",1905  "limitations": [1906   "Org-level Console setting can disable web search (400 'web search is not enabled')",1907   "Request-level allowed_domains must be a subset of org allowlist",1908   "Wildcards only in path",1909   "Not on Amazon Bedrock; Vertex + Foundry-on-Azure only basic version",1910   "encrypted_content must be round-tripped unchanged (400 otherwise)"1911  ],1912  "security": [1913   "Search results are untrusted content; homograph domains bypass filters (use ASCII)"1914  ],1915  "beta_header": null,1916  "status": [1917   "DOCUMENTED",1918   "LIVE_VERIFIED"1919  ],1920  "examples": {1921   "curl": "examples/anthropic/web-search/web_search.sh",1922   "python": "examples/anthropic/web-search/web_search.py",1923   "typescript": "examples/anthropic/web-search/web_search.ts"1924  },1925  "verification": {1926   "method": "live_api",1927   "verified_at": "2026-09-18",1928   "result": "success",1929   "http_status": 200,1930   "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"1931  },1932  "sources": [1933   {1934    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool",1935    "retrieved_at": "2026-09-18"1936   },1937   {1938    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools",1939    "retrieved_at": "2026-09-18"1940   },1941   {1942    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",1943    "retrieved_at": "2026-09-18"1944   },1945   {1946    "url": "https://platform.claude.com/docs/en/api/messages/create",1947    "retrieved_at": "2026-09-18"1948   },1949   {1950    "url": "https://platform.claude.com/docs/en/release-notes/api",1951    "retrieved_at": "2026-09-18"1952   }1953  ],1954  "last_verified": "2026-09-18",1955  "name_constraint": "name must be 'web_search'",1956  "zdr": "eligible only for web_search_20250305 or later versions with allowed_callers:[\"direct\"]",1957  "dynamic_filtering_models": [],1958  "_fragment": "generated/fragments/tools/anthropic-tools.json"1959 },1960 {1961  "provider": "anthropic",1962  "name": "Web search tool (web_search_20260209)",1963  "type": "web_search_20260209",1964  "category": "server",1965  "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).",1966  "compatible_models": [1967   "claude-fable-5-1",1968   "claude-opus-5",1969   "claude-sonnet-5",1970   "claude-fable-5",1971   "claude-opus-4-8",1972   "claude-opus-4-7",1973   "claude-sonnet-4-6",1974   "claude-opus-4-6",1975   "claude-opus-4-5-20251101",1976   "claude-haiku-4-5-20251001",1977   "claude-sonnet-4-5-20250929",1978   "claude-mythos-5-1",1979   "claude-mythos-5"1980  ],1981  "compatible_endpoints": [1982   "POST /v1/messages",1983   "POST /v1/messages/batches"1984  ],1985  "parameters_schema": {1986   "type": "object",1987   "required": [1988    "type",1989    "name"1990   ],1991   "properties": {1992    "type": {1993     "const": "web_search_20260209"1994    },1995    "name": {1996     "const": "web_search"1997    },1998    "max_uses": {1999     "type": "integer",2000     "exclusiveMinimum": 0,2001     "description": "Cap searches per request; exceeding -> max_uses_exceeded result error"2002    },2003    "allowed_domains": {2004     "type": "array",2005     "items": {2006      "type": "string"2007     },2008     "description": "bare domains (+optional path); mutually exclusive with blocked_domains (live 400)"2009    },2010    "blocked_domains": {2011     "type": "array",2012     "items": {2013      "type": "string"2014     }2015    },2016    "user_location": {2017     "type": "object",2018     "properties": {2019      "type": {2020       "const": "approximate"2021      },2022      "city": "string",2023      "region": "string",2024      "country": "ISO 3166-1 alpha-2 (live 400: 'String should have at most 2 characters')",2025      "timezone": "IANA tz"2026     }2027    },2028    "cache_control": {2029     "type": "object",2030     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."2031    },2032    "defer_loading": {2033     "type": "boolean",2034     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."2035    },2036    "strict": {2037     "type": "boolean",2038     "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)."2039    },2040    "allowed_callers": {2041     "type": "array",2042     "items": {2043      "enum": [2044       "direct",2045       "code_execution_20250825",2046       "code_execution_20260120",2047       "code_execution_20260521"2048      ]2049     },2050     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"]).",2051     "default": [2052      "code_execution_20260120"2053     ]2054    }2055   }2056  },2057  "tool_choice_support": "auto (server tool; tool_choice tool naming web_search not documented)",2058  "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)",2059  "streaming_events": [2060   "content_block_start server_tool_use",2061   "input_json_delta (query)",2062   "content_block_stop",2063   "content_block_start web_search_tool_result (whole block, no deltas)",2064   "text deltas with citations_delta"2065  ],2066  "result_shape": {2067   "server_tool_use": {2068    "type": "server_tool_use",2069    "id": "srvtoolu_…",2070    "name": "web_search",2071    "input": {2072     "query": "…"2073    }2074   },2075   "web_search_tool_result": {2076    "type": "web_search_tool_result",2077    "tool_use_id": "srvtoolu_…",2078    "content": "[{type:web_search_result,url,title,encrypted_content,page_age}] | {type:web_search_tool_result_error,error_code}"2079   },2080   "citations": {2081    "type": "web_search_result_location",2082    "url": "…",2083    "title": "…",2084    "encrypted_index": "…",2085    "cited_text": "<=150 chars"2086   },2087   "usage": {2088    "server_tool_use": {2089     "web_search_requests": 12090    }2091   },2092   "error_codes": [2093    "too_many_requests",2094    "invalid_tool_input",2095    "max_uses_exceeded",2096    "query_too_long",2097    "request_too_large",2098    "unavailable"2099   ]2100  },2101  "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.",2102  "limitations": [2103   "Org-level Console setting can disable web search (400 'web search is not enabled')",2104   "Request-level allowed_domains must be a subset of org allowlist",2105   "Wildcards only in path",2106   "Not on Amazon Bedrock; Vertex + Foundry-on-Azure only basic version",2107   "encrypted_content must be round-tripped unchanged (400 otherwise)"2108  ],2109  "security": [2110   "Search results are untrusted content; homograph domains bypass filters (use ASCII)"2111  ],2112  "beta_header": null,2113  "status": [2114   "DOCUMENTED",2115   "LIVE_VERIFIED"2116  ],2117  "examples": {2118   "curl": "examples/anthropic/web-search/web_search.sh",2119   "python": "examples/anthropic/web-search/web_search.py",2120   "typescript": "examples/anthropic/web-search/web_search.ts"2121  },2122  "verification": {2123   "method": "live_api",2124   "verified_at": "2026-09-18",2125   "result": "success",2126   "http_status": 200,2127   "request_note": "c2 haiku without allowed_callers -> 400 'does not support programmatic tool calling…set allowed_callers=[\"direct\"]'; c5 with [\"direct\"] -> 200"2128  },2129  "sources": [2130   {2131    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool",2132    "retrieved_at": "2026-09-18"2133   },2134   {2135    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools",2136    "retrieved_at": "2026-09-18"2137   },2138   {2139    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",2140    "retrieved_at": "2026-09-18"2141   },2142   {2143    "url": "https://platform.claude.com/docs/en/api/messages/create",2144    "retrieved_at": "2026-09-18"2145   },2146   {2147    "url": "https://platform.claude.com/docs/en/release-notes/api",2148    "retrieved_at": "2026-09-18"2149   }2150  ],2151  "last_verified": "2026-09-18",2152  "name_constraint": "name must be 'web_search'",2153  "zdr": "eligible only for web_search_20250305 or later versions with allowed_callers:[\"direct\"]",2154  "dynamic_filtering_models": [2155   "claude-fable-5-1",2156   "claude-mythos-5-1",2157   "claude-fable-5",2158   "claude-mythos-5",2159   "claude-opus-5",2160   "claude-opus-4-8",2161   "claude-opus-4-7",2162   "claude-opus-4-6",2163   "claude-opus-4-5-20251101",2164   "claude-sonnet-5",2165   "claude-sonnet-4-6",2166   "claude-sonnet-4-5-20250929"2167  ],2168  "_fragment": "generated/fragments/tools/anthropic-tools.json"2169 },2170 {2171  "provider": "anthropic",2172  "name": "Web search tool (web_search_20260318)",2173  "type": "web_search_20260318",2174  "category": "server",2175  "description": "Adds response_inclusion control over web_search_20260209. Released 2026-06-11.",2176  "compatible_models": [2177   "claude-fable-5-1",2178   "claude-opus-5",2179   "claude-sonnet-5",2180   "claude-fable-5",2181   "claude-opus-4-8",2182   "claude-opus-4-7",2183   "claude-sonnet-4-6",2184   "claude-opus-4-6",2185   "claude-opus-4-5-20251101",2186   "claude-haiku-4-5-20251001",2187   "claude-sonnet-4-5-20250929",2188   "claude-mythos-5-1",2189   "claude-mythos-5"2190  ],2191  "compatible_endpoints": [2192   "POST /v1/messages",2193   "POST /v1/messages/batches"2194  ],2195  "parameters_schema": {2196   "type": "object",2197   "required": [2198    "type",2199    "name"2200   ],2201   "properties": {2202    "type": {2203     "const": "web_search_20260318"2204    },2205    "name": {2206     "const": "web_search"2207    },2208    "max_uses": {2209     "type": "integer",2210     "exclusiveMinimum": 0,2211     "description": "Cap searches per request; exceeding -> max_uses_exceeded result error"2212    },2213    "allowed_domains": {2214     "type": "array",2215     "items": {2216      "type": "string"2217     },2218     "description": "bare domains (+optional path); mutually exclusive with blocked_domains (live 400)"2219    },2220    "blocked_domains": {2221     "type": "array",2222     "items": {2223      "type": "string"2224     }2225    },2226    "user_location": {2227     "type": "object",2228     "properties": {2229      "type": {2230       "const": "approximate"2231      },2232      "city": "string",2233      "region": "string",2234      "country": "ISO 3166-1 alpha-2 (live 400: 'String should have at most 2 characters')",2235      "timezone": "IANA tz"2236     }2237    },2238    "cache_control": {2239     "type": "object",2240     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."2241    },2242    "defer_loading": {2243     "type": "boolean",2244     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."2245    },2246    "strict": {2247     "type": "boolean",2248     "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)."2249    },2250    "allowed_callers": {2251     "type": "array",2252     "items": {2253      "enum": [2254       "direct",2255       "code_execution_20250825",2256       "code_execution_20260120",2257       "code_execution_20260521"2258      ]2259     },2260     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"]).",2261     "default": [2262      "code_execution_20260120"2263     ]2264    },2265    "response_inclusion": {2266     "enum": [2267      "full",2268      "excluded"2269     ],2270     "default": "full",2271     "description": "excluded drops nested server_tool_use/result pairs consumed by a completed code execution call"2272    }2273   }2274  },2275  "tool_choice_support": "auto (server tool; tool_choice tool naming web_search not documented)",2276  "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)",2277  "streaming_events": [2278   "content_block_start server_tool_use",2279   "input_json_delta (query)",2280   "content_block_stop",2281   "content_block_start web_search_tool_result (whole block, no deltas)",2282   "text deltas with citations_delta"2283  ],2284  "result_shape": {2285   "server_tool_use": {2286    "type": "server_tool_use",2287    "id": "srvtoolu_…",2288    "name": "web_search",2289    "input": {2290     "query": "…"2291    }2292   },2293   "web_search_tool_result": {2294    "type": "web_search_tool_result",2295    "tool_use_id": "srvtoolu_…",2296    "content": "[{type:web_search_result,url,title,encrypted_content,page_age}] | {type:web_search_tool_result_error,error_code}"2297   },2298   "citations": {2299    "type": "web_search_result_location",2300    "url": "…",2301    "title": "…",2302    "encrypted_index": "…",2303    "cited_text": "<=150 chars"2304   },2305   "usage": {2306    "server_tool_use": {2307     "web_search_requests": 12308    }2309   },2310   "error_codes": [2311    "too_many_requests",2312    "invalid_tool_input",2313    "max_uses_exceeded",2314    "query_too_long",2315    "request_too_large",2316    "unavailable"2317   ]2318  },2319  "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.",2320  "limitations": [2321   "Org-level Console setting can disable web search (400 'web search is not enabled')",2322   "Request-level allowed_domains must be a subset of org allowlist",2323   "Wildcards only in path",2324   "Not on Amazon Bedrock; Vertex + Foundry-on-Azure only basic version",2325   "encrypted_content must be round-tripped unchanged (400 otherwise)"2326  ],2327  "security": [2328   "Search results are untrusted content; homograph domains bypass filters (use ASCII)"2329  ],2330  "beta_header": null,2331  "status": [2332   "DOCUMENTED"2333  ],2334  "examples": {2335   "curl": "examples/anthropic/web-search/web_search.sh",2336   "python": "examples/anthropic/web-search/web_search.py",2337   "typescript": "examples/anthropic/web-search/web_search.ts"2338  },2339  "verification": {2340   "method": "docs_only",2341   "verified_at": "2026-09-18",2342   "result": "success",2343   "http_status": null,2344   "request_note": "not exercised live in this run"2345  },2346  "sources": [2347   {2348    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool",2349    "retrieved_at": "2026-09-18"2350   },2351   {2352    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools",2353    "retrieved_at": "2026-09-18"2354   },2355   {2356    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",2357    "retrieved_at": "2026-09-18"2358   },2359   {2360    "url": "https://platform.claude.com/docs/en/api/messages/create",2361    "retrieved_at": "2026-09-18"2362   },2363   {2364    "url": "https://platform.claude.com/docs/en/release-notes/api",2365    "retrieved_at": "2026-09-18"2366   }2367  ],2368  "last_verified": "2026-09-18",2369  "name_constraint": "name must be 'web_search'",2370  "zdr": "eligible only for web_search_20250305 or later versions with allowed_callers:[\"direct\"]",2371  "dynamic_filtering_models": [2372   "claude-fable-5-1",2373   "claude-mythos-5-1",2374   "claude-fable-5",2375   "claude-mythos-5",2376   "claude-opus-5",2377   "claude-opus-4-8",2378   "claude-opus-4-7",2379   "claude-opus-4-6",2380   "claude-opus-4-5-20251101",2381   "claude-sonnet-5",2382   "claude-sonnet-4-6",2383   "claude-sonnet-4-5-20250929"2384  ],2385  "_fragment": "generated/fragments/tools/anthropic-tools.json"2386 },2387 {2388  "provider": "anthropic",2389  "name": "Web fetch tool (web_fetch_20250910)",2390  "type": "web_fetch_20250910",2391  "category": "server",2392  "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).",2393  "compatible_models": [2394   "claude-fable-5-1",2395   "claude-opus-5",2396   "claude-sonnet-5",2397   "claude-fable-5",2398   "claude-opus-4-8",2399   "claude-opus-4-7",2400   "claude-sonnet-4-6",2401   "claude-opus-4-6",2402   "claude-opus-4-5-20251101",2403   "claude-haiku-4-5-20251001",2404   "claude-sonnet-4-5-20250929",2405   "claude-mythos-5-1",2406   "claude-mythos-5"2407  ],2408  "compatible_endpoints": [2409   "POST /v1/messages",2410   "POST /v1/messages/batches"2411  ],2412  "parameters_schema": {2413   "type": "object",2414   "required": [2415    "type",2416    "name"2417   ],2418   "properties": {2419    "type": {2420     "const": "web_fetch_20250910"2421    },2422    "name": {2423     "const": "web_fetch"2424    },2425    "max_uses": {2426     "type": "integer",2427     "exclusiveMinimum": 0,2428     "description": "No default limit; failed fetches count"2429    },2430    "allowed_domains": {2431     "type": "array",2432     "items": {2433      "type": "string"2434     },2435     "description": "domain-only matching (paths never match)"2436    },2437    "blocked_domains": {2438     "type": "array",2439     "items": {2440      "type": "string"2441     }2442    },2443    "citations": {2444     "type": "object",2445     "properties": {2446      "enabled": {2447       "type": "boolean",2448       "default": false2449      }2450     }2451    },2452    "max_content_tokens": {2453     "type": "integer",2454     "exclusiveMinimum": 0,2455     "description": "approximate cap on text content (not PDFs); live 400 for 0"2456    },2457    "url_sources": {2458     "type": "object",2459     "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}"2460    },2461    "cache_control": {2462     "type": "object",2463     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."2464    },2465    "defer_loading": {2466     "type": "boolean",2467     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."2468    },2469    "strict": {2470     "type": "boolean",2471     "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)."2472    },2473    "allowed_callers": {2474     "type": "array",2475     "items": {2476      "enum": [2477       "direct",2478       "code_execution_20250825",2479       "code_execution_20260120",2480       "code_execution_20260521"2481      ]2482     },2483     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])."2484    }2485   }2486  },2487  "tool_choice_support": "auto",2488  "parallel": "server-side loop (pause_turn); mixed with client tools -> deferred until tool_result returned",2489  "streaming_events": [2490   "content_block_start server_tool_use",2491   "input_json_delta (url)",2492   "content_block_start web_fetch_tool_result (whole)"2493  ],2494  "result_shape": {2495   "server_tool_use": {2496    "type": "server_tool_use",2497    "id": "srvtoolu_…",2498    "name": "web_fetch",2499    "input": {2500     "url": "https://…"2501    }2502   },2503   "web_fetch_tool_result": {2504    "type": "web_fetch_tool_result",2505    "tool_use_id": "srvtoolu_…",2506    "content": {2507     "type": "web_fetch_result",2508     "url": "…",2509     "retrieved_at": "ISO-8601",2510     "content": {2511      "type": "document",2512      "source": {2513       "type": "text|base64",2514       "media_type": "text/plain|application/pdf",2515       "data": "…"2516      },2517      "title": "…",2518      "citations": {2519       "enabled": true2520      }2521     }2522    },2523    "caller": {2524     "type": "direct"2525    }2526   },2527   "error": {2528    "type": "web_fetch_tool_result",2529    "tool_use_id": "…",2530    "content": {2531     "type": "web_fetch_tool_result_error",2532     "error_code": "url_not_in_prior_context"2533    },2534    "caller": {2535     "type": "direct"2536    }2537   },2538   "citations": {2539    "type": "char_location",2540    "document_index": 0,2541    "document_title": "…",2542    "start_char_index": 0,2543    "end_char_index": 0,2544    "cited_text": "…"2545   },2546   "usage": {2547    "server_tool_use": {2548     "web_search_requests": 0,2549     "web_fetch_requests": 12550    }2551   },2552   "error_codes": [2553    "invalid_tool_input",2554    "url_too_long (250 chars)",2555    "url_not_allowed",2556    "url_not_in_prior_context",2557    "url_not_accessible",2558    "too_many_requests",2559    "unsupported_content_type",2560    "max_uses_exceeded",2561    "unavailable"2562   ],2563   "live_note": "d1/k21: the web_fetch_tool_result block carried caller:{type:direct} (not shown in docs example)"2564  },2565  "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.",2566  "limitations": [2567   "No JavaScript rendering",2568   "URL max 250 chars",2569   "Only text, HTML, PDF",2570   "Not on Bedrock/Vertex; Foundry-on-Azure only basic version",2571   "Org-level domain settings apply"2572  ],2573  "security": [2574   "Data exfiltration risk: URLs only from prior context; restrict with allowed_domains/max_uses; publishers may log URL parameters"2575  ],2576  "beta_header": null,2577  "status": [2578   "DOCUMENTED",2579   "LIVE_VERIFIED"2580  ],2581  "examples": {2582   "curl": "examples/anthropic/web-fetch/web_fetch.sh",2583   "python": "examples/anthropic/web-fetch/web_fetch.py",2584   "typescript": "examples/anthropic/web-fetch/web_fetch.ts"2585  },2586  "verification": {2587   "method": "live_api",2588   "verified_at": "2026-09-18",2589   "result": "success",2590   "http_status": 200,2591   "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"2592  },2593  "sources": [2594   {2595    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool",2596    "retrieved_at": "2026-09-18"2597   },2598   {2599    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools",2600    "retrieved_at": "2026-09-18"2601   },2602   {2603    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",2604    "retrieved_at": "2026-09-18"2605   },2606   {2607    "url": "https://platform.claude.com/docs/en/api/messages/create",2608    "retrieved_at": "2026-09-18"2609   }2610  ],2611  "last_verified": "2026-09-18",2612  "name_constraint": "name must be 'web_fetch'",2613  "dynamic_filtering_models": [],2614  "_fragment": "generated/fragments/tools/anthropic-tools.json"2615 },2616 {2617  "provider": "anthropic",2618  "name": "Web fetch tool (web_fetch_20260209)",2619  "type": "web_fetch_20260209",2620  "category": "server",2621  "description": "Adds dynamic filtering (code execution provisioned automatically; allowed_callers default [\"code_execution_20260120\"]). Not ZDR-eligible by default.",2622  "compatible_models": [2623   "claude-fable-5-1",2624   "claude-opus-5",2625   "claude-sonnet-5",2626   "claude-fable-5",2627   "claude-opus-4-8",2628   "claude-opus-4-7",2629   "claude-sonnet-4-6",2630   "claude-opus-4-6",2631   "claude-opus-4-5-20251101",2632   "claude-haiku-4-5-20251001",2633   "claude-sonnet-4-5-20250929",2634   "claude-mythos-5-1",2635   "claude-mythos-5"2636  ],2637  "compatible_endpoints": [2638   "POST /v1/messages",2639   "POST /v1/messages/batches"2640  ],2641  "parameters_schema": {2642   "type": "object",2643   "required": [2644    "type",2645    "name"2646   ],2647   "properties": {2648    "type": {2649     "const": "web_fetch_20260209"2650    },2651    "name": {2652     "const": "web_fetch"2653    },2654    "max_uses": {2655     "type": "integer",2656     "exclusiveMinimum": 0,2657     "description": "No default limit; failed fetches count"2658    },2659    "allowed_domains": {2660     "type": "array",2661     "items": {2662      "type": "string"2663     },2664     "description": "domain-only matching (paths never match)"2665    },2666    "blocked_domains": {2667     "type": "array",2668     "items": {2669      "type": "string"2670     }2671    },2672    "citations": {2673     "type": "object",2674     "properties": {2675      "enabled": {2676       "type": "boolean",2677       "default": false2678      }2679     }2680    },2681    "max_content_tokens": {2682     "type": "integer",2683     "exclusiveMinimum": 0,2684     "description": "approximate cap on text content (not PDFs); live 400 for 0"2685    },2686    "url_sources": {2687     "type": "object",2688     "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}"2689    },2690    "cache_control": {2691     "type": "object",2692     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."2693    },2694    "defer_loading": {2695     "type": "boolean",2696     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."2697    },2698    "strict": {2699     "type": "boolean",2700     "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)."2701    },2702    "allowed_callers": {2703     "type": "array",2704     "items": {2705      "enum": [2706       "direct",2707       "code_execution_20250825",2708       "code_execution_20260120",2709       "code_execution_20260521"2710      ]2711     },2712     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"]).",2713     "default": [2714      "code_execution_20260120"2715     ]2716    }2717   }2718  },2719  "tool_choice_support": "auto",2720  "parallel": "server-side loop (pause_turn); mixed with client tools -> deferred until tool_result returned",2721  "streaming_events": [2722   "content_block_start server_tool_use",2723   "input_json_delta (url)",2724   "content_block_start web_fetch_tool_result (whole)"2725  ],2726  "result_shape": {2727   "server_tool_use": {2728    "type": "server_tool_use",2729    "id": "srvtoolu_…",2730    "name": "web_fetch",2731    "input": {2732     "url": "https://…"2733    }2734   },2735   "web_fetch_tool_result": {2736    "type": "web_fetch_tool_result",2737    "tool_use_id": "srvtoolu_…",2738    "content": {2739     "type": "web_fetch_result",2740     "url": "…",2741     "retrieved_at": "ISO-8601",2742     "content": {2743      "type": "document",2744      "source": {2745       "type": "text|base64",2746       "media_type": "text/plain|application/pdf",2747       "data": "…"2748      },2749      "title": "…",2750      "citations": {2751       "enabled": true2752      }2753     }2754    },2755    "caller": {2756     "type": "direct"2757    }2758   },2759   "error": {2760    "type": "web_fetch_tool_result",2761    "tool_use_id": "…",2762    "content": {2763     "type": "web_fetch_tool_result_error",2764     "error_code": "url_not_in_prior_context"2765    },2766    "caller": {2767     "type": "direct"2768    }2769   },2770   "citations": {2771    "type": "char_location",2772    "document_index": 0,2773    "document_title": "…",2774    "start_char_index": 0,2775    "end_char_index": 0,2776    "cited_text": "…"2777   },2778   "usage": {2779    "server_tool_use": {2780     "web_search_requests": 0,2781     "web_fetch_requests": 12782    }2783   },2784   "error_codes": [2785    "invalid_tool_input",2786    "url_too_long (250 chars)",2787    "url_not_allowed",2788    "url_not_in_prior_context",2789    "url_not_accessible",2790    "too_many_requests",2791    "unsupported_content_type",2792    "max_uses_exceeded",2793    "unavailable"2794   ],2795   "live_note": "d1/k21: the web_fetch_tool_result block carried caller:{type:direct} (not shown in docs example)"2796  },2797  "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.",2798  "limitations": [2799   "No JavaScript rendering",2800   "URL max 250 chars",2801   "Only text, HTML, PDF",2802   "Not on Bedrock/Vertex; Foundry-on-Azure only basic version",2803   "Org-level domain settings apply"2804  ],2805  "security": [2806   "Data exfiltration risk: URLs only from prior context; restrict with allowed_domains/max_uses; publishers may log URL parameters"2807  ],2808  "beta_header": null,2809  "status": [2810   "DOCUMENTED"2811  ],2812  "examples": {2813   "curl": "examples/anthropic/web-fetch/web_fetch.sh",2814   "python": "examples/anthropic/web-fetch/web_fetch.py",2815   "typescript": "examples/anthropic/web-fetch/web_fetch.ts"2816  },2817  "verification": {2818   "method": "docs_only",2819   "verified_at": "2026-09-18",2820   "result": "success",2821   "http_status": null,2822   "request_note": "not exercised live in this run"2823  },2824  "sources": [2825   {2826    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool",2827    "retrieved_at": "2026-09-18"2828   },2829   {2830    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools",2831    "retrieved_at": "2026-09-18"2832   },2833   {2834    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",2835    "retrieved_at": "2026-09-18"2836   },2837   {2838    "url": "https://platform.claude.com/docs/en/api/messages/create",2839    "retrieved_at": "2026-09-18"2840   }2841  ],2842  "last_verified": "2026-09-18",2843  "name_constraint": "name must be 'web_fetch'",2844  "dynamic_filtering_models": [2845   "claude-fable-5-1",2846   "claude-mythos-5-1",2847   "claude-fable-5",2848   "claude-mythos-5",2849   "claude-opus-4-8",2850   "claude-opus-4-7",2851   "claude-opus-4-6",2852   "claude-sonnet-5",2853   "claude-sonnet-4-6"2854  ],2855  "_fragment": "generated/fragments/tools/anthropic-tools.json"2856 },2857 {2858  "provider": "anthropic",2859  "name": "Web fetch tool (web_fetch_20260309)",2860  "type": "web_fetch_20260309",2861  "category": "server",2862  "description": "Adds use_cache (cache bypass).",2863  "compatible_models": [2864   "claude-fable-5-1",2865   "claude-opus-5",2866   "claude-sonnet-5",2867   "claude-fable-5",2868   "claude-opus-4-8",2869   "claude-opus-4-7",2870   "claude-sonnet-4-6",2871   "claude-opus-4-6",2872   "claude-opus-4-5-20251101",2873   "claude-haiku-4-5-20251001",2874   "claude-sonnet-4-5-20250929",2875   "claude-mythos-5-1",2876   "claude-mythos-5"2877  ],2878  "compatible_endpoints": [2879   "POST /v1/messages",2880   "POST /v1/messages/batches"2881  ],2882  "parameters_schema": {2883   "type": "object",2884   "required": [2885    "type",2886    "name"2887   ],2888   "properties": {2889    "type": {2890     "const": "web_fetch_20260309"2891    },2892    "name": {2893     "const": "web_fetch"2894    },2895    "max_uses": {2896     "type": "integer",2897     "exclusiveMinimum": 0,2898     "description": "No default limit; failed fetches count"2899    },2900    "allowed_domains": {2901     "type": "array",2902     "items": {2903      "type": "string"2904     },2905     "description": "domain-only matching (paths never match)"2906    },2907    "blocked_domains": {2908     "type": "array",2909     "items": {2910      "type": "string"2911     }2912    },2913    "citations": {2914     "type": "object",2915     "properties": {2916      "enabled": {2917       "type": "boolean",2918       "default": false2919      }2920     }2921    },2922    "max_content_tokens": {2923     "type": "integer",2924     "exclusiveMinimum": 0,2925     "description": "approximate cap on text content (not PDFs); live 400 for 0"2926    },2927    "url_sources": {2928     "type": "object",2929     "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}"2930    },2931    "cache_control": {2932     "type": "object",2933     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."2934    },2935    "defer_loading": {2936     "type": "boolean",2937     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."2938    },2939    "strict": {2940     "type": "boolean",2941     "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)."2942    },2943    "allowed_callers": {2944     "type": "array",2945     "items": {2946      "enum": [2947       "direct",2948       "code_execution_20250825",2949       "code_execution_20260120",2950       "code_execution_20260521"2951      ]2952     },2953     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"]).",2954     "default": [2955      "code_execution_20260120"2956     ]2957    },2958    "use_cache": {2959     "type": "boolean",2960     "default": true,2961     "description": "false bypasses the fetch cache (slower)"2962    }2963   }2964  },2965  "tool_choice_support": "auto",2966  "parallel": "server-side loop (pause_turn); mixed with client tools -> deferred until tool_result returned",2967  "streaming_events": [2968   "content_block_start server_tool_use",2969   "input_json_delta (url)",2970   "content_block_start web_fetch_tool_result (whole)"2971  ],2972  "result_shape": {2973   "server_tool_use": {2974    "type": "server_tool_use",2975    "id": "srvtoolu_…",2976    "name": "web_fetch",2977    "input": {2978     "url": "https://…"2979    }2980   },2981   "web_fetch_tool_result": {2982    "type": "web_fetch_tool_result",2983    "tool_use_id": "srvtoolu_…",2984    "content": {2985     "type": "web_fetch_result",2986     "url": "…",2987     "retrieved_at": "ISO-8601",2988     "content": {2989      "type": "document",2990      "source": {2991       "type": "text|base64",2992       "media_type": "text/plain|application/pdf",2993       "data": "…"2994      },2995      "title": "…",2996      "citations": {2997       "enabled": true2998      }2999     }3000    },3001    "caller": {3002     "type": "direct"3003    }3004   },3005   "error": {3006    "type": "web_fetch_tool_result",3007    "tool_use_id": "…",3008    "content": {3009     "type": "web_fetch_tool_result_error",3010     "error_code": "url_not_in_prior_context"3011    },3012    "caller": {3013     "type": "direct"3014    }3015   },3016   "citations": {3017    "type": "char_location",3018    "document_index": 0,3019    "document_title": "…",3020    "start_char_index": 0,3021    "end_char_index": 0,3022    "cited_text": "…"3023   },3024   "usage": {3025    "server_tool_use": {3026     "web_search_requests": 0,3027     "web_fetch_requests": 13028    }3029   },3030   "error_codes": [3031    "invalid_tool_input",3032    "url_too_long (250 chars)",3033    "url_not_allowed",3034    "url_not_in_prior_context",3035    "url_not_accessible",3036    "too_many_requests",3037    "unsupported_content_type",3038    "max_uses_exceeded",3039    "unavailable"3040   ],3041   "live_note": "d1/k21: the web_fetch_tool_result block carried caller:{type:direct} (not shown in docs example)"3042  },3043  "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.",3044  "limitations": [3045   "No JavaScript rendering",3046   "URL max 250 chars",3047   "Only text, HTML, PDF",3048   "Not on Bedrock/Vertex; Foundry-on-Azure only basic version",3049   "Org-level domain settings apply"3050  ],3051  "security": [3052   "Data exfiltration risk: URLs only from prior context; restrict with allowed_domains/max_uses; publishers may log URL parameters"3053  ],3054  "beta_header": null,3055  "status": [3056   "DOCUMENTED"3057  ],3058  "examples": {3059   "curl": "examples/anthropic/web-fetch/web_fetch.sh",3060   "python": "examples/anthropic/web-fetch/web_fetch.py",3061   "typescript": "examples/anthropic/web-fetch/web_fetch.ts"3062  },3063  "verification": {3064   "method": "docs_only",3065   "verified_at": "2026-09-18",3066   "result": "success",3067   "http_status": null,3068   "request_note": "not exercised live in this run"3069  },3070  "sources": [3071   {3072    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool",3073    "retrieved_at": "2026-09-18"3074   },3075   {3076    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools",3077    "retrieved_at": "2026-09-18"3078   },3079   {3080    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",3081    "retrieved_at": "2026-09-18"3082   },3083   {3084    "url": "https://platform.claude.com/docs/en/api/messages/create",3085    "retrieved_at": "2026-09-18"3086   }3087  ],3088  "last_verified": "2026-09-18",3089  "name_constraint": "name must be 'web_fetch'",3090  "dynamic_filtering_models": [3091   "claude-fable-5-1",3092   "claude-mythos-5-1",3093   "claude-fable-5",3094   "claude-mythos-5",3095   "claude-opus-4-8",3096   "claude-opus-4-7",3097   "claude-opus-4-6",3098   "claude-sonnet-5",3099   "claude-sonnet-4-6"3100  ],3101  "_fragment": "generated/fragments/tools/anthropic-tools.json"3102 },3103 {3104  "provider": "anthropic",3105  "name": "Web fetch tool (web_fetch_20260318)",3106  "type": "web_fetch_20260318",3107  "category": "server",3108  "description": "Adds response_inclusion. Released 2026-06-11. Live: accepted on haiku with allowed_callers:[\"direct\"], response_inclusion:excluded, use_cache:false (k30, 200).",3109  "compatible_models": [3110   "claude-fable-5-1",3111   "claude-opus-5",3112   "claude-sonnet-5",3113   "claude-fable-5",3114   "claude-opus-4-8",3115   "claude-opus-4-7",3116   "claude-sonnet-4-6",3117   "claude-opus-4-6",3118   "claude-opus-4-5-20251101",3119   "claude-haiku-4-5-20251001",3120   "claude-sonnet-4-5-20250929",3121   "claude-mythos-5-1",3122   "claude-mythos-5"3123  ],3124  "compatible_endpoints": [3125   "POST /v1/messages",3126   "POST /v1/messages/batches"3127  ],3128  "parameters_schema": {3129   "type": "object",3130   "required": [3131    "type",3132    "name"3133   ],3134   "properties": {3135    "type": {3136     "const": "web_fetch_20260318"3137    },3138    "name": {3139     "const": "web_fetch"3140    },3141    "max_uses": {3142     "type": "integer",3143     "exclusiveMinimum": 0,3144     "description": "No default limit; failed fetches count"3145    },3146    "allowed_domains": {3147     "type": "array",3148     "items": {3149      "type": "string"3150     },3151     "description": "domain-only matching (paths never match)"3152    },3153    "blocked_domains": {3154     "type": "array",3155     "items": {3156      "type": "string"3157     }3158    },3159    "citations": {3160     "type": "object",3161     "properties": {3162      "enabled": {3163       "type": "boolean",3164       "default": false3165      }3166     }3167    },3168    "max_content_tokens": {3169     "type": "integer",3170     "exclusiveMinimum": 0,3171     "description": "approximate cap on text content (not PDFs); live 400 for 0"3172    },3173    "url_sources": {3174     "type": "object",3175     "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}"3176    },3177    "cache_control": {3178     "type": "object",3179     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."3180    },3181    "defer_loading": {3182     "type": "boolean",3183     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."3184    },3185    "strict": {3186     "type": "boolean",3187     "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)."3188    },3189    "allowed_callers": {3190     "type": "array",3191     "items": {3192      "enum": [3193       "direct",3194       "code_execution_20250825",3195       "code_execution_20260120",3196       "code_execution_20260521"3197      ]3198     },3199     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"]).",3200     "default": [3201      "code_execution_20260120"3202     ]3203    },3204    "use_cache": {3205     "type": "boolean",3206     "default": true3207    },3208    "response_inclusion": {3209     "enum": [3210      "full",3211      "excluded"3212     ],3213     "default": "full"3214    }3215   }3216  },3217  "tool_choice_support": "auto",3218  "parallel": "server-side loop (pause_turn); mixed with client tools -> deferred until tool_result returned",3219  "streaming_events": [3220   "content_block_start server_tool_use",3221   "input_json_delta (url)",3222   "content_block_start web_fetch_tool_result (whole)"3223  ],3224  "result_shape": {3225   "server_tool_use": {3226    "type": "server_tool_use",3227    "id": "srvtoolu_…",3228    "name": "web_fetch",3229    "input": {3230     "url": "https://…"3231    }3232   },3233   "web_fetch_tool_result": {3234    "type": "web_fetch_tool_result",3235    "tool_use_id": "srvtoolu_…",3236    "content": {3237     "type": "web_fetch_result",3238     "url": "…",3239     "retrieved_at": "ISO-8601",3240     "content": {3241      "type": "document",3242      "source": {3243       "type": "text|base64",3244       "media_type": "text/plain|application/pdf",3245       "data": "…"3246      },3247      "title": "…",3248      "citations": {3249       "enabled": true3250      }3251     }3252    },3253    "caller": {3254     "type": "direct"3255    }3256   },3257   "error": {3258    "type": "web_fetch_tool_result",3259    "tool_use_id": "…",3260    "content": {3261     "type": "web_fetch_tool_result_error",3262     "error_code": "url_not_in_prior_context"3263    },3264    "caller": {3265     "type": "direct"3266    }3267   },3268   "citations": {3269    "type": "char_location",3270    "document_index": 0,3271    "document_title": "…",3272    "start_char_index": 0,3273    "end_char_index": 0,3274    "cited_text": "…"3275   },3276   "usage": {3277    "server_tool_use": {3278     "web_search_requests": 0,3279     "web_fetch_requests": 13280    }3281   },3282   "error_codes": [3283    "invalid_tool_input",3284    "url_too_long (250 chars)",3285    "url_not_allowed",3286    "url_not_in_prior_context",3287    "url_not_accessible",3288    "too_many_requests",3289    "unsupported_content_type",3290    "max_uses_exceeded",3291    "unavailable"3292   ],3293   "live_note": "d1/k21: the web_fetch_tool_result block carried caller:{type:direct} (not shown in docs example)"3294  },3295  "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.",3296  "limitations": [3297   "No JavaScript rendering",3298   "URL max 250 chars",3299   "Only text, HTML, PDF",3300   "Not on Bedrock/Vertex; Foundry-on-Azure only basic version",3301   "Org-level domain settings apply"3302  ],3303  "security": [3304   "Data exfiltration risk: URLs only from prior context; restrict with allowed_domains/max_uses; publishers may log URL parameters"3305  ],3306  "beta_header": null,3307  "status": [3308   "DOCUMENTED",3309   "LIVE_VERIFIED"3310  ],3311  "examples": {3312   "curl": "examples/anthropic/web-fetch/web_fetch.sh",3313   "python": "examples/anthropic/web-fetch/web_fetch.py",3314   "typescript": "examples/anthropic/web-fetch/web_fetch.ts"3315  },3316  "verification": {3317   "method": "live_api",3318   "verified_at": "2026-09-18",3319   "result": "success",3320   "http_status": 200,3321   "request_note": "k30_web_fetch_20260318_direct_haiku 200 (no fetch performed)"3322  },3323  "sources": [3324   {3325    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool",3326    "retrieved_at": "2026-09-18"3327   },3328   {3329    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools",3330    "retrieved_at": "2026-09-18"3331   },3332   {3333    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",3334    "retrieved_at": "2026-09-18"3335   },3336   {3337    "url": "https://platform.claude.com/docs/en/api/messages/create",3338    "retrieved_at": "2026-09-18"3339   }3340  ],3341  "last_verified": "2026-09-18",3342  "name_constraint": "name must be 'web_fetch'",3343  "dynamic_filtering_models": [3344   "claude-fable-5-1",3345   "claude-mythos-5-1",3346   "claude-fable-5",3347   "claude-mythos-5",3348   "claude-opus-4-8",3349   "claude-opus-4-7",3350   "claude-opus-4-6",3351   "claude-sonnet-5",3352   "claude-sonnet-4-6"3353  ],3354  "_fragment": "generated/fragments/tools/anthropic-tools.json"3355 },3356 {3357  "provider": "anthropic",3358  "name": "Code execution tool (code_execution_20250825)",3359  "type": "code_execution_20250825",3360  "category": "server",3361  "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).",3362  "compatible_models": [3363   "claude-fable-5-1",3364   "claude-mythos-5-1",3365   "claude-fable-5",3366   "claude-mythos-5",3367   "claude-opus-5",3368   "claude-opus-4-8",3369   "claude-opus-4-7",3370   "claude-opus-4-6",3371   "claude-opus-4-5-20251101",3372   "claude-sonnet-5",3373   "claude-sonnet-4-6",3374   "claude-sonnet-4-5-20250929",3375   "claude-haiku-4-5-20251001"3376  ],3377  "compatible_endpoints": [3378   "POST /v1/messages",3379   "POST /v1/messages/batches"3380  ],3381  "parameters_schema": {3382   "type": "object",3383   "required": [3384    "type",3385    "name"3386   ],3387   "properties": {3388    "type": {3389     "const": "code_execution_20250825"3390    },3391    "name": {3392     "const": "code_execution"3393    },3394    "cache_control": {3395     "type": "object",3396     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."3397    },3398    "defer_loading": {3399     "type": "boolean",3400     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."3401    },3402    "strict": {3403     "type": "boolean",3404     "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)."3405    },3406    "allowed_callers": {3407     "type": "array",3408     "items": {3409      "enum": [3410       "direct",3411       "code_execution_20250825",3412       "code_execution_20260120",3413       "code_execution_20260521"3414      ]3415     },3416     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])."3417    }3418   },3419   "request_level": {3420    "container": "string container id | {id?, skills?: [{type: anthropic|custom, skill_id, version}] (max 20 skills)}",3421    "messages[].content[] container_upload": {3422     "type": "container_upload",3423     "file_id": "file_… (Files API)"3424    }3425   }3426  },3427  "tool_choice_support": "auto",3428  "parallel": "server-side loop; pause_turn possible; mixed with client tools -> result deferred",3429  "streaming_events": [3430   "content_block_start server_tool_use (bash_code_execution / text_editor_code_execution / code_execution)",3431   "input_json_delta",3432   "result block arrives whole in one content_block_start"3433  ],3434  "result_shape": {3435   "server_tool_use (bash)": {3436    "type": "server_tool_use",3437    "id": "srvtoolu_…",3438    "name": "bash_code_execution",3439    "input": {3440     "command": "python3 -c \"print(2+2)\""3441    }3442   },3443   "bash_code_execution_tool_result": {3444    "type": "bash_code_execution_tool_result",3445    "tool_use_id": "srvtoolu_…",3446    "content": {3447     "type": "bash_code_execution_result",3448     "stdout": "4\n",3449     "stderr": "",3450     "return_code": 0,3451     "content": [3452      {3453       "type": "code_execution_output",3454       "file_id": "file_…"3455      }3456     ]3457    }3458   },3459   "server_tool_use (editor)": {3460    "type": "server_tool_use",3461    "name": "text_editor_code_execution",3462    "input": {3463     "command": "view|create|str_replace",3464     "path": "…",3465     "file_text": "…",3466     "old_str": "…",3467     "new_str": "…"3468    }3469   },3470   "text_editor_code_execution_tool_result": {3471    "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[]}"3472   },3473   "server_tool_use (PTC python cell)": {3474    "type": "server_tool_use",3475    "name": "code_execution",3476    "input": {3477     "code": "python source"3478    }3479   },3480   "code_execution_tool_result": {3481    "type": "code_execution_tool_result",3482    "tool_use_id": "srvtoolu_…",3483    "content": {3484     "type": "code_execution_result",3485     "stdout": "…",3486     "stderr": "…",3487     "return_code": 0,3488     "content": [],3489     "abort_reason": null3490    }3491   },3492   "errors": {3493    "type": "*_tool_result_error",3494    "error_code": [3495     "unavailable",3496     "execution_time_exceeded",3497     "invalid_tool_input",3498     "too_many_requests",3499     "output_file_too_large (bash)",3500     "file_not_found (text_editor)"3501    ]3502   },3503   "top_level container": {3504    "id": "container_…",3505    "expires_at": "ISO-8601 (rolling, ~5h ahead live)",3506    "skills": "[…] when skills loaded"3507   },3508   "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"3509  },3510  "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).",3511  "limitations": [3512   "No internet in the sandbox; only pre-installed libs (pandas, numpy, scipy, sklearn, statsmodels, matplotlib, seaborn, pyarrow, openpyxl, pillow, python-docx/pptx, pypdf, sympy…)",3513   "Not on Bedrock/Vertex; Foundry requires Hosted-on-Anthropic",3514   "Not ZDR-eligible; container data retained up to 30 days",3515   "Haiku 4.5: no PTC / REPL persistence"3516  ],3517  "security": [3518   "Isolated container; outputs (files) carry C2PA credentials for media",3519   "Distinguish from client bash tool in system prompt (separate environments)"3520  ],3521  "beta_header": null,3522  "status": [3523   "DOCUMENTED",3524   "LIVE_VERIFIED"3525  ],3526  "examples": {3527   "curl": "examples/anthropic/code-execution/code_execution.sh",3528   "python": "examples/anthropic/code-execution/code_execution.py",3529   "typescript": "examples/anthropic/code-execution/code_execution.ts"3530  },3531  "verification": {3532   "method": "live_api",3533   "verified_at": "2026-09-18",3534   "result": "success",3535   "http_status": 200,3536   "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'\""3537  },3538  "sources": [3539   {3540    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool",3541    "retrieved_at": "2026-09-18"3542   },3543   {3544    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling",3545    "retrieved_at": "2026-09-18"3546   },3547   {3548    "url": "https://platform.claude.com/docs/en/build-with-claude/skills-guide",3549    "retrieved_at": "2026-09-18"3550   },3551   {3552    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",3553    "retrieved_at": "2026-09-18"3554   },3555   {3556    "url": "https://platform.claude.com/docs/en/api/messages/create",3557    "retrieved_at": "2026-09-18"3558   },3559   {3560    "url": "https://platform.claude.com/docs/en/release-notes/api",3561    "retrieved_at": "2026-09-18"3562   }3563  ],3564  "last_verified": "2026-09-18",3565  "name_constraint": "name must be 'code_execution'",3566  "sub_tools": [3567   "bash_code_execution",3568   "text_editor_code_execution",3569   "code_execution (PTC Python cell, 20260120+)"3570  ],3571  "internal_type_ids_seen_live": [3572   "bash_code_execution_20250825",3573   "text_editor_code_execution_20250825",3574   "python_with_tools_code_execution_20250825",3575   "python_with_tools_code_execution_20260120",3576   "python_with_tools_code_execution_20260521"3577  ],3578  "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.",3579  "_fragment": "generated/fragments/tools/anthropic-tools.json"3580 },3581 {3582  "provider": "anthropic",3583  "name": "Code execution tool (code_execution_20260120)",3584  "type": "code_execution_20260120",3585  "category": "server",3586  "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.",3587  "compatible_models": [3588   "claude-fable-5-1",3589   "claude-mythos-5-1",3590   "claude-fable-5",3591   "claude-mythos-5",3592   "claude-opus-5",3593   "claude-opus-4-8",3594   "claude-opus-4-7",3595   "claude-opus-4-6",3596   "claude-opus-4-5-20251101",3597   "claude-sonnet-5",3598   "claude-sonnet-4-6",3599   "claude-sonnet-4-5-20250929",3600   "claude-haiku-4-5-20251001"3601  ],3602  "compatible_endpoints": [3603   "POST /v1/messages",3604   "POST /v1/messages/batches"3605  ],3606  "parameters_schema": {3607   "type": "object",3608   "required": [3609    "type",3610    "name"3611   ],3612   "properties": {3613    "type": {3614     "const": "code_execution_20260120"3615    },3616    "name": {3617     "const": "code_execution"3618    },3619    "cache_control": {3620     "type": "object",3621     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."3622    },3623    "defer_loading": {3624     "type": "boolean",3625     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."3626    },3627    "strict": {3628     "type": "boolean",3629     "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)."3630    },3631    "allowed_callers": {3632     "type": "array",3633     "items": {3634      "enum": [3635       "direct",3636       "code_execution_20250825",3637       "code_execution_20260120",3638       "code_execution_20260521"3639      ]3640     },3641     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])."3642    }3643   },3644   "request_level": {3645    "container": "string container id | {id?, skills?: [{type: anthropic|custom, skill_id, version}] (max 20 skills)}",3646    "messages[].content[] container_upload": {3647     "type": "container_upload",3648     "file_id": "file_… (Files API)"3649    }3650   }3651  },3652  "tool_choice_support": "auto",3653  "parallel": "server-side loop; pause_turn possible; mixed with client tools -> result deferred",3654  "streaming_events": [3655   "content_block_start server_tool_use (bash_code_execution / text_editor_code_execution / code_execution)",3656   "input_json_delta",3657   "result block arrives whole in one content_block_start"3658  ],3659  "result_shape": {3660   "server_tool_use (bash)": {3661    "type": "server_tool_use",3662    "id": "srvtoolu_…",3663    "name": "bash_code_execution",3664    "input": {3665     "command": "python3 -c \"print(2+2)\""3666    }3667   },3668   "bash_code_execution_tool_result": {3669    "type": "bash_code_execution_tool_result",3670    "tool_use_id": "srvtoolu_…",3671    "content": {3672     "type": "bash_code_execution_result",3673     "stdout": "4\n",3674     "stderr": "",3675     "return_code": 0,3676     "content": [3677      {3678       "type": "code_execution_output",3679       "file_id": "file_…"3680      }3681     ]3682    }3683   },3684   "server_tool_use (editor)": {3685    "type": "server_tool_use",3686    "name": "text_editor_code_execution",3687    "input": {3688     "command": "view|create|str_replace",3689     "path": "…",3690     "file_text": "…",3691     "old_str": "…",3692     "new_str": "…"3693    }3694   },3695   "text_editor_code_execution_tool_result": {3696    "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[]}"3697   },3698   "server_tool_use (PTC python cell)": {3699    "type": "server_tool_use",3700    "name": "code_execution",3701    "input": {3702     "code": "python source"3703    }3704   },3705   "code_execution_tool_result": {3706    "type": "code_execution_tool_result",3707    "tool_use_id": "srvtoolu_…",3708    "content": {3709     "type": "code_execution_result",3710     "stdout": "…",3711     "stderr": "…",3712     "return_code": 0,3713     "content": [],3714     "abort_reason": null3715    }3716   },3717   "errors": {3718    "type": "*_tool_result_error",3719    "error_code": [3720     "unavailable",3721     "execution_time_exceeded",3722     "invalid_tool_input",3723     "too_many_requests",3724     "output_file_too_large (bash)",3725     "file_not_found (text_editor)"3726    ]3727   },3728   "top_level container": {3729    "id": "container_…",3730    "expires_at": "ISO-8601 (rolling, ~5h ahead live)",3731    "skills": "[…] when skills loaded"3732   },3733   "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"3734  },3735  "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).",3736  "limitations": [3737   "No internet in the sandbox; only pre-installed libs (pandas, numpy, scipy, sklearn, statsmodels, matplotlib, seaborn, pyarrow, openpyxl, pillow, python-docx/pptx, pypdf, sympy…)",3738   "Not on Bedrock/Vertex; Foundry requires Hosted-on-Anthropic",3739   "Not ZDR-eligible; container data retained up to 30 days",3740   "Haiku 4.5: no PTC / REPL persistence"3741  ],3742  "security": [3743   "Isolated container; outputs (files) carry C2PA credentials for media",3744   "Distinguish from client bash tool in system prompt (separate environments)"3745  ],3746  "beta_header": null,3747  "status": [3748   "DOCUMENTED",3749   "LIVE_VERIFIED"3750  ],3751  "examples": {3752   "curl": "examples/anthropic/code-execution/code_execution.sh",3753   "python": "examples/anthropic/code-execution/code_execution.py",3754   "typescript": "examples/anthropic/code-execution/code_execution.ts"3755  },3756  "verification": {3757   "method": "live_api",3758   "verified_at": "2026-09-18",3759   "result": "success",3760   "http_status": 200,3761   "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}"3762  },3763  "sources": [3764   {3765    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool",3766    "retrieved_at": "2026-09-18"3767   },3768   {3769    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling",3770    "retrieved_at": "2026-09-18"3771   },3772   {3773    "url": "https://platform.claude.com/docs/en/build-with-claude/skills-guide",3774    "retrieved_at": "2026-09-18"3775   },3776   {3777    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",3778    "retrieved_at": "2026-09-18"3779   },3780   {3781    "url": "https://platform.claude.com/docs/en/api/messages/create",3782    "retrieved_at": "2026-09-18"3783   },3784   {3785    "url": "https://platform.claude.com/docs/en/release-notes/api",3786    "retrieved_at": "2026-09-18"3787   }3788  ],3789  "last_verified": "2026-09-18",3790  "name_constraint": "name must be 'code_execution'",3791  "sub_tools": [3792   "bash_code_execution",3793   "text_editor_code_execution",3794   "code_execution (PTC Python cell, 20260120+)"3795  ],3796  "internal_type_ids_seen_live": [3797   "bash_code_execution_20250825",3798   "text_editor_code_execution_20250825",3799   "python_with_tools_code_execution_20250825",3800   "python_with_tools_code_execution_20260120",3801   "python_with_tools_code_execution_20260521"3802  ],3803  "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.",3804  "_fragment": "generated/fragments/tools/anthropic-tools.json"3805 },3806 {3807  "provider": "anthropic",3808  "name": "Code execution tool (code_execution_20260521)",3809  "type": "code_execution_20260521",3810  "category": "server",3811  "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.",3812  "compatible_models": [3813   "claude-fable-5-1",3814   "claude-mythos-5-1",3815   "claude-fable-5",3816   "claude-mythos-5",3817   "claude-opus-5",3818   "claude-opus-4-8",3819   "claude-opus-4-7",3820   "claude-opus-4-6",3821   "claude-opus-4-5-20251101",3822   "claude-sonnet-5",3823   "claude-sonnet-4-6",3824   "claude-sonnet-4-5-20250929",3825   "claude-haiku-4-5-20251001"3826  ],3827  "compatible_endpoints": [3828   "POST /v1/messages",3829   "POST /v1/messages/batches"3830  ],3831  "parameters_schema": {3832   "type": "object",3833   "required": [3834    "type",3835    "name"3836   ],3837   "properties": {3838    "type": {3839     "const": "code_execution_20260521"3840    },3841    "name": {3842     "const": "code_execution"3843    },3844    "cache_control": {3845     "type": "object",3846     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."3847    },3848    "defer_loading": {3849     "type": "boolean",3850     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."3851    },3852    "strict": {3853     "type": "boolean",3854     "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)."3855    },3856    "allowed_callers": {3857     "type": "array",3858     "items": {3859      "enum": [3860       "direct",3861       "code_execution_20250825",3862       "code_execution_20260120",3863       "code_execution_20260521"3864      ]3865     },3866     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])."3867    }3868   },3869   "request_level": {3870    "container": "string container id | {id?, skills?: [{type: anthropic|custom, skill_id, version}] (max 20 skills)}",3871    "messages[].content[] container_upload": {3872     "type": "container_upload",3873     "file_id": "file_… (Files API)"3874    }3875   }3876  },3877  "tool_choice_support": "auto",3878  "parallel": "server-side loop; pause_turn possible; mixed with client tools -> result deferred",3879  "streaming_events": [3880   "content_block_start server_tool_use (bash_code_execution / text_editor_code_execution / code_execution)",3881   "input_json_delta",3882   "result block arrives whole in one content_block_start"3883  ],3884  "result_shape": {3885   "server_tool_use (bash)": {3886    "type": "server_tool_use",3887    "id": "srvtoolu_…",3888    "name": "bash_code_execution",3889    "input": {3890     "command": "python3 -c \"print(2+2)\""3891    }3892   },3893   "bash_code_execution_tool_result": {3894    "type": "bash_code_execution_tool_result",3895    "tool_use_id": "srvtoolu_…",3896    "content": {3897     "type": "bash_code_execution_result",3898     "stdout": "4\n",3899     "stderr": "",3900     "return_code": 0,3901     "content": [3902      {3903       "type": "code_execution_output",3904       "file_id": "file_…"3905      }3906     ]3907    }3908   },3909   "server_tool_use (editor)": {3910    "type": "server_tool_use",3911    "name": "text_editor_code_execution",3912    "input": {3913     "command": "view|create|str_replace",3914     "path": "…",3915     "file_text": "…",3916     "old_str": "…",3917     "new_str": "…"3918    }3919   },3920   "text_editor_code_execution_tool_result": {3921    "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[]}"3922   },3923   "server_tool_use (PTC python cell)": {3924    "type": "server_tool_use",3925    "name": "code_execution",3926    "input": {3927     "code": "python source"3928    }3929   },3930   "code_execution_tool_result": {3931    "type": "code_execution_tool_result",3932    "tool_use_id": "srvtoolu_…",3933    "content": {3934     "type": "code_execution_result",3935     "stdout": "…",3936     "stderr": "…",3937     "return_code": 0,3938     "content": [],3939     "abort_reason": null3940    }3941   },3942   "errors": {3943    "type": "*_tool_result_error",3944    "error_code": [3945     "unavailable",3946     "execution_time_exceeded",3947     "invalid_tool_input",3948     "too_many_requests",3949     "output_file_too_large (bash)",3950     "file_not_found (text_editor)"3951    ]3952   },3953   "top_level container": {3954    "id": "container_…",3955    "expires_at": "ISO-8601 (rolling, ~5h ahead live)",3956    "skills": "[…] when skills loaded"3957   },3958   "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"3959  },3960  "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).",3961  "limitations": [3962   "No internet in the sandbox; only pre-installed libs (pandas, numpy, scipy, sklearn, statsmodels, matplotlib, seaborn, pyarrow, openpyxl, pillow, python-docx/pptx, pypdf, sympy…)",3963   "Not on Bedrock/Vertex; Foundry requires Hosted-on-Anthropic",3964   "Not ZDR-eligible; container data retained up to 30 days",3965   "Haiku 4.5: no PTC / REPL persistence"3966  ],3967  "security": [3968   "Isolated container; outputs (files) carry C2PA credentials for media",3969   "Distinguish from client bash tool in system prompt (separate environments)"3970  ],3971  "beta_header": null,3972  "status": [3973   "DOCUMENTED",3974   "LIVE_VERIFIED"3975  ],3976  "examples": {3977   "curl": "examples/anthropic/code-execution/code_execution.sh",3978   "python": "examples/anthropic/code-execution/code_execution.py",3979   "typescript": "examples/anthropic/code-execution/code_execution.ts"3980  },3981  "verification": {3982   "method": "live_api",3983   "verified_at": "2026-09-18",3984   "result": "success",3985   "http_status": 200,3986   "request_note": "e3 (haiku): accepted; bash_code_execution ran print(3*3) -> '9'"3987  },3988  "sources": [3989   {3990    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool",3991    "retrieved_at": "2026-09-18"3992   },3993   {3994    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling",3995    "retrieved_at": "2026-09-18"3996   },3997   {3998    "url": "https://platform.claude.com/docs/en/build-with-claude/skills-guide",3999    "retrieved_at": "2026-09-18"4000   },4001   {4002    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",4003    "retrieved_at": "2026-09-18"4004   },4005   {4006    "url": "https://platform.claude.com/docs/en/api/messages/create",4007    "retrieved_at": "2026-09-18"4008   },4009   {4010    "url": "https://platform.claude.com/docs/en/release-notes/api",4011    "retrieved_at": "2026-09-18"4012   }4013  ],4014  "last_verified": "2026-09-18",4015  "name_constraint": "name must be 'code_execution'",4016  "sub_tools": [4017   "bash_code_execution",4018   "text_editor_code_execution",4019   "code_execution (PTC Python cell, 20260120+)"4020  ],4021  "internal_type_ids_seen_live": [4022   "bash_code_execution_20250825",4023   "text_editor_code_execution_20250825",4024   "python_with_tools_code_execution_20250825",4025   "python_with_tools_code_execution_20260120",4026   "python_with_tools_code_execution_20260521"4027  ],4028  "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.",4029  "_fragment": "generated/fragments/tools/anthropic-tools.json"4030 },4031 {4032  "provider": "anthropic",4033  "name": "Code execution tool (code_execution_20250522)",4034  "type": "code_execution_20250522",4035  "category": "server",4036  "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.",4037  "compatible_models": [4038   "claude-fable-5-1",4039   "claude-mythos-5-1",4040   "claude-fable-5",4041   "claude-mythos-5",4042   "claude-opus-5",4043   "claude-opus-4-8",4044   "claude-opus-4-7",4045   "claude-opus-4-6",4046   "claude-opus-4-5-20251101",4047   "claude-sonnet-5",4048   "claude-sonnet-4-6",4049   "claude-sonnet-4-5-20250929",4050   "claude-haiku-4-5-20251001"4051  ],4052  "compatible_endpoints": [4053   "POST /v1/messages",4054   "POST /v1/messages/batches"4055  ],4056  "parameters_schema": {4057   "type": "object",4058   "required": [4059    "type",4060    "name"4061   ],4062   "properties": {4063    "type": {4064     "const": "code_execution_20250522"4065    },4066    "name": {4067     "const": "code_execution"4068    },4069    "cache_control": {4070     "type": "object",4071     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."4072    },4073    "defer_loading": {4074     "type": "boolean",4075     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."4076    },4077    "strict": {4078     "type": "boolean",4079     "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)."4080    },4081    "allowed_callers": {4082     "type": "array",4083     "items": {4084      "enum": [4085       "direct",4086       "code_execution_20250825",4087       "code_execution_20260120",4088       "code_execution_20260521"4089      ]4090     },4091     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])."4092    }4093   },4094   "request_level": {4095    "container": "string container id | {id?, skills?: [{type: anthropic|custom, skill_id, version}] (max 20 skills)}",4096    "messages[].content[] container_upload": {4097     "type": "container_upload",4098     "file_id": "file_… (Files API)"4099    }4100   }4101  },4102  "tool_choice_support": "auto",4103  "parallel": "server-side loop; pause_turn possible; mixed with client tools -> result deferred",4104  "streaming_events": [4105   "content_block_start server_tool_use (bash_code_execution / text_editor_code_execution / code_execution)",4106   "input_json_delta",4107   "result block arrives whole in one content_block_start"4108  ],4109  "result_shape": {4110   "server_tool_use (bash)": {4111    "type": "server_tool_use",4112    "id": "srvtoolu_…",4113    "name": "bash_code_execution",4114    "input": {4115     "command": "python3 -c \"print(2+2)\""4116    }4117   },4118   "bash_code_execution_tool_result": {4119    "type": "bash_code_execution_tool_result",4120    "tool_use_id": "srvtoolu_…",4121    "content": {4122     "type": "bash_code_execution_result",4123     "stdout": "4\n",4124     "stderr": "",4125     "return_code": 0,4126     "content": [4127      {4128       "type": "code_execution_output",4129       "file_id": "file_…"4130      }4131     ]4132    }4133   },4134   "server_tool_use (editor)": {4135    "type": "server_tool_use",4136    "name": "text_editor_code_execution",4137    "input": {4138     "command": "view|create|str_replace",4139     "path": "…",4140     "file_text": "…",4141     "old_str": "…",4142     "new_str": "…"4143    }4144   },4145   "text_editor_code_execution_tool_result": {4146    "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[]}"4147   },4148   "server_tool_use (PTC python cell)": {4149    "type": "server_tool_use",4150    "name": "code_execution",4151    "input": {4152     "code": "python source"4153    }4154   },4155   "code_execution_tool_result": {4156    "type": "code_execution_tool_result",4157    "tool_use_id": "srvtoolu_…",4158    "content": {4159     "type": "code_execution_result",4160     "stdout": "…",4161     "stderr": "…",4162     "return_code": 0,4163     "content": [],4164     "abort_reason": null4165    }4166   },4167   "errors": {4168    "type": "*_tool_result_error",4169    "error_code": [4170     "unavailable",4171     "execution_time_exceeded",4172     "invalid_tool_input",4173     "too_many_requests",4174     "output_file_too_large (bash)",4175     "file_not_found (text_editor)"4176    ]4177   },4178   "top_level container": {4179    "id": "container_…",4180    "expires_at": "ISO-8601 (rolling, ~5h ahead live)",4181    "skills": "[…] when skills loaded"4182   },4183   "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"4184  },4185  "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).",4186  "limitations": [4187   "No internet in the sandbox; only pre-installed libs (pandas, numpy, scipy, sklearn, statsmodels, matplotlib, seaborn, pyarrow, openpyxl, pillow, python-docx/pptx, pypdf, sympy…)",4188   "Not on Bedrock/Vertex; Foundry requires Hosted-on-Anthropic",4189   "Not ZDR-eligible; container data retained up to 30 days",4190   "Haiku 4.5: no PTC / REPL persistence"4191  ],4192  "security": [4193   "Isolated container; outputs (files) carry C2PA credentials for media",4194   "Distinguish from client bash tool in system prompt (separate environments)"4195  ],4196  "beta_header": null,4197  "status": [4198   "DOCUMENTED",4199   "LEGACY"4200  ],4201  "examples": {4202   "curl": "examples/anthropic/code-execution/code_execution.sh",4203   "python": "examples/anthropic/code-execution/code_execution.py",4204   "typescript": "examples/anthropic/code-execution/code_execution.ts"4205  },4206  "verification": {4207   "method": "sdk_types",4208   "verified_at": "2026-09-18",4209   "result": "success",4210   "http_status": null,4211   "request_note": "type string present in sources/anthropic/openapi/{python,node}-sdk-api.md"4212  },4213  "sources": [4214   {4215    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool",4216    "retrieved_at": "2026-09-18"4217   },4218   {4219    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling",4220    "retrieved_at": "2026-09-18"4221   },4222   {4223    "url": "https://platform.claude.com/docs/en/build-with-claude/skills-guide",4224    "retrieved_at": "2026-09-18"4225   },4226   {4227    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",4228    "retrieved_at": "2026-09-18"4229   },4230   {4231    "url": "https://platform.claude.com/docs/en/api/messages/create",4232    "retrieved_at": "2026-09-18"4233   },4234   {4235    "url": "https://platform.claude.com/docs/en/release-notes/api",4236    "retrieved_at": "2026-09-18"4237   }4238  ],4239  "last_verified": "2026-09-18",4240  "name_constraint": "name must be 'code_execution'",4241  "sub_tools": [4242   "bash_code_execution",4243   "text_editor_code_execution",4244   "code_execution (PTC Python cell, 20260120+)"4245  ],4246  "internal_type_ids_seen_live": [4247   "bash_code_execution_20250825",4248   "text_editor_code_execution_20250825",4249   "python_with_tools_code_execution_20250825",4250   "python_with_tools_code_execution_20260120",4251   "python_with_tools_code_execution_20260521"4252  ],4253  "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.",4254  "_fragment": "generated/fragments/tools/anthropic-tools.json"4255 },4256 {4257  "provider": "anthropic",4258  "name": "Tool search tool (tool_search_tool_regex)",4259  "type": "tool_search_tool_regex_20251119",4260  "category": "server",4261  "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).",4262  "compatible_models": [4263   "claude-fable-5-1",4264   "claude-mythos-5-1",4265   "claude-fable-5",4266   "claude-mythos-5",4267   "claude-opus-5",4268   "claude-opus-4-8",4269   "claude-opus-4-7",4270   "claude-opus-4-6",4271   "claude-sonnet-4-6",4272   "claude-opus-4-5-20251101",4273   "claude-sonnet-4-5-20250929",4274   "claude-haiku-4-5-20251001"4275  ],4276  "compatible_endpoints": [4277   "POST /v1/messages",4278   "POST /v1/messages/batches"4279  ],4280  "parameters_schema": {4281   "type": "object",4282   "required": [4283    "type",4284    "name"4285   ],4286   "properties": {4287    "type": {4288     "enum": [4289      "tool_search_tool_regex_20251119",4290      "tool_search_tool_regex"4291     ]4292    },4293    "name": {4294     "const": "tool_search_tool_regex"4295    },4296    "cache_control": {4297     "type": "object",4298     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."4299    },4300    "defer_loading": {4301     "type": "boolean",4302     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."4303    },4304    "strict": {4305     "type": "boolean",4306     "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)."4307    },4308    "allowed_callers": {4309     "type": "array",4310     "items": {4311      "enum": [4312       "direct",4313       "code_execution_20250825",4314       "code_execution_20260120",4315       "code_execution_20260521"4316      ]4317     },4318     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])."4319    }4320   },4321   "constraints": [4322    "never set defer_loading:true on the search tool itself (400 'At least one tool must have defer_loading=false')",4323    "deferred tool + cache_control -> 400 (live k23)",4324    "max 10,000 deferred tools"4325   ]4326  },4327  "tool_choice_support": "auto",4328  "parallel": "server-side; results expand automatically",4329  "streaming_events": [4330   "server_tool_use start + input_json_delta (pattern/query/limit)",4331   "tool_search_tool_result whole block"4332  ],4333  "result_shape": {4334   "server_tool_use": {4335    "type": "server_tool_use",4336    "id": "srvtoolu_…",4337    "name": "tool_search_tool_regex",4338    "input": {4339     "pattern": "weather",4340     "limit": 104341    }4342   },4343   "tool_search_tool_result": {4344    "type": "tool_search_tool_result",4345    "tool_use_id": "srvtoolu_…",4346    "content": {4347     "type": "tool_search_tool_search_result",4348     "tool_references": [4349      {4350       "type": "tool_reference",4351       "tool_name": "get_weather"4352      }4353     ]4354    }4355   },4356   "error": {4357    "content": {4358     "type": "tool_search_tool_result_error",4359     "error_code": "invalid_tool_input|unavailable|too_many_requests|execution_time_exceeded",4360     "error_message": "…"4361    }4362   },4363   "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').",4364   "custom_search": {4365    "type": "tool_result",4366    "tool_use_id": "toolu_…",4367    "content": [4368     {4369      "type": "tool_reference",4370      "tool_name": "…"4371     }4372    ]4373   }4374  },4375  "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).",4376  "limitations": [4377   "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",4378   "Bedrock: InvokeModel only"4379  ],4380  "security": [],4381  "beta_header": null,4382  "status": [4383   "DOCUMENTED",4384   "LIVE_VERIFIED"4385  ],4386  "examples": {4387   "curl": "examples/anthropic/tools/tool-search/basic.sh",4388   "python": "examples/anthropic/tools/tool-search/basic.py",4389   "typescript": "examples/anthropic/tools/tool-search/basic.ts"4390  },4391  "verification": {4392   "method": "live_api",4393   "verified_at": "2026-09-18",4394   "result": "success",4395   "http_status": 200,4396   "request_note": "f1 (haiku): pattern 'weather', limit 10 -> tool_reference get_weather -> tool_use get_weather"4397  },4398  "sources": [4399   {4400    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool",4401    "retrieved_at": "2026-09-18"4402   },4403   {4404    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",4405    "retrieved_at": "2026-09-18"4406   },4407   {4408    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching",4409    "retrieved_at": "2026-09-18"4410   },4411   {4412    "url": "https://platform.claude.com/docs/en/api/messages/create",4413    "retrieved_at": "2026-09-18"4414   }4415  ],4416  "last_verified": "2026-09-18",4417  "name_constraint": "name must be 'tool_search_tool_regex'",4418  "_fragment": "generated/fragments/tools/anthropic-tools.json"4419 },4420 {4421  "provider": "anthropic",4422  "name": "Tool search tool (tool_search_tool_bm25)",4423  "type": "tool_search_tool_bm25_20251119",4424  "category": "server",4425  "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).",4426  "compatible_models": [4427   "claude-fable-5-1",4428   "claude-mythos-5-1",4429   "claude-fable-5",4430   "claude-mythos-5",4431   "claude-opus-5",4432   "claude-opus-4-8",4433   "claude-opus-4-7",4434   "claude-opus-4-6",4435   "claude-sonnet-4-6",4436   "claude-opus-4-5-20251101",4437   "claude-sonnet-4-5-20250929",4438   "claude-haiku-4-5-20251001"4439  ],4440  "compatible_endpoints": [4441   "POST /v1/messages",4442   "POST /v1/messages/batches"4443  ],4444  "parameters_schema": {4445   "type": "object",4446   "required": [4447    "type",4448    "name"4449   ],4450   "properties": {4451    "type": {4452     "enum": [4453      "tool_search_tool_bm25_20251119",4454      "tool_search_tool_bm25"4455     ]4456    },4457    "name": {4458     "const": "tool_search_tool_bm25"4459    },4460    "cache_control": {4461     "type": "object",4462     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."4463    },4464    "defer_loading": {4465     "type": "boolean",4466     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."4467    },4468    "strict": {4469     "type": "boolean",4470     "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)."4471    },4472    "allowed_callers": {4473     "type": "array",4474     "items": {4475      "enum": [4476       "direct",4477       "code_execution_20250825",4478       "code_execution_20260120",4479       "code_execution_20260521"4480      ]4481     },4482     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])."4483    }4484   },4485   "constraints": [4486    "never set defer_loading:true on the search tool itself (400 'At least one tool must have defer_loading=false')",4487    "deferred tool + cache_control -> 400 (live k23)",4488    "max 10,000 deferred tools"4489   ]4490  },4491  "tool_choice_support": "auto",4492  "parallel": "server-side; results expand automatically",4493  "streaming_events": [4494   "server_tool_use start + input_json_delta (pattern/query/limit)",4495   "tool_search_tool_result whole block"4496  ],4497  "result_shape": {4498   "server_tool_use": {4499    "type": "server_tool_use",4500    "id": "srvtoolu_…",4501    "name": "tool_search_tool_regex",4502    "input": {4503     "pattern": "weather",4504     "limit": 104505    }4506   },4507   "tool_search_tool_result": {4508    "type": "tool_search_tool_result",4509    "tool_use_id": "srvtoolu_…",4510    "content": {4511     "type": "tool_search_tool_search_result",4512     "tool_references": [4513      {4514       "type": "tool_reference",4515       "tool_name": "get_weather"4516      }4517     ]4518    }4519   },4520   "error": {4521    "content": {4522     "type": "tool_search_tool_result_error",4523     "error_code": "invalid_tool_input|unavailable|too_many_requests|execution_time_exceeded",4524     "error_message": "…"4525    }4526   },4527   "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').",4528   "custom_search": {4529    "type": "tool_result",4530    "tool_use_id": "toolu_…",4531    "content": [4532     {4533      "type": "tool_reference",4534      "tool_name": "…"4535     }4536    ]4537   }4538  },4539  "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).",4540  "limitations": [4541   "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",4542   "Bedrock: InvokeModel only"4543  ],4544  "security": [],4545  "beta_header": null,4546  "status": [4547   "DOCUMENTED",4548   "LIVE_VERIFIED"4549  ],4550  "examples": {4551   "curl": "examples/anthropic/tools/tool-search/basic.sh",4552   "python": "examples/anthropic/tools/tool-search/basic.py",4553   "typescript": "examples/anthropic/tools/tool-search/basic.ts"4554  },4555  "verification": {4556   "method": "live_api",4557   "verified_at": "2026-09-18",4558   "result": "success",4559   "http_status": 200,4560   "request_note": "f2 (haiku): query 'stock price AAPL Apple' -> tool_reference get_stock_price -> tool_use"4561  },4562  "sources": [4563   {4564    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool",4565    "retrieved_at": "2026-09-18"4566   },4567   {4568    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",4569    "retrieved_at": "2026-09-18"4570   },4571   {4572    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching",4573    "retrieved_at": "2026-09-18"4574   },4575   {4576    "url": "https://platform.claude.com/docs/en/api/messages/create",4577    "retrieved_at": "2026-09-18"4578   }4579  ],4580  "last_verified": "2026-09-18",4581  "name_constraint": "name must be 'tool_search_tool_bm25'",4582  "_fragment": "generated/fragments/tools/anthropic-tools.json"4583 },4584 {4585  "provider": "anthropic",4586  "name": "Advisor tool (beta)",4587  "type": "advisor_20260301",4588  "category": "server",4589  "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.",4590  "compatible_models": [4591   "claude-haiku-4-5-20251001",4592   "claude-sonnet-4-6",4593   "claude-sonnet-5",4594   "claude-opus-4-6",4595   "claude-opus-4-7",4596   "claude-opus-4-8",4597   "claude-opus-5",4598   "claude-fable-5",4599   "claude-mythos-5",4600   "claude-fable-5-1",4601   "claude-mythos-5-1"4602  ],4603  "compatible_endpoints": [4604   "POST /v1/messages",4605   "POST /v1/messages/batches"4606  ],4607  "parameters_schema": {4608   "type": "object",4609   "required": [4610    "type",4611    "name",4612    "model"4613   ],4614   "properties": {4615    "type": {4616     "const": "advisor_20260301"4617    },4618    "name": {4619     "const": "advisor"4620    },4621    "model": {4622     "type": "string",4623     "description": "advisor model id; must be >= Sonnet 4.6 and at least as capable as the executor (see pairs)"4624    },4625    "max_uses": {4626     "type": "integer",4627     "description": "per-request cap -> advisor_tool_result_error max_uses_exceeded"4628    },4629    "max_tokens": {4630     "type": "integer",4631     "minimum": 1024,4632     "description": "caps advisor output (thinking+text) per call; adds stop_reason to result"4633    },4634    "caching": {4635     "type": [4636      "object",4637      "null"4638     ],4639     "description": "{type: ephemeral, ttl: 5m|1h} on/off switch for advisor-side caching"4640    },4641    "cache_control": {4642     "type": "object",4643     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."4644    },4645    "strict": {4646     "type": "boolean",4647     "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)."4648    },4649    "defer_loading": {4650     "type": "boolean",4651     "description": "Exclude from the initial system prompt; loaded when tool search returns a tool_reference. Max 10,000 deferred tools/request."4652    },4653    "allowed_callers": {4654     "type": "array",4655     "items": {4656      "enum": [4657       "direct",4658       "code_execution_20250825",4659       "code_execution_20260120",4660       "code_execution_20260521"4661      ]4662     },4663     "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])."4664    },4665    "input_examples": {4666     "type": "array",4667     "items": {4668      "type": "object"4669     },4670     "description": "Schema-validated example inputs (user-defined + Anthropic-schema client tools only; not toolsets/server tools)."4671    }4672   },4673   "executor_advisor_pairs": {4674    "claude-haiku-4-5-20251001": [4675     "claude-mythos-5-1",4676     "claude-fable-5-1",4677     "claude-mythos-5",4678     "claude-fable-5",4679     "claude-opus-5",4680     "claude-opus-4-8",4681     "claude-opus-4-7",4682     "claude-opus-4-6",4683     "claude-sonnet-5",4684     "claude-sonnet-4-6"4685    ],4686    "claude-sonnet-4-6": [4687     "claude-mythos-5-1",4688     "claude-fable-5-1",4689     "claude-mythos-5",4690     "claude-fable-5",4691     "claude-opus-5",4692     "claude-opus-4-8",4693     "claude-opus-4-7",4694     "claude-opus-4-6",4695     "claude-sonnet-5",4696     "claude-sonnet-4-6"4697    ],4698    "claude-sonnet-5": [4699     "claude-mythos-5-1",4700     "claude-fable-5-1",4701     "claude-mythos-5",4702     "claude-fable-5",4703     "claude-opus-5",4704     "claude-opus-4-8",4705     "claude-opus-4-7",4706     "claude-sonnet-5"4707    ],4708    "claude-opus-4-6": [4709     "claude-mythos-5-1",4710     "claude-fable-5-1",4711     "claude-mythos-5",4712     "claude-fable-5",4713     "claude-opus-5",4714     "claude-opus-4-8",4715     "claude-opus-4-7",4716     "claude-opus-4-6",4717     "claude-sonnet-5"4718    ],4719    "claude-opus-4-7": [4720     "claude-mythos-5-1",4721     "claude-fable-5-1",4722     "claude-mythos-5",4723     "claude-fable-5",4724     "claude-opus-5",4725     "claude-opus-4-8",4726     "claude-opus-4-7"4727    ],4728    "claude-opus-4-8": [4729     "claude-mythos-5-1",4730     "claude-fable-5-1",4731     "claude-mythos-5",4732     "claude-fable-5",4733     "claude-opus-5",4734     "claude-opus-4-8",4735     "claude-opus-4-7"4736    ],4737    "claude-opus-5": [4738     "claude-mythos-5-1",4739     "claude-fable-5-1",4740     "claude-mythos-5",4741     "claude-fable-5",4742     "claude-opus-5"4743    ],4744    "claude-fable-5": [4745     "claude-mythos-5-1",4746     "claude-fable-5-1",4747     "claude-mythos-5",4748     "claude-fable-5",4749     "claude-opus-5"4750    ],4751    "claude-mythos-5": [4752     "claude-mythos-5-1",4753     "claude-fable-5-1",4754     "claude-mythos-5",4755     "claude-fable-5",4756     "claude-opus-5"4757    ],4758    "claude-fable-5-1": [4759     "claude-mythos-5-1",4760     "claude-fable-5-1"4761    ],4762    "claude-mythos-5-1": [4763     "claude-mythos-5-1",4764     "claude-fable-5-1"4765    ]4766   }4767  },4768  "tool_choice_support": "auto",4769  "parallel": "server-side; pause_turn possible while advisor pending",4770  "streaming_events": [4771   "server_tool_use start/stop then quiet (ping every ~30 s) until advisor_tool_result arrives whole in one content_block_start",4772   "message_delta with usage.iterations"4773  ],4774  "result_shape": {4775   "server_tool_use": {4776    "type": "server_tool_use",4777    "id": "srvtoolu_…",4778    "name": "advisor",4779    "input": {}4780   },4781   "advisor_tool_result": {4782    "type": "advisor_tool_result",4783    "tool_use_id": "srvtoolu_…",4784    "content": "{type:advisor_result,text,stop_reason?} | {type:advisor_redacted_result,encrypted_content,stop_reason?} | {type:advisor_tool_result_error,error_code}"4785   },4786   "error_codes": [4787    "max_uses_exceeded",4788    "too_many_requests",4789    "overloaded",4790    "prompt_too_long",4791    "execution_time_exceeded",4792    "model_not_found",4793    "unavailable"4794   ],4795   "usage.iterations": [4796    {4797     "type": "message",4798     "input_tokens": 0,4799     "output_tokens": 04800    },4801    {4802     "type": "advisor_message",4803     "model": "claude-opus-5",4804     "input_tokens": 0,4805     "output_tokens": 04806    }4807   ],4808   "live_note": "k18 (haiku executor, sonnet 4.6 advisor, 'Reply with OK'): 200, no advisor call, usage.iterations present with one message iteration"4809  },4810  "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.",4811  "limitations": [4812   "Claude API + Claude Platform on AWS only (beta)",4813   "Invalid executor/advisor pair -> 400",4814   "count_tokens covers only the executor's first sampling call"4815  ],4816  "security": [],4817  "beta_header": "advisor-tool-2026-03-01",4818  "status": [4819   "DOCUMENTED",4820   "BETA",4821   "LIVE_VERIFIED"4822  ],4823  "examples": {4824   "curl": "examples/anthropic/tools/advisor/basic.sh"4825  },4826  "verification": {4827   "method": "live_api",4828   "verified_at": "2026-09-18",4829   "result": "success",4830   "http_status": 200,4831   "request_note": "k18_advisor_haiku_exec 200; k18b without header 400"4832  },4833  "sources": [4834   {4835    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool",4836    "retrieved_at": "2026-09-18"4837   },4838   {4839    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",4840    "retrieved_at": "2026-09-18"4841   },4842   {4843    "url": "https://platform.claude.com/docs/en/release-notes/api",4844    "retrieved_at": "2026-09-18"4845   },4846   {4847    "url": "https://platform.claude.com/docs/en/build-with-claude/token-counting",4848    "retrieved_at": "2026-09-18"4849   }4850  ],4851  "last_verified": "2026-09-18",4852  "_fragment": "generated/fragments/tools/anthropic-tools.json"4853 },4854 {4855  "provider": "anthropic",4856  "name": "MCP connector toolset (beta)",4857  "type": "mcp_toolset",4858  "category": "mcp",4859  "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.",4860  "compatible_models": [4861   "claude-fable-5-1",4862   "claude-opus-5",4863   "claude-sonnet-5",4864   "claude-fable-5",4865   "claude-opus-4-8",4866   "claude-opus-4-7",4867   "claude-sonnet-4-6",4868   "claude-opus-4-6",4869   "claude-opus-4-5-20251101",4870   "claude-haiku-4-5-20251001",4871   "claude-sonnet-4-5-20250929",4872   "claude-mythos-5-1",4873   "claude-mythos-5"4874  ],4875  "compatible_endpoints": [4876   "POST /v1/messages",4877   "POST /v1/messages/batches"4878  ],4879  "parameters_schema": {4880   "type": "object",4881   "required": [4882    "type",4883    "mcp_server_name"4884   ],4885   "properties": {4886    "type": {4887     "const": "mcp_toolset"4888    },4889    "mcp_server_name": {4890     "type": "string",4891     "description": "must match exactly one mcp_servers[].name; each server referenced by exactly one toolset"4892    },4893    "default_config": {4894     "type": "object",4895     "properties": {4896      "enabled": {4897       "type": "boolean",4898       "default": true4899      },4900      "defer_loading": {4901       "type": "boolean",4902       "default": false4903      }4904     }4905    },4906    "configs": {4907     "type": "object",4908     "description": "tool name -> {enabled?, defer_loading?} overrides (unknown names: warning only)"4909    },4910    "cache_control": {4911     "type": "object",4912     "description": "Prompt-cache breakpoint {type: ephemeral, ttl?: 5m|1h}. Not allowed together with defer_loading:true (live 400)."4913    }4914   },4915   "mcp_servers[]": {4916    "type": {4917     "const": "url"4918    },4919    "url": "https://… (Streamable HTTP or SSE)",4920    "name": "unique id",4921    "authorization_token": "OAuth bearer token obtained by you",4922    "tool_configuration": "DEPRECATED (2025-04-04 header): {enabled?, allowed_tools?[]}"4923   },4924   "limits": {4925    "mcp_servers maxItems": 204926   }4927  },4928  "tool_choice_support": "auto",4929  "parallel": "server-executed; an mcp_tool_use without result in a tool_use-stop response is deferred like server_tool_use",4930  "streaming_events": [4931   "content_block_start mcp_tool_use + input_json_delta",4932   "mcp_tool_result whole block"4933  ],4934  "result_shape": {4935   "mcp_tool_use": {4936    "type": "mcp_tool_use",4937    "id": "mcptoolu_…",4938    "name": "read_wiki_structure",4939    "server_name": "deepwiki",4940    "input": {4941     "repoName": "…"4942    }4943   },4944   "mcp_tool_result": {4945    "type": "mcp_tool_result",4946    "tool_use_id": "mcptoolu_…",4947    "is_error": false,4948    "content": [4949     {4950      "type": "text",4951      "text": "…"4952     }4953    ]4954   },4955   "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)"4956  },4957  "billing": "Tokens only (tool definitions fetched from the server count as input; Batches priced the same). Live i1: 2,367 input tokens.",4958  "limitations": [4959   "Remote HTTP servers only (no stdio); OAuth flow is your responsibility",4960   "Not ZDR-eligible",4961   "MCP tools cannot be called programmatically (PTC) and mcp_toolset does not accept strict/allowed_callers",4962   "count_tokens rejects requests with mcp_servers",4963   "Not on Bedrock/Vertex"4964  ],4965  "security": [4966   "Only connect to trusted servers; tool results are untrusted content"4967  ],4968  "beta_header": "mcp-client-2025-11-20",4969  "status": [4970   "DOCUMENTED",4971   "BETA",4972   "LIVE_VERIFIED"4973  ],4974  "examples": {4975   "curl": "examples/anthropic/mcp/mcp_connector.sh",4976   "python": "examples/anthropic/mcp/mcp_connector.py",4977   "typescript": "examples/anthropic/mcp/mcp_connector.ts",4978   "server": "examples/anthropic/mcp/mini-mcp-server.ts"4979  },4980  "verification": {4981   "method": "live_api",4982   "verified_at": "2026-09-18",4983   "result": "success",4984   "http_status": 200,4985   "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"4986  },4987  "sources": [4988   {4989    "url": "https://platform.claude.com/docs/en/agents-and-tools/mcp-connector",4990    "retrieved_at": "2026-09-18"4991   },4992   {4993    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",4994    "retrieved_at": "2026-09-18"4995   },4996   {4997    "url": "https://platform.claude.com/docs/en/api/beta/messages/create",4998    "retrieved_at": "2026-09-18"4999   },5000   {5001    "url": "https://platform.claude.com/docs/en/api/beta-headers",5002    "retrieved_at": "2026-09-18"5003   }5004  ],5005  "last_verified": "2026-09-18",5006  "beta_history": {5007   "mcp-client-2025-04-04": "deprecated (tool_configuration on server def)",5008   "mcp-client-2025-11-20": "current",5009   "mcp-client-2026-09-15": "LIVE_DISCOVERED in an error message; not accepted on 2026-09-18"5010  },5011  "_fragment": "generated/fragments/tools/anthropic-tools.json"5012 },5013 {5014  "provider": "anthropic",5015  "name": "Programmatic tool calling (allowed_callers / caller)",5016  "type": "allowed_callers:code_execution_20260120",5017  "category": "programmatic",5018  "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:<srvtoolu 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.",5019  "compatible_models": [5020   "claude-fable-5-1",5021   "claude-mythos-5-1",5022   "claude-fable-5",5023   "claude-mythos-5",5024   "claude-opus-5",5025   "claude-opus-4-8",5026   "claude-opus-4-7",5027   "claude-opus-4-6",5028   "claude-opus-4-5-20251101",5029   "claude-sonnet-5",5030   "claude-sonnet-4-6",5031   "claude-sonnet-4-5-20250929"5032  ],5033  "compatible_endpoints": [5034   "POST /v1/messages",5035   "POST /v1/messages/batches"5036  ],5037  "parameters_schema": {5038   "allowed_callers": {5039    "type": "array",5040    "items": {5041     "enum": [5042      "direct",5043      "code_execution_20250825",5044      "code_execution_20260120",5045      "code_execution_20260521"5046     ]5047    },5048    "description": "Who may call the tool. Default [\"direct\"] (web_search/web_fetch _20260209+ default to [\"code_execution_20260120\"])."5049   },5050   "requires": "tools[] includes {type: code_execution_20260120|code_execution_20260521, name: code_execution}",5051   "container": "required on continuation requests while a programmatic call is pending"5052  },5053  "tool_choice_support": "tool_choice may not name a tool whose allowed_callers omits direct (live 400)",5054  "parallel": "disable_parallel_tool_use:true unsupported with PTC; several programmatic calls may be pending at once (answer all in one user message)",5055  "streaming_events": [5056   "server_tool_use code_execution start + input_json_delta(code)",5057   "tool_use with caller",5058   "later: code_execution_tool_result whole block"5059  ],5060  "result_shape": {5061   "tool_use (programmatic)": {5062    "type": "tool_use",5063    "id": "toolu_…",5064    "name": "query_database",5065    "input": {5066     "sql": "SELECT 1 AS one"5067    },5068    "caller": {5069     "type": "code_execution_20260120",5070     "tool_id": "srvtoolu_…"5071    }5072   },5073   "tool_use (direct)": {5074    "caller": {5075     "type": "direct"5076    }5077   },5078   "completion": {5079    "type": "code_execution_tool_result",5080    "tool_use_id": "srvtoolu_…",5081    "content": {5082     "type": "code_execution_result",5083     "stdout": "[{'one': 1}]\n",5084     "stderr": "",5085     "return_code": 0,5086     "content": [],5087     "abort_reason": null5088    }5089   },5090   "timeout": "TimeoutError in stderr after ~270 s waiting for your result; idle containers reclaimed after ~5 min"5091  },5092  "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.",5093  "limitations": [5094   "Haiku 4.5 unsupported (live 400 naming the tools)",5095   "strict:true tools cannot have code_execution callers (live 400)",5096   "No MCP tools, no computer/browser toolsets",5097   "Recursive $ref schemas rejected",5098   "tool_result content must be string/text only; no text after tool_results",5099   "Not on Bedrock/Vertex; Foundry Hosted-on-Anthropic only; not ZDR"5100  ],5101  "security": [5102   "allowed_callers is guidance, not a hard block: still handle direct tool_use for every tool",5103   "Tool results are strings that Claude's code may parse/exec — beware injection"5104  ],5105  "beta_header": null,5106  "status": [5107   "DOCUMENTED",5108   "LIVE_VERIFIED"5109  ],5110  "examples": {5111   "curl": "examples/anthropic/tools/programmatic-tool-calling/basic.sh",5112   "python": "examples/anthropic/tools/programmatic-tool-calling/basic.py",5113   "typescript": "examples/anthropic/tools/programmatic-tool-calling/basic.ts"5114  },5115  "verification": {5116   "method": "live_api",5117   "verified_at": "2026-09-18",5118   "result": "success",5119   "http_status": 200,5120   "request_note": "g1/g2 claude-sonnet-4-6 full round trip; g3 haiku 400; g4 tool_choice 400; k28 strict 400"5121  },5122  "sources": [5123   {5124    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling",5125    "retrieved_at": "2026-09-18"5126   },5127   {5128    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference",5129    "retrieved_at": "2026-09-18"5130   },5131   {5132    "url": "https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools",5133    "retrieved_at": "2026-09-18"5134   },5135   {5136    "url": "https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons",5137    "retrieved_at": "2026-09-18"5138   }5139  ],5140  "last_verified": "2026-09-18",5141  "release_history": "beta 2025-11-24 (advanced-tool-use-2025-11-20) -> GA 2026-02-17; code_execution_20260120 SDK support 2026-06-18",5142  "_fragment": "generated/fragments/tools/anthropic-tools.json"5143 },5144 {5145  "provider": "gemini",5146  "name": "Function calling (custom client tools)",5147  "type": "functionDeclarations",5148  "category": "client",5149  "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.",5150  "compatible_models": [5151   "gemini-3.8-flash",5152   "gemini-3.7-flash",5153   "gemini-3.6-flash",5154   "gemini-3.5-flash",5155   "gemini-3.5-flash-lite",5156   "gemini-3.1-pro-preview",5157   "gemini-3.1-pro-preview-customtools",5158   "gemini-3.1-flash-lite",5159   "gemini-3.1-flash-lite-preview",5160   "gemini-3-flash-preview",5161   "gemini-3-pro-preview",5162   "gemini-2.5-pro",5163   "gemini-2.5-flash",5164   "gemini-2.5-flash-lite",5165   "gemini-robotics-er-2-preview",5166   "gemini-robotics-er-1.6-preview",5167   "gemini-3.8-live",5168   "gemini-3.8-live-extended-thinking",5169   "gemini-3.1-flash-live-preview",5170   "gemini-2.5-flash-native-audio-preview-12-2025",5171   "gemini-robotics-er-2-streaming-preview"5172  ],5173  "compatible_endpoints": [5174   "POST /v1beta/models/{model}:generateContent",5175   "POST /v1beta/models/{model}:streamGenerateContent",5176   "POST /v1beta/models/{model}:countTokens (tools counted)",5177   "POST /v1beta/models/{model}:batchGenerateContent (same request schema)",5178   "WSS /ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent (setup.tools; toolCall/toolResponse messages; behavior NON_BLOCKING)",5179   "POST /v1beta/interactions (as `{\"type\":\"function\",name,description,parameters}` + `generation_config.tool_choice`)"5180  ],5181  "parameters_schema": {5182   "type": "object",5183   "description": "tools[].functionDeclarations[] item",5184   "required": [5185    "name"5186   ],5187   "properties": {5188    "name": {5189     "type": "string",5190     "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."5191    },5192    "description": {5193     "type": "string",5194     "description": "Required per REST reference (discovery marks the whole object optional). Purpose of the function; crucial for tool selection."5195    },5196    "parameters": {5197     "type": "object",5198     "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)."5199    },5200    "parametersJsonSchema": {5201     "type": "object",5202     "description": "Full JSON Schema object describing the parameters object (supports additionalProperties, propertyOrdering...). Mutually exclusive with `parameters`."5203    },5204    "response": {5205     "type": "object",5206     "description": "Schema of the function's return value (OpenAPI subset). Mutually exclusive with responseJsonSchema."5207    },5208    "responseJsonSchema": {5209     "type": "object",5210     "description": "JSON Schema of the return value. Mutually exclusive with `response`."5211    },5212    "behavior": {5213     "type": "string",5214     "enum": [5215      "UNSPECIFIED",5216      "BLOCKING",5217      "NON_BLOCKING"5218     ],5219     "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."5220    }5221   },5222   "toolConfig.functionCallingConfig": {5223    "mode": {5224     "enum": [5225      "MODE_UNSPECIFIED",5226      "AUTO",5227      "ANY",5228      "NONE",5229      "VALIDATED"5230     ],5231     "default": "AUTO (VALIDATED when built-in tools or structured outputs are also enabled / when includeServerSideToolInvocations=true)"5232    },5233    "allowedFunctionNames": {5234     "type": "array<string>",5235     "description": "Only with mode ANY or VALIDATED"5236    }5237   }5238  },5239  "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.",5240  "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.",5241  "streaming_events": [5242   "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",5243   "Live API server messages: toolCall {functionCalls[{id,name,args}]}, toolCallCancellation {ids[]}; client sends toolResponse {functionResponses[]}",5244   "finishReason values to check: STOP, MALFORMED_FUNCTION_CALL, UNEXPECTED_TOOL_CALL, TOO_MANY_TOOL_CALLS, MISSING_THOUGHT_SIGNATURE"5245  ],5246  "result_shape": {5247   "model part": {5248    "functionCall": {5249     "name": "get_weather",5250     "args": {5251      "city": "Paris"5252     },5253     "id": "m4q8z1v6"5254    },5255    "thoughtSignature": "<base64, Gemini 3: mandatory echo on first FC of each step>"5256   },5257   "your reply part (role user)": {5258    "functionResponse": {5259     "name": "get_weather",5260     "id": "m4q8z1v6",5261     "response": {5262      "result": "..."5263     },5264     "parts": [5265      {5266       "inlineData": {5267        "mimeType": "image/png",5268        "data": "<base64>"5269       }5270      }5271     ],5272     "scheduling": "SILENT|WHEN_IDLE|INTERRUPT (Live NON_BLOCKING only)",5273     "willContinue": "bool (Live NON_BLOCKING only)"5274    }5275   },5276   "multimodal ref": "response: {\"image\": {\"$ref\": \"<inlineData.display_name>\"}} (Gemini 3)",5277   "Live": {5278    "server": {5279     "toolCall": {5280      "functionCalls": [5281       {5282        "id": "...",5283        "name": "...",5284        "args": {}5285       }5286      ]5287     }5288    },5289    "client": {5290     "toolResponse": {5291      "functionResponses": [5292       {5293        "id": "...",5294        "name": "...",5295        "response": {5296         "result": "ok",5297         "scheduling": "INTERRUPT"5298        }5299       }5300      ]5301     }5302    }5303   }5304  },5305  "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.",5306  "limitations": [5307   "Only a subset of OpenAPI 3.03 Schema is supported in `parameters`; use parametersJsonSchema for full JSON Schema",5308   "ANY mode may reject very large or deeply nested schemas (simplify names/nesting/count)",5309   "Keep active set to ~10-20 tools (best practice); max 512 declarations (SDK docstring)",5310   "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",5311   "Do not merge/split parts carrying signatures; do not interleave parallel FC/FR",5312   "Automatic function calling is Python SDK only (JS SDK: AFC for mcpToTool/callable tools); Live API has no automatic tool response handling",5313   "Pre-tool structured text (XML before a call) can cause MALFORMED_FUNCTION_CALL — wrap notes in an `update()` function instead",5314   "`behavior` only honored by BidiGenerateContent",5315   "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",5316   "When parts mix functionCall/toolCall/toolResponse do not assume functionCall is last — iterate parts"5317  ],5318  "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.",5319  "beta_header": null,5320  "status": [5321   "DOCUMENTED",5322   "LIVE_VERIFIED"5323  ],5324  "examples": {5325   "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\"}}}'",5326   "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)",5327   "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));"5328  },5329  "verification": {5330   "method": "live_api",5331   "verified_at": "2026-09-18",5332   "result": "success",5333   "http_status": 200,5334   "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)"5335  },5336  "sources": [5337   {5338    "url": "https://ai.google.dev/gemini-api/docs/function-calling",5339    "retrieved_at": "2026-09-18"5340   },5341   {5342    "url": "https://ai.google.dev/gemini-api/docs/generate-content/function-calling",5343    "retrieved_at": "2026-09-18"5344   },5345   {5346    "url": "https://ai.google.dev/gemini-api/docs/thought-signatures",5347    "retrieved_at": "2026-09-18"5348   },5349   {5350    "url": "https://ai.google.dev/gemini-api/docs/generate-content/thought-signatures",5351    "retrieved_at": "2026-09-18"5352   },5353   {5354    "url": "https://ai.google.dev/api/generate-content#Tool",5355    "retrieved_at": "2026-09-18"5356   },5357   {5358    "url": "https://ai.google.dev/api/generate-content#FunctionDeclaration",5359    "retrieved_at": "2026-09-18"5360   },5361   {5362    "url": "https://ai.google.dev/api/generate-content#FunctionCallingConfig",5363    "retrieved_at": "2026-09-18"5364   },5365   {5366    "url": "https://ai.google.dev/gemini-api/docs/live-tools",5367    "retrieved_at": "2026-09-18"5368   },5369   {5370    "url": "https://ai.google.dev/gemini-api/docs/tool-combination",5371    "retrieved_at": "2026-09-18"5372   }5373  ],5374  "_fragment": "generated/fragments/tools/gemini-tools.json"5375 },5376 {5377  "provider": "gemini",5378  "name": "Grounding with Google Search",5379  "type": "googleSearch",5380  "category": "server",5381  "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.",5382  "compatible_models": [5383   "gemini-3.8-flash",5384   "gemini-3.7-flash",5385   "gemini-3.6-flash",5386   "gemini-3.5-flash",5387   "gemini-3.5-flash-lite",5388   "gemini-3.1-pro-preview",5389   "gemini-3.1-pro-preview-customtools",5390   "gemini-3.1-flash-lite",5391   "gemini-3.1-flash-lite-preview",5392   "gemini-3-flash-preview",5393   "gemini-3-pro-preview",5394   "gemini-3.1-flash-image",5395   "gemini-3.1-flash-image-preview",5396   "gemini-3-pro-image",5397   "gemini-3-pro-image-preview",5398   "gemini-2.5-pro",5399   "gemini-2.5-flash",5400   "gemini-2.5-flash-lite",5401   "gemini-robotics-er-2-preview",5402   "gemini-robotics-er-1.6-preview",5403   "gemini-3.8-live",5404   "gemini-3.8-live-extended-thinking",5405   "gemini-3.1-flash-live-preview",5406   "gemini-2.5-flash-native-audio-preview-12-2025",5407   "gemini-robotics-er-2-streaming-preview",5408   "gemini-2.0-flash (RETIRED 2026-06-01)"5409  ],5410  "compatible_endpoints": [5411   "POST /v1beta/models/{model}:generateContent",5412   "POST /v1beta/models/{model}:streamGenerateContent",5413   "WSS /ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent (setup.tools[{googleSearch:{}}])",5414   "POST /v1beta/interactions (as `{\"type\":\"google_search\"}`; search_types: [\"web_search\",\"image_search\"])",5415   "POST /v1beta/models/{model}:batchGenerateContent"5416  ],5417  "parameters_schema": {5418   "type": "object",5419   "description": "tools[].googleSearch",5420   "properties": {5421    "timeRangeFilter": {5422     "type": "object",5423     "properties": {5424      "startTime": {5425       "type": "string (RFC 3339 timestamp)",5426       "description": "Inclusive start"5427      },5428      "endTime": {5429       "type": "string (RFC 3339 timestamp)",5430       "description": "Exclusive end"5431      }5432     },5433     "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.)"5434    },5435    "searchTypes": {5436     "type": "object",5437     "properties": {5438      "webSearch": {5439       "type": "object (empty)",5440       "description": "Enables web search; text results only. Default when searchTypes unset."5441      },5442      "imageSearch": {5443       "type": "object (empty)",5444       "description": "Enables image search; image bytes returned. Documented for gemini-3.1-flash-image (Nano Banana 2); cannot be used to search for people."5445      }5446     }5447    }5448   },5449   "toolConfig.retrievalConfig": {5450    "latLng": {5451     "latitude": "number",5452     "longitude": "number"5453    },5454    "languageCode": "string (BCP-47)"5455   }5456  },5457  "tool_choice_support": "None (server decides whether to search). Not affected by functionCallingConfig. Legacy dynamic retrieval threshold only exists on googleSearchRetrieval.",5458  "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).",5459  "streaming_events": [5460   "streamGenerateContent: groundingMetadata arrives on candidates; groundingChunks in a chunk contain only chunks not yet sent — client must accumulate; groundingChunkIndices index the accumulated list",5461   "With includeServerSideToolInvocations=true: toolCall {toolType:GOOGLE_SEARCH_WEB|GOOGLE_SEARCH_IMAGE, args:{queries[]}, id} and toolResponse {response:{search_suggestions}} parts appear in model content",5462   "Live API: same googleSearch tool; grounding metadata in serverContent"5463  ],5464  "result_shape": {5465   "candidates[].groundingMetadata": {5466    "webSearchQueries": [5467     "..."5468    ],5469    "imageSearchQueries": [5470     "..."5471    ],5472    "searchEntryPoint": {5473     "renderedContent": "<HTML/CSS widget>",5474     "sdkBlob": "base64 JSON [[term,url],...]"5475    },5476    "groundingChunks": [5477     {5478      "web": {5479       "uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/...",5480       "title": "example.com"5481      }5482     },5483     {5484      "image": {5485       "imageUri": "...",5486       "sourceUri": "...",5487       "title": "...",5488       "domain": "example.com"5489      }5490     }5491    ],5492    "groundingSupports": [5493     {5494      "segment": {5495       "partIndex": 0,5496       "startIndex": 0,5497       "endIndex": 85,5498       "text": "..."5499      },5500      "groundingChunkIndices": [5501       05502      ],5503      "confidenceScores": [5504       0.95505      ],5506      "renderedParts": [5507       05508      ]5509     }5510    ],5511    "retrievalMetadata": {5512     "googleSearchDynamicRetrievalScore": "only with legacy dynamic retrieval"5513    }5514   },5515   "usageMetadata": {5516    "toolUsePromptTokenCount": "tokens injected by tools"5517   }5518  },5519  "billing": {5520   "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.",5521   "gemini_2_5_models": "Paid tier: 1,500 RPD free (shared Flash/Flash-Lite), then $35 per 1,000 grounded PROMPTS (billed per prompt).",5522   "free_tier": "500 RPD free (shared Flash and Flash-Lite); not available for Pro.",5523   "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.",5524   "image_search": "Same $14 per 1,000 requests for text and image-based grounding (Nano Banana 2 pricing table)."5525  },5526  "limitations": [5527   "Must display searchEntryPoint.renderedContent (Search Suggestions) per Terms of Service",5528   "Cannot be combined with fileSearch (File Search guide: not combinable with other tools)",5529   "Legacy 1.5/2.0 models used googleSearchRetrieval; 2.0 models were shut down 2026-06-01",5530   "Live API: only tool alongside function calling; Maps/URL context/code execution unsupported there",5531   "Image search cannot be used to search for people",5532   "timeRangeFilter: start and end must both be set",5533   "Built-in tools depend on location/time context — conflicting system_instruction can degrade tool combination"5534  ],5535  "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.",5536  "beta_header": null,5537  "status": [5538   "DOCUMENTED",5539   "ACCOUNT_RESTRICTED"5540  ],5541  "examples": {5542   "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\": {}}]}'",5543   "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)",5544   "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));"5545  },5546  "verification": {5547   "method": "live_api",5548   "verified_at": "2026-09-18",5549   "result": "restricted",5550   "http_status": 429,5551   "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)"5552  },5553  "sources": [5554   {5555    "url": "https://ai.google.dev/gemini-api/docs/google-search",5556    "retrieved_at": "2026-09-18"5557   },5558   {5559    "url": "https://ai.google.dev/gemini-api/docs/generate-content/google-search",5560    "retrieved_at": "2026-09-18"5561   },5562   {5563    "url": "https://ai.google.dev/api/generate-content#GoogleSearch",5564    "retrieved_at": "2026-09-18"5565   },5566   {5567    "url": "https://ai.google.dev/api/generate-content#GroundingMetadata",5568    "retrieved_at": "2026-09-18"5569   },5570   {5571    "url": "https://ai.google.dev/gemini-api/docs/pricing",5572    "retrieved_at": "2026-09-18"5573   },5574   {5575    "url": "https://ai.google.dev/gemini-api/docs/generate-content/image-generation",5576    "retrieved_at": "2026-09-18"5577   },5578   {5579    "url": "https://ai.google.dev/gemini-api/docs/live-tools",5580    "retrieved_at": "2026-09-18"5581   },5582   {5583    "url": "https://ai.google.dev/gemini-api/docs/tool-combination",5584    "retrieved_at": "2026-09-18"5585   }5586  ],5587  "_fragment": "generated/fragments/tools/gemini-tools.json"5588 },5589 {5590  "provider": "gemini",5591  "name": "Grounding with Google Image Search (searchTypes.imageSearch)",5592  "type": "googleSearch.searchTypes.imageSearch",5593  "category": "server",5594  "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.",5595  "compatible_models": [5596   "gemini-3.1-flash-image",5597   "gemini-3.1-flash-image-preview"5598  ],5599  "compatible_endpoints": [5600   "POST /v1beta/models/{model}:generateContent",5601   "POST /v1beta/models/{model}:streamGenerateContent",5602   "POST /v1beta/interactions (search_types: [\"image_search\"])"5603  ],5604  "parameters_schema": {5605   "type": "object",5606   "properties": {5607    "searchTypes": {5608     "webSearch": {},5609     "imageSearch": {}5610    }5611   }5612  },5613  "tool_choice_support": "none",5614  "parallel": "combinable with webSearch in the same googleSearch tool",5615  "streaming_events": [5616   "groundingMetadata with image chunks on candidates"5617  ],5618  "result_shape": {5619   "groundingChunks[].image": {5620    "imageUri": "string",5621    "sourceUri": "string",5622    "title": "string",5623    "domain": "string"5624   },5625   "imageSearchQueries": [5626    "string"5627   ]5628  },5629  "billing": "5,000 free search requests/month (shared across Gemini 3.x), then $14 per 1,000 requests for text and image-based grounding.",5630  "limitations": [5631   "Documented only for the Nano Banana 2 image model on 2026-09-18 — support on text models UNVERIFIED",5632   "No people search"5633  ],5634  "security": "Same display/attribution obligations as web grounding.",5635  "beta_header": null,5636  "status": [5637   "DOCUMENTED"5638  ],5639  "examples": {5640   "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\": {}}}}]}'",5641   "python": "tools=[types.Tool(google_search=types.GoogleSearch(search_types=types.SearchTypes(web_search=types.WebSearch(), image_search=types.ImageSearch())))]",5642   "typescript": "tools: [{ googleSearch: { searchTypes: { webSearch: {}, imageSearch: {} } } }]"5643  },5644  "verification": {5645   "method": "docs_only",5646   "verified_at": "2026-09-18",5647   "result": "not_tested",5648   "http_status": null,5649   "request_note": "not exercised in the 2026-09-18 run (docs only)"5650  },5651  "sources": [5652   {5653    "url": "https://ai.google.dev/gemini-api/docs/generate-content/image-generation",5654    "retrieved_at": "2026-09-18"5655   },5656   {5657    "url": "https://ai.google.dev/api/generate-content#SearchTypes",5658    "retrieved_at": "2026-09-18"5659   },5660   {5661    "url": "https://ai.google.dev/gemini-api/docs/models/gemini-3.1-flash-image",5662    "retrieved_at": "2026-09-18"5663   },5664   {5665    "url": "https://ai.google.dev/gemini-api/docs/pricing",5666    "retrieved_at": "2026-09-18"5667   }5668  ],5669  "_fragment": "generated/fragments/tools/gemini-tools.json"5670 },5671 {5672  "provider": "gemini",5673  "name": "Google Search retrieval (legacy dynamic retrieval)",5674  "type": "googleSearchRetrieval",5675  "category": "server",5676  "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.",5677  "compatible_models": [5678   "gemini-2.0-flash (RETIRED 2026-06-01)",5679   "gemini-2.0-flash-lite (RETIRED 2026-06-01; search grounding 'Not supported' on its model page)",5680   "gemini-1.5-* (RETIRED; not in models list)"5681  ],5682  "compatible_endpoints": [5683   "POST /v1beta/models/{model}:generateContent",5684   "POST /v1beta/models/{model}:streamGenerateContent"5685  ],5686  "parameters_schema": {5687   "type": "object",5688   "properties": {5689    "dynamicRetrievalConfig": {5690     "type": "object",5691     "properties": {5692      "mode": {5693       "enum": [5694        "MODE_UNSPECIFIED",5695        "MODE_DYNAMIC"5696       ]5697      },5698      "dynamicThreshold": {5699       "type": "number",5700       "description": "threshold in [0,1]; default system value"5701      }5702     }5703    }5704   }5705  },5706  "tool_choice_support": "dynamic retrieval threshold only",5707  "parallel": null,5708  "streaming_events": [5709   "groundingMetadata on candidates (same shape as googleSearch) + retrievalMetadata.googleSearchDynamicRetrievalScore"5710  ],5711  "result_shape": {5712   "groundingMetadata.retrievalMetadata": {5713    "googleSearchDynamicRetrievalScore": 0.735714   }5715  },5716  "billing": "Historically per grounded prompt ($35 / 1,000 grounded prompts, 1,500 RPD free on 2.5-era pricing). No current price line.",5717  "limitations": [5718   "Not supported on Gemini 2.5/3.x — use googleSearch",5719   "No live model in the 2026-09-18 ListModels output is documented to accept it"5720  ],5721  "security": "Same as googleSearch.",5722  "beta_header": null,5723  "status": [5724   "DOCUMENTED",5725   "LEGACY",5726   "DEPRECATED"5727  ],5728  "examples": {5729   "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}}}]}'",5730   "python": "types.Tool(google_search_retrieval=types.GoogleSearchRetrieval(dynamic_retrieval_config=types.DynamicRetrievalConfig(mode='MODE_DYNAMIC', dynamic_threshold=0.7)))",5731   "typescript": "{ googleSearchRetrieval: { dynamicRetrievalConfig: { mode: 'MODE_DYNAMIC', dynamicThreshold: 0.7 } } }"5732  },5733  "verification": {5734   "method": "docs_only",5735   "verified_at": "2026-09-18",5736   "result": "not_tested",5737   "http_status": null,5738   "request_note": "not exercised in the 2026-09-18 run (docs only)"5739  },5740  "sources": [5741   {5742    "url": "https://ai.google.dev/api/generate-content#GoogleSearchRetrieval",5743    "retrieved_at": "2026-09-18"5744   },5745   {5746    "url": "https://ai.google.dev/api/generate-content#DynamicRetrievalConfig",5747    "retrieved_at": "2026-09-18"5748   },5749   {5750    "url": "https://ai.google.dev/gemini-api/docs/google-search",5751    "retrieved_at": "2026-09-18"5752   },5753   {5754    "url": "https://ai.google.dev/gemini-api/docs/deprecations",5755    "retrieved_at": "2026-09-18"5756   },5757   {5758    "url": "https://ai.google.dev/gemini-api/docs/changelog",5759    "retrieved_at": "2026-09-18"5760   }5761  ],5762  "_fragment": "generated/fragments/tools/gemini-tools.json"5763 },5764 {5765  "provider": "gemini",5766  "name": "Grounding with Google Maps",5767  "type": "googleMaps",5768  "category": "server",5769  "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.",5770  "compatible_models": [5771   "gemini-3.8-flash",5772   "gemini-3.7-flash",5773   "gemini-3.6-flash",5774   "gemini-3.5-flash",5775   "gemini-3.5-flash-lite",5776   "gemini-3.1-pro-preview",5777   "gemini-3.1-flash-lite",5778   "gemini-3.1-flash-lite-preview",5779   "gemini-3-flash-preview",5780   "gemini-2.5-pro",5781   "gemini-2.5-flash",5782   "gemini-2.5-flash-lite",5783   "gemini-robotics-er-2-preview",5784   "gemini-robotics-er-1.6-preview",5785   "gemini-2.0-flash (RETIRED 2026-06-01)"5786  ],5787  "compatible_endpoints": [5788   "POST /v1beta/models/{model}:generateContent",5789   "POST /v1beta/models/{model}:streamGenerateContent",5790   "POST /v1beta/interactions (as `{\"type\":\"google_maps\"}`)"5791  ],5792  "parameters_schema": {5793   "type": "object",5794   "properties": {5795    "enableWidget": {5796     "type": "boolean",5797     "description": "Return googleMapsWidgetContextToken in groundingMetadata to render a Google Maps widget."5798    }5799   },5800   "toolConfig.retrievalConfig": {5801    "latLng": {5802     "latitude": "number [-90,90]",5803     "longitude": "number [-180,180]"5804    },5805    "languageCode": "string BCP-47"5806   }5807  },5808  "tool_choice_support": "none (off by default; enable only for geo queries)",5809  "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",5810  "streaming_events": [5811   "groundingMetadata on candidates",5812   "toolCall {toolType:GOOGLE_MAPS,args:{queries[]}} / toolResponse {response:{places, google_maps_widget_context_token}} with includeServerSideToolInvocations"5813  ],5814  "result_shape": {5815   "groundingMetadata": {5816    "groundingChunks": [5817     {5818      "maps": {5819       "uri": "https://maps.google.com/?cid=...",5820       "title": "Place name",5821       "placeId": "places/ChIJ...",5822       "text": "...",5823       "placeAnswerSources": {5824        "reviewSnippets": [5825         {5826          "reviewId": "...",5827          "googleMapsUri": "...",5828          "title": "..."5829         }5830        ]5831       }5832      }5833     }5834    ],5835    "groundingSupports": [5836     {5837      "segment": {5838       "startIndex": 0,5839       "endIndex": 79,5840       "text": "..."5841      },5842      "groundingChunkIndices": [5843       05844      ]5845     }5846    ],5847    "webSearchQueries": [5848     "restaurants near me"5849    ],5850    "googleMapsWidgetContextToken": "only when enableWidget=true"5851   }5852  },5853  "billing": {5854   "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.",5855   "pricing_page_gemini_3_model_tables": "5,000 prompts per month (free, shared across Gemini 3), then $14 / 1,000 search queries.",5856   "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.",5857   "note": "Documentation is inconsistent ($25/1K prompts vs $14/1K queries for Gemini 3) — DOCUMENTATION_INCOMPLETE; parent agent to verify billing dashboard if needed."5858  },5859  "limitations": [5860   "Text only (no multimodal inputs/outputs beyond text)",5861   "Off by default",5862   "Not available in the Live API",5863   "Not combinable with fileSearch",5864   "Prohibited: high-risk activities incl. emergency response; distribution in Google Maps Platform Prohibited Territories",5865   "Gemini 3 Pro Preview page: Maps 'Not supported'"5866  ],5867  "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).",5868  "beta_header": null,5869  "status": [5870   "DOCUMENTED",5871   "GA",5872   "LIVE_VERIFIED"5873  ],5874  "examples": {5875   "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}}}}'",5876   "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)",5877   "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));"5878  },5879  "verification": {5880   "method": "live_api",5881   "verified_at": "2026-09-18",5882   "result": "success",5883   "http_status": 200,5884   "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)"5885  },5886  "sources": [5887   {5888    "url": "https://ai.google.dev/gemini-api/docs/maps-grounding",5889    "retrieved_at": "2026-09-18"5890   },5891   {5892    "url": "https://ai.google.dev/gemini-api/docs/generate-content/maps-grounding",5893    "retrieved_at": "2026-09-18"5894   },5895   {5896    "url": "https://ai.google.dev/api/generate-content#GoogleMaps",5897    "retrieved_at": "2026-09-18"5898   },5899   {5900    "url": "https://ai.google.dev/api/generate-content#Maps",5901    "retrieved_at": "2026-09-18"5902   },5903   {5904    "url": "https://ai.google.dev/gemini-api/docs/pricing",5905    "retrieved_at": "2026-09-18"5906   },5907   {5908    "url": "https://ai.google.dev/gemini-api/docs/changelog",5909    "retrieved_at": "2026-09-18"5910   }5911  ],5912  "_fragment": "generated/fragments/tools/gemini-tools.json"5913 },5914 {5915  "provider": "gemini",5916  "name": "URL context",5917  "type": "urlContext",5918  "category": "server",5919  "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.",5920  "compatible_models": [5921   "gemini-3.8-flash",5922   "gemini-3.7-flash",5923   "gemini-3.6-flash",5924   "gemini-3.5-flash",5925   "gemini-3.5-flash-lite",5926   "gemini-3.1-pro-preview",5927   "gemini-3.1-pro-preview-customtools",5928   "gemini-3.1-flash-lite",5929   "gemini-3.1-flash-lite-preview",5930   "gemini-3-flash-preview",5931   "gemini-3-pro-preview",5932   "gemini-2.5-pro",5933   "gemini-2.5-flash",5934   "gemini-2.5-flash-lite",5935   "gemini-robotics-er-2-preview",5936   "gemini-robotics-er-1.6-preview"5937  ],5938  "compatible_endpoints": [5939   "POST /v1beta/models/{model}:generateContent",5940   "POST /v1beta/models/{model}:streamGenerateContent",5941   "POST /v1beta/interactions (as `{\"type\":\"url_context\"}`)"5942  ],5943  "parameters_schema": {5944   "type": "object",5945   "description": "tools[].urlContext — empty object, no configurable fields",5946   "properties": {}5947  },5948  "tool_choice_support": "none",5949  "parallel": "up to 20 URLs per request; combinable with googleSearch, codeExecution, functionDeclarations (Gemini 3)",5950  "streaming_events": [5951   "urlContextMetadata on candidates",5952   "toolCall {toolType:URL_CONTEXT,args:{urls[]}} / toolResponse {response:{urls_metadata:[{retrieved_url,url_retrieval_status}]}} with includeServerSideToolInvocations"5953  ],5954  "result_shape": {5955   "candidates[].urlContextMetadata": {5956    "urlMetadata": [5957     {5958      "retrievedUrl": "https://...",5959      "urlRetrievalStatus": "URL_RETRIEVAL_STATUS_SUCCESS"5960     }5961    ]5962   },5963   "usageMetadata": {5964    "toolUsePromptTokenCount": 10309,5965    "toolUsePromptTokensDetails": [5966     {5967      "modality": "TEXT",5968      "tokenCount": 103095969     }5970    ]5971   }5972  },5973  "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.",5974  "limitations": [5975   "Max 20 URLs per request",5976   "Max 34 MB of content per URL",5977   "URLs must be public: no localhost/private networks/tunnels (ngrok, pinggy), no paywalls or logins",5978   "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",5979   "Unsupported: paywalled content, YouTube videos, Google Workspace files (Docs/Sheets), video and audio files",5980   "Only the given URLs are read (no nested links)",5981   "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",5982   "Not combinable with fileSearch; not available in the Live API"5983  ],5984  "security": "Content moderation check on each URL; unsafe URLs return URL_RETRIEVAL_STATUS_UNSAFE. Treat fetched content as untrusted (prompt-injection risk).",5985  "beta_header": null,5986  "status": [5987   "DOCUMENTED",5988   "GA",5989   "LIVE_VERIFIED"5990  ],5991  "examples": {5992   "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\": {}}]}'",5993   "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)",5994   "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));"5995  },5996  "verification": {5997   "method": "live_api",5998   "verified_at": "2026-09-18",5999   "result": "success",6000   "http_status": 200,6001   "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)"6002  },6003  "sources": [6004   {6005    "url": "https://ai.google.dev/gemini-api/docs/url-context",6006    "retrieved_at": "2026-09-18"6007   },6008   {6009    "url": "https://ai.google.dev/gemini-api/docs/generate-content/url-context",6010    "retrieved_at": "2026-09-18"6011   },6012   {6013    "url": "https://ai.google.dev/api/generate-content#UrlContext",6014    "retrieved_at": "2026-09-18"6015   },6016   {6017    "url": "https://ai.google.dev/api/generate-content#UrlContextMetadata",6018    "retrieved_at": "2026-09-18"6019   },6020   {6021    "url": "https://ai.google.dev/gemini-api/docs/pricing",6022    "retrieved_at": "2026-09-18"6023   },6024   {6025    "url": "https://ai.google.dev/gemini-api/docs/changelog",6026    "retrieved_at": "2026-09-18"6027   }6028  ],6029  "_fragment": "generated/fragments/tools/gemini-tools.json"6030 },6031 {6032  "provider": "gemini",6033  "name": "Code execution",6034  "type": "codeExecution",6035  "category": "server",6036  "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).",6037  "compatible_models": [6038   "gemini-3.8-flash",6039   "gemini-3.7-flash",6040   "gemini-3.6-flash",6041   "gemini-3.5-flash",6042   "gemini-3.5-flash-lite",6043   "gemini-3.1-pro-preview",6044   "gemini-3.1-pro-preview-customtools",6045   "gemini-3.1-flash-lite",6046   "gemini-3.1-flash-lite-preview",6047   "gemini-3-flash-preview",6048   "gemini-3-pro-preview",6049   "gemini-2.5-pro",6050   "gemini-2.5-flash",6051   "gemini-2.5-flash-lite",6052   "gemini-robotics-er-2-preview",6053   "gemini-robotics-er-1.6-preview",6054   "gemini-2.0-flash (RETIRED 2026-06-01)"6055  ],6056  "compatible_endpoints": [6057   "POST /v1beta/models/{model}:generateContent",6058   "POST /v1beta/models/{model}:streamGenerateContent",6059   "POST /v1beta/interactions (as `{\"type\":\"code_execution\"}`)",6060   "POST /v1beta/models/{model}:batchGenerateContent"6061  ],6062  "parameters_schema": {6063   "type": "object",6064   "description": "tools[].codeExecution — empty object, no configurable fields",6065   "properties": {}6066  },6067  "tool_choice_support": "none (model decides). Prompt explicitly ('write code to ...') for non-obvious uses.",6068  "parallel": "iterative: several executableCode/codeExecutionResult pairs per response; combinable with googleSearch and (Gemini 3) function calling",6069  "streaming_events": [6070   "streamGenerateContent chunks carry executableCode, codeExecutionResult, inlineData (image/png) and text parts as they are produced",6071   "In multi-turn use, echo executableCode/codeExecutionResult parts (with id and thoughtSignature) back in history"6072  ],6073  "result_shape": {6074   "parts": [6075    {6076     "executableCode": {6077      "language": "PYTHON",6078      "code": "print(sum(range(1,51)))",6079      "id": "opt"6080     },6081     "thoughtSignature": "..."6082    },6083    {6084     "codeExecutionResult": {6085      "outcome": "OUTCOME_OK",6086      "output": "1275\n",6087      "id": "opt"6088     }6089    },6090    {6091     "inlineData": {6092      "mimeType": "image/png",6093      "data": "<base64 matplotlib figure>"6094     }6095    },6096    {6097     "text": "The sum is 1275."6098    }6099   ]6100  },6101  "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.",6102  "limitations": [6103   "Python only (≥3.10); other languages can be generated but not run",6104   "Max runtime 30 s per execution; up to 5 automatic retries on error",6105   "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",6106   "Only matplotlib renders graphs; output files always returned as part.inlineData",6107   "Input file size bounded by the model context window (AI Studio: ~1M tokens ≈ 2 MB text)",6108   "Cannot return other artifacts (media files) beyond images",6109   "May regress other output quality (e.g. creative writing); model-dependent reliability",6110   "Not supported in the Live API; not combinable with fileSearch"6111  ],6112  "security": "Code runs in Google's sandbox, not on your machine; no network/library installation. Treat outputs as model-generated.",6113  "beta_header": null,6114  "status": [6115   "DOCUMENTED",6116   "LIVE_VERIFIED"6117  ],6118  "examples": {6119   "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\": {}}]}'",6120   "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)",6121   "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));"6122  },6123  "verification": {6124   "method": "live_api",6125   "verified_at": "2026-09-18",6126   "result": "success",6127   "http_status": 200,6128   "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)"6129  },6130  "sources": [6131   {6132    "url": "https://ai.google.dev/gemini-api/docs/code-execution",6133    "retrieved_at": "2026-09-18"6134   },6135   {6136    "url": "https://ai.google.dev/gemini-api/docs/generate-content/code-execution",6137    "retrieved_at": "2026-09-18"6138   },6139   {6140    "url": "https://ai.google.dev/api/generate-content#CodeExecution",6141    "retrieved_at": "2026-09-18"6142   },6143   {6144    "url": "https://ai.google.dev/api/generate-content#ExecutableCode",6145    "retrieved_at": "2026-09-18"6146   },6147   {6148    "url": "https://ai.google.dev/api/generate-content#CodeExecutionResult",6149    "retrieved_at": "2026-09-18"6150   },6151   {6152    "url": "https://ai.google.dev/gemini-api/docs/pricing",6153    "retrieved_at": "2026-09-18"6154   }6155  ],6156  "_fragment": "generated/fragments/tools/gemini-tools.json"6157 },6158 {6159  "provider": "gemini",6160  "name": "Computer Use (Preview)",6161  "type": "computerUse",6162  "category": "client",6163  "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.",6164  "compatible_models": [6165   "gemini-3.8-flash (recommended)",6166   "gemini-3.7-flash",6167   "gemini-3.6-flash (model page: Supported (Preview))",6168   "gemini-3.5-flash",6169   "gemini-3.5-flash-lite",6170   "gemini-3-flash-preview",6171   "gemini-2.5-computer-use-preview-10-2025 (legacy, browser only)",6172   "gemini-robotics-er-2-preview",6173   "gemini-robotics-er-1.6-preview"6174  ],6175  "compatible_endpoints": [6176   "POST /v1beta/models/{model}:generateContent",6177   "POST /v1beta/models/{model}:streamGenerateContent",6178   "POST /v1beta/interactions (as `{\"type\":\"computer_use\"}`)"6179  ],6180  "parameters_schema": {6181   "type": "object",6182   "required": [6183    "environment"6184   ],6185   "properties": {6186    "environment": {6187     "type": "string",6188     "enum": [6189      "ENVIRONMENT_UNSPECIFIED",6190      "ENVIRONMENT_BROWSER",6191      "ENVIRONMENT_MOBILE",6192      "ENVIRONMENT_DESKTOP"6193     ],6194     "description": "Required. UNSPECIFIED defaults to browser. Mobile/desktop: Gemini 3.x only."6195    },6196    "excludedPredefinedFunctions": {6197     "type": "array<string>",6198     "description": "Predefined action names to drop (restrict action space or override with your own declaration)."6199    },6200    "enablePromptInjectionDetection": {6201     "type": "boolean",6202     "default": false,6203     "description": "Gemini 3.5 Flash+: scan screenshots for hidden adversarial instructions and block execution when detected."6204    },6205    "disabledSafetyPolicies": {6206     "type": "array<enum>",6207     "enum": [6208      "FINANCIAL_TRANSACTIONS",6209      "SENSITIVE_DATA_MODIFICATION",6210      "COMMUNICATION_TOOL",6211      "ACCOUNT_CREATION",6212      "DATA_MODIFICATION",6213      "USER_CONSENT_MANAGEMENT",6214      "LEGAL_TERMS_AND_AGREEMENTS"6215     ],6216     "description": "Gemini 3.x safety policy categories to disable (overrides are preferences; require_confirmation may still be returned)."6217    }6218   },6219   "companion": "Add extra tools[].functionDeclarations for custom actions; generationConfig.thinkingConfig.thinkingLevel to trade speed vs accuracy (Gemini 3.x)."6220  },6221  "tool_choice_support": "Predefined functions behave like function declarations; functionCallingConfig applies (not documented specifically). excludedPredefinedFunctions restricts the set.",6222  "parallel": "Typically one action per step; the loop repeats until the task ends. Multiple functionCall parts may occur.",6223  "streaming_events": [6224   "functionCall parts in generateContent/streamGenerateContent chunks (Gemini 3.x args include intent; may include safety_decision)",6225   "Client returns functionResponse with screenshot (inlineData image/png) + current url"6226  ],6227  "result_shape": {6228   "gemini_3x": {6229    "functionCall": {6230     "name": "click",6231     "args": {6232      "x": 450,6233      "y": 120,6234      "intent": "Click the search box"6235     }6236    }6237   },6238   "legacy_2_5": {6239    "functionCall": {6240     "name": "type_text_at",6241     "args": {6242      "x": 371,6243      "y": 470,6244      "text": "...",6245      "press_enter": true6246     }6247    }6248   },6249   "safety": {6250    "functionCall": {6251     "name": "click_at",6252     "args": {6253      "x": 60,6254      "y": 100,6255      "safety_decision": {6256       "decision": "require_confirmation",6257       "explanation": "Must check check-box"6258      }6259     }6260    }6261   },6262   "functionResponse (you)": {6263    "name": "click",6264    "id": "<functionCall.id>",6265    "response": {6266     "url": "https://...",6267     "safety_acknowledgement": true6268    },6269    "parts": [6270     {6271      "inlineData": {6272       "mimeType": "image/png",6273       "data": "<screenshot>"6274      }6275     }6276    ]6277   },6278   "action_catalogue": {6279    "browser": [6280     "click",6281     "double_click",6282     "triple_click",6283     "middle_click",6284     "right_click",6285     "mouse_down",6286     "mouse_up",6287     "move",6288     "type",6289     "drag_and_drop",6290     "wait",6291     "press_key",6292     "key_down",6293     "key_up",6294     "hotkey",6295     "take_screenshot",6296     "scroll",6297     "go_back",6298     "navigate",6299     "go_forward"6300    ],6301    "mobile": [6302     "open_app",6303     "click",6304     "list_apps",6305     "wait",6306     "go_back",6307     "type",6308     "drag_and_drop",6309     "long_press",6310     "press_key",6311     "take_screenshot"6312    ],6313    "desktop": [6314     "click",6315     "double_click",6316     "triple_click",6317     "middle_click",6318     "right_click",6319     "mouse_down",6320     "mouse_up",6321     "move",6322     "type",6323     "drag_and_drop",6324     "wait",6325     "press_key",6326     "key_down",6327     "key_up",6328     "hotkey",6329     "take_screenshot",6330     "scroll"6331    ],6332    "legacy_2_5": [6333     "open_web_browser",6334     "wait_5_seconds",6335     "go_back",6336     "go_forward",6337     "search",6338     "navigate",6339     "click_at",6340     "hover_at",6341     "type_text_at",6342     "key_combination",6343     "scroll_document",6344     "scroll_at",6345     "drag_and_drop"6346    ]6347   }6348  },6349  "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.",6350  "limitations": [6351   "Preview: may contain errors and security vulnerabilities; avoid critical decisions/sensitive data",6352   "Coordinates normalized 0-999 — client must scale to viewport; no need to send display size",6353   "Legacy 2.5 model: browser only, 128k input / 64k output, image+text input",6354   "gemini-3-pro-preview model page: Computer use 'Not supported' (changelog 2025 said launched) — conflicting docs",6355   "Not in Live API",6356   "Safety overrides are preferences; always implement safety_decision handling"6357  ],6358  "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.",6359  "beta_header": null,6360  "status": [6361   "DOCUMENTED",6362   "PREVIEW",6363   "ACCOUNT_RESTRICTED"6364  ],6365  "examples": {6366   "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\"}}]}'",6367   "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)",6368   "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));"6369  },6370  "verification": {6371   "method": "live_api",6372   "verified_at": "2026-09-18",6373   "result": "restricted",6374   "http_status": 429,6375   "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)"6376  },6377  "sources": [6378   {6379    "url": "https://ai.google.dev/gemini-api/docs/computer-use",6380    "retrieved_at": "2026-09-18"6381   },6382   {6383    "url": "https://ai.google.dev/gemini-api/docs/generate-content/computer-use",6384    "retrieved_at": "2026-09-18"6385   },6386   {6387    "url": "https://ai.google.dev/api/generate-content#ComputerUse",6388    "retrieved_at": "2026-09-18"6389   },6390   {6391    "url": "https://ai.google.dev/gemini-api/docs/models/gemini-2.5-computer-use-preview-10-2025",6392    "retrieved_at": "2026-09-18"6393   },6394   {6395    "url": "https://ai.google.dev/gemini-api/docs/pricing",6396    "retrieved_at": "2026-09-18"6397   },6398   {6399    "url": "https://ai.google.dev/gemini-api/docs/changelog",6400    "retrieved_at": "2026-09-18"6401   }6402  ],6403  "_fragment": "generated/fragments/tools/gemini-tools.json"6404 },6405 {6406  "provider": "gemini",6407  "name": "File Search (managed RAG)",6408  "type": "fileSearch",6409  "category": "server",6410  "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.",6411  "compatible_models": [6412   "gemini-3.8-flash",6413   "gemini-3.7-flash",6414   "gemini-3.6-flash",6415   "gemini-3.5-flash",6416   "gemini-3.5-flash-lite",6417   "gemini-3.1-pro-preview (model page: 'Supported (AI Studio only)')",6418   "gemini-3.1-flash-lite",6419   "gemini-3.1-flash-lite-preview",6420   "gemini-3-flash-preview",6421   "gemini-3-pro-preview (model page)",6422   "gemini-2.5-pro",6423   "gemini-2.5-flash-lite",6424   "gemini-2.5-flash (model page: Supported; absent from the File Search guide table)",6425   "gemini-robotics-er-2-preview",6426   "gemini-robotics-er-1.6-preview"6427  ],6428  "compatible_endpoints": [6429   "POST /v1beta/models/{model}:generateContent",6430   "POST /v1beta/models/{model}:streamGenerateContent",6431   "POST /v1beta/interactions (as `{\"type\":\"file_search\",\"file_search_store_names\":[...]}`; also a Deep Research agent tool)",6432   "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)"6433  ],6434  "parameters_schema": {6435   "type": "object",6436   "required": [6437    "fileSearchStoreNames"6438   ],6439   "properties": {6440    "fileSearchStoreNames": {6441     "type": "array<string>",6442     "description": "Store resource names, e.g. fileSearchStores/my-store-123a456b789c"6443    },6444    "metadataFilter": {6445     "type": "string",6446     "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)."6447    },6448    "topK": {6449     "type": "integer",6450     "description": "Number of semantic retrieval chunks to retrieve (REST reference/discovery only; not in the guide)."6451    }6452   }6453  },6454  "tool_choice_support": "none (server decides when to retrieve)",6455  "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",6456  "streaming_events": [6457   "groundingMetadata on candidates (retrievedContext chunks; accumulate across stream chunks)",6458   "toolCall {toolType:FILE_SEARCH} / toolResponse parts with includeServerSideToolInvocations (no user-visible args)"6459  ],6460  "result_shape": {6461   "groundingMetadata": {6462    "groundingChunks": [6463     {6464      "retrievedContext": {6465       "title": "sample.txt",6466       "uri": "...",6467       "text": "chunk text",6468       "fileSearchStore": "fileSearchStores/my-store-123",6469       "pageNumber": 3,6470       "mediaId": "fileSearchStores/my-store-123/media/BlobId-456",6471       "customMetadata": [6472        {6473         "key": "author",6474         "stringValue": "Robert Graves"6475        },6476        {6477         "key": "year",6478         "numericValue": 19346479        }6480       ]6481      }6482     }6483    ],6484    "groundingSupports": [6485     {6486      "segment": {6487       "startIndex": 0,6488       "endIndex": 50,6489       "text": "..."6490      },6491      "groundingChunkIndices": [6492       06493      ]6494     }6495    ]6496   }6497  },6498  "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.",6499  "limitations": [6500   "Max 100 MB per file/document (discovery mediaUpload maxSize 104857600)",6501   "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",6502   "Not supported in the Live API",6503   "Cannot be combined with Google Search, URL context, etc. (guide)",6504   "Audio/video not supported; images (PNG/JPEG ≤ 4K×4K) only with embeddingModel models/gemini-embedding-2 set at store creation",6505   "Max 20 customMetadata per Document; displayName ≤ 512 chars; store id ≤ 40 chars derived from displayName + 12-char suffix; store names are globally scoped",6506   "Chunking: whiteSpaceConfig.maxTokensPerChunk (words; ≤ 512 recommended) / maxOverlapTokens",6507   "Delete a store/document containing documents/chunks requires ?force=true (else FAILED_PRECONDITION)"6508  ],6509  "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.",6510  "beta_header": null,6511  "status": [6512   "DOCUMENTED",6513   "PREVIEW",6514   "LIVE_VERIFIED"6515  ],6516  "examples": {6517   "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\\\"\"}}]}'",6518   "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)",6519   "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));"6520  },6521  "verification": {6522   "method": "live_api",6523   "verified_at": "2026-09-18",6524   "result": "success",6525   "http_status": 200,6526   "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)"6527  },6528  "sources": [6529   {6530    "url": "https://ai.google.dev/gemini-api/docs/file-search",6531    "retrieved_at": "2026-09-18"6532   },6533   {6534    "url": "https://ai.google.dev/gemini-api/docs/generate-content/file-search",6535    "retrieved_at": "2026-09-18"6536   },6537   {6538    "url": "https://ai.google.dev/api/file-search/file-search-stores",6539    "retrieved_at": "2026-09-18"6540   },6541   {6542    "url": "https://ai.google.dev/api/file-search/documents",6543    "retrieved_at": "2026-09-18"6544   },6545   {6546    "url": "https://ai.google.dev/api/generate-content#FileSearch",6547    "retrieved_at": "2026-09-18"6548   },6549   {6550    "url": "https://ai.google.dev/api/generate-content#RetrievedContext",6551    "retrieved_at": "2026-09-18"6552   },6553   {6554    "url": "https://ai.google.dev/gemini-api/docs/pricing",6555    "retrieved_at": "2026-09-18"6556   },6557   {6558    "url": "https://ai.google.dev/gemini-api/docs/changelog",6559    "retrieved_at": "2026-09-18"6560   }6561  ],6562  "_fragment": "generated/fragments/tools/gemini-tools.json"6563 },6564 {6565  "provider": "gemini",6566  "name": "Remote MCP servers (server-side, tools[].mcpServers)",6567  "type": "mcpServers",6568  "category": "mcp",6569  "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).",6570  "compatible_models": "UNVERIFIED for generateContent; Interactions API mcp_server: Gemini 3 models (examples use gemini-3.8-flash) and deep-research-* agents",6571  "compatible_endpoints": [6572   "POST /v1beta/models/{model}:generateContent (schema only — UNVERIFIED)",6573   "POST /v1beta/interactions (documented: type mcp_server)"6574  ],6575  "parameters_schema": {6576   "type": "array",6577   "items": {6578    "type": "object",6579    "properties": {6580     "name": {6581      "type": "string"6582     },6583     "streamableHttpTransport": {6584      "type": "object",6585      "properties": {6586       "url": {6587        "type": "string",6588        "description": "Full MCP endpoint URL, e.g. https://api.example.com/mcp"6589       },6590       "headers": {6591        "type": "object (map<string,string>)",6592        "description": "auth headers etc."6593       },6594       "timeout": {6595        "type": "string (duration, e.g. '3.5s')"6596       },6597       "sseReadTimeout": {6598        "type": "string (duration)"6599       },6600       "terminateOnClose": {6601        "type": "boolean"6602       }6603      }6604     }6605    }6606   },6607   "interactions_twin": {6608    "type": "mcp_server",6609    "name": "string (no '-')",6610    "url": "string",6611    "headers": "object",6612    "allowed_tools": "array<string>"6613   }6614  },6615  "tool_choice_support": "UNVERIFIED",6616  "parallel": "UNVERIFIED",6617  "streaming_events": [6618   "UNVERIFIED for generateContent; Interactions API returns mcp tool call/result steps"6619  ],6620  "result_shape": "UNVERIFIED (Interactions: function_call/function_result-style steps for MCP tools)",6621  "billing": "Not documented (tokens of tool schemas/results presumably billed as input; UNVERIFIED).",6622  "limitations": [6623   "Streamable HTTP transport only (no SSE) — Interactions docs",6624   "Server names must not contain '-'",6625   "No generateContent guide coverage"6626  ],6627  "security": "Remote servers receive your headers (tokens) from Google's side; only connect to trusted servers.",6628  "beta_header": null,6629  "status": [6630   "DOCUMENTED",6631   "DOCUMENTATION_INCOMPLETE",6632   "UNVERIFIED"6633  ],6634  "examples": {6635   "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\"}}]}]}'",6636   "python": "types.Tool(mcp_servers=[types.McpServer(name='weather', streamable_http_transport=types.StreamableHttpTransport(url='https://example.com/mcp'))])  # UNVERIFIED on generateContent",6637   "typescript": "// Interactions API (documented): tools: [{ type: 'mcp_server', name: 'weather', url: 'https://example.com/mcp' }]"6638  },6639  "verification": {6640   "method": "docs_only",6641   "verified_at": "2026-09-18",6642   "result": "not_tested",6643   "http_status": null,6644   "request_note": "not exercised in the 2026-09-18 run (docs only)"6645  },6646  "sources": [6647   {6648    "url": "https://ai.google.dev/api/generate-content#McpServer",6649    "retrieved_at": "2026-09-18"6650   },6651   {6652    "url": "https://ai.google.dev/api/generate-content#StreamableHttpTransport",6653    "retrieved_at": "2026-09-18"6654   },6655   {6656    "url": "https://ai.google.dev/gemini-api/docs/function-calling",6657    "retrieved_at": "2026-09-18"6658   },6659   {6660    "url": "https://ai.google.dev/gemini-api/docs/deep-research",6661    "retrieved_at": "2026-09-18"6662   },6663   {6664    "url": "https://github.com/googleapis/python-genai (README: MCP for Gemini Enterprise Agent Platform)",6665    "retrieved_at": "2026-09-18"6666   }6667  ],6668  "_fragment": "generated/fragments/tools/gemini-tools.json"6669 },6670 {6671  "provider": "gemini",6672  "name": "MCP via SDK (client-side automatic tool calling)",6673  "type": "mcp (SDK-side)",6674  "category": "mcp",6675  "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.",6676  "compatible_models": "Any model with function calling (examples use gemini-3.8-flash / gemini-2.5-flash).",6677  "compatible_endpoints": [6678   "POST /v1beta/models/{model}:generateContent (SDK wraps it)",6679   "POST /v1beta/models/{model}:streamGenerateContent (stream variants)",6680   "SDK Chats (AFC is moving to Chats in the next major SDK version per README)"6681  ],6682  "parameters_schema": {6683   "python": {6684    "config.tools": "[ClientSession, ...] or python callables",6685    "config.automatic_function_calling": {6686     "disable": "bool",6687     "maximum_remote_calls": "int (default 10)",6688     "ignore_call_history": "bool"6689    }6690   },6691   "javascript": {6692    "config.tools": "[mcpToTool(client, ...)]",6693    "config.automaticFunctionCalling": {6694     "disable": "bool",6695     "maximumRemoteCalls": "int"6696    }6697   }6698  },6699  "tool_choice_support": "functionCallingConfig applies as for any declarations (AFC also runs in ANY mode; disable to stop the loop).",6700  "parallel": "AFC executes parallel functionCalls sequentially/asynchronously per SDK; response.automatic_function_calling_history keeps the trace (Python).",6701  "streaming_events": [6702   "SDK-level only; stream variants supported by AFC in current versions (README warns this moves to Chats)"6703  ],6704  "result_shape": "Final GenerateContentResponse.text after the loop; Python: response.automatic_function_calling_history[] with the intermediate Content objects.",6705  "billing": "Ordinary token billing per model turn; each AFC round trip is a new generateContent request.",6706  "limitations": [6707   "Experimental; breaking changes possible",6708   "Only MCP tools (no resources, no prompts)",6709   "Python and JS/TS SDKs only",6710   "Python AFC 'currently doesn't parse argument descriptions' into property descriptions — whole docstring becomes the function description (for callables)",6711   "Live API: no automatic tool response handling"6712  ],6713  "security": "The MCP server runs where your SDK runs (stdio/local or remote transport you choose); credentials never reach Google.",6714  "beta_header": null,6715  "status": [6716   "DOCUMENTED",6717   "BETA"6718  ],6719  "examples": {6720   "curl": "n/a — SDK-only feature (wire format is plain functionDeclarations)",6721   "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())",6722   "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();"6723  },6724  "verification": {6725   "method": "docs_only",6726   "verified_at": "2026-09-18",6727   "result": "not_tested",6728   "http_status": null,6729   "request_note": "not exercised in the 2026-09-18 run (docs only)"6730  },6731  "sources": [6732   {6733    "url": "https://ai.google.dev/gemini-api/docs/generate-content/function-calling",6734    "retrieved_at": "2026-09-18"6735   },6736   {6737    "url": "https://github.com/googleapis/python-genai",6738    "retrieved_at": "2026-09-18"6739   },6740   {6741    "url": "https://github.com/googleapis/js-genai",6742    "retrieved_at": "2026-09-18"6743   }6744  ],6745  "_fragment": "generated/fragments/tools/gemini-tools.json"6746 },6747 {6748  "provider": "openai",6749  "name": "Function calling (custom function tool)",6750  "type": "function",6751  "category": "client",6752  "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.",6753  "compatible_models": [6754   "chat-latest",6755   "gpt-4.1",6756   "gpt-4.1-mini",6757   "gpt-4.1-nano",6758   "gpt-4o",6759   "gpt-4o-mini",6760   "gpt-5",6761   "gpt-5-chat-latest",6762   "gpt-5-codex",6763   "gpt-5-mini",6764   "gpt-5-nano",6765   "gpt-5-pro",6766   "gpt-5.1",6767   "gpt-5.1-chat-latest",6768   "gpt-5.1-codex",6769   "gpt-5.1-codex-max",6770   "gpt-5.1-codex-mini",6771   "gpt-5.2",6772   "gpt-5.2-chat-latest",6773   "gpt-5.2-codex",6774   "gpt-5.2-pro",6775   "gpt-5.3-chat-latest",6776   "gpt-5.3-codex",6777   "gpt-5.4",6778   "gpt-5.4-mini",6779   "gpt-5.4-nano",6780   "gpt-5.4-pro",6781   "gpt-5.5",6782   "gpt-5.5-pro",6783   "gpt-audio-mini",6784   "gpt-oss-120b",6785   "gpt-oss-20b",6786   "o1",6787   "o1-pro",6788   "o3",6789   "o3-mini",6790   "o3-pro",6791   "o4-mini"6792  ],6793  "compatible_endpoints": [6794   "POST /v1/responses",6795   "POST /v1/chat/completions",6796   "POST /v1/realtime (session.tools)",6797   "Agents API (agent tool config)"6798  ],6799  "parameters_schema": {6800   "properties": {6801    "type": {6802     "type": "string",6803     "enum": [6804      "function"6805     ],6806     "description": "The type of the function tool. Always `function`.",6807     "default": "function",6808     "x-stainless-const": true6809    },6810    "name": {6811     "type": "string",6812     "description": "The name of the function to call."6813    },6814    "async": {6815     "type": "boolean"6816    },6817    "description": {6818     "anyOf": [6819      {6820       "type": "string",6821       "description": "A description of the function. Used by the model to determine whether or not to call the function."6822      },6823      {6824       "type": "null"6825      }6826     ]6827    },6828    "parameters": {6829     "anyOf": [6830      {6831       "additionalProperties": {},6832       "type": "object",6833       "description": "A JSON schema object describing the parameters of the function."6834      },6835      {6836       "type": "null"6837      }6838     ]6839    },6840    "output_schema": {6841     "anyOf": [6842      {6843       "additionalProperties": {},6844       "type": "object",6845       "description": "A JSON schema object describing the JSON value encoded in string outputs for this function."6846      },6847      {6848       "type": "null"6849      }6850     ]6851    },6852    "strict": {6853     "anyOf": [6854      {6855       "type": "boolean",6856       "description": "Whether strict parameter validation is enforced for this function tool."6857      },6858      {6859       "type": "null"6860      }6861     ]6862    },6863    "defer_loading": {6864     "type": "boolean",6865     "description": "Whether this function is deferred and loaded via tool search."6866    },6867    "allowed_callers": {6868     "anyOf": [6869      {6870       "items": {6871        "type": "string",6872        "enum": [6873         "direct",6874         "programmatic"6875        ]6876       },6877       "type": "array",6878       "description": "The tool invocation context(s)."6879      },6880      {6881       "type": "null"6882      }6883     ]6884    }6885   },6886   "type": "object",6887   "required": [6888    "type",6889    "name",6890    "strict",6891    "parameters"6892   ],6893   "title": "Function",6894   "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)."6895  },6896  "tool_choice_support": {6897   "modes": [6898    "none",6899    "auto",6900    "required"6901   ],6902   "allowed_tools": {6903    "type": "allowed_tools",6904    "mode": "auto|required",6905    "tools": [6906     "{type,name,...}"6907    ]6908   },6909   "specific": {6910    "type": "function",6911    "name": "<fn>"6912   },6913   "chat_completions": {6914    "type": "function",6915    "function": {6916     "name": "<fn>"6917    }6918   }6919  },6920  "parallel": {6921   "supported": true,6922   "parameter": "parallel_tool_calls (default true)",6923   "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."6924  },6925  "streaming_events": [6926   "response.output_item.added",6927   "response.function_call_arguments.delta",6928   "response.function_call_arguments.done",6929   "response.output_item.done"6930  ],6931  "result_shape": {6932   "items": [6933    {6934     "schema_name": "FunctionToolCall",6935     "type": "function_call",6936     "schema": {6937      "type": "object",6938      "title": "Function tool call",6939      "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",6940      "properties": {6941       "id": {6942        "type": "string",6943        "description": "The unique ID of the function tool call.\n"6944       },6945       "type": {6946        "type": "string",6947        "enum": [6948         "function_call"6949        ],6950        "description": "The type of the function tool call. Always `function_call`.\n",6951        "x-stainless-const": true6952       },6953       "call_id": {6954        "type": "string",6955        "description": "The unique ID of the function tool call generated by the model.\n"6956       },6957       "caller": {6958        "anyOf": [6959         {6960          "oneOf": [6961           {6962            "properties": {6963             "type": {6964              "type": "string",6965              "enum": [6966               "direct"6967              ],6968              "default": "direct",6969              "x-stainless-const": true6970             }6971            },6972            "type": "object",6973            "required": [6974             "type"6975            ]6976           },6977           {6978            "properties": {6979             "type": {6980              "type": "string",6981              "enum": [6982               "program"6983              ],6984              "default": "program",6985              "x-stainless-const": true6986             },6987             "caller_id": {6988              "type": "string",6989              "description": "The call ID of the program item that produced this tool call."6990             }6991            },6992            "type": "object",6993            "required": [6994             "type",6995             "caller_id"6996            ]6997           }6998          ],6999          "description": "The execution context that produced this tool call.",7000          "discriminator": {7001           "propertyName": "type"7002          }7003         },7004         {7005          "type": "null"7006         }7007        ]7008       },7009       "namespace": {7010        "type": "string",7011        "description": "The namespace of the function to run.\n"7012       },7013       "name": {7014        "type": "string",7015        "description": "The name of the function to run.\n"7016       },7017       "arguments": {7018        "type": "string",7019        "description": "A JSON string of the arguments to pass to the function.\n"7020       },7021       "status": {7022        "type": "string",7023        "description": "The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.\n",7024        "enum": [7025         "in_progress",7026         "completed",7027         "incomplete"7028        ]7029       },7030       "async": {7031        "type": "boolean",7032        "description": "Whether the function tool call runs asynchronously.\n"7033       }7034      },7035      "required": [7036       "type",7037       "call_id",7038       "name",7039       "arguments"7040      ]7041     }7042    },7043    {7044     "schema_name": "FunctionCallOutputItemParam",7045     "type": "function_call_output",7046     "schema": {7047      "properties": {7048       "id": {7049        "anyOf": [7050         {7051          "type": "string",7052          "description": "The unique ID of the function tool call output. Populated when this item is returned via API.",7053          "example": "fc_123"7054         },7055         {7056          "type": "null"7057         }7058        ]7059       },7060       "call_id": {7061        "anyOf": [7062         {7063          "type": "string",7064          "maxLength": 64,7065          "minLength": 1,7066          "description": "The unique ID of the function tool call generated by the model."7067         },7068         {7069          "type": "null"7070         }7071        ]7072       },7073       "type": {7074        "type": "string",7075        "enum": [7076         "function_call_output"7077        ],7078        "description": "The type of the function tool call output. Always `function_call_output`.",7079        "default": "function_call_output",7080        "x-stainless-const": true7081       },7082       "output": {7083        "oneOf": [7084         {7085          "type": "string",7086          "maxLength": 10485760,7087          "description": "A JSON string of the output of the function tool call."7088         },7089         {7090          "items": {7091           "oneOf": [7092            {7093             "properties": {7094              "type": {7095               "type": "string",7096               "enum": [7097                "input_text"7098               ],7099               "description": "The type of the input item. Always `input_text`.",7100               "default": "input_text",7101               "x-stainless-const": true7102              },7103              "text": {7104               "type": "string",7105               "maxLength": 10485760,7106               "description": "The text input to the model."7107              },7108              "prompt_cache_breakpoint": {7109               "anyOf": [7110                {7111                 "properties": {7112                  "mode": {7113                   "$comment": "depth-limited"7114                  }7115                 },7116                 "type": "object",7117                 "required": [7118                  {7119                   "$comment": "depth-limited"7120                  }7121                 ],7122                 "title": "Prompt cache breakpoint",7123                 "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."7124                },7125                {7126                 "type": "null"7127                }7128               ]7129              }7130             },7131             "type": "object",7132             "required": [7133              "type",7134              "text"7135             ],7136             "title": "Input text",7137             "description": "A text input to the model."7138            },7139            {7140             "properties": {7141              "type": {7142               "type": "string",7143               "enum": [7144                "input_image"7145               ],7146               "description": "The type of the input item. Always `input_image`.",7147               "default": "input_image",7148               "x-stainless-const": true7149              },7150              "image_url": {7151               "anyOf": [7152                {7153                 "type": "string",7154                 "maxLength": 20971520,7155                 "format": "uri",7156                 "description": "The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL."7157                },7158                {7159                 "type": "null"7160                }7161               ]7162              },7163              "file_id": {7164               "anyOf": [7165                {7166                 "type": "string",7167                 "description": "The ID of the file to be sent to the model.",7168                 "example": "file-123"7169                },7170                {7171                 "type": "null"7172                }7173               ]7174              },7175              "detail": {7176               "anyOf": [7177                {7178                 "type": "string",7179                 "enum": [7180                  {7181                   "$comment": "depth-limited"7182                  },7183                  {7184                   "$comment": "depth-limited"7185                  },7186                  {7187                   "$comment": "depth-limited"7188                  },7189                  {7190                   "$comment": "depth-limited"7191                  }7192                 ]7193                },7194                {7195                 "type": "null"7196                }7197               ]7198              },7199              "prompt_cache_breakpoint": {7200               "anyOf": [7201                {7202                 "properties": {7203                  "mode": {7204                   "$comment": "depth-limited"7205                  }7206                 },7207                 "type": "object",7208                 "required": [7209                  {7210                   "$comment": "depth-limited"7211                  }7212                 ],7213                 "title": "Prompt cache breakpoint",7214                 "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."7215                },7216                {7217                 "type": "null"7218                }7219               ]7220              }7221             },7222             "type": "object",7223             "required": [7224              "type"7225             ],7226             "title": "Input image",7227             "description": "An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision)"7228            },7229            {7230             "properties": {7231              "type": {7232               "type": "string",7233               "enum": [7234                "input_file"7235               ],7236               "description": "The type of the input item. Always `input_file`.",7237               "default": "input_file",7238               "x-stainless-const": true7239              },7240              "file_id": {7241               "anyOf": [7242                {7243                 "type": "string",7244                 "description": "The ID of the file to be sent to the model.",7245                 "example": "file-123"7246                },7247                {7248                 "type": "null"7249                }7250               ]7251              },7252              "filename": {7253               "anyOf": [7254                {7255                 "type": "string",7256                 "description": "The name of the file to be sent to the model."7257                },7258                {7259                 "type": "null"7260                }7261               ]7262              },7263              "file_data": {7264               "anyOf": [7265                {7266                 "type": "string",7267                 "maxLength": 73400320,7268                 "description": "The base64-encoded data of the file to be sent to the model."7269                },7270                {7271                 "type": "null"7272                }7273               ]7274              },7275              "file_url": {7276               "anyOf": [7277                {7278                 "type": "string",7279                 "format": "uri",7280                 "description": "The URL of the file to be sent to the model."7281                },7282                {7283                 "type": "null"7284                }7285               ]7286              },7287              "detail": {7288               "type": "string",7289               "enum": [7290                "auto",7291                "low",7292                "high"7293               ]7294              },7295              "prompt_cache_breakpoint": {7296               "anyOf": [7297                {7298                 "properties": {7299                  "mode": {7300                   "$comment": "depth-limited"7301                  }7302                 },7303                 "type": "object",7304                 "required": [7305                  {7306                   "$comment": "depth-limited"7307                  }7308                 ],7309                 "title": "Prompt cache breakpoint",7310                 "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."7311                },7312                {7313                 "type": "null"7314                }7315               ]7316              }7317             },7318             "type": "object",7319             "required": [7320              "type"7321             ],7322             "title": "Input file",7323             "description": "A file input to the model."7324            }7325           ],7326           "description": "A piece of message content, such as text, an image, or a file.",7327           "discriminator": {7328            "propertyName": "type"7329           }7330          },7331          "type": "array",7332          "description": "An array of content outputs (text, image, file) for the function tool call."7333         }7334        ],7335        "description": "Text, image, or file output of the function tool call."7336       },7337       "name": {7338        "anyOf": [7339         {7340          "type": "string",7341          "maxLength": 128,7342          "minLength": 1,7343          "description": "The name of the tool that produced the output."7344         },7345         {7346          "type": "null"7347         }7348        ]7349       },7350       "namespace": {7351        "anyOf": [7352         {7353          "type": "string",7354          "maxLength": 64,7355          "minLength": 1,7356          "pattern": "^[a-zA-Z0-9_-]+$",7357          "description": "The namespace of the tool that produced the output."7358         },7359         {7360          "type": "null"7361         }7362        ]7363       },7364       "caller": {7365        "anyOf": [7366         {7367          "oneOf": [7368           {7369            "properties": {7370             "type": {7371              "type": "string",7372              "enum": [7373               "direct"7374              ],7375              "description": "The caller type. Always `direct`.",7376              "default": "direct",7377              "x-stainless-const": true7378             }7379            },7380            "type": "object",7381            "required": [7382             "type"7383            ]7384           },7385           {7386            "properties": {7387             "type": {7388              "type": "string",7389              "enum": [7390               "program"7391              ],7392              "description": "The caller type. Always `program`.",7393              "default": "program",7394              "x-stainless-const": true7395             },7396             "caller_id": {7397              "type": "string",7398              "maxLength": 64,7399              "minLength": 1,7400              "description": "The call ID of the program item that produced this tool call."7401             }7402            },7403            "type": "object",7404            "required": [7405             "type",7406             "caller_id"7407            ]7408           }7409          ],7410          "description": "The execution context that produced this tool call.",7411          "discriminator": {7412           "propertyName": "type"7413          }7414         },7415         {7416          "type": "null"7417         }7418        ]7419       },7420       "status": {7421        "anyOf": [7422         {7423          "type": "string",7424          "enum": [7425           "in_progress",7426           "completed",7427           "incomplete"7428          ]7429         },7430         {7431          "type": "null"7432         }7433        ]7434       }7435      },7436      "type": "object",7437      "required": [7438       "type",7439       "output"7440      ],7441      "title": "Function tool call output",7442      "description": "The output of a function tool call."7443     }7444    }7445   ],7446   "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}."7447  },7448  "billing": {7449   "model": "Function definitions are injected into the system message and billed as input tokens; call arguments are output tokens.",7450   "per_call": null,7451   "source": "https://developers.openai.com/api/docs/pricing#built-in-tools"7452  },7453  "limitations": [7454   "Strict mode requires all properties in `required`, `additionalProperties: false`, supported JSON Schema subset; strict schemas are cached and not eligible for ZDR.",7455   "Soft guidance: < 20 functions available at the start of a turn.",7456   "Chat Completions: `strict` defaults to false; Responses: omitted `strict` = best effort strict.",7457   "GPT-6 Astra requires the Responses API for tool calling."7458  ],7459  "security": [7460   "Validate arguments server-side (schema/regex) before executing; the model can be prompt-injected by tool outputs.",7461   "Reasoning items returned alongside tool calls must be passed back with the outputs (reasoning models)."7462  ],7463  "beta_header": null,7464  "status": [7465   "DOCUMENTED",7466   "LIVE_VERIFIED"7467  ],7468  "examples": {7469   "curl": "examples/openai/tools/function-calling/function_calling.sh",7470   "python": "examples/openai/tools/function-calling/function_calling.py",7471   "typescript": "examples/openai/tools/function-calling/function_calling.ts"7472  },7473  "verification": {7474   "forced_call": {7475    "method": "live_api",7476    "verified_at": "2026-09-18",7477    "result": "success",7478    "http_status": 200,7479    "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"7480   },7481   "streaming": {7482    "method": "live_api",7483    "verified_at": "2026-09-18",7484    "result": "success",7485    "http_status": 200,7486    "request_note": "response.output_item.added -> response.function_call_arguments.delta x N -> response.function_call_arguments.done -> response.output_item.done"7487   },7488   "strict_invalid_schema": {7489    "method": "live_api",7490    "verified_at": "2026-09-18",7491    "result": "success",7492    "http_status": 400,7493    "request_note": "missing additionalProperties:false -> 400 invalid_request_error code=invalid_function_parameters param=tools[0].parameters"7494   },7495   "allowed_tools": {7496    "method": "live_api",7497    "verified_at": "2026-09-18",7498    "result": "success",7499    "http_status": 200,7500    "request_note": "tool_choice {type:allowed_tools, mode:required, tools:[{type:function,name:get_weather}]} + parallel_tool_calls:false -> function_call"7501   },7502   "chat_completions": {7503    "method": "live_api",7504    "verified_at": "2026-09-18",7505    "result": "success",7506    "http_status": 200,7507    "request_note": "gpt-4.1-nano chat.completions tool_choice forced -> choices[0].message.tool_calls[0].function"7508   }7509  },7510  "sources": [7511   {7512    "url": "https://developers.openai.com/api/docs/guides/function-calling",7513    "retrieved_at": "2026-09-18"7514   },7515   {7516    "url": "https://developers.openai.com/api/docs/guides/async-tool-calling",7517    "retrieved_at": "2026-09-18"7518   },7519   {7520    "url": "https://developers.openai.com/api/reference/resources/responses/methods/create",7521    "retrieved_at": "2026-09-18"7522   },7523   {7524    "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)",7525    "retrieved_at": "2026-09-18"7526   }7527  ],7528  "last_verified": "2026-09-18",7529  "_fragment": "generated/fragments/tools/openai-tools.json"7530 },7531 {7532  "provider": "openai",7533  "name": "Custom tool (free-form text or CFG grammar)",7534  "type": "custom",7535  "category": "client",7536  "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).",7537  "compatible_models": [7538   "chat-latest",7539   "gpt-4.1",7540   "gpt-4.1-mini",7541   "gpt-4.1-nano",7542   "gpt-4o",7543   "gpt-4o-mini",7544   "gpt-5",7545   "gpt-5-chat-latest",7546   "gpt-5-codex",7547   "gpt-5-mini",7548   "gpt-5-nano",7549   "gpt-5-pro",7550   "gpt-5.1",7551   "gpt-5.1-chat-latest",7552   "gpt-5.1-codex",7553   "gpt-5.1-codex-max",7554   "gpt-5.1-codex-mini",7555   "gpt-5.2",7556   "gpt-5.2-chat-latest",7557   "gpt-5.2-codex",7558   "gpt-5.2-pro",7559   "gpt-5.3-chat-latest",7560   "gpt-5.3-codex",7561   "gpt-5.4",7562   "gpt-5.4-mini",7563   "gpt-5.4-nano",7564   "gpt-5.4-pro",7565   "gpt-5.5",7566   "gpt-5.5-pro",7567   "gpt-audio-mini",7568   "gpt-oss-120b",7569   "gpt-oss-20b",7570   "o1",7571   "o1-pro",7572   "o3",7573   "o3-mini",7574   "o3-pro",7575   "o4-mini"7576  ],7577  "compatible_endpoints": [7578   "POST /v1/responses",7579   "POST /v1/chat/completions"7580  ],7581  "parameters_schema": {7582   "properties": {7583    "type": {7584     "type": "string",7585     "enum": [7586      "custom"7587     ],7588     "description": "The type of the custom tool. Always `custom`.",7589     "default": "custom",7590     "x-stainless-const": true7591    },7592    "name": {7593     "type": "string",7594     "description": "The name of the custom tool, used to identify it in tool calls."7595    },7596    "async": {7597     "type": "boolean",7598     "description": "Whether the tool response can be returned asynchronously versus immediately returned on next response creation."7599    },7600    "description": {7601     "type": "string",7602     "description": "Optional description of the custom tool, used to provide more context."7603    },7604    "format": {7605     "oneOf": [7606      {7607       "properties": {7608        "type": {7609         "type": "string",7610         "enum": [7611          "text"7612         ],7613         "description": "Unconstrained text format. Always `text`.",7614         "default": "text",7615         "x-stainless-const": true7616        }7617       },7618       "type": "object",7619       "required": [7620        "type"7621       ],7622       "title": "Text format",7623       "description": "Unconstrained free-form text."7624      },7625      {7626       "properties": {7627        "type": {7628         "type": "string",7629         "enum": [7630          "grammar"7631         ],7632         "description": "Grammar format. Always `grammar`.",7633         "default": "grammar",7634         "x-stainless-const": true7635        },7636        "syntax": {7637         "type": "string",7638         "enum": [7639          "lark",7640          "regex"7641         ]7642        },7643        "definition": {7644         "type": "string",7645         "description": "The grammar definition."7646        }7647       },7648       "type": "object",7649       "required": [7650        "type",7651        "syntax",7652        "definition"7653       ],7654       "title": "Grammar format",7655       "description": "A grammar defined by the user."7656      }7657     ],7658     "description": "The input format for the custom tool. Default is unconstrained text.",7659     "discriminator": {7660      "propertyName": "type"7661     }7662    },7663    "defer_loading": {7664     "type": "boolean",7665     "description": "Whether this tool should be deferred and discovered via tool search."7666    },7667    "allowed_callers": {7668     "anyOf": [7669      {7670       "items": {7671        "type": "string",7672        "enum": [7673         "direct",7674         "programmatic"7675        ]7676       },7677       "type": "array",7678       "minItems": 1,7679       "description": "The tool invocation context(s)."7680      },7681      {7682       "type": "null"7683      }7684     ]7685    }7686   },7687   "type": "object",7688   "required": [7689    "type",7690    "name"7691   ],7692   "title": "Custom tool",7693   "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)"7694  },7695  "tool_choice_support": {7696   "modes": [7697    "none",7698    "auto",7699    "required"7700   ],7701   "allowed_tools": {7702    "type": "allowed_tools",7703    "mode": "auto|required",7704    "tools": [7705     "{type,name,...}"7706    ]7707   },7708   "specific": {7709    "type": "custom",7710    "name": "<tool>"7711   },7712   "chat_completions": {7713    "type": "custom",7714    "custom": {7715     "name": "<tool>"7716    }7717   }7718  },7719  "parallel": {7720   "supported": true,7721   "parameter": "parallel_tool_calls"7722  },7723  "streaming_events": [7724   "response.output_item.added",7725   "response.custom_tool_call_input.delta",7726   "response.custom_tool_call_input.done",7727   "response.output_item.done"7728  ],7729  "result_shape": {7730   "items": [7731    {7732     "schema_name": "CustomToolCall",7733     "type": "custom_tool_call",7734     "schema": {7735      "type": "object",7736      "title": "Custom tool call",7737      "description": "A call to a custom tool created by the model.\n",7738      "properties": {7739       "type": {7740        "type": "string",7741        "enum": [7742         "custom_tool_call"7743        ],7744        "x-stainless-const": true,7745        "description": "The type of the custom tool call. Always `custom_tool_call`.\n"7746       },7747       "id": {7748        "type": "string",7749        "description": "The unique ID of the custom tool call in the OpenAI platform.\n"7750       },7751       "call_id": {7752        "type": "string",7753        "description": "An identifier used to map this custom tool call to a tool call output.\n"7754       },7755       "caller": {7756        "anyOf": [7757         {7758          "oneOf": [7759           {7760            "properties": {7761             "type": {7762              "type": "string",7763              "enum": [7764               "direct"7765              ],7766              "default": "direct",7767              "x-stainless-const": true7768             }7769            },7770            "type": "object",7771            "required": [7772             "type"7773            ]7774           },7775           {7776            "properties": {7777             "type": {7778              "type": "string",7779              "enum": [7780               "program"7781              ],7782              "default": "program",7783              "x-stainless-const": true7784             },7785             "caller_id": {7786              "type": "string",7787              "description": "The call ID of the program item that produced this tool call."7788             }7789            },7790            "type": "object",7791            "required": [7792             "type",7793             "caller_id"7794            ]7795           }7796          ],7797          "description": "The execution context that produced this tool call.",7798          "discriminator": {7799           "propertyName": "type"7800          }7801         },7802         {7803          "type": "null"7804         }7805        ]7806       },7807       "namespace": {7808        "type": "string",7809        "description": "The namespace of the custom tool being called.\n"7810       },7811       "name": {7812        "type": "string",7813        "description": "The name of the custom tool being called.\n"7814       },7815       "input": {7816        "type": "string",7817        "description": "The input for the custom tool call generated by the model.\n"7818       },7819       "async": {7820        "type": "boolean",7821        "description": "Whether the custom tool call runs asynchronously.\n"7822       }7823      },7824      "required": [7825       "type",7826       "call_id",7827       "name",7828       "input"7829      ]7830     }7831    },7832    {7833     "schema_name": "CustomToolCallOutput",7834     "type": "custom_tool_call_output",7835     "schema": {7836      "type": "object",7837      "title": "Custom tool call output",7838      "description": "The output of a custom tool call from your code, being sent back to the model.\n",7839      "properties": {7840       "type": {7841        "type": "string",7842        "enum": [7843         "custom_tool_call_output"7844        ],7845        "x-stainless-const": true,7846        "description": "The type of the custom tool call output. Always `custom_tool_call_output`.\n"7847       },7848       "id": {7849        "type": "string",7850        "description": "The unique ID of the custom tool call output in the OpenAI platform.\n"7851       },7852       "call_id": {7853        "type": "string",7854        "description": "The call ID, used to map this custom tool call output to a custom tool call.\n"7855       },7856       "caller": {7857        "anyOf": [7858         {7859          "oneOf": [7860           {7861            "properties": {7862             "type": {7863              "type": "string",7864              "enum": [7865               "direct"7866              ],7867              "description": "The caller type. Always `direct`.",7868              "default": "direct",7869              "x-stainless-const": true7870             }7871            },7872            "type": "object",7873            "required": [7874             "type"7875            ]7876           },7877           {7878            "properties": {7879             "type": {7880              "type": "string",7881              "enum": [7882               "program"7883              ],7884              "description": "The caller type. Always `program`.",7885              "default": "program",7886              "x-stainless-const": true7887             },7888             "caller_id": {7889              "type": "string",7890              "maxLength": 64,7891              "minLength": 1,7892              "description": "The call ID of the program item that produced this tool call."7893             }7894            },7895            "type": "object",7896            "required": [7897             "type",7898             "caller_id"7899            ]7900           }7901          ],7902          "description": "The execution context that produced this tool call.",7903          "discriminator": {7904           "propertyName": "type"7905          }7906         },7907         {7908          "type": "null"7909         }7910        ]7911       },7912       "output": {7913        "description": "The output from the custom tool call generated by your code.\nCan be a string or an list of output content.\n",7914        "oneOf": [7915         {7916          "type": "string",7917          "description": "A string of the output of the custom tool call.\n",7918          "title": "string output"7919         },7920         {7921          "type": "array",7922          "items": {7923           "oneOf": [7924            {7925             "properties": {7926              "type": {7927               "type": "string",7928               "enum": [7929                "input_text"7930               ],7931               "description": "The type of the input item. Always `input_text`.",7932               "default": "input_text",7933               "x-stainless-const": true7934              },7935              "text": {7936               "type": "string",7937               "description": "The text input to the model."7938              },7939              "prompt_cache_breakpoint": {7940               "properties": {7941                "mode": {7942                 "type": {7943                  "$comment": "depth-limited"7944                 },7945                 "enum": {7946                  "$comment": "depth-limited"7947                 },7948                 "description": {7949                  "$comment": "depth-limited"7950                 },7951                 "default": {7952                  "$comment": "depth-limited"7953                 },7954                 "x-stainless-const": {7955                  "$comment": "depth-limited"7956                 }7957                }7958               },7959               "type": "object",7960               "required": [7961                "mode"7962               ],7963               "title": "Prompt cache breakpoint",7964               "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."7965              }7966             },7967             "type": "object",7968             "required": [7969              "type",7970              "text"7971             ],7972             "title": "Input text",7973             "description": "A text input to the model."7974            },7975            {7976             "properties": {7977              "type": {7978               "type": "string",7979               "enum": [7980                "input_image"7981               ],7982               "description": "The type of the input item. Always `input_image`.",7983               "default": "input_image",7984               "x-stainless-const": true7985              },7986              "image_url": {7987               "anyOf": [7988                {7989                 "type": "string",7990                 "format": "uri",7991                 "description": "The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL."7992                },7993                {7994                 "type": "null"7995                }7996               ]7997              },7998              "file_id": {7999               "anyOf": [8000                {8001                 "type": "string",8002                 "description": "The ID of the file to be sent to the model."8003                },8004                {8005                 "type": "null"8006                }8007               ]8008              },8009              "detail": {8010               "type": "string",8011               "enum": [8012                "low",8013                "high",8014                "auto",8015                "original"8016               ]8017              },8018              "prompt_cache_breakpoint": {8019               "properties": {8020                "mode": {8021                 "type": {8022                  "$comment": "depth-limited"8023                 },8024                 "enum": {8025                  "$comment": "depth-limited"8026                 },8027                 "description": {8028                  "$comment": "depth-limited"8029                 },8030                 "default": {8031                  "$comment": "depth-limited"8032                 },8033                 "x-stainless-const": {8034                  "$comment": "depth-limited"8035                 }8036                }8037               },8038               "type": "object",8039               "required": [8040                "mode"8041               ],8042               "title": "Prompt cache breakpoint",8043               "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."8044              }8045             },8046             "type": "object",8047             "required": [8048              "type",8049              "detail"8050             ],8051             "title": "Input image",8052             "description": "An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision)."8053            },8054            {8055             "properties": {8056              "type": {8057               "type": "string",8058               "enum": [8059                "input_file"8060               ],8061               "description": "The type of the input item. Always `input_file`.",8062               "default": "input_file",8063               "x-stainless-const": true8064              },8065              "file_id": {8066               "anyOf": [8067                {8068                 "type": "string",8069                 "description": "The ID of the file to be sent to the model."8070                },8071                {8072                 "type": "null"8073                }8074               ]8075              },8076              "filename": {8077               "type": "string",8078               "description": "The name of the file to be sent to the model."8079              },8080              "file_data": {8081               "type": "string",8082               "description": "The content of the file to be sent to the model.\n"8083              },8084              "prompt_cache_breakpoint": {8085               "properties": {8086                "mode": {8087                 "type": {8088                  "$comment": "depth-limited"8089                 },8090                 "enum": {8091                  "$comment": "depth-limited"8092                 },8093                 "description": {8094                  "$comment": "depth-limited"8095                 },8096                 "default": {8097                  "$comment": "depth-limited"8098                 },8099                 "x-stainless-const": {8100                  "$comment": "depth-limited"8101                 }8102                }8103               },8104               "type": "object",8105               "required": [8106                "mode"8107               ],8108               "title": "Prompt cache breakpoint",8109               "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."8110              },8111              "file_url": {8112               "type": "string",8113               "format": "uri",8114               "description": "The URL of the file to be sent to the model."8115              },8116              "detail": {8117               "type": "string",8118               "enum": [8119                "auto",8120                "low",8121                "high"8122               ]8123              }8124             },8125             "type": "object",8126             "required": [8127              "type"8128             ],8129             "title": "Input file",8130             "description": "A file input to the model."8131            }8132           ],8133           "discriminator": {8134            "propertyName": "type"8135           }8136          },8137          "title": "output content list",8138          "description": "Text, image, or file output of the custom tool call.\n"8139         }8140        ]8141       }8142      },8143      "required": [8144       "type",8145       "call_id",8146       "output"8147      ]8148     }8149    }8150   ],8151   "summary": "Output item `custom_tool_call` {id, call_id, name, input: string, status}; reply with `custom_tool_call_output` {call_id, output}."8152  },8153  "billing": {8154   "model": "Token billing only.",8155   "source": "https://developers.openai.com/api/docs/pricing#built-in-tools"8156  },8157  "limitations": [8158   "Grammar too complex -> API error; keep terminals bounded; no verbose regex mode; Lark subset only.",8159   "Chat Completions shape differs: {type: custom, custom: {name, description, format: {type: grammar, grammar: {syntax, definition}}}}."8160  ],8161  "security": [8162   "Grammar constrains syntax, not semantics — still validate the input before acting on it."8163  ],8164  "beta_header": null,8165  "status": [8166   "DOCUMENTED",8167   "LIVE_VERIFIED"8168  ],8169  "examples": {8170   "curl": "examples/openai/tools/custom-tools/custom_tools.sh",8171   "python": "examples/openai/tools/custom-tools/custom_tools.py",8172   "typescript": "examples/openai/tools/custom-tools/custom_tools.ts"8173  },8174  "verification": {8175   "regex_grammar": {8176    "method": "live_api",8177    "verified_at": "2026-09-18",8178    "result": "success",8179    "http_status": 200,8180    "request_note": "gpt-5.4-nano: format grammar regex ^(yes|no)$ forced -> custom_tool_call input='yes'"8181   },8182   "text_format": {8183    "method": "live_api",8184    "verified_at": "2026-09-18",8185    "result": "success",8186    "http_status": 200,8187    "request_note": "gpt-5.4-nano: default text format, tool_choice required -> custom_tool_call"8188   },8189   "streaming": {8190    "method": "live_api",8191    "verified_at": "2026-09-18",8192    "result": "success",8193    "http_status": 200,8194    "request_note": "response.custom_tool_call_input.delta -> .done"8195   }8196  },8197  "sources": [8198   {8199    "url": "https://developers.openai.com/api/docs/guides/function-calling#custom-tools",8200    "retrieved_at": "2026-09-18"8201   },8202   {8203    "url": "https://developers.openai.com/api/reference/resources/responses/methods/create",8204    "retrieved_at": "2026-09-18"8205   },8206   {8207    "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)",8208    "retrieved_at": "2026-09-18"8209   }8210  ],8211  "last_verified": "2026-09-18",8212  "_fragment": "generated/fragments/tools/openai-tools.json"8213 },8214 {8215  "provider": "openai",8216  "name": "Namespace (group of function/custom tools)",8217  "type": "namespace",8218  "category": "client",8219  "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`.",8220  "compatible_models": [8221   "chat-latest",8222   "gpt-4.1",8223   "gpt-4.1-mini",8224   "gpt-4.1-nano",8225   "gpt-4o",8226   "gpt-4o-mini",8227   "gpt-5",8228   "gpt-5-chat-latest",8229   "gpt-5-codex",8230   "gpt-5-mini",8231   "gpt-5-nano",8232   "gpt-5-pro",8233   "gpt-5.1",8234   "gpt-5.1-chat-latest",8235   "gpt-5.1-codex",8236   "gpt-5.1-codex-max",8237   "gpt-5.1-codex-mini",8238   "gpt-5.2",8239   "gpt-5.2-chat-latest",8240   "gpt-5.2-codex",8241   "gpt-5.2-pro",8242   "gpt-5.3-chat-latest",8243   "gpt-5.3-codex",8244   "gpt-5.4",8245   "gpt-5.4-mini",8246   "gpt-5.4-nano",8247   "gpt-5.4-pro",8248   "gpt-5.5",8249   "gpt-5.5-pro",8250   "gpt-audio-mini",8251   "gpt-oss-120b",8252   "gpt-oss-20b",8253   "o1",8254   "o1-pro",8255   "o3",8256   "o3-mini",8257   "o3-pro",8258   "o4-mini"8259  ],8260  "compatible_endpoints": [8261   "POST /v1/responses"8262  ],8263  "parameters_schema": {8264   "properties": {8265    "type": {8266     "type": "string",8267     "enum": [8268      "namespace"8269     ],8270     "description": "The type of the tool. Always `namespace`.",8271     "default": "namespace",8272     "x-stainless-const": true8273    },8274    "name": {8275     "type": "string",8276     "minLength": 1,8277     "description": "The namespace name used in tool calls (for example, `crm`)."8278    },8279    "description": {8280     "type": "string",8281     "description": "A description of the namespace shown to the model."8282    },8283    "tools": {8284     "items": {8285      "oneOf": [8286       {8287        "properties": {8288         "name": {8289          "type": "string",8290          "maxLength": 128,8291          "minLength": 1,8292          "pattern": "^[a-zA-Z0-9_-]+$"8293         },8294         "description": {8295          "anyOf": [8296           {8297            "type": "string"8298           },8299           {8300            "type": "null"8301           }8302          ]8303         },8304         "parameters": {8305          "anyOf": [8306           {8307            "properties": {},8308            "type": "object",8309            "required": []8310           },8311           {8312            "type": "null"8313           }8314          ]8315         },8316         "strict": {8317          "anyOf": [8318           {8319            "type": "boolean",8320            "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."8321           },8322           {8323            "type": "null"8324           }8325          ]8326         },8327         "type": {8328          "type": "string",8329          "enum": [8330           "function"8331          ],8332          "default": "function",8333          "x-stainless-const": true8334         },8335         "async": {8336          "type": "boolean",8337          "description": "Whether the tool response can be returned asynchronously versus immediately returned on next response creation."8338         },8339         "output_schema": {8340          "anyOf": [8341           {8342            "additionalProperties": {},8343            "type": "object",8344            "description": "A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs."8345           },8346           {8347            "type": "null"8348           }8349          ]8350         },8351         "defer_loading": {8352          "type": "boolean",8353          "description": "Whether this function should be deferred and discovered via tool search."8354         },8355         "allowed_callers": {8356          "anyOf": [8357           {8358            "items": {8359             "type": "string",8360             "enum": [8361              "direct",8362              "programmatic"8363             ]8364            },8365            "type": "array",8366            "minItems": 1,8367            "description": "The tool invocation context(s)."8368           },8369           {8370            "type": "null"8371           }8372          ]8373         }8374        },8375        "type": "object",8376        "required": [8377         "name",8378         "type"8379        ]8380       },8381       {8382        "properties": {8383         "type": {8384          "type": "string",8385          "enum": [8386           "custom"8387          ],8388          "description": "The type of the custom tool. Always `custom`.",8389          "default": "custom",8390          "x-stainless-const": true8391         },8392         "name": {8393          "type": "string",8394          "description": "The name of the custom tool, used to identify it in tool calls."8395         },8396         "async": {8397          "type": "boolean",8398          "description": "Whether the tool response can be returned asynchronously versus immediately returned on next response creation."8399         },8400         "description": {8401          "type": "string",8402          "description": "Optional description of the custom tool, used to provide more context."8403         },8404         "format": {8405          "oneOf": [8406           {8407            "properties": {8408             "type": {8409              "type": "string",8410              "enum": [8411               {8412                "$comment": "depth-limited"8413               }8414              ],8415              "description": "Unconstrained text format. Always `text`.",8416              "default": "text",8417              "x-stainless-const": true8418             }8419            },8420            "type": "object",8421            "required": [8422             "type"8423            ],8424            "title": "Text format",8425            "description": "Unconstrained free-form text."8426           },8427           {8428            "properties": {8429             "type": {8430              "type": "string",8431              "enum": [8432               {8433                "$comment": "depth-limited"8434               }8435              ],8436              "description": "Grammar format. Always `grammar`.",8437              "default": "grammar",8438              "x-stainless-const": true8439             },8440             "syntax": {8441              "type": {8442               "$comment": "depth-limited"8443              },8444              "enum": {8445               "$comment": "depth-limited"8446              }8447             },8448             "definition": {8449              "type": "string",8450              "description": "The grammar definition."8451             }8452            },8453            "type": "object",8454            "required": [8455             "type",8456             "syntax",8457             "definition"8458            ],8459            "title": "Grammar format",8460            "description": "A grammar defined by the user."8461           }8462          ],8463          "description": "The input format for the custom tool. Default is unconstrained text.",8464          "discriminator": {8465           "propertyName": "type"8466          }8467         },8468         "defer_loading": {8469          "type": "boolean",8470          "description": "Whether this tool should be deferred and discovered via tool search."8471         },8472         "allowed_callers": {8473          "anyOf": [8474           {8475            "items": {8476             "type": "string",8477             "enum": [8478              "direct",8479              "programmatic"8480             ]8481            },8482            "type": "array",8483            "minItems": 1,8484            "description": "The tool invocation context(s)."8485           },8486           {8487            "type": "null"8488           }8489          ]8490         }8491        },8492        "type": "object",8493        "required": [8494         "type",8495         "name"8496        ],8497        "title": "Custom tool",8498        "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)"8499       }8500      ],8501      "description": "A function or custom tool that belongs to a namespace.",8502      "discriminator": {8503       "propertyName": "type"8504      }8505     },8506     "type": "array",8507     "minItems": 1,8508     "description": "The function/custom tools available inside this namespace."8509    }8510   },8511   "type": "object",8512   "required": [8513    "type",8514    "name",8515    "description",8516    "tools"8517   ],8518   "title": "Namespace",8519   "description": "Groups function/custom tools under a shared namespace."8520  },8521  "tool_choice_support": {8522   "modes": [8523    "none",8524    "auto",8525    "required"8526   ],8527   "allowed_tools": {8528    "type": "allowed_tools",8529    "mode": "auto|required",8530    "tools": [8531     "{type,name,...}"8532    ]8533   },8534   "note": "tool_choice targets the inner tool by name"8535  },8536  "parallel": {8537   "supported": true,8538   "parameter": "parallel_tool_calls"8539  },8540  "streaming_events": [8541   "response.output_item.added",8542   "response.function_call_arguments.delta",8543   "response.function_call_arguments.done",8544   "response.output_item.done"8545  ],8546  "result_shape": {8547   "items": [8548    {8549     "schema_name": "FunctionToolCall",8550     "type": "function_call",8551     "schema": {8552      "type": "object",8553      "title": "Function tool call",8554      "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",8555      "properties": {8556       "id": {8557        "type": "string",8558        "description": "The unique ID of the function tool call.\n"8559       },8560       "type": {8561        "type": "string",8562        "enum": [8563         "function_call"8564        ],8565        "description": "The type of the function tool call. Always `function_call`.\n",8566        "x-stainless-const": true8567       },8568       "call_id": {8569        "type": "string",8570        "description": "The unique ID of the function tool call generated by the model.\n"8571       },8572       "caller": {8573        "anyOf": [8574         {8575          "oneOf": [8576           {8577            "properties": {8578             "type": {8579              "type": "string",8580              "enum": [8581               "direct"8582              ],8583              "default": "direct",8584              "x-stainless-const": true8585             }8586            },8587            "type": "object",8588            "required": [8589             "type"8590            ]8591           },8592           {8593            "properties": {8594             "type": {8595              "type": "string",8596              "enum": [8597               "program"8598              ],8599              "default": "program",8600              "x-stainless-const": true8601             },8602             "caller_id": {8603              "type": "string",8604              "description": "The call ID of the program item that produced this tool call."8605             }8606            },8607            "type": "object",8608            "required": [8609             "type",8610             "caller_id"8611            ]8612           }8613          ],8614          "description": "The execution context that produced this tool call.",8615          "discriminator": {8616           "propertyName": "type"8617          }8618         },8619         {8620          "type": "null"8621         }8622        ]8623       },8624       "namespace": {8625        "type": "string",8626        "description": "The namespace of the function to run.\n"8627       },8628       "name": {8629        "type": "string",8630        "description": "The name of the function to run.\n"8631       },8632       "arguments": {8633        "type": "string",8634        "description": "A JSON string of the arguments to pass to the function.\n"8635       },8636       "status": {8637        "type": "string",8638        "description": "The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.\n",8639        "enum": [8640         "in_progress",8641         "completed",8642         "incomplete"8643        ]8644       },8645       "async": {8646        "type": "boolean",8647        "description": "Whether the function tool call runs asynchronously.\n"8648       }8649      },8650      "required": [8651       "type",8652       "call_id",8653       "name",8654       "arguments"8655      ]8656     }8657    },8658    {8659     "schema_name": "CustomToolCall",8660     "type": "custom_tool_call",8661     "schema": {8662      "type": "object",8663      "title": "Custom tool call",8664      "description": "A call to a custom tool created by the model.\n",8665      "properties": {8666       "type": {8667        "type": "string",8668        "enum": [8669         "custom_tool_call"8670        ],8671        "x-stainless-const": true,8672        "description": "The type of the custom tool call. Always `custom_tool_call`.\n"8673       },8674       "id": {8675        "type": "string",8676        "description": "The unique ID of the custom tool call in the OpenAI platform.\n"8677       },8678       "call_id": {8679        "type": "string",8680        "description": "An identifier used to map this custom tool call to a tool call output.\n"8681       },8682       "caller": {8683        "anyOf": [8684         {8685          "oneOf": [8686           {8687            "properties": {8688             "type": {8689              "type": "string",8690              "enum": [8691               "direct"8692              ],8693              "default": "direct",8694              "x-stainless-const": true8695             }8696            },8697            "type": "object",8698            "required": [8699             "type"8700            ]8701           },8702           {8703            "properties": {8704             "type": {8705              "type": "string",8706              "enum": [8707               "program"8708              ],8709              "default": "program",8710              "x-stainless-const": true8711             },8712             "caller_id": {8713              "type": "string",8714              "description": "The call ID of the program item that produced this tool call."8715             }8716            },8717            "type": "object",8718            "required": [8719             "type",8720             "caller_id"8721            ]8722           }8723          ],8724          "description": "The execution context that produced this tool call.",8725          "discriminator": {8726           "propertyName": "type"8727          }8728         },8729         {8730          "type": "null"8731         }8732        ]8733       },8734       "namespace": {8735        "type": "string",8736        "description": "The namespace of the custom tool being called.\n"8737       },8738       "name": {8739        "type": "string",8740        "description": "The name of the custom tool being called.\n"8741       },8742       "input": {8743        "type": "string",8744        "description": "The input for the custom tool call generated by the model.\n"8745       },8746       "async": {8747        "type": "boolean",8748        "description": "Whether the custom tool call runs asynchronously.\n"8749       }8750      },8751      "required": [8752       "type",8753       "call_id",8754       "name",8755       "input"8756      ]8757     }8758    }8759   ],8760   "summary": "Inner tool call items gain `namespace: <name>`; `function_call_output` may echo `namespace`."8761  },8762  "billing": {8763   "model": "Token billing only.",8764   "source": "https://developers.openai.com/api/docs/pricing#built-in-tools"8765  },8766  "limitations": [8767   "`defer_loading` applies to the tools inside the namespace, not the namespace object.",8768   "Model pages do not list `namespace` separately; availability follows function calling (verified on gpt-5.4-nano)."8769  ],8770  "security": [8771   "Same as function calling."8772  ],8773  "beta_header": null,8774  "status": [8775   "DOCUMENTED",8776   "LIVE_VERIFIED"8777  ],8778  "examples": {8779   "curl": "examples/openai/tools/function-calling/function_calling.sh",8780   "python": "examples/openai/tools/function-calling/function_calling.py",8781   "typescript": "examples/openai/tools/function-calling/function_calling.ts"8782  },8783  "verification": {8784   "namespace_call": {8785    "method": "live_api",8786    "verified_at": "2026-09-18",8787    "result": "success",8788    "http_status": 200,8789    "request_note": "gpt-5.4-nano: namespace 'weather' wrapping get_weather, tool_choice required -> function_call with namespace='weather'"8790   }8791  },8792  "sources": [8793   {8794    "url": "https://developers.openai.com/api/docs/guides/function-calling#namespaces",8795    "retrieved_at": "2026-09-18"8796   },8797   {8798    "url": "https://developers.openai.com/api/docs/guides/tools-tool-search",8799    "retrieved_at": "2026-09-18"8800   },8801   {8802    "url": "https://developers.openai.com/api/reference/resources/responses/methods/create",8803    "retrieved_at": "2026-09-18"8804   },8805   {8806    "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)",8807    "retrieved_at": "2026-09-18"8808   }8809  ],8810  "last_verified": "2026-09-18",8811  "_fragment": "generated/fragments/tools/openai-tools.json"8812 },8813 {8814  "provider": "openai",8815  "name": "Tool search (deferred tool loading)",8816  "type": "tool_search",8817  "category": "hosted",8818  "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.",8819  "compatible_models": [8820   "gpt-5.4",8821   "gpt-5.4-mini",8822   "gpt-5.4-pro",8823   "gpt-5.5",8824   "gpt-5.6-cyber",8825   "gpt-5.6-luna",8826   "gpt-5.6-sol",8827   "gpt-5.6-terra",8828   "gpt-6-astra",8829   "gpt-daybreak-blue-latest",8830   "gpt-daybreak-red-latest"8831  ],8832  "compatible_endpoints": [8833   "POST /v1/responses",8834   "Agents API (session tools)"8835  ],8836  "parameters_schema": {8837   "properties": {8838    "type": {8839     "type": "string",8840     "enum": [8841      "tool_search"8842     ],8843     "description": "The type of the tool. Always `tool_search`.",8844     "default": "tool_search",8845     "x-stainless-const": true8846    },8847    "execution": {8848     "type": "string",8849     "enum": [8850      "server",8851      "client"8852     ]8853    },8854    "description": {8855     "anyOf": [8856      {8857       "type": "string",8858       "description": "Description shown to the model for a client-executed tool search tool."8859      },8860      {8861       "type": "null"8862      }8863     ]8864    },8865    "parameters": {8866     "anyOf": [8867      {8868       "properties": {},8869       "type": "object",8870       "required": []8871      },8872      {8873       "type": "null"8874      }8875     ]8876    }8877   },8878   "type": "object",8879   "required": [8880    "type"8881   ],8882   "title": "Tool search tool",8883   "description": "Hosted or BYOT tool search configuration for deferred tools."8884  },8885  "tool_choice_support": {8886   "modes": [8887    "auto",8888    "required",8889    "none"8890   ],8891   "note": "tool_choice applies to the tools currently callable in the turn"8892  },8893  "parallel": {8894   "supported": false,8895   "notes": "Search happens before the eventual function call."8896  },8897  "streaming_events": [8898   "response.output_item.added",8899   "response.output_item.done"8900  ],8901  "result_shape": {8902   "items": [8903    {8904     "schema_name": "ToolSearchCall",8905     "type": "tool_search_call",8906     "schema": {8907      "properties": {8908       "type": {8909        "type": "string",8910        "enum": [8911         "tool_search_call"8912        ],8913        "description": "The type of the item. Always `tool_search_call`.",8914        "default": "tool_search_call",8915        "x-stainless-const": true8916       },8917       "id": {8918        "type": "string",8919        "description": "The unique ID of the tool search call item."8920       },8921       "call_id": {8922        "anyOf": [8923         {8924          "type": "string",8925          "description": "The unique ID of the tool search call generated by the model."8926         },8927         {8928          "type": "null"8929         }8930        ]8931       },8932       "execution": {8933        "type": "string",8934        "enum": [8935         "server",8936         "client"8937        ]8938       },8939       "arguments": {8940        "description": "Arguments used for the tool search call."8941       },8942       "status": {8943        "type": "string",8944        "enum": [8945         "in_progress",8946         "completed",8947         "incomplete"8948        ]8949       },8950       "created_by": {8951        "type": "string",8952        "description": "The identifier of the actor that created the item."8953       }8954      },8955      "type": "object",8956      "required": [8957       "type",8958       "id",8959       "call_id",8960       "execution",8961       "arguments",8962       "status"8963      ]8964     }8965    },8966    {8967     "schema_name": "ToolSearchOutput",8968     "type": "tool_search_output",8969     "schema": {8970      "properties": {8971       "type": {8972        "type": "string",8973        "enum": [8974         "tool_search_output"8975        ],8976        "description": "The type of the item. Always `tool_search_output`.",8977        "default": "tool_search_output",8978        "x-stainless-const": true8979       },8980       "id": {8981        "type": "string",8982        "description": "The unique ID of the tool search output item."8983       },8984       "call_id": {8985        "anyOf": [8986         {8987          "type": "string",8988          "description": "The unique ID of the tool search call generated by the model."8989         },8990         {8991          "type": "null"8992         }8993        ]8994       },8995       "execution": {8996        "type": "string",8997        "enum": [8998         "server",8999         "client"9000        ]9001       },9002       "tools": {9003        "items": {9004         "description": "A tool that can be used to generate a response.\n",9005         "discriminator": {9006          "propertyName": "type"9007         },9008         "oneOf": [9009          {9010           "properties": {9011            "type": {9012             "type": "string",9013             "enum": [9014              "function"9015             ],9016             "description": "The type of the function tool. Always `function`.",9017             "default": "function",9018             "x-stainless-const": true9019            },9020            "name": {9021             "type": "string",9022             "description": "The name of the function to call."9023            },9024            "async": {9025             "type": "boolean"9026            },9027            "description": {9028             "anyOf": [9029              {9030               "type": "string",9031               "description": "A description of the function. Used by the model to determine whether or not to call the function."9032              },9033              {9034               "type": "null"9035              }9036             ]9037            },9038            "parameters": {9039             "anyOf": [9040              {9041               "additionalProperties": {},9042               "type": "object",9043               "description": "A JSON schema object describing the parameters of the function."9044              },9045              {9046               "type": "null"9047              }9048             ]9049            },9050            "output_schema": {9051             "anyOf": [9052              {9053               "additionalProperties": {},9054               "type": "object",9055               "description": "A JSON schema object describing the JSON value encoded in string outputs for this function."9056              },9057              {9058               "type": "null"9059              }9060             ]9061            },9062            "strict": {9063             "anyOf": [9064              {9065               "type": "boolean",9066               "description": "Whether strict parameter validation is enforced for this function tool."9067              },9068              {9069               "type": "null"9070              }9071             ]9072            },9073            "defer_loading": {9074             "type": "boolean",9075             "description": "Whether this function is deferred and loaded via tool search."9076            },9077            "allowed_callers": {9078             "anyOf": [9079              {9080               "items": {9081                "type": "string",9082                "enum": [9083                 {9084                  "$comment": "depth-limited"9085                 },9086                 {9087                  "$comment": "depth-limited"9088                 }9089                ]9090               },9091               "type": "array",9092               "description": "The tool invocation context(s)."9093              },9094              {9095               "type": "null"9096              }9097             ]9098            }9099           },9100           "type": "object",9101           "required": [9102            "type",9103            "name",9104            "strict",9105            "parameters"9106           ],9107           "title": "Function",9108           "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)."9109          },9110          {9111           "properties": {9112            "type": {9113             "type": "string",9114             "enum": [9115              "file_search"9116             ],9117             "description": "The type of the file search tool. Always `file_search`.",9118             "default": "file_search",9119             "x-stainless-const": true9120            },9121            "vector_store_ids": {9122             "items": {9123              "type": "string"9124             },9125             "type": "array",9126             "description": "The IDs of the vector stores to search."9127            },9128            "max_num_results": {9129             "type": "integer",9130             "description": "The maximum number of results to return. This number should be between 1 and 50 inclusive."9131            },9132            "ranking_options": {9133             "properties": {9134              "ranker": {9135               "type": "string",9136               "enum": [9137                {9138                 "$comment": "depth-limited"9139                },9140                {9141                 "$comment": "depth-limited"9142                }9143               ]9144              },9145              "score_threshold": {9146               "type": "number",9147               "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."9148              },9149              "hybrid_search": {9150               "properties": {9151                "embedding_weight": {9152                 "$comment": "depth-limited"9153                },9154                "text_weight": {9155                 "$comment": "depth-limited"9156                }9157               },9158               "type": "object",9159               "required": [9160                {9161                 "$comment": "depth-limited"9162                },9163                {9164                 "$comment": "depth-limited"9165                }9166               ]9167              }9168             },9169             "type": "object",9170             "required": []9171            },9172            "filters": {9173             "anyOf": [9174              {9175               "anyOf": [9176                {9177                 "$comment": "depth-limited"9178                },9179                {9180                 "$comment": "depth-limited"9181                }9182               ]9183              },9184              {9185               "type": "null"9186              }9187             ]9188            }9189           },9190           "type": "object",9191           "required": [9192            "type",9193            "vector_store_ids"9194           ],9195           "title": "File search",9196           "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)."9197          },9198          {9199           "properties": {9200            "type": {9201             "type": "string",9202             "enum": [9203              "computer"9204             ],9205             "description": "The type of the computer tool. Always `computer`.",9206             "default": "computer",9207             "x-stainless-const": true9208            }9209           },9210           "type": "object",9211           "required": [9212            "type"9213           ],9214           "title": "Computer",9215           "description": "A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use)."9216          },9217          {9218           "properties": {9219            "type": {9220             "type": "string",9221             "enum": [9222              "computer_use_preview"9223             ],9224             "description": "The type of the computer use tool. Always `computer_use_preview`.",9225             "default": "computer_use_preview",9226             "x-stainless-const": true9227            },9228            "environment": {9229             "type": "string",9230             "enum": [9231              "windows",9232              "mac",9233              "linux",9234              "ubuntu",9235              "browser"9236             ]9237            },9238            "display_width": {9239             "type": "integer",9240             "description": "The width of the computer display."9241            },9242            "display_height": {9243             "type": "integer",9244             "description": "The height of the computer display."9245            }9246           },9247           "type": "object",9248           "required": [9249            "type",9250            "environment",9251            "display_width",9252            "display_height"9253           ],9254           "title": "Computer use preview",9255           "description": "A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use)."9256          },9257          {9258           "type": "object",9259           "title": "Web search",9260           "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",9261           "properties": {9262            "type": {9263             "type": "string",9264             "enum": [9265              "web_search",9266              "web_search_2025_08_26"9267             ],9268             "description": "The type of the web search tool. One of `web_search` or `web_search_2025_08_26`.",9269             "default": "web_search"9270            },9271            "external_web_access": {9272             "type": "boolean",9273             "default": true,9274             "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."9275            },9276            "filters": {9277             "anyOf": [9278              {9279               "type": "object",9280               "description": "Filters for the search.\n",9281               "properties": {9282                "allowed_domains": {9283                 "anyOf": [9284                  {9285                   "$comment": "depth-limited"9286                  },9287                  {9288                   "$comment": "depth-limited"9289                  }9290                 ]9291                }9292               }9293              },9294              {9295               "type": "null"9296              }9297             ]9298            },9299            "user_location": {9300             "anyOf": [9301              {9302               "type": "object",9303               "title": "Web search approximate location",9304               "description": "The approximate location of the user.\n",9305               "properties": {9306                "type": {9307                 "type": {9308                  "$comment": "depth-limited"9309                 },9310                 "enum": {9311                  "$comment": "depth-limited"9312                 },9313                 "description": {9314                  "$comment": "depth-limited"9315                 },9316                 "default": {9317                  "$comment": "depth-limited"9318                 },9319                 "x-stainless-const": {9320                  "$comment": "depth-limited"9321                 }9322                },9323                "country": {9324                 "anyOf": {9325                  "$comment": "depth-limited"9326                 }9327                },9328                "region": {9329                 "anyOf": {9330                  "$comment": "depth-limited"9331                 }9332                },9333                "city": {9334                 "anyOf": {9335                  "$comment": "depth-limited"9336                 }9337                },9338                "timezone": {9339                 "anyOf": {9340                  "$comment": "depth-limited"9341                 }9342                }9343               }9344              },9345              {9346               "type": "null"9347              }9348             ]9349            },9350            "search_context_size": {9351             "type": "string",9352             "enum": [9353              "low",9354              "medium",9355              "high"9356             ],9357             "default": "medium",9358             "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."9359            }9360           },9361           "required": [9362            "type"9363           ]9364          },9365          {9366           "type": "object",9367           "title": "MCP tool",9368           "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",9369           "properties": {9370            "type": {9371             "type": "string",9372             "enum": [9373              "mcp"9374             ],9375             "description": "The type of the MCP tool. Always `mcp`.",9376             "x-stainless-const": true9377            },9378            "server_label": {9379             "type": "string",9380             "description": "A label for this MCP server, used to identify it in tool calls.\n"9381            },9382            "server_url": {9383             "type": "string",9384             "format": "uri",9385             "description": "The URL for the MCP server. One of `server_url`, `connector_id`, or\n`tunnel_id` must be provided.\n"9386            },9387            "connector_id": {9388             "type": "string",9389             "deprecated": true,9390             "enum": [9391              "connector_dropbox",9392              "connector_gmail",9393              "connector_googlecalendar",9394              "connector_googledrive",9395              "connector_microsoftteams",9396              "connector_outlookcalendar",9397              "connector_outlookemail",9398              "connector_sharepoint"9399             ],9400             "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"9401            },9402            "tunnel_id": {9403             "type": "string",9404             "pattern": "^tunnel_[a-z0-9]{32}$",9405             "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"9406            },9407            "authorization": {9408             "type": "string",9409             "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"9410            },9411            "server_description": {9412             "type": "string",9413             "description": "Optional description of the MCP server, used to provide more context.\n"9414            },9415            "headers": {9416             "anyOf": [9417              {9418               "type": "object",9419               "additionalProperties": {9420                "type": "string"9421               },9422               "description": "Optional HTTP headers to send to the MCP server. Use for authentication\nor other purposes.\n"9423              },9424              {9425               "type": "null"9426              }9427             ]9428            },9429            "allowed_tools": {9430             "anyOf": [9431              {9432               "description": "List of allowed tool names or a filter object.\n",9433               "oneOf": [9434                {9435                 "type": "array",9436                 "title": "MCP allowed tools",9437                 "description": "A string array of allowed tool names",9438                 "items": {9439                  "type": {9440                   "$comment": "depth-limited"9441                  }9442                 }9443                },9444                {9445                 "type": {9446                  "$comment": "depth-limited"9447                 },9448                 "title": {9449                  "$comment": "depth-limited"9450                 },9451                 "description": {9452                  "$comment": "depth-limited"9453                 },9454                 "properties": {9455                  "$comment": "depth-limited"9456                 },9457                 "required": {9458                  "$comment": "depth-limited"9459                 },9460                 "additionalProperties": {9461                  "$comment": "depth-limited"9462                 }9463                }9464               ]9465              },9466              {9467               "type": "null"9468              }9469             ]9470            },9471            "allowed_callers": {9472             "anyOf": [9473              {9474               "type": "array",9475               "minItems": 1,9476               "items": {9477                "type": "string",9478                "enum": [9479                 {9480                  "$comment": "depth-limited"9481                 },9482                 {9483                  "$comment": "depth-limited"9484                 }9485                ]9486               },9487               "description": "The tool invocation context(s)."9488              },9489              {9490               "type": "null"9491              }9492             ]9493            },9494            "require_approval": {9495             "anyOf": [9496              {9497               "description": "Specify which of the MCP server's tools require approval.",9498               "oneOf": [9499                {9500                 "type": "object",9501                 "title": "MCP tool approval filter",9502                 "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",9503                 "properties": {9504                  "always": {9505                   "$comment": "depth-limited"9506                  },9507                  "never": {9508                   "$comment": "depth-limited"9509                  }9510                 },9511                 "additionalProperties": false9512                },9513                {9514                 "type": "string",9515                 "title": "MCP tool approval setting",9516                 "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",9517                 "enum": [9518                  {9519                   "$comment": "depth-limited"9520                  },9521                  {9522                   "$comment": "depth-limited"9523                  }9524                 ]9525                }9526               ],9527               "default": "always"9528              },9529              {9530               "type": "null"9531              }9532             ]9533            },9534            "defer_loading": {9535             "type": "boolean",9536             "description": "Whether this MCP tool is deferred and discovered via tool search.\n"9537            }9538           },9539           "required": [9540            "type",9541            "server_label"9542           ]9543          },9544          {9545           "type": "object",9546           "title": "Code interpreter",9547           "description": "A tool that runs Python code to help generate a response to a prompt.\n",9548           "properties": {9549            "type": {9550             "type": "string",9551             "enum": [9552              "code_interpreter"9553             ],9554             "description": "The type of the code interpreter tool. Always `code_interpreter`.\n",9555             "x-stainless-const": true9556            },9557            "container": {9558             "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",9559             "oneOf": [9560              {9561               "type": "string",9562               "description": "The container ID."9563              },9564              {9565               "properties": {9566                "type": {9567                 "type": {9568                  "$comment": "depth-limited"9569                 },9570                 "enum": {9571                  "$comment": "depth-limited"9572                 },9573                 "description": {9574                  "$comment": "depth-limited"9575                 },9576                 "default": {9577                  "$comment": "depth-limited"9578                 },9579                 "x-stainless-const": {9580                  "$comment": "depth-limited"9581                 }9582                },9583                "file_ids": {9584                 "items": {9585                  "$comment": "depth-limited"9586                 },9587                 "type": {9588                  "$comment": "depth-limited"9589                 },9590                 "maxItems": {9591                  "$comment": "depth-limited"9592                 },9593                 "description": {9594                  "$comment": "depth-limited"9595                 }9596                },9597                "memory_limit": {9598                 "anyOf": {9599                  "$comment": "depth-limited"9600                 }9601                },9602                "network_policy": {9603                 "oneOf": {9604                  "$comment": "depth-limited"9605                 },9606                 "description": {9607                  "$comment": "depth-limited"9608                 },9609                 "discriminator": {9610                  "$comment": "depth-limited"9611                 }9612                }9613               },9614               "type": "object",9615               "required": [9616                "type"9617               ],9618               "title": "CodeInterpreterToolAuto",9619               "description": "Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on."9620              }9621             ]9622            },9623            "allowed_callers": {9624             "anyOf": [9625              {9626               "type": "array",9627               "minItems": 1,9628               "items": {9629                "type": "string",9630                "enum": [9631                 {9632                  "$comment": "depth-limited"9633                 },9634                 {9635                  "$comment": "depth-limited"9636                 }9637                ]9638               },9639               "description": "The tool invocation context(s)."9640              },9641              {9642               "type": "null"9643              }9644             ]9645            }9646           },9647           "required": [9648            "type",9649            "container"9650           ]9651          },9652          {9653           "properties": {9654            "type": {9655             "type": "string",9656             "enum": [9657              "programmatic_tool_calling"9658             ],9659             "description": "The type of the tool. Always `programmatic_tool_calling`.",9660             "default": "programmatic_tool_calling",9661             "x-stainless-const": true9662            }9663           },9664           "type": "object",9665           "required": [9666            "type"9667           ]9668          },9669          {9670           "type": "object",9671           "title": "Image generation tool",9672           "description": "A tool that generates images using the GPT image models.\n",9673           "properties": {9674            "type": {9675             "type": "string",9676             "enum": [9677              "image_generation"9678             ],9679             "description": "The type of the image generation tool. Always `image_generation`.\n",9680             "x-stainless-const": true9681            },9682            "model": {9683             "anyOf": [9684              {9685               "type": "string"9686              },9687              {9688               "type": "string",9689               "enum": [9690                "gpt-image-1",9691                "gpt-image-1-mini",9692                "gpt-image-1.5",9693                "gpt-image-2",9694                "gpt-image-2-2026-04-21",9695                "gpt-image-2.5-sunburst",9696                "gpt-image-2.5-sunburst-2026-09-08",9697                "gpt-image-2.5-flare",9698                "gpt-image-2.5-flare-2026-09-08"9699               ],9700               "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",9701               "default": "gpt-image-1"9702              }9703             ]9704            },9705            "quality": {9706             "type": "string",9707             "enum": [9708              "low",9709              "medium",9710              "high",9711              "xhigh",9712              "max",9713              "auto"9714             ],9715             "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",9716             "default": "auto"9717            },9718            "size": {9719             "anyOf": [9720              {9721               "type": "string"9722              },9723              {9724               "type": "string",9725               "enum": [9726                "1024x1024",9727                "1024x1536",9728                "1536x1024",9729                "auto"9730               ]9731              }9732             ],9733             "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`.",9734             "default": "auto"9735            },9736            "output_format": {9737             "type": "string",9738             "enum": [9739              "png",9740              "webp",9741              "jpeg"9742             ],9743             "description": "The output format of the generated image. One of `png`, `webp`, or\n`jpeg`. Default: `png`.\n",9744             "default": "png"9745            },9746            "output_compression": {9747             "type": "integer",9748             "minimum": 0,9749             "maximum": 100,9750             "description": "Compression level for the output image. Default: 100.\n",9751             "default": 1009752            },9753            "moderation": {9754             "type": "string",9755             "enum": [9756              "auto",9757              "low"9758             ],9759             "description": "Moderation level for the generated image. Default: `auto`.\n",9760             "default": "auto"9761            },9762            "background": {9763             "type": "string",9764             "enum": [9765              "transparent",9766              "opaque",9767              "auto"9768             ],9769             "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",9770             "default": "auto"9771            },9772            "input_fidelity": {9773             "anyOf": [9774              {9775               "type": "string",9776               "enum": [9777                "high",9778                "low"9779               ],9780               "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`."9781              },9782              {9783               "type": "null"9784              }9785             ]9786            },9787            "input_image_mask": {9788             "type": "object",9789             "description": "Optional mask for inpainting. Contains `image_url`\n(string, optional) and `file_id` (string, optional).\n",9790             "properties": {9791              "image_url": {9792               "type": "string",9793               "description": "Base64-encoded mask image.\n"9794              },9795              "file_id": {9796               "type": "string",9797               "description": "File ID for the mask image.\n"9798              }9799             },9800             "required": [],9801             "additionalProperties": false9802            },9803            "partial_images": {9804             "type": "integer",9805             "minimum": 0,9806             "maximum": 3,9807             "description": "Number of partial images to generate in streaming mode, from 0 (default value) to 3.\n",9808             "default": 09809            },9810            "action": {9811             "type": "string",9812             "enum": [9813              "generate",9814              "edit",9815              "auto"9816             ]9817            }9818           },9819           "required": [9820            "type"9821           ]9822          },9823          {9824           "properties": {9825            "type": {9826             "type": "string",9827             "enum": [9828              "local_shell"9829             ],9830             "description": "The type of the local shell tool. Always `local_shell`.",9831             "default": "local_shell",9832             "x-stainless-const": true9833            }9834           },9835           "type": "object",9836           "required": [9837            "type"9838           ],9839           "title": "Local shell tool",9840           "description": "A tool that allows the model to execute shell commands in a local environment."9841          },9842          {9843           "properties": {9844            "type": {9845             "type": "string",9846             "enum": [9847              "shell"9848             ],9849             "description": "The type of the shell tool. Always `shell`.",9850             "default": "shell",9851             "x-stainless-const": true9852            },9853            "environment": {9854             "anyOf": [9855              {9856               "oneOf": [9857                {9858                 "properties": {9859                  "$comment": "depth-limited"9860                 },9861                 "type": {9862                  "$comment": "depth-limited"9863                 },9864                 "required": {9865                  "$comment": "depth-limited"9866                 }9867                },9868                {9869                 "properties": {9870                  "$comment": "depth-limited"9871                 },9872                 "type": {9873                  "$comment": "depth-limited"9874                 },9875                 "required": {9876                  "$comment": "depth-limited"9877                 }9878                },9879                {9880                 "properties": {9881                  "$comment": "depth-limited"9882                 },9883                 "type": {9884                  "$comment": "depth-limited"9885                 },9886                 "required": {9887                  "$comment": "depth-limited"9888                 }9889                }9890               ],9891               "discriminator": {9892                "propertyName": "type"9893               }9894              },9895              {9896               "type": "null"9897              }9898             ]9899            },9900            "allowed_callers": {9901             "anyOf": [9902              {9903               "items": {9904                "type": "string",9905                "enum": [9906                 {9907                  "$comment": "depth-limited"9908                 },9909                 {9910                  "$comment": "depth-limited"9911                 }9912                ]9913               },9914               "type": "array",9915               "minItems": 1,9916               "description": "The tool invocation context(s)."9917              },9918              {9919               "type": "null"9920              }9921             ]9922            }9923           },9924           "type": "object",9925           "required": [9926            "type"9927           ],9928           "title": "Shell tool",9929           "description": "A tool that allows the model to execute shell commands."9930          },9931          {9932           "properties": {9933            "type": {9934             "type": "string",9935             "enum": [9936              "custom"9937             ],9938             "description": "The type of the custom tool. Always `custom`.",9939             "default": "custom",9940             "x-stainless-const": true9941            },9942            "name": {9943             "type": "string",9944             "description": "The name of the custom tool, used to identify it in tool calls."9945            },9946            "async": {9947             "type": "boolean",9948             "description": "Whether the tool response can be returned asynchronously versus immediately returned on next response creation."9949            },9950            "description": {9951             "type": "string",9952             "description": "Optional description of the custom tool, used to provide more context."9953            },9954            "format": {9955             "oneOf": [9956              {9957               "properties": {9958                "type": {9959                 "type": {9960                  "$comment": "depth-limited"9961                 },9962                 "enum": {9963                  "$comment": "depth-limited"9964                 },9965                 "description": {9966                  "$comment": "depth-limited"9967                 },9968                 "default": {9969                  "$comment": "depth-limited"9970                 },9971                 "x-stainless-const": {9972                  "$comment": "depth-limited"9973                 }9974                }9975               },9976               "type": "object",9977               "required": [9978                "type"9979               ],9980               "title": "Text format",9981               "description": "Unconstrained free-form text."9982              },9983              {9984               "properties": {9985                "type": {9986                 "type": {9987                  "$comment": "depth-limited"9988                 },9989                 "enum": {9990                  "$comment": "depth-limited"9991                 },9992                 "description": {9993                  "$comment": "depth-limited"9994                 },9995                 "default": {9996                  "$comment": "depth-limited"9997                 },9998                 "x-stainless-const": {9999                  "$comment": "depth-limited"10000                 }10001                },10002                "syntax": {10003                 "$comment": "depth-limited"10004                },10005                "definition": {10006                 "type": {10007                  "$comment": "depth-limited"10008                 },10009                 "description": {10010                  "$comment": "depth-limited"10011                 }10012                }10013               },10014               "type": "object",10015               "required": [10016                "type",10017                "syntax",10018                "definition"10019               ],10020               "title": "Grammar format",10021               "description": "A grammar defined by the user."10022              }10023             ],10024             "description": "The input format for the custom tool. Default is unconstrained text.",10025             "discriminator": {10026              "propertyName": "type"10027             }10028            },10029            "defer_loading": {10030             "type": "boolean",10031             "description": "Whether this tool should be deferred and discovered via tool search."10032            },10033            "allowed_callers": {10034             "anyOf": [10035              {10036               "items": {10037                "type": "string",10038                "enum": [10039                 {10040                  "$comment": "depth-limited"10041                 },10042                 {10043                  "$comment": "depth-limited"10044                 }10045                ]10046               },10047               "type": "array",10048               "minItems": 1,10049               "description": "The tool invocation context(s)."10050              },10051              {10052               "type": "null"10053              }10054             ]10055            }10056           },10057           "type": "object",10058           "required": [10059            "type",10060            "name"10061           ],10062           "title": "Custom tool",10063           "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)"10064          },10065          {10066           "properties": {10067            "type": {10068             "type": "string",10069             "enum": [10070              "namespace"10071             ],10072             "description": "The type of the tool. Always `namespace`.",10073             "default": "namespace",10074             "x-stainless-const": true10075            },10076            "name": {10077             "type": "string",10078             "minLength": 1,10079             "description": "The namespace name used in tool calls (for example, `crm`)."10080            },10081            "description": {10082             "type": "string",10083             "description": "A description of the namespace shown to the model."10084            },10085            "tools": {10086             "items": {10087              "oneOf": [10088               {10089                "properties": {10090                 "name": {10091                  "$comment": "depth-limited"10092                 },10093                 "description": {10094                  "$comment": "depth-limited"10095                 },10096                 "parameters": {10097                  "$comment": "depth-limited"10098                 },10099                 "strict": {10100                  "$comment": "depth-limited"10101                 },10102                 "type": {10103                  "$comment": "depth-limited"10104                 },10105                 "async": {10106                  "$comment": "depth-limited"10107                 },10108                 "output_schema": {10109                  "$comment": "depth-limited"10110                 },10111                 "defer_loading": {10112                  "$comment": "depth-limited"10113                 },10114                 "allowed_callers": {10115                  "$comment": "depth-limited"10116                 }10117                },10118                "type": "object",10119                "required": [10120                 {10121                  "$comment": "depth-limited"10122                 },10123                 {10124                  "$comment": "depth-limited"10125                 }10126                ]10127               },10128               {10129                "properties": {10130                 "type": {10131                  "$comment": "depth-limited"10132                 },10133                 "name": {10134                  "$comment": "depth-limited"10135                 },10136                 "async": {10137                  "$comment": "depth-limited"10138                 },10139                 "description": {10140                  "$comment": "depth-limited"10141                 },10142                 "format": {10143                  "$comment": "depth-limited"10144                 },10145                 "defer_loading": {10146                  "$comment": "depth-limited"10147                 },10148                 "allowed_callers": {10149                  "$comment": "depth-limited"10150                 }10151                },10152                "type": "object",10153                "required": [10154                 {10155                  "$comment": "depth-limited"10156                 },10157                 {10158                  "$comment": "depth-limited"10159                 }10160                ],10161                "title": "Custom tool",10162                "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)"10163               }10164              ],10165              "description": "A function or custom tool that belongs to a namespace.",10166              "discriminator": {10167               "propertyName": "type"10168              }10169             },10170             "type": "array",10171             "minItems": 1,10172             "description": "The function/custom tools available inside this namespace."10173            }10174           },10175           "type": "object",10176           "required": [10177            "type",10178            "name",10179            "description",10180            "tools"10181           ],10182           "title": "Namespace",10183           "description": "Groups function/custom tools under a shared namespace."10184          },10185          {10186           "properties": {10187            "type": {10188             "type": "string",10189             "enum": [10190              "tool_search"10191             ],10192             "description": "The type of the tool. Always `tool_search`.",10193             "default": "tool_search",10194             "x-stainless-const": true10195            },10196            "execution": {10197             "type": "string",10198             "enum": [10199              "server",10200              "client"10201             ]10202            },10203            "description": {10204             "anyOf": [10205              {10206               "type": "string",10207               "description": "Description shown to the model for a client-executed tool search tool."10208              },10209              {10210               "type": "null"10211              }10212             ]10213            },10214            "parameters": {10215             "anyOf": [10216              {10217               "properties": {},10218               "type": "object",10219               "required": []10220              },10221              {10222               "type": "null"10223              }10224             ]10225            }10226           },10227           "type": "object",10228           "required": [10229            "type"10230           ],10231           "title": "Tool search tool",10232           "description": "Hosted or BYOT tool search configuration for deferred tools."10233          },10234          {10235           "properties": {10236            "type": {10237             "type": "string",10238             "enum": [10239              "web_search_preview",10240              "web_search_preview_2025_03_11"10241             ],10242             "description": "The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`.",10243             "default": "web_search_preview",10244             "x-stainless-const": true10245            },10246            "user_location": {10247             "anyOf": [10248              {10249               "properties": {10250                "type": {10251                 "type": {10252                  "$comment": "depth-limited"10253                 },10254                 "enum": {10255                  "$comment": "depth-limited"10256                 },10257                 "description": {10258                  "$comment": "depth-limited"10259                 },10260                 "default": {10261                  "$comment": "depth-limited"10262                 },10263                 "x-stainless-const": {10264                  "$comment": "depth-limited"10265                 }10266                },10267                "country": {10268                 "anyOf": {10269                  "$comment": "depth-limited"10270                 }10271                },10272                "region": {10273                 "anyOf": {10274                  "$comment": "depth-limited"10275                 }10276                },10277                "city": {10278                 "anyOf": {10279                  "$comment": "depth-limited"10280                 }10281                },10282                "timezone": {10283                 "anyOf": {10284                  "$comment": "depth-limited"10285                 }10286                }10287               },10288               "type": "object",10289               "required": [10290                "type"10291               ]10292              },10293              {10294               "type": "null"10295              }10296             ]10297            },10298            "search_context_size": {10299             "type": "string",10300             "enum": [10301              "low",10302              "medium",10303              "high"10304             ]10305            },10306            "search_content_types": {10307             "items": {10308              "type": "string",10309              "enum": [10310               "text",10311               "image"10312              ]10313             },10314             "type": "array"10315            }10316           },10317           "type": "object",10318           "required": [10319            "type"10320           ],10321           "title": "Web search preview",10322           "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)."10323          },10324          {10325           "properties": {10326            "type": {10327             "type": "string",10328             "enum": [10329              "apply_patch"10330             ],10331             "description": "The type of the tool. Always `apply_patch`.",10332             "default": "apply_patch",10333             "x-stainless-const": true10334            },10335            "allowed_callers": {10336             "anyOf": [10337              {10338               "items": {10339                "type": "string",10340                "enum": [10341                 {10342                  "$comment": "depth-limited"10343                 },10344                 {10345                  "$comment": "depth-limited"10346                 }10347                ]10348               },10349               "type": "array",10350               "minItems": 1,10351               "description": "The tool invocation context(s)."10352              },10353              {10354               "type": "null"10355              }10356             ]10357            }10358           },10359           "type": "object",10360           "required": [10361            "type"10362           ],10363           "title": "Apply patch tool",10364           "description": "Allows the assistant to create, delete, or update files using unified diffs."10365          }10366         ]10367        },10368        "type": "array",10369        "description": "The loaded tool definitions returned by tool search."10370       },10371       "status": {10372        "type": "string",10373        "enum": [10374         "in_progress",10375         "completed",10376         "incomplete"10377        ]10378       },10379       "created_by": {10380        "type": "string",10381        "description": "The identifier of the actor that created the item."10382       }10383      },10384      "type": "object",10385      "required": [10386       "type",10387       "id",10388       "call_id",10389       "execution",10390       "tools",10391       "status"10392      ]10393     }10394    }10395   ],10396   "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."10397  },10398  "billing": {10399   "model": "Token billing only; saves input tokens by not sending deferred definitions up front.",10400   "source": "https://developers.openai.com/api/docs/pricing#built-in-tools"10401  },10402  "limitations": [10403   "Responses API: only gpt-5.4 and later models (gpt-5.4-nano page does not list tool_search).",10404   "`additional_tools` input item can inject tools mid-conversation."10405  ],10406  "security": [10407   "Client-executed search lets the app decide which tools exist per turn — keep an allowlist."10408  ],10409  "beta_header": null,10410  "status": [10411   "DOCUMENTED",10412   "LIVE_VERIFIED"10413  ],10414  "examples": {10415   "curl": "examples/openai/tools/tool-search/tool_search.sh",10416   "python": "examples/openai/tools/tool-search/tool_search.py",10417   "typescript": "examples/openai/tools/tool-search/tool_search.ts"10418  },10419  "verification": {10420   "hosted": {10421    "method": "live_api",10422    "verified_at": "2026-09-18",10423    "result": "success",10424    "http_status": 200,10425    "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'}"10426   }10427  },10428  "sources": [10429   {10430    "url": "https://developers.openai.com/api/docs/guides/tools-tool-search",10431    "retrieved_at": "2026-09-18"10432   },10433   {10434    "url": "https://developers.openai.com/api/reference/resources/responses/methods/create",10435    "retrieved_at": "2026-09-18"10436   },10437   {10438    "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)",10439    "retrieved_at": "2026-09-18"10440   }10441  ],10442  "last_verified": "2026-09-18",10443  "_fragment": "generated/fragments/tools/openai-tools.json"10444 },10445 {10446  "provider": "openai",10447  "name": "Programmatic Tool Calling",10448  "type": "programmatic_tool_calling",10449  "category": "hosted",10450  "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}`.",10451  "compatible_models": [],10452  "compatible_endpoints": [10453   "POST /v1/responses",10454   "Agents API (enabled by default)"10455  ],10456  "parameters_schema": {10457   "properties": {10458    "type": {10459     "type": "string",10460     "enum": [10461      "programmatic_tool_calling"10462     ],10463     "description": "The type of the tool. Always `programmatic_tool_calling`.",10464     "default": "programmatic_tool_calling",10465     "x-stainless-const": true10466    }10467   },10468   "type": "object",10469   "required": [10470    "type"10471   ]10472  },10473  "tool_choice_support": {10474   "modes": [10475    "auto",10476    "required",10477    "none"10478   ],10479   "specific": {10480    "type": "programmatic_tool_calling"10481   }10482  },10483  "parallel": {10484   "supported": true,10485   "notes": "Program can call tools in parallel inside the runtime."10486  },10487  "streaming_events": [10488   "response.output_item.added",10489   "response.output_item.done"10490  ],10491  "result_shape": {10492   "items": [10493    {10494     "schema_name": "FunctionToolCall",10495     "type": "function_call",10496     "schema": {10497      "type": "object",10498      "title": "Function tool call",10499      "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",10500      "properties": {10501       "id": {10502        "type": "string",10503        "description": "The unique ID of the function tool call.\n"10504       },10505       "type": {10506        "type": "string",10507        "enum": [10508         "function_call"10509        ],10510        "description": "The type of the function tool call. Always `function_call`.\n",10511        "x-stainless-const": true10512       },10513       "call_id": {10514        "type": "string",10515        "description": "The unique ID of the function tool call generated by the model.\n"10516       },10517       "caller": {10518        "anyOf": [10519         {10520          "oneOf": [10521           {10522            "properties": {10523             "type": {10524              "type": "string",10525              "enum": [10526               "direct"10527              ],10528              "default": "direct",10529              "x-stainless-const": true10530             }10531            },10532            "type": "object",10533            "required": [10534             "type"10535            ]10536           },10537           {10538            "properties": {10539             "type": {10540              "type": "string",10541              "enum": [10542               "program"10543              ],10544              "default": "program",10545              "x-stainless-const": true10546             },10547             "caller_id": {10548              "type": "string",10549              "description": "The call ID of the program item that produced this tool call."10550             }10551            },10552            "type": "object",10553            "required": [10554             "type",10555             "caller_id"10556            ]10557           }10558          ],10559          "description": "The execution context that produced this tool call.",10560          "discriminator": {10561           "propertyName": "type"10562          }10563         },10564         {10565          "type": "null"10566         }10567        ]10568       },10569       "namespace": {10570        "type": "string",10571        "description": "The namespace of the function to run.\n"10572       },10573       "name": {10574        "type": "string",10575        "description": "The name of the function to run.\n"10576       },10577       "arguments": {10578        "type": "string",10579        "description": "A JSON string of the arguments to pass to the function.\n"10580       },10581       "status": {10582        "type": "string",10583        "description": "The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.\n",10584        "enum": [10585         "in_progress",10586         "completed",10587         "incomplete"10588        ]10589       },10590       "async": {10591        "type": "boolean",10592        "description": "Whether the function tool call runs asynchronously.\n"10593       }10594      },10595      "required": [10596       "type",10597       "call_id",10598       "name",10599       "arguments"10600      ]10601     }10602    }10603   ],10604   "summary": "Standard Responses object; nested `function_call` items with caller.type = program; results returned as `function_call_output` with the same caller."10605  },10606  "billing": {10607   "model": "Token billing only.",10608   "source": "https://developers.openai.com/api/docs/pricing#built-in-tools"10609  },10610  "limitations": [10611   "Check the model page before enabling; not listed on gpt-5.4-nano.",10612   "Supports ZDR without a persistent container.",10613   "Not live-tested (no cheap eligible model identified)."10614  ],10615  "security": [10616   "Require application-level approval for high-impact actions regardless of caller; MCP `require_approval` can pause the program."10617  ],10618  "beta_header": null,10619  "status": [10620   "DOCUMENTED",10621   "UNVERIFIED"10622  ],10623  "examples": {},10624  "verification": {10625   "docs": {10626    "method": "docs_only",10627    "verified_at": "2026-09-18",10628    "result": "success",10629    "http_status": 0,10630    "request_note": "not called"10631   }10632  },10633  "sources": [10634   {10635    "url": "https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling",10636    "retrieved_at": "2026-09-18"10637   },10638   {10639    "url": "https://developers.openai.com/api/reference/resources/responses/methods/create",10640    "retrieved_at": "2026-09-18"10641   },10642   {10643    "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)",10644    "retrieved_at": "2026-09-18"10645   }10646  ],10647  "last_verified": "2026-09-18",10648  "_fragment": "generated/fragments/tools/openai-tools.json"10649 },10650 {10651  "provider": "openai",10652  "name": "Web search (hosted)",10653  "type": "web_search",10654  "category": "hosted",10655  "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]).",10656  "compatible_models": [10657   "chat-latest",10658   "gpt-4.1",10659   "gpt-4.1-mini",10660   "gpt-4o",10661   "gpt-4o-mini",10662   "gpt-4o-mini-audio-preview",10663   "gpt-5",10664   "gpt-5-chat-latest",10665   "gpt-5-codex",10666   "gpt-5-mini",10667   "gpt-5-nano",10668   "gpt-5-pro",10669   "gpt-5.1",10670   "gpt-5.1-chat-latest",10671   "gpt-5.1-codex",10672   "gpt-5.1-codex-max",10673   "gpt-5.1-codex-mini",10674   "gpt-5.2",10675   "gpt-5.2-chat-latest",10676   "gpt-5.2-codex",10677   "gpt-5.2-pro",10678   "gpt-5.3-chat-latest",10679   "gpt-5.3-codex",10680   "gpt-5.4",10681   "gpt-5.4-mini",10682   "gpt-5.4-nano",10683   "gpt-5.4-pro",10684   "gpt-5.5",10685   "gpt-5.5-pro",10686   "gpt-5.6-cyber",10687   "gpt-5.6-luna",10688   "gpt-5.6-sol",10689   "gpt-5.6-terra",10690   "gpt-6-astra",10691   "gpt-daybreak-blue-latest",10692   "gpt-daybreak-red-latest",10693   "gpt-oss-120b",10694   "gpt-oss-20b",10695   "o3",10696   "o3-deep-research",10697   "o3-pro",10698   "o4-mini",10699   "o4-mini-deep-research"10700  ],10701  "compatible_endpoints": [10702   "POST /v1/responses",10703   "Realtime/Live (web_search tool in Live sessions)",10704   "Agents API"10705  ],10706  "parameters_schema": {10707   "type": "object",10708   "title": "Web search",10709   "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",10710   "properties": {10711    "type": {10712     "type": "string",10713     "enum": [10714      "web_search",10715      "web_search_2025_08_26"10716     ],10717     "description": "The type of the web search tool. One of `web_search` or `web_search_2025_08_26`.",10718     "default": "web_search"10719    },10720    "external_web_access": {10721     "type": "boolean",10722     "default": true,10723     "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."10724    },10725    "filters": {10726     "anyOf": [10727      {10728       "type": "object",10729       "description": "Filters for the search.\n",10730       "properties": {10731        "allowed_domains": {10732         "anyOf": [10733          {10734           "type": "array",10735           "title": "Allowed domains for the search.",10736           "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",10737           "items": {10738            "type": "string",10739            "description": "Allowed domain for the search."10740           },10741           "default": []10742          },10743          {10744           "type": "null"10745          }10746         ]10747        }10748       }10749      },10750      {10751       "type": "null"10752      }10753     ]10754    },10755    "user_location": {10756     "anyOf": [10757      {10758       "type": "object",10759       "title": "Web search approximate location",10760       "description": "The approximate location of the user.\n",10761       "properties": {10762        "type": {10763         "type": "string",10764         "enum": [10765          "approximate"10766         ],10767         "description": "The type of location approximation. Always `approximate`.",10768         "default": "approximate",10769         "x-stainless-const": true10770        },10771        "country": {10772         "anyOf": [10773          {10774           "type": "string",10775           "description": "The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`."10776          },10777          {10778           "type": "null"10779          }10780         ]10781        },10782        "region": {10783         "anyOf": [10784          {10785           "type": "string",10786           "description": "Free text input for the region of the user, e.g. `California`."10787          },10788          {10789           "type": "null"10790          }10791         ]10792        },10793        "city": {10794         "anyOf": [10795          {10796           "type": "string",10797           "description": "Free text input for the city of the user, e.g. `San Francisco`."10798          },10799          {10800           "type": "null"10801          }10802         ]10803        },10804        "timezone": {10805         "anyOf": [10806          {10807           "type": "string",10808           "description": "The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`."10809          },10810          {10811           "type": "null"10812          }10813         ]10814        }10815       }10816      },10817      {10818       "type": "null"10819      }10820     ]10821    },10822    "search_context_size": {10823     "type": "string",10824     "enum": [10825      "low",10826      "medium",10827      "high"10828     ],10829     "default": "medium",10830     "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."10831    }10832   },10833   "required": [10834    "type"10835   ]10836  },10837  "tool_choice_support": {10838   "modes": [10839    "none",10840    "auto",10841    "required"10842   ],10843   "allowed_tools": {10844    "type": "allowed_tools",10845    "mode": "auto|required",10846    "tools": [10847     "{type,name,...}"10848    ]10849   },10850   "specific": {10851    "type": "web_search"10852   },10853   "note": "Live: tool_choice {type: web_search} accepted and echoed back as {type: web_search_preview}; spec ToolChoiceTypes enum only lists web_search_preview."10854  },10855  "parallel": {10856   "supported": false,10857   "notes": "Built-in tools are not batched with parallel function calls."10858  },10859  "streaming_events": [10860   "response.output_item.added",10861   "response.web_search_call.in_progress",10862   "response.web_search_call.searching",10863   "response.web_search_call.completed",10864   "response.output_item.done",10865   "response.output_text.annotation.added"10866  ],10867  "result_shape": {10868   "items": [10869    {10870     "schema_name": "WebSearchToolCall",10871     "type": "web_search_call",10872     "schema": {10873      "type": "object",10874      "title": "Web search tool call",10875      "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",10876      "properties": {10877       "id": {10878        "type": "string",10879        "description": "The unique ID of the web search tool call.\n"10880       },10881       "type": {10882        "type": "string",10883        "enum": [10884         "web_search_call"10885        ],10886        "description": "The type of the web search tool call. Always `web_search_call`.\n",10887        "x-stainless-const": true10888       },10889       "status": {10890        "type": "string",10891        "enum": [10892         "in_progress",10893         "searching",10894         "completed",10895         "failed",10896         "incomplete"10897        ]10898       },10899       "action": {10900        "type": "object",10901        "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",10902        "oneOf": [10903         {10904          "type": "object",10905          "title": "Search action",10906          "description": "Action type \"search\" - Performs a web search query.\n",10907          "properties": {10908           "type": {10909            "type": "string",10910            "enum": [10911             "search"10912            ],10913            "description": "The action type.\n",10914            "x-stainless-const": true10915           },10916           "query": {10917            "type": "string",10918            "deprecated": true,10919            "description": "The search query.\n"10920           },10921           "queries": {10922            "type": "array",10923            "title": "Search queries",10924            "description": "The search queries.\n",10925            "items": {10926             "type": "string",10927             "description": "A search query.\n"10928            }10929           },10930           "sources": {10931            "type": "array",10932            "title": "Web search sources",10933            "description": "The sources used in the search.\n",10934            "items": {10935             "type": "object",10936             "title": "Web search source",10937             "description": "A source used in the search.\n",10938             "properties": {10939              "type": {10940               "type": "string",10941               "enum": [10942                "url"10943               ],10944               "description": "The type of source. Always `url`.\n",10945               "x-stainless-const": true10946              },10947              "url": {10948               "type": "string",10949               "format": "uri",10950               "description": "The URL of the source.\n"10951              }10952             },10953             "required": [10954              "type",10955              "url"10956             ]10957            }10958           }10959          },10960          "required": [10961           "type"10962          ]10963         },10964         {10965          "type": "object",10966          "title": "Open page action",10967          "description": "Action type \"open_page\" - Opens a specific URL from search results.\n",10968          "properties": {10969           "type": {10970            "type": "string",10971            "enum": [10972             "open_page"10973            ],10974            "description": "The action type.\n",10975            "x-stainless-const": true10976           },10977           "url": {10978            "description": "The URL opened by the model.\n",10979            "anyOf": [10980             {10981              "type": "string",10982              "format": "uri"10983             },10984             {10985              "type": "null"10986             }10987            ]10988           }10989          },10990          "required": [10991           "type"10992          ]10993         },10994         {10995          "type": "object",10996          "title": "Find action",10997          "description": "Action type \"find_in_page\": Searches for a pattern within a loaded page.\n",10998          "properties": {10999           "type": {11000            "type": "string",11001            "enum": [11002             "find_in_page"11003            ],11004            "description": "The action type.\n",11005            "x-stainless-const": true11006           },11007           "url": {11008            "type": "string",11009            "format": "uri",11010            "description": "The URL of the page searched for the pattern.\n"11011           },11012           "pattern": {11013            "type": "string",11014            "description": "The pattern or text to search for within the page.\n"11015           }11016          },11017          "required": [11018           "type",11019           "url",11020           "pattern"11021          ]11022         }11023        ],11024        "discriminator": {11025         "propertyName": "type"11026        }11027       }11028      },11029      "required": [11030       "id",11031       "type",11032       "status",11033       "action"11034      ]11035     }11036    }11037   ],11038   "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}."11039  },11040  "billing": {11041   "per_call": "$10.00 / 1k calls (web_search, all models; image web search same) + search content tokens billed at model rates",11042   "preview": "$10/1k (reasoning models) or $25/1k with free content tokens (non-reasoning)",11043   "source": "https://developers.openai.com/api/docs/pricing#built-in-tools"11044  },11045  "limitations": [11046   "Search context window limited to 128k even on 1M models.",11047   "Not supported with gpt-5 `minimal` reasoning; gpt-5.4 reasoning `none` may degrade quality.",11048   "Up to 100 allowed_domains / 100 blocked_domains.",11049   "Rate limits = underlying model tiered limits.",11050   "`web_search_preview` ignores `external_web_access`, no `filters`/`return_token_budget`."11051  ],11052  "security": [11053   "Treat page content as untrusted (prompt injection); prefer `filters.allowed_domains` for sensitive workflows.",11054   "`external_web_access: false` runs cache-only."11055  ],11056  "beta_header": null,11057  "status": [11058   "DOCUMENTED",11059   "LIVE_VERIFIED"11060  ],11061  "examples": {11062   "curl": "examples/openai/tools/web-search/web_search.sh",11063   "python": "examples/openai/tools/web-search/web_search.py",11064   "typescript": "examples/openai/tools/web-search/web_search.ts"11065  },11066  "verification": {11067   "forced_search": {11068    "method": "live_api",11069    "verified_at": "2026-09-18",11070    "result": "success",11071    "http_status": 200,11072    "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"11073   },11074   "auto_no_search": {11075    "method": "live_api",11076    "verified_at": "2026-09-18",11077    "result": "success",11078    "http_status": 200,11079    "request_note": "same prompt with tool_choice auto -> model answered without calling the tool (search is optional under auto)"11080   },11081   "max_output_tokens_64": {11082    "method": "live_api",11083    "verified_at": "2026-09-18",11084    "result": "failure",11085    "http_status": 200,11086    "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"11087   },11088   "streaming": {11089    "method": "live_api",11090    "verified_at": "2026-09-18",11091    "result": "success",11092    "http_status": 200,11093    "request_note": "response.web_search_call.in_progress -> searching -> completed"11094   }11095  },11096  "sources": [11097   {11098    "url": "https://developers.openai.com/api/docs/guides/tools-web-search",11099    "retrieved_at": "2026-09-18"11100   },11101   {11102    "url": "https://developers.openai.com/api/docs/pricing#built-in-tools",11103    "retrieved_at": "2026-09-18"11104   },11105   {11106    "url": "https://developers.openai.com/api/reference/resources/responses/methods/create",11107    "retrieved_at": "2026-09-18"11108   },11109   {11110    "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)",11111    "retrieved_at": "2026-09-18"11112   }11113  ],11114  "last_verified": "2026-09-18",11115  "_fragment": "generated/fragments/tools/openai-tools.json"11116 },11117 {11118  "provider": "openai",11119  "name": "Web search (dated snapshot 2025-08-26)",11120  "type": "web_search_2025_08_26",11121  "category": "hosted",11122  "description": "Dated alias of `web_search` (same schema, WebSearchTool).",11123  "compatible_models": [11124   "chat-latest",11125   "gpt-4.1",11126   "gpt-4.1-mini",11127   "gpt-4o",11128   "gpt-4o-mini",11129   "gpt-4o-mini-audio-preview",11130   "gpt-5",11131   "gpt-5-chat-latest",11132   "gpt-5-codex",11133   "gpt-5-mini",11134   "gpt-5-nano",11135   "gpt-5-pro",11136   "gpt-5.1",11137   "gpt-5.1-chat-latest",11138   "gpt-5.1-codex",11139   "gpt-5.1-codex-max",11140   "gpt-5.1-codex-mini",11141   "gpt-5.2",11142   "gpt-5.2-chat-latest",11143   "gpt-5.2-codex",11144   "gpt-5.2-pro",11145   "gpt-5.3-chat-latest",11146   "gpt-5.3-codex",11147   "gpt-5.4",11148   "gpt-5.4-mini",11149   "gpt-5.4-nano",11150   "gpt-5.4-pro",11151   "gpt-5.5",11152   "gpt-5.5-pro",11153   "gpt-5.6-cyber",11154   "gpt-5.6-luna",11155   "gpt-5.6-sol",11156   "gpt-5.6-terra",11157   "gpt-6-astra",11158   "gpt-daybreak-blue-latest",11159   "gpt-daybreak-red-latest",11160   "gpt-oss-120b",11161   "gpt-oss-20b",11162   "o3",11163   "o3-deep-research",11164   "o3-pro",11165   "o4-mini",11166   "o4-mini-deep-research"11167  ],11168  "compatible_endpoints": [11169   "POST /v1/responses"11170  ],11171  "parameters_schema": {11172   "type": "object",11173   "title": "Web search",11174   "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",11175   "properties": {11176    "type": {11177     "type": "string",11178     "enum": [11179      "web_search",11180      "web_search_2025_08_26"11181     ],11182     "description": "The type of the web search tool. One of `web_search` or `web_search_2025_08_26`.",11183     "default": "web_search"11184    },11185    "external_web_access": {11186     "type": "boolean",11187     "default": true,11188     "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."11189    },11190    "filters": {11191     "anyOf": [11192      {11193       "type": "object",11194       "description": "Filters for the search.\n",11195       "properties": {11196        "allowed_domains": {11197         "anyOf": [11198          {11199           "type": "array",11200           "title": "Allowed domains for the search.",11201           "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",11202           "items": {11203            "type": "string",11204            "description": "Allowed domain for the search."11205           },11206           "default": []11207          },11208          {11209           "type": "null"11210          }11211         ]11212        }11213       }11214      },11215      {11216       "type": "null"11217      }11218     ]11219    },11220    "user_location": {11221     "anyOf": [11222      {11223       "type": "object",11224       "title": "Web search approximate location",11225       "description": "The approximate location of the user.\n",11226       "properties": {11227        "type": {11228         "type": "string",11229         "enum": [11230          "approximate"11231         ],11232         "description": "The type of location approximation. Always `approximate`.",11233         "default": "approximate",11234         "x-stainless-const": true11235        },11236        "country": {11237         "anyOf": [11238          {11239           "type": "string",11240           "description": "The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`."11241          },11242          {11243           "type": "null"11244          }11245         ]11246        },11247        "region": {11248         "anyOf": [11249          {11250           "type": "string",11251           "description": "Free text input for the region of the user, e.g. `California`."11252          },11253          {11254           "type": "null"11255          }11256         ]11257        },11258        "city": {11259         "anyOf": [11260          {11261           "type": "string",11262           "description": "Free text input for the city of the user, e.g. `San Francisco`."11263          },11264          {11265           "type": "null"11266          }11267         ]11268        },11269        "timezone": {11270         "anyOf": [11271          {11272           "type": "string",11273           "description": "The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`."11274          },11275          {11276           "type": "null"11277          }11278         ]11279        }11280       }11281      },11282      {11283       "type": "null"11284      }11285     ]11286    },11287    "search_context_size": {11288     "type": "string",11289     "enum": [11290      "low",11291      "medium",11292      "high"11293     ],11294     "default": "medium",11295     "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."11296    }11297   },11298   "required": [11299    "type"11300   ]11301  },11302  "tool_choice_support": {11303   "modes": [11304    "none",11305    "auto",11306    "required"11307   ],11308   "allowed_tools": {11309    "type": "allowed_tools",11310    "mode": "auto|required",11311    "tools": [11312     "{type,name,...}"11313    ]11314   }11315  },11316  "parallel": {11317   "supported": false11318  },11319  "streaming_events": [],11320  "result_shape": {11321   "items": [11322    {11323     "schema_name": "WebSearchToolCall",11324     "type": "web_search_call",11325     "schema": {11326      "type": "object",11327      "title": "Web search tool call",11328      "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",11329      "properties": {11330       "id": {11331        "type": "string",11332        "description": "The unique ID of the web search tool call.\n"11333       },11334       "type": {11335        "type": "string",11336        "enum": [11337         "web_search_call"11338        ],11339        "description": "The type of the web search tool call. Always `web_search_call`.\n",11340        "x-stainless-const": true11341       },11342       "status": {11343        "type": "string",11344        "enum": [11345         "in_progress",11346         "searching",11347         "completed",11348         "failed",11349         "incomplete"11350        ]11351       },11352       "action": {11353        "type": "object",11354        "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",11355        "oneOf": [11356         {11357          "type": "object",11358          "title": "Search action",11359          "description": "Action type \"search\" - Performs a web search query.\n",11360          "properties": {11361           "type": {11362            "type": "string",11363            "enum": [11364             "search"11365            ],11366            "description": "The action type.\n",11367            "x-stainless-const": true11368           },11369           "query": {11370            "type": "string",11371            "deprecated": true,11372            "description": "The search query.\n"11373           },11374           "queries": {11375            "type": "array",11376            "title": "Search queries",11377            "description": "The search queries.\n",11378            "items": {11379             "type": "string",11380             "description": "A search query.\n"11381            }11382           },11383           "sources": {11384            "type": "array",11385            "title": "Web search sources",11386            "description": "The sources used in the search.\n",11387            "items": {11388             "type": "object",11389             "title": "Web search source",11390             "description": "A source used in the search.\n",11391             "properties": {11392              "type": {11393               "type": "string",11394               "enum": [11395                "url"11396               ],11397               "description": "The type of source. Always `url`.\n",11398               "x-stainless-const": true11399              },11400              "url": {11401               "type": "string",11402               "format": "uri",11403               "description": "The URL of the source.\n"11404              }11405             },11406             "required": [11407              "type",11408              "url"11409             ]11410            }11411           }11412          },11413          "required": [11414           "type"11415          ]11416         },11417         {11418          "type": "object",11419          "title": "Open page action",11420          "description": "Action type \"open_page\" - Opens a specific URL from search results.\n",11421          "properties": {11422           "type": {11423            "type": "string",11424            "enum": [11425             "open_page"11426            ],11427            "description": "The action type.\n",11428            "x-stainless-const": true11429           },11430           "url": {11431            "description": "The URL opened by the model.\n",11432            "anyOf": [11433             {11434              "type": "string",11435              "format": "uri"11436             },11437             {11438              "type": "null"11439             }11440            ]11441           }11442          },11443          "required": [11444           "type"11445          ]11446         },11447         {11448          "type": "object",11449          "title": "Find action",11450          "description": "Action type \"find_in_page\": Searches for a pattern within a loaded page.\n",11451          "properties": {11452           "type": {11453            "type": "string",11454            "enum": [11455             "find_in_page"11456            ],11457            "description": "The action type.\n",11458            "x-stainless-const": true11459           },11460           "url": {11461            "type": "string",11462            "format": "uri",11463            "description": "The URL of the page searched for the pattern.\n"11464           },11465           "pattern": {11466            "type": "string",11467            "description": "The pattern or text to search for within the page.\n"11468           }11469          },11470          "required": [11471           "type",11472           "url",11473           "pattern"11474          ]11475         }11476        ],11477        "discriminator": {11478         "propertyName": "type"11479        }11480       }11481      },11482      "required": [11483       "id",11484       "type",11485       "status",11486       "action"11487      ]11488     }11489    }11490   ],11491   "summary": "Same as web_search."11492  },11493  "billing": {11494   "per_call": "$10.00 / 1k calls (web_search, all models; image web search same) + search content tokens billed at model rates",11495   "preview": "$10/1k (reasoning models) or $25/1k with free content tokens (non-reasoning)",11496   "source": "https://developers.openai.com/api/docs/pricing#built-in-tools"11497  },11498  "limitations": [11499   "Search context window limited to 128k even on 1M models.",11500   "Not supported with gpt-5 `minimal` reasoning; gpt-5.4 reasoning `none` may degrade quality.",11501   "Up to 100 allowed_domains / 100 blocked_domains.",11502   "Rate limits = underlying model tiered limits.",11503   "`web_search_preview` ignores `external_web_access`, no `filters`/`return_token_budget`."11504  ],11505  "security": [11506   "Treat page content as untrusted (prompt injection); prefer `filters.allowed_domains` for sensitive workflows.",11507   "`external_web_access: false` runs cache-only."11508  ],11509  "beta_header": null,11510  "status": [11511   "DOCUMENTED",11512   "UNVERIFIED"11513  ],11514  "examples": {11515   "curl": "examples/openai/tools/web-search/web_search.sh",11516   "python": "examples/openai/tools/web-search/web_search.py",11517   "typescript": "examples/openai/tools/web-search/web_search.ts"11518  },11519  "verification": {11520   "docs": {11521    "method": "docs_only",11522    "verified_at": "2026-09-18",11523    "result": "success",11524    "http_status": 0,11525    "request_note": "alias not called"11526   }11527  },11528  "sources": [11529   {11530    "url": "https://developers.openai.com/api/docs/guides/tools-web-search",11531    "retrieved_at": "2026-09-18"11532   },11533   {11534    "url": "https://developers.openai.com/api/reference/resources/responses/methods/create",11535    "retrieved_at": "2026-09-18"11536   },11537   {11538    "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)",11539    "retrieved_at": "2026-09-18"11540   }11541  ],11542  "last_verified": "2026-09-18",11543  "_fragment": "generated/fragments/tools/openai-tools.json"11544 },11545 {11546  "provider": "openai",11547  "name": "Web search preview (legacy)",11548  "type": "web_search_preview",11549  "category": "hosted",11550  "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`.",11551  "compatible_models": [11552   "chat-latest",11553   "gpt-4.1",11554   "gpt-4.1-mini",11555   "gpt-4o",11556   "gpt-4o-mini",11557   "gpt-4o-mini-audio-preview",11558   "gpt-5",11559   "gpt-5-chat-latest",11560   "gpt-5-codex",11561   "gpt-5-mini",11562   "gpt-5-nano",11563   "gpt-5-pro",11564   "gpt-5.1",11565   "gpt-5.1-chat-latest",11566   "gpt-5.1-codex",11567   "gpt-5.1-codex-max",11568   "gpt-5.1-codex-mini",11569   "gpt-5.2",11570   "gpt-5.2-chat-latest",11571   "gpt-5.2-codex",11572   "gpt-5.2-pro",11573   "gpt-5.3-chat-latest",11574   "gpt-5.3-codex",11575   "gpt-5.4",11576   "gpt-5.4-mini",11577   "gpt-5.4-nano",11578   "gpt-5.4-pro",11579   "gpt-5.5",11580   "gpt-5.5-pro",11581   "gpt-5.6-cyber",11582   "gpt-5.6-luna",11583   "gpt-5.6-sol",11584   "gpt-5.6-terra",11585   "gpt-6-astra",11586   "gpt-daybreak-blue-latest",11587   "gpt-daybreak-red-latest",11588   "gpt-oss-120b",11589   "gpt-oss-20b",11590   "o3",11591   "o3-deep-research",11592   "o3-pro",11593   "o4-mini",11594   "o4-mini-deep-research"11595  ],11596  "compatible_endpoints": [11597   "POST /v1/responses"11598  ],11599  "parameters_schema": {11600   "properties": {11601    "type": {11602     "type": "string",11603     "enum": [11604      "web_search_preview",11605      "web_search_preview_2025_03_11"11606     ],11607     "description": "The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`.",11608     "default": "web_search_preview",11609     "x-stainless-const": true11610    },11611    "user_location": {11612     "anyOf": [11613      {11614       "properties": {11615        "type": {11616         "type": "string",11617         "enum": [11618          "approximate"11619         ],11620         "description": "The type of location approximation. Always `approximate`.",11621         "default": "approximate",11622         "x-stainless-const": true11623        },11624        "country": {11625         "anyOf": [11626          {11627           "type": "string",11628           "description": "The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`."11629          },11630          {11631           "type": "null"11632          }11633         ]11634        },11635        "region": {11636         "anyOf": [11637          {11638           "type": "string",11639           "description": "Free text input for the region of the user, e.g. `California`."11640          },11641          {11642           "type": "null"11643          }11644         ]11645        },11646        "city": {11647         "anyOf": [11648          {11649           "type": "string",11650           "description": "Free text input for the city of the user, e.g. `San Francisco`."11651          },11652          {11653           "type": "null"11654          }11655         ]11656        },11657        "timezone": {11658         "anyOf": [11659          {11660           "type": "string",11661           "description": "The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`."11662          },11663          {11664           "type": "null"11665          }11666         ]11667        }11668       },11669       "type": "object",11670       "required": [11671        "type"11672       ]11673      },11674      {11675       "type": "null"11676      }11677     ]11678    },11679    "search_context_size": {11680     "type": "string",11681     "enum": [11682      "low",11683      "medium",11684      "high"11685     ]11686    },11687    "search_content_types": {11688     "items": {11689      "type": "string",11690      "enum": [11691       "text",11692       "image"11693      ]11694     },11695     "type": "array"11696    }11697   },11698   "type": "object",11699   "required": [11700    "type"11701   ],11702   "title": "Web search preview",11703   "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)."11704  },11705  "tool_choice_support": {11706   "modes": [11707    "none",11708    "auto",11709    "required"11710   ],11711   "allowed_tools": {11712    "type": "allowed_tools",11713    "mode": "auto|required",11714    "tools": [11715     "{type,name,...}"11716    ]11717   },11718   "specific": {11719    "type": "web_search_preview"11720   }11721  },11722  "parallel": {11723   "supported": false11724  },11725  "streaming_events": [],11726  "result_shape": {11727   "items": [11728    {11729     "schema_name": "WebSearchToolCall",11730     "type": "web_search_call",11731     "schema": {11732      "type": "object",11733      "title": "Web search tool call",11734      "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",11735      "properties": {11736       "id": {11737        "type": "string",11738        "description": "The unique ID of the web search tool call.\n"11739       },11740       "type": {11741        "type": "string",11742        "enum": [11743         "web_search_call"11744        ],11745        "description": "The type of the web search tool call. Always `web_search_call`.\n",11746        "x-stainless-const": true11747       },11748       "status": {11749        "type": "string",11750        "enum": [11751         "in_progress",11752         "searching",11753         "completed",11754         "failed",11755         "incomplete"11756        ]11757       },11758       "action": {11759        "type": "object",11760        "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",11761        "oneOf": [11762         {11763          "type": "object",11764          "title": "Search action",11765          "description": "Action type \"search\" - Performs a web search query.\n",11766          "properties": {11767           "type": {11768            "type": "string",11769            "enum": [11770             "search"11771            ],11772            "description": "The action type.\n",11773            "x-stainless-const": true11774           },11775           "query": {11776            "type": "string",11777            "deprecated": true,11778            "description": "The search query.\n"11779           },11780           "queries": {11781            "type": "array",11782            "title": "Search queries",11783            "description": "The search queries.\n",11784            "items": {11785             "type": "string",11786             "description": "A search query.\n"11787            }11788           },11789           "sources": {11790            "type": "array",11791            "title": "Web search sources",11792            "description": "The sources used in the search.\n",11793            "items": {11794             "type": "object",11795             "title": "Web search source",11796             "description": "A source used in the search.\n",11797             "properties": {11798              "type": {11799               "type": "string",11800               "enum": [11801                "url"11802               ],11803               "description": "The type of source. Always `url`.\n",11804               "x-stainless-const": true11805              },11806              "url": {11807               "type": "string",11808               "format": "uri",11809               "description": "The URL of the source.\n"11810              }11811             },11812             "required": [11813              "type",11814              "url"11815             ]11816            }11817           }11818          },11819          "required": [11820           "type"11821          ]11822         },11823         {11824          "type": "object",11825          "title": "Open page action",11826          "description": "Action type \"open_page\" - Opens a specific URL from search results.\n",11827          "properties": {11828           "type": {11829            "type": "string",11830            "enum": [11831             "open_page"11832            ],11833            "description": "The action type.\n",11834            "x-stainless-const": true11835           },11836           "url": {11837            "description": "The URL opened by the model.\n",11838            "anyOf": [11839             {11840              "type": "string",11841              "format": "uri"11842             },11843             {11844              "type": "null"11845             }11846            ]11847           }11848          },11849          "required": [11850           "type"11851          ]11852         },11853         {11854          "type": "object",11855          "title": "Find action",11856          "description": "Action type \"find_in_page\": Searches for a pattern within a loaded page.\n",11857          "properties": {11858           "type": {11859            "type": "string",11860            "enum": [11861             "find_in_page"11862            ],11863            "description": "The action type.\n",11864            "x-stainless-const": true11865           },11866           "url": {11867            "type": "string",11868            "format": "uri",11869            "description": "The URL of the page searched for the pattern.\n"11870           },11871           "pattern": {11872            "type": "string",11873            "description": "The pattern or text to search for within the page.\n"11874           }11875          },11876          "required": [11877           "type",11878           "url",11879           "pattern"11880          ]11881         }11882        ],11883        "discriminator": {11884         "propertyName": "type"11885        }11886       }11887      },11888      "required": [11889       "id",11890       "type",11891       "status",11892       "action"11893      ]11894     }11895    }11896   ],11897   "summary": "Same `web_search_call` item."11898  },11899  "billing": {11900   "per_call": "$10.00 / 1k calls (web_search, all models; image web search same) + search content tokens billed at model rates",11901   "preview": "$10/1k (reasoning models) or $25/1k with free content tokens (non-reasoning)",11902   "source": "https://developers.openai.com/api/docs/pricing#built-in-tools"11903  },11904  "limitations": [11905   "Search context window limited to 128k even on 1M models.",11906   "Not supported with gpt-5 `minimal` reasoning; gpt-5.4 reasoning `none` may degrade quality.",11907   "Up to 100 allowed_domains / 100 blocked_domains.",11908   "Rate limits = underlying model tiered limits.",11909   "`web_search_preview` ignores `external_web_access`, no `filters`/`return_token_budget`.",11910   "Docs recommend migrating to web_search."11911  ],11912  "security": [11913   "Treat page content as untrusted (prompt injection); prefer `filters.allowed_domains` for sensitive workflows.",11914   "`external_web_access: false` runs cache-only."11915  ],11916  "beta_header": null,11917  "status": [11918   "DOCUMENTED",11919   "LEGACY",11920   "UNVERIFIED"11921  ],11922  "examples": {11923   "curl": "examples/openai/tools/web-search/web_search.sh",11924   "python": "examples/openai/tools/web-search/web_search.py",11925   "typescript": "examples/openai/tools/web-search/web_search.ts"11926  },11927  "verification": {11928   "docs": {11929    "method": "docs_only",11930    "verified_at": "2026-09-18",11931    "result": "success",11932    "http_status": 0,11933    "request_note": "not called (legacy)"11934   }11935  },11936  "sources": [11937   {11938    "url": "https://developers.openai.com/api/docs/guides/tools-web-search",11939    "retrieved_at": "2026-09-18"11940   },11941   {11942    "url": "https://developers.openai.com/api/reference/resources/responses/methods/create",11943    "retrieved_at": "2026-09-18"11944   },11945   {11946    "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)",11947    "retrieved_at": "2026-09-18"11948   }11949  ],11950  "last_verified": "2026-09-18",11951  "_fragment": "generated/fragments/tools/openai-tools.json"11952 },11953 {11954  "provider": "openai",11955  "name": "Web search preview (dated snapshot 2025-03-11)",11956  "type": "web_search_preview_2025_03_11",11957  "category": "hosted",11958  "description": "Dated alias of `web_search_preview`.",11959  "compatible_models": [11960   "chat-latest",11961   "gpt-4.1",11962   "gpt-4.1-mini",11963   "gpt-4o",11964   "gpt-4o-mini",11965   "gpt-4o-mini-audio-preview",11966   "gpt-5",11967   "gpt-5-chat-latest",11968   "gpt-5-codex",11969   "gpt-5-mini",11970   "gpt-5-nano",11971   "gpt-5-pro",11972   "gpt-5.1",11973   "gpt-5.1-chat-latest",11974   "gpt-5.1-codex",11975   "gpt-5.1-codex-max",11976   "gpt-5.1-codex-mini",11977   "gpt-5.2",11978   "gpt-5.2-chat-latest",11979   "gpt-5.2-codex",11980   "gpt-5.2-pro",11981   "gpt-5.3-chat-latest",11982   "gpt-5.3-codex",11983   "gpt-5.4",11984   "gpt-5.4-mini",11985   "gpt-5.4-nano",11986   "gpt-5.4-pro",11987   "gpt-5.5",11988   "gpt-5.5-pro",11989   "gpt-5.6-cyber",11990   "gpt-5.6-luna",11991   "gpt-5.6-sol",11992   "gpt-5.6-terra",11993   "gpt-6-astra",11994   "gpt-daybreak-blue-latest",11995   "gpt-daybreak-red-latest",11996   "gpt-oss-120b",11997   "gpt-oss-20b",11998   "o3",11999   "o3-deep-research",12000   "o3-pro",12001   "o4-mini",12002   "o4-mini-deep-research"12003  ],12004  "compatible_endpoints": [12005   "POST /v1/responses"12006  ],12007  "parameters_schema": {12008   "properties": {12009    "type": {12010     "type": "string",12011     "enum": [12012      "web_search_preview",12013      "web_search_preview_2025_03_11"12014     ],12015     "description": "The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`.",12016     "default": "web_search_preview",12017     "x-stainless-const": true12018    },12019    "user_location": {12020     "anyOf": [12021      {12022       "properties": {12023        "type": {12024         "type": "string",12025         "enum": [12026          "approximate"12027         ],12028         "description": "The type of location approximation. Always `approximate`.",12029         "default": "approximate",12030         "x-stainless-const": true12031        },12032        "country": {12033         "anyOf": [12034          {12035           "type": "string",12036           "description": "The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`."12037          },12038          {12039           "type": "null"12040          }12041         ]12042        },12043        "region": {12044         "anyOf": [12045          {12046           "type": "string",12047           "description": "Free text input for the region of the user, e.g. `California`."12048          },12049          {12050           "type": "null"12051          }12052         ]12053        },12054        "city": {12055         "anyOf": [12056          {12057           "type": "string",12058           "description": "Free text input for the city of the user, e.g. `San Francisco`."12059          },12060          {12061           "type": "null"12062          }12063         ]12064        },12065        "timezone": {12066         "anyOf": [12067          {12068           "type": "string",12069           "description": "The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`."12070          },12071          {12072           "type": "null"12073          }12074         ]12075        }12076       },12077       "type": "object",12078       "required": [12079        "type"12080       ]12081      },12082      {12083       "type": "null"12084      }12085     ]12086    },12087    "search_context_size": {12088     "type": "string",12089     "enum": [12090      "low",12091      "medium",12092      "high"12093     ]12094    },12095    "search_content_types": {12096     "items": {12097      "type": "string",12098      "enum": [12099       "text",12100       "image"12101      ]12102     },12103     "type": "array"12104    }12105   },12106   "type": "object",12107   "required": [12108    "type"12109   ],12110   "title": "Web search preview",12111   "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)."12112  },12113  "tool_choice_support": {12114   "modes": [12115    "none",12116    "auto",12117    "required"12118   ],12119   "allowed_tools": {12120    "type": "allowed_tools",12121    "mode": "auto|required",12122    "tools": [12123     "{type,name,...}"12124    ]12125   },12126   "specific": {12127    "type": "web_search_preview_2025_03_11"12128   }12129  },12130  "parallel": {12131   "supported": false12132  },12133  "streaming_events": [],12134  "result_shape": {12135   "items": [12136    {12137     "schema_name": "WebSearchToolCall",12138     "type": "web_search_call",12139     "schema": {12140      "type": "object",12141      "title": "Web search tool call",12142      "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",12143      "properties": {12144       "id": {12145        "type": "string",12146        "description": "The unique ID of the web search tool call.\n"12147       },12148       "type": {12149        "type": "string",12150        "enum": [12151         "web_search_call"12152        ],12153        "description": "The type of the web search tool call. Always `web_search_call`.\n",12154        "x-stainless-const": true12155       },12156       "status": {12157        "type": "string",12158        "enum": [12159         "in_progress",12160         "searching",12161         "completed",12162         "failed",12163         "incomplete"12164        ]12165       },12166       "action": {12167        "type": "object",12168        "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",12169        "oneOf": [12170         {12171          "type": "object",12172          "title": "Search action",12173          "description": "Action type \"search\" - Performs a web search query.\n",12174          "properties": {12175           "type": {12176            "type": "string",12177            "enum": [12178             "search"12179            ],12180            "description": "The action type.\n",12181            "x-stainless-const": true12182           },12183           "query": {12184            "type": "string",12185            "deprecated": true,12186            "description": "The search query.\n"12187           },12188           "queries": {12189            "type": "array",12190            "title": "Search queries",12191            "description": "The search queries.\n",12192            "items": {12193             "type": "string",12194             "description": "A search query.\n"12195            }12196           },12197           "sources": {12198            "type": "array",12199            "title": "Web search sources",12200            "description": "The sources used in the search.\n",12201            "items": {12202             "type": "object",12203             "title": "Web search source",12204             "description": "A source used in the search.\n",12205             "properties": {12206              "type": {12207               "type": "string",12208               "enum": [12209                "url"12210               ],12211               "description": "The type of source. Always `url`.\n",12212               "x-stainless-const": true12213              },12214              "url": {12215               "type": "string",12216               "format": "uri",12217               "description": "The URL of the source.\n"12218              }12219             },12220             "required": [12221              "type",12222              "url"12223             ]12224            }12225           }12226          },12227          "required": [12228           "type"12229          ]12230         },12231         {12232          "type": "object",12233          "title": "Open page action",12234          "description": "Action type \"open_page\" - Opens a specific URL from search results.\n",12235          "properties": {12236           "type": {12237            "type": "string",12238            "enum": [12239             "open_page"12240            ],12241            "description": "The action type.\n",12242            "x-stainless-const": true12243           },12244           "url": {12245            "description": "The URL opened by the model.\n",12246            "anyOf": [12247             {12248              "type": "string",12249              "format": "uri"12250             },12251             {12252              "type": "null"12253             }12254            ]12255           }12256          },12257          "required": [12258           "type"12259          ]12260         },12261         {12262          "type": "object",12263          "title": "Find action",12264          "description": "Action type \"find_in_page\": Searches for a pattern within a loaded page.\n",12265          "properties": {12266           "type": {12267            "type": "string",12268            "enum": [12269             "find_in_page"12270            ],12271            "description": "The action type.\n",12272            "x-stainless-const": true12273           },12274           "url": {12275            "type": "string",12276            "format": "uri",12277            "description": "The URL of the page searched for the pattern.\n"12278           },12279           "pattern": {12280            "type": "string",12281            "description": "The pattern or text to search for within the page.\n"12282           }12283          },12284          "required": [12285           "type",12286           "url",12287           "pattern"12288          ]12289         }12290        ],12291        "discriminator": {12292         "propertyName": "type"12293        }12294       }12295      },12296      "required": [12297       "id",12298       "type",12299       "status",12300       "action"12301      ]12302     }12303    }12304   ],12305   "summary": "Same `web_search_call` item."12306  },12307  "billing": {12308   "per_call": "$10.00 / 1k calls (web_search, all models; image web search same) + search content tokens billed at model rates",12309   "preview": "$10/1k (reasoning models) or $25/1k with free content tokens (non-reasoning)",12310   "source": "https://developers.openai.com/api/docs/pricing#built-in-tools"12311  },12312  "limitations": [12313   "Search context window limited to 128k even on 1M models.",12314   "Not supported with gpt-5 `minimal` reasoning; gpt-5.4 reasoning `none` may degrade quality.",12315   "Up to 100 allowed_domains / 100 blocked_domains.",12316   "Rate limits = underlying model tiered limits.",12317   "`web_search_preview` ignores `external_web_access`, no `filters`/`return_token_budget`."12318  ],12319  "security": [12320   "Treat page content as untrusted (prompt injection); prefer `filters.allowed_domains` for sensitive workflows.",12321   "`external_web_access: false` runs cache-only."12322  ],12323  "beta_header": null,12324  "status": [12325   "DOCUMENTED",12326   "LEGACY",12327   "UNVERIFIED"12328  ],12329  "examples": {12330   "curl": "examples/openai/tools/web-search/web_search.sh",12331   "python": "examples/openai/tools/web-search/web_search.py",12332   "typescript": "examples/openai/tools/web-search/web_search.ts"12333  },12334  "verification": {12335   "docs": {12336    "method": "docs_only",12337    "verified_at": "2026-09-18",12338    "result": "success",12339    "http_status": 0,12340    "request_note": "not called"12341   }12342  },12343  "sources": [12344   {12345    "url": "https://developers.openai.com/api/docs/guides/tools-web-search",12346    "retrieved_at": "2026-09-18"12347   },12348   {12349    "url": "https://developers.openai.com/api/reference/resources/responses/methods/create",12350    "retrieved_at": "2026-09-18"12351   },12352   {12353    "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)",12354    "retrieved_at": "2026-09-18"12355   }12356  ],12357  "last_verified": "2026-09-18",12358  "_fragment": "generated/fragments/tools/openai-tools.json"12359 },12360 {12361  "provider": "openai",12362  "name": "File search (vector stores)",12363  "type": "file_search",12364  "category": "hosted",12365  "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.",12366  "compatible_models": [12367   "chat-latest",12368   "gpt-4.1",12369   "gpt-4.1-mini",12370   "gpt-4.1-nano",12371   "gpt-4o",12372   "gpt-4o-mini",12373   "gpt-4o-mini-audio-preview",12374   "gpt-5",12375   "gpt-5-chat-latest",12376   "gpt-5-mini",12377   "gpt-5-nano",12378   "gpt-5-pro",12379   "gpt-5.1",12380   "gpt-5.1-chat-latest",12381   "gpt-5.2",12382   "gpt-5.2-chat-latest",12383   "gpt-5.2-pro",12384   "gpt-5.3-chat-latest",12385   "gpt-5.4",12386   "gpt-5.4-mini",12387   "gpt-5.4-nano",12388   "gpt-5.4-pro",12389   "gpt-5.5",12390   "gpt-5.5-pro",12391   "gpt-5.6-cyber",12392   "gpt-5.6-luna",12393   "gpt-5.6-sol",12394   "gpt-5.6-terra",12395   "gpt-6-astra",12396   "gpt-daybreak-blue-latest",12397   "gpt-daybreak-red-latest",12398   "o1",12399   "o1-mini",12400   "o1-pro",12401   "o3",12402   "o3-mini",12403   "o3-pro",12404   "o4-mini"12405  ],12406  "compatible_endpoints": [12407   "POST /v1/responses",12408   "Assistants API (legacy)"12409  ],12410  "parameters_schema": {12411   "properties": {12412    "type": {12413     "type": "string",12414     "enum": [12415      "file_search"12416     ],12417     "description": "The type of the file search tool. Always `file_search`.",12418     "default": "file_search",12419     "x-stainless-const": true12420    },12421    "vector_store_ids": {12422     "items": {12423      "type": "string"12424     },12425     "type": "array",12426     "description": "The IDs of the vector stores to search."12427    },12428    "max_num_results": {12429     "type": "integer",12430     "description": "The maximum number of results to return. This number should be between 1 and 50 inclusive."12431    },12432    "ranking_options": {12433     "properties": {12434      "ranker": {12435       "type": "string",12436       "enum": [12437        "auto",12438        "default-2024-11-15"12439       ]12440      },12441      "score_threshold": {12442       "type": "number",12443       "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."12444      },12445      "hybrid_search": {12446       "properties": {12447        "embedding_weight": {12448         "type": "number",12449         "description": "The weight of the embedding in the reciprocal ranking fusion."12450        },12451        "text_weight": {12452         "type": "number",12453         "description": "The weight of the text in the reciprocal ranking fusion."12454        }12455       },12456       "type": "object",12457       "required": [12458        "embedding_weight",12459        "text_weight"12460       ]12461      }12462     },12463     "type": "object",12464     "required": []12465    },12466    "filters": {12467     "anyOf": [12468      {12469       "anyOf": [12470        {12471         "type": "object",12472         "additionalProperties": false,12473         "title": "Comparison Filter",12474         "description": "A filter used to compare a specified attribute key to a given value using a defined comparison operation.\n",12475         "properties": {12476          "type": {12477           "type": "string",12478           "default": "eq",12479           "enum": [12480            "eq",12481            "ne",12482            "gt",12483            "gte",12484            "lt",12485            "lte",12486            "in",12487            "nin"12488           ],12489           "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"12490          },12491          "key": {12492           "type": "string",12493           "description": "The key to compare against the value."12494          },12495          "value": {12496           "oneOf": [12497            {12498             "type": "string"12499            },12500            {12501             "type": "number"12502            },12503            {12504             "type": "boolean"12505            },12506            {12507             "type": "array",12508             "items": {12509              "oneOf": [12510               {12511                "$comment": "depth-limited"12512               },12513               {12514                "$comment": "depth-limited"12515               }12516              ]12517             }12518            }12519           ],12520           "description": "The value to compare against the attribute key; supports string, number, or boolean types."12521          }12522         },12523         "required": [12524          "type",12525          "key",12526          "value"12527         ]12528        },12529        {12530         "$recursiveAnchor": true,12531         "type": "object",12532         "additionalProperties": false,12533         "title": "Compound Filter",12534         "description": "Combine multiple filters using `and` or `or`.",12535         "properties": {12536          "type": {12537           "type": "string",12538           "description": "Type of operation: `and` or `or`.",12539           "enum": [12540            "and",12541            "or"12542           ]12543          },12544          "filters": {12545           "type": "array",12546           "description": "Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`.",12547           "items": {12548            "oneOf": [12549             {12550              "type": {12551               "$comment": "depth-limited"12552              },12553              "additionalProperties": {12554               "$comment": "depth-limited"12555              },12556              "title": {12557               "$comment": "depth-limited"12558              },12559              "description": {12560               "$comment": "depth-limited"12561              },12562              "properties": {12563               "$comment": "depth-limited"12564              },12565              "required": {12566               "$comment": "depth-limited"12567              }12568             },12569             {12570              "$recursiveRef": "#"12571             }12572            ],12573            "discriminator": {12574             "propertyName": "type"12575            }12576           }12577          }12578         },12579         "required": [12580          "type",12581          "filters"12582         ]12583        }12584       ]12585      },12586      {12587       "type": "null"12588      }12589     ]12590    }12591   },12592   "type": "object",12593   "required": [12594    "type",12595    "vector_store_ids"12596   ],12597   "title": "File search",12598   "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)."12599  },12600  "tool_choice_support": {12601   "modes": [12602    "none",12603    "auto",12604    "required"12605   ],12606   "allowed_tools": {12607    "type": "allowed_tools",12608    "mode": "auto|required",12609    "tools": [12610     "{type,name,...}"12611    ]12612   },12613   "specific": {12614    "type": "file_search"12615   }12616  },12617  "parallel": {12618   "supported": false12619  },12620  "streaming_events": [12621   "response.output_item.added",12622   "response.file_search_call.in_progress",12623   "response.file_search_call.searching",12624   "response.file_search_call.completed",12625   "response.output_item.done",12626   "response.output_text.annotation.added"12627  ],12628  "result_shape": {12629   "items": [12630    {12631     "schema_name": "FileSearchToolCall",12632     "type": "file_search_call",12633     "schema": {12634      "type": "object",12635      "title": "File search tool call",12636      "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",12637      "properties": {12638       "id": {12639        "type": "string",12640        "description": "The unique ID of the file search tool call.\n"12641       },12642       "type": {12643        "type": "string",12644        "enum": [12645         "file_search_call"12646        ],12647        "description": "The type of the file search tool call. Always `file_search_call`.\n",12648        "x-stainless-const": true12649       },12650       "status": {12651        "type": "string",12652        "description": "The status of the file search tool call. One of `in_progress`,\n`searching`, `incomplete` or `failed`,\n",12653        "enum": [12654         "in_progress",12655         "searching",12656         "completed",12657         "incomplete",12658         "failed"12659        ]12660       },12661       "queries": {12662        "type": "array",12663        "items": {12664         "type": "string"12665        },12666        "description": "The queries used to search for files.\n"12667       },12668       "results": {12669        "anyOf": [12670         {12671          "type": "array",12672          "description": "The results of the file search tool call.\n",12673          "items": {12674           "type": "object",12675           "properties": {12676            "file_id": {12677             "type": "string",12678             "description": "The unique ID of the file.\n"12679            },12680            "text": {12681             "type": "string",12682             "description": "The text that was retrieved from the file.\n"12683            },12684            "filename": {12685             "type": "string",12686             "description": "The name of the file.\n"12687            },12688            "attributes": {12689             "anyOf": [12690              {12691               "type": "object",12692               "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",12693               "maxProperties": 16,12694               "propertyNames": {12695                "type": "string",12696                "maxLength": 6412697               },12698               "additionalProperties": {12699                "oneOf": [12700                 {12701                  "type": "string",12702                  "maxLength": 51212703                 },12704                 {12705                  "type": "number"12706                 },12707                 {12708                  "type": "boolean"12709                 }12710                ]12711               }12712              },12713              {12714               "type": "null"12715              }12716             ]12717            },12718            "score": {12719             "type": "number",12720             "format": "float",12721             "description": "The relevance score of the file - a value between 0 and 1.\n"12722            }12723           }12724          }12725         },12726         {12727          "type": "null"12728         }12729        ]12730       }12731      },12732      "required": [12733       "id",12734       "type",12735       "status",12736       "queries"12737      ]12738     }12739    }12740   ],12741   "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."12742  },12743  "billing": {12744   "per_call": "$2.50 / 1k calls",12745   "storage": "$0.10 / GB / day (1 GB free)",12746   "source": "https://developers.openai.com/api/docs/pricing#built-in-tools"12747  },12748  "limitations": [12749   "max_num_results 1-50.",12750   "Deep research models support only `type` and `vector_store_ids`.",12751   "Vector store CRUD is documented in the vector-stores fragment (other agent)."12752  ],12753  "security": [12754   "Only upload trusted files: retrieved text is model input (prompt injection)."12755  ],12756  "beta_header": null,12757  "status": [12758   "DOCUMENTED",12759   "LIVE_VERIFIED"12760  ],12761  "examples": {12762   "curl": "examples/openai/tools/file-search/file_search.sh",12763   "python": "examples/openai/tools/file-search/file_search.py",12764   "typescript": "examples/openai/tools/file-search/file_search.ts"12765  },12766  "verification": {12767   "search": {12768    "method": "live_api",12769    "verified_at": "2026-09-18",12770    "result": "success",12771    "http_status": 200,12772    "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)"12773   },12774   "max_output_tokens_32": {12775    "method": "live_api",12776    "verified_at": "2026-09-18",12777    "result": "failure",12778    "http_status": 200,12779    "request_note": "with max_output_tokens 32 the response was incomplete and file_search_call.status='incomplete'"12780   },12781   "streaming": {12782    "method": "live_api",12783    "verified_at": "2026-09-18",12784    "result": "success",12785    "http_status": 200,12786    "request_note": "response.file_search_call.in_progress -> searching -> completed"12787   }12788  },12789  "sources": [12790   {12791    "url": "https://developers.openai.com/api/docs/guides/tools-file-search",12792    "retrieved_at": "2026-09-18"12793   },12794   {12795    "url": "https://developers.openai.com/api/docs/pricing#built-in-tools",12796    "retrieved_at": "2026-09-18"12797   },12798   {12799    "url": "https://developers.openai.com/api/reference/resources/responses/methods/create",12800    "retrieved_at": "2026-09-18"12801   },12802   {12803    "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)",12804    "retrieved_at": "2026-09-18"12805   }12806  ],12807  "last_verified": "2026-09-18",12808  "_fragment": "generated/fragments/tools/openai-tools.json"12809 },12810 {12811  "provider": "openai",12812  "name": "Code interpreter (Python sandbox container)",12813  "type": "code_interpreter",12814  "category": "hosted",12815  "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]`.",12816  "compatible_models": [12817   "chat-latest",12818   "gpt-4.1",12819   "gpt-4.1-mini",12820   "gpt-4.1-nano",12821   "gpt-4o",12822   "gpt-4o-mini",12823   "gpt-4o-mini-audio-preview",12824   "gpt-5",12825   "gpt-5-chat-latest",12826   "gpt-5-mini",12827   "gpt-5-nano",12828   "gpt-5.1",12829   "gpt-5.1-chat-latest",12830   "gpt-5.2",12831   "gpt-5.2-chat-latest",12832   "gpt-5.3-chat-latest",12833   "gpt-5.4",12834   "gpt-5.4-mini",12835   "gpt-5.4-nano",12836   "gpt-5.5",12837   "gpt-5.5-pro",12838   "gpt-5.6-cyber",12839   "gpt-5.6-luna",12840   "gpt-5.6-sol",12841   "gpt-5.6-terra",12842   "gpt-6-astra",12843   "gpt-daybreak-blue-latest",12844   "gpt-daybreak-red-latest",12845   "gpt-oss-120b",12846   "gpt-oss-20b",12847   "o1-mini",12848   "o3",12849   "o3-deep-research",12850   "o3-mini",12851   "o4-mini",12852   "o4-mini-deep-research"12853  ],12854  "compatible_endpoints": [12855   "POST /v1/responses",12856   "Assistants API (legacy)"12857  ],12858  "parameters_schema": {12859   "type": "object",12860   "title": "Code interpreter",12861   "description": "A tool that runs Python code to help generate a response to a prompt.\n",12862   "properties": {12863    "type": {12864     "type": "string",12865     "enum": [12866      "code_interpreter"12867     ],12868     "description": "The type of the code interpreter tool. Always `code_interpreter`.\n",12869     "x-stainless-const": true12870    },12871    "container": {12872     "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",12873     "oneOf": [12874      {12875       "type": "string",12876       "description": "The container ID."12877      },12878      {12879       "properties": {12880        "type": {12881         "type": "string",12882         "enum": [12883          "auto"12884         ],12885         "description": "Always `auto`.",12886         "default": "auto",12887         "x-stainless-const": true12888        },12889        "file_ids": {12890         "items": {12891          "type": "string",12892          "example": "file-123"12893         },12894         "type": "array",12895         "maxItems": 50,12896         "description": "An optional list of uploaded files to make available to your code."12897        },12898        "memory_limit": {12899         "anyOf": [12900          {12901           "type": "string",12902           "enum": [12903            "1g",12904            "4g",12905            "16g",12906            "64g"12907           ]12908          },12909          {12910           "type": "null"12911          }12912         ]12913        },12914        "network_policy": {12915         "oneOf": [12916          {12917           "properties": {12918            "type": {12919             "type": "string",12920             "enum": [12921              "disabled"12922             ],12923             "description": "Disable outbound network access. Always `disabled`.",12924             "default": "disabled",12925             "x-stainless-const": true12926            }12927           },12928           "type": "object",12929           "required": [12930            "type"12931           ]12932          },12933          {12934           "properties": {12935            "type": {12936             "type": "string",12937             "enum": [12938              "allowlist"12939             ],12940             "description": "Allow outbound network access only to specified domains. Always `allowlist`.",12941             "default": "allowlist",12942             "x-stainless-const": true12943            },12944            "allowed_domains": {12945             "items": {12946              "type": "string"12947             },12948             "type": "array",12949             "minItems": 1,12950             "description": "A list of allowed domains when type is `allowlist`."12951            },12952            "domain_secrets": {12953             "items": {12954              "properties": {12955               "$comment": "depth-limited"12956              },12957              "type": {12958               "$comment": "depth-limited"12959              },12960              "required": {12961               "$comment": "depth-limited"12962              }12963             },12964             "type": "array",12965             "minItems": 1,12966             "description": "Optional domain-scoped secrets for allowlisted domains."12967            }12968           },12969           "type": "object",12970           "required": [12971            "type",12972            "allowed_domains"12973           ]12974          }12975         ],12976         "description": "Network access policy for the container.",12977         "discriminator": {12978          "propertyName": "type"12979         }12980        }12981       },12982       "type": "object",12983       "required": [12984        "type"12985       ],12986       "title": "CodeInterpreterToolAuto",12987       "description": "Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on."12988      }12989     ]12990    },12991    "allowed_callers": {12992     "anyOf": [12993      {12994       "type": "array",12995       "minItems": 1,12996       "items": {12997        "type": "string",12998        "enum": [12999         "direct",13000         "programmatic"13001        ]13002       },13003       "description": "The tool invocation context(s)."13004      },13005      {13006       "type": "null"13007      }13008     ]13009    }13010   },13011   "required": [13012    "type",13013    "container"13014   ]13015  },13016  "tool_choice_support": {13017   "modes": [13018    "none",13019    "auto",13020    "required"13021   ],13022   "allowed_tools": {13023    "type": "allowed_tools",13024    "mode": "auto|required",13025    "tools": [13026     "{type,name,...}"13027    ]13028   },13029   "specific": {13030    "type": "code_interpreter"13031   }13032  },13033  "parallel": {13034   "supported": false13035  },13036  "streaming_events": [13037   "response.output_item.added",13038   "response.code_interpreter_call.in_progress",13039   "response.code_interpreter_call_code.delta",13040   "response.code_interpreter_call_code.done",13041   "response.code_interpreter_call.interpreting",13042   "response.code_interpreter_call.completed",13043   "response.output_item.done",13044   "response.output_text.annotation.added"13045  ],13046  "result_shape": {13047   "items": [13048    {13049     "schema_name": "CodeInterpreterToolCall",13050     "type": "code_interpreter_call",13051     "schema": {13052      "type": "object",13053      "title": "Code interpreter tool call",13054      "description": "A tool call to run code.\n",13055      "properties": {13056       "type": {13057        "type": "string",13058        "enum": [13059         "code_interpreter_call"13060        ],13061        "default": "code_interpreter_call",13062        "x-stainless-const": true,13063        "description": "The type of the code interpreter tool call. Always `code_interpreter_call`.\n"13064       },13065       "id": {13066        "type": "string",13067        "description": "The unique ID of the code interpreter tool call.\n"13068       },13069       "status": {13070        "type": "string",13071        "enum": [13072         "in_progress",13073         "completed",13074         "incomplete",13075         "interpreting",13076         "failed"13077        ],13078        "description": "The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`.\n"13079       },13080       "container_id": {13081        "type": "string",13082        "description": "The ID of the container used to run the code.\n"13083       },13084       "code": {13085        "anyOf": [13086         {13087          "type": "string",13088          "description": "The code to run, or null if not available.\n"13089         },13090         {13091          "type": "null"13092         }13093        ]13094       },13095       "outputs": {13096        "anyOf": [13097         {13098          "type": "array",13099          "items": {13100           "oneOf": [13101            {13102             "properties": {13103              "type": {13104               "type": "string",13105               "enum": [13106                "logs"13107               ],13108               "description": "The type of the output. Always `logs`.",13109               "default": "logs",13110               "x-stainless-const": true13111              },13112              "logs": {13113               "type": "string",13114               "description": "The logs output from the code interpreter."13115              }13116             },13117             "type": "object",13118             "required": [13119              "type",13120              "logs"13121             ],13122             "title": "Code interpreter output logs",13123             "description": "The logs output from the code interpreter."13124            },13125            {13126             "properties": {13127              "type": {13128               "type": "string",13129               "enum": [13130                "image"13131               ],13132               "description": "The type of the output. Always `image`.",13133               "default": "image",13134               "x-stainless-const": true13135              },13136              "url": {13137               "type": "string",13138               "format": "uri",13139               "description": "The URL of the image output from the code interpreter."13140              }13141             },13142             "type": "object",13143             "required": [13144              "type",13145              "url"13146             ],13147             "title": "Code interpreter output image",13148             "description": "The image output from the code interpreter."13149            }13150           ],13151           "discriminator": {13152            "propertyName": "type"13153           }13154          },13155          "discriminator": {13156           "propertyName": "type"13157          },13158          "description": "The outputs generated by the code interpreter, such as logs or images.\nCan be null if no outputs are available.\n"13159         },13160         {13161          "type": "null"13162         }13163        ]13164       }13165      },13166      "required": [13167       "type",13168       "id",13169       "status",13170       "container_id",13171       "code",13172       "outputs"13173      ]13174     }13175    }13176   ],13177   "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}."13178  },13179  "billing": {13180   "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)",13181   "source": "https://developers.openai.com/api/docs/pricing#built-in-tools"13182  },13183  "limitations": [13184   "Container expires after 20 min of inactivity (auto containers: expires_after last_active_at 20 min); expired containers cannot be revived.",13185   "No outbound network by default (network_policy allowlist/disabled; org allow-list applies).",13186   "Model knows the tool as the 'python tool'."13187  ],13188  "security": [13189   "Network-enabled containers: prompt-injection driven exfiltration risk; only allowlist trusted domains; use domain_secrets instead of raw credentials."13190  ],13191  "beta_header": null,13192  "status": [13193   "DOCUMENTED",13194   "LIVE_VERIFIED"13195  ],13196  "examples": {13197   "curl": "examples/openai/tools/code-interpreter/code_interpreter.sh",13198   "python": "examples/openai/tools/code-interpreter/code_interpreter.py",13199   "typescript": "examples/openai/tools/code-interpreter/code_interpreter.ts"13200  },13201  "verification": {13202   "auto_container": {13203    "method": "live_api",13204    "verified_at": "2026-09-18",13205    "result": "success",13206    "http_status": 200,13207    "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)"13208   },13209   "streaming": {13210    "method": "docs_only",13211    "verified_at": "2026-09-18",13212    "result": "success",13213    "http_status": 0,13214    "request_note": "not streamed live (cost); events from spec"13215   }13216  },13217  "sources": [13218   {13219    "url": "https://developers.openai.com/api/docs/guides/tools-code-interpreter",13220    "retrieved_at": "2026-09-18"13221   },13222   {13223    "url": "https://developers.openai.com/api/reference/resources/containers",13224    "retrieved_at": "2026-09-18"13225   },13226   {13227    "url": "https://developers.openai.com/api/docs/pricing#built-in-tools",13228    "retrieved_at": "2026-09-18"13229   },13230   {13231    "url": "https://developers.openai.com/api/reference/resources/responses/methods/create",13232    "retrieved_at": "2026-09-18"13233   },13234   {13235    "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)",13236    "retrieved_at": "2026-09-18"13237   }13238  ],13239  "last_verified": "2026-09-18",13240  "_fragment": "generated/fragments/tools/openai-tools.json"13241 },13242 {13243  "provider": "openai",13244  "name": "Computer use (preview tool + computer-use-preview model)",13245  "type": "computer_use_preview",13246  "category": "client",13247  "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.",13248  "compatible_models": [13249   "gpt-5.4",13250   "gpt-5.4-mini",13251   "gpt-5.4-pro",13252   "gpt-5.5",13253   "gpt-5.6-cyber",13254   "gpt-5.6-luna",13255   "gpt-5.6-sol",13256   "gpt-5.6-terra",13257   "gpt-6-astra",13258   "gpt-daybreak-blue-latest",13259   "gpt-daybreak-red-latest"13260  ],13261  "compatible_endpoints": [13262   "POST /v1/responses"13263  ],13264  "parameters_schema": {13265   "properties": {13266    "type": {13267     "type": "string",13268     "enum": [13269      "computer_use_preview"13270     ],13271     "description": "The type of the computer use tool. Always `computer_use_preview`.",13272     "default": "computer_use_preview",13273     "x-stainless-const": true13274    },13275    "environment": {13276     "type": "string",13277     "enum": [13278      "windows",13279      "mac",13280      "linux",13281      "ubuntu",13282      "browser"13283     ]13284    },13285    "display_width": {13286     "type": "integer",13287     "description": "The width of the computer display."13288    },13289    "display_height": {13290     "type": "integer",13291     "description": "The height of the computer display."13292    }13293   },13294   "type": "object",13295   "required": [13296    "type",13297    "environment",13298    "display_width",13299    "display_height"13300   ],13301   "title": "Computer use preview",13302   "description": "A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use)."13303  },13304  "tool_choice_support": {13305   "modes": [13306    "none",13307    "auto",13308    "required"13309   ],13310   "allowed_tools": {13311    "type": "allowed_tools",13312    "mode": "auto|required",13313    "tools": [13314     "{type,name,...}"13315    ]13316   },13317   "specific": {13318    "type": "computer_use_preview"13319   }13320  },13321  "parallel": {13322   "supported": false13323  },13324  "streaming_events": [13325   "response.output_item.added",13326   "response.output_item.done"13327  ],13328  "result_shape": {13329   "items": [13330    {13331     "schema_name": "ComputerToolCall",13332     "type": "computer_call",13333     "schema": {13334      "type": "object",13335      "title": "Computer tool call",13336      "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",13337      "properties": {13338       "type": {13339        "type": "string",13340        "description": "The type of the computer call. Always `computer_call`.",13341        "enum": [13342         "computer_call"13343        ],13344        "default": "computer_call"13345       },13346       "id": {13347        "type": "string",13348        "description": "The unique ID of the computer call."13349       },13350       "call_id": {13351        "type": "string",13352        "description": "An identifier used when responding to the tool call with output.\n"13353       },13354       "action": {13355        "oneOf": [13356         {13357          "properties": {13358           "type": {13359            "type": "string",13360            "enum": [13361             "click"13362            ],13363            "description": "Specifies the event type. For a click action, this property is always `click`.",13364            "default": "click",13365            "x-stainless-const": true13366           },13367           "button": {13368            "type": "string",13369            "enum": [13370             "left",13371             "right",13372             "wheel",13373             "back",13374             "forward"13375            ]13376           },13377           "x": {13378            "type": "integer",13379            "description": "The x-coordinate where the click occurred."13380           },13381           "y": {13382            "type": "integer",13383            "description": "The y-coordinate where the click occurred."13384           },13385           "keys": {13386            "anyOf": [13387             {13388              "items": {13389               "type": "string"13390              },13391              "type": "array",13392              "description": "The keys being held while clicking."13393             },13394             {13395              "type": "null"13396             }13397            ]13398           }13399          },13400          "type": "object",13401          "required": [13402           "type",13403           "button",13404           "x",13405           "y"13406          ],13407          "title": "Click",13408          "description": "A click action."13409         },13410         {13411          "properties": {13412           "type": {13413            "type": "string",13414            "enum": [13415             "double_click"13416            ],13417            "description": "Specifies the event type. For a double click action, this property is always set to `double_click`.",13418            "default": "double_click",13419            "x-stainless-const": true13420           },13421           "x": {13422            "type": "integer",13423            "description": "The x-coordinate where the double click occurred."13424           },13425           "y": {13426            "type": "integer",13427            "description": "The y-coordinate where the double click occurred."13428           },13429           "keys": {13430            "anyOf": [13431             {13432              "items": {13433               "type": "string"13434              },13435              "type": "array",13436              "description": "The keys being held while double-clicking."13437             },13438             {13439              "type": "null"13440             }13441            ]13442           }13443          },13444          "type": "object",13445          "required": [13446           "type",13447           "x",13448           "y",13449           "keys"13450          ],13451          "title": "DoubleClick",13452          "description": "A double click action."13453         },13454         {13455          "properties": {13456           "type": {13457            "type": "string",13458            "enum": [13459             "drag"13460            ],13461            "description": "Specifies the event type. For a drag action, this property is always set to `drag`.",13462            "default": "drag",13463            "x-stainless-const": true13464           },13465           "path": {13466            "items": {13467             "properties": {13468              "x": {13469               "type": "integer",13470               "description": "The x-coordinate."13471              },13472              "y": {13473               "type": "integer",13474               "description": "The y-coordinate."13475              }13476             },13477             "type": "object",13478             "required": [13479              "x",13480              "y"13481             ],13482             "title": "Coordinate",13483             "description": "An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`."13484            },13485            "type": "array",13486            "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```"13487           },13488           "keys": {13489            "anyOf": [13490             {13491              "items": {13492               "type": "string"13493              },13494              "type": "array",13495              "description": "The keys being held while dragging the mouse."13496             },13497             {13498              "type": "null"13499             }13500            ]13501           }13502          },13503          "type": "object",13504          "required": [13505           "type",13506           "path"13507          ],13508          "title": "Drag",13509          "description": "A drag action."13510         },13511         {13512          "properties": {13513           "type": {13514            "type": "string",13515            "enum": [13516             "keypress"13517            ],13518            "description": "Specifies the event type. For a keypress action, this property is always set to `keypress`.",13519            "default": "keypress",13520            "x-stainless-const": true13521           },13522           "keys": {13523            "items": {13524             "type": "string",13525             "description": "One of the keys the model is requesting to be pressed."13526            },13527            "type": "array",13528            "description": "The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key."13529           }13530          },13531          "type": "object",13532          "required": [13533           "type",13534           "keys"13535          ],13536          "title": "KeyPress",13537          "description": "A collection of keypresses the model would like to perform."13538         },13539         {13540          "properties": {13541           "type": {13542            "type": "string",13543            "enum": [13544             "move"13545            ],13546            "description": "Specifies the event type. For a move action, this property is always set to `move`.",13547            "default": "move",13548            "x-stainless-const": true13549           },13550           "x": {13551            "type": "integer",13552            "description": "The x-coordinate to move to."13553           },13554           "y": {13555            "type": "integer",13556            "description": "The y-coordinate to move to."13557           },13558           "keys": {13559            "anyOf": [13560             {13561              "items": {13562               "type": "string"13563              },13564              "type": "array",13565              "description": "The keys being held while moving the mouse."13566             },13567             {13568              "type": "null"13569             }13570            ]13571           }13572          },13573          "type": "object",13574          "required": [13575           "type",13576           "x",13577           "y"13578          ],13579          "title": "Move",13580          "description": "A mouse move action."13581         },13582         {13583          "properties": {13584           "type": {13585            "type": "string",13586            "enum": [13587             "screenshot"13588            ],13589            "description": "Specifies the event type. For a screenshot action, this property is always set to `screenshot`.",13590            "default": "screenshot",13591            "x-stainless-const": true13592           }13593          },13594          "type": "object",13595          "required": [13596           "type"13597          ],13598          "title": "Screenshot",13599          "description": "A screenshot action."13600         },13601         {13602          "properties": {13603           "type": {13604            "type": "string",13605            "enum": [13606             "scroll"13607            ],13608            "description": "Specifies the event type. For a scroll action, this property is always set to `scroll`.",13609            "default": "scroll",13610            "x-stainless-const": true13611           },13612           "x": {13613            "type": "integer",13614            "description": "The x-coordinate where the scroll occurred."13615           },13616           "y": {13617            "type": "integer",13618            "description": "The y-coordinate where the scroll occurred."13619           },13620           "scroll_x": {13621            "type": "integer",13622            "description": "The horizontal scroll distance."13623           },13624           "scroll_y": {13625            "type": "integer",13626            "description": "The vertical scroll distance."13627           },13628           "keys": {13629            "anyOf": [13630             {13631              "items": {13632               "type": "string"13633              },13634              "type": "array",13635              "description": "The keys being held while scrolling."13636             },13637             {13638              "type": "null"13639             }13640            ]13641           }13642          },13643          "type": "object",13644          "required": [13645           "type",13646           "x",13647           "y",13648           "scroll_x",13649           "scroll_y"13650          ],13651          "title": "Scroll",13652          "description": "A scroll action."13653         },13654         {13655          "properties": {13656           "type": {13657            "type": "string",13658            "enum": [13659             "type"13660            ],13661            "description": "Specifies the event type. For a type action, this property is always set to `type`.",13662            "default": "type",13663            "x-stainless-const": true13664           },13665           "text": {13666            "type": "string",13667            "description": "The text to type."13668           }13669          },13670          "type": "object",13671          "required": [13672           "type",13673           "text"13674          ],13675          "title": "Type",13676          "description": "An action to type in text."13677         },13678         {13679          "properties": {13680           "type": {13681            "type": "string",13682            "enum": [13683             "wait"13684            ],13685            "description": "Specifies the event type. For a wait action, this property is always set to `wait`.",13686            "default": "wait",13687            "x-stainless-const": true13688           }13689          },13690          "type": "object",13691          "required": [13692           "type"13693          ],13694          "title": "Wait",13695          "description": "A wait action."13696         }13697        ],13698        "discriminator": {13699         "propertyName": "type"13700        }13701       },13702       "actions": {13703        "title": "Computer Action List",13704        "type": "array",13705        "description": "Flattened batched actions for `computer_use`. Each action includes an\n`type` discriminator and action-specific fields.\n",13706        "items": {13707         "oneOf": [13708          {13709           "properties": {13710            "type": {13711             "type": "string",13712             "enum": [13713              "click"13714             ],13715             "description": "Specifies the event type. For a click action, this property is always `click`.",13716             "default": "click",13717             "x-stainless-const": true13718            },13719            "button": {13720             "type": "string",13721             "enum": [13722              "left",13723              "right",13724              "wheel",13725              "back",13726              "forward"13727             ]13728            },13729            "x": {13730             "type": "integer",13731             "description": "The x-coordinate where the click occurred."13732            },13733            "y": {13734             "type": "integer",13735             "description": "The y-coordinate where the click occurred."13736            },13737            "keys": {13738             "anyOf": [13739              {13740               "items": {13741                "type": "string"13742               },13743               "type": "array",13744               "description": "The keys being held while clicking."13745              },13746              {13747               "type": "null"13748              }13749             ]13750            }13751           },13752           "type": "object",13753           "required": [13754            "type",13755            "button",13756            "x",13757            "y"13758           ],13759           "title": "Click",13760           "description": "A click action."13761          },13762          {13763           "properties": {13764            "type": {13765             "type": "string",13766             "enum": [13767              "double_click"13768             ],13769             "description": "Specifies the event type. For a double click action, this property is always set to `double_click`.",13770             "default": "double_click",13771             "x-stainless-const": true13772            },13773            "x": {13774             "type": "integer",13775             "description": "The x-coordinate where the double click occurred."13776            },13777            "y": {13778             "type": "integer",13779             "description": "The y-coordinate where the double click occurred."13780            },13781            "keys": {13782             "anyOf": [13783              {13784               "items": {13785                "type": "string"13786               },13787               "type": "array",13788               "description": "The keys being held while double-clicking."13789              },13790              {13791               "type": "null"13792              }13793             ]13794            }13795           },13796           "type": "object",13797           "required": [13798            "type",13799            "x",13800            "y",13801            "keys"13802           ],13803           "title": "DoubleClick",13804           "description": "A double click action."13805          },13806          {13807           "properties": {13808            "type": {13809             "type": "string",13810             "enum": [13811              "drag"13812             ],13813             "description": "Specifies the event type. For a drag action, this property is always set to `drag`.",13814             "default": "drag",13815             "x-stainless-const": true13816            },13817            "path": {13818             "items": {13819              "properties": {13820               "x": {13821                "type": {13822                 "$comment": "depth-limited"13823                },13824                "description": {13825                 "$comment": "depth-limited"13826                }13827               },13828               "y": {13829                "type": {13830                 "$comment": "depth-limited"13831                },13832                "description": {13833                 "$comment": "depth-limited"13834                }13835               }13836              },13837              "type": "object",13838              "required": [13839               "x",13840               "y"13841              ],13842              "title": "Coordinate",13843              "description": "An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`."13844             },13845             "type": "array",13846             "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```"13847            },13848            "keys": {13849             "anyOf": [13850              {13851               "items": {13852                "type": "string"13853               },13854               "type": "array",13855               "description": "The keys being held while dragging the mouse."13856              },13857              {13858               "type": "null"13859              }13860             ]13861            }13862           },13863           "type": "object",13864           "required": [13865            "type",13866            "path"13867           ],13868           "title": "Drag",13869           "description": "A drag action."13870          },13871          {13872           "properties": {13873            "type": {13874             "type": "string",13875             "enum": [13876              "keypress"13877             ],13878             "description": "Specifies the event type. For a keypress action, this property is always set to `keypress`.",13879             "default": "keypress",13880             "x-stainless-const": true13881            },13882            "keys": {13883             "items": {13884              "type": "string",13885              "description": "One of the keys the model is requesting to be pressed."13886             },13887             "type": "array",13888             "description": "The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key."13889            }13890           },13891           "type": "object",13892           "required": [13893            "type",13894            "keys"13895           ],13896           "title": "KeyPress",13897           "description": "A collection of keypresses the model would like to perform."13898          },13899          {13900           "properties": {13901            "type": {13902             "type": "string",13903             "enum": [13904              "move"13905             ],13906             "description": "Specifies the event type. For a move action, this property is always set to `move`.",13907             "default": "move",13908             "x-stainless-const": true13909            },13910            "x": {13911             "type": "integer",13912             "description": "The x-coordinate to move to."13913            },13914            "y": {13915             "type": "integer",13916             "description": "The y-coordinate to move to."13917            },13918            "keys": {13919             "anyOf": [13920              {13921               "items": {13922                "type": "string"13923               },13924               "type": "array",13925               "description": "The keys being held while moving the mouse."13926              },13927              {13928               "type": "null"13929              }13930             ]13931            }13932           },13933           "type": "object",13934           "required": [13935            "type",13936            "x",13937            "y"13938           ],13939           "title": "Move",13940           "description": "A mouse move action."13941          },13942          {13943           "properties": {13944            "type": {13945             "type": "string",13946             "enum": [13947              "screenshot"13948             ],13949             "description": "Specifies the event type. For a screenshot action, this property is always set to `screenshot`.",13950             "default": "screenshot",13951             "x-stainless-const": true13952            }13953           },13954           "type": "object",13955           "required": [13956            "type"13957           ],13958           "title": "Screenshot",13959           "description": "A screenshot action."13960          },13961          {13962           "properties": {13963            "type": {13964             "type": "string",13965             "enum": [13966              "scroll"13967             ],13968             "description": "Specifies the event type. For a scroll action, this property is always set to `scroll`.",13969             "default": "scroll",13970             "x-stainless-const": true13971            },13972            "x": {13973             "type": "integer",13974             "description": "The x-coordinate where the scroll occurred."13975            },13976            "y": {13977             "type": "integer",13978             "description": "The y-coordinate where the scroll occurred."13979            },13980            "scroll_x": {13981             "type": "integer",13982             "description": "The horizontal scroll distance."13983            },13984            "scroll_y": {13985             "type": "integer",13986             "description": "The vertical scroll distance."13987            },13988            "keys": {13989             "anyOf": [13990              {13991               "items": {13992                "type": "string"13993               },13994               "type": "array",13995               "description": "The keys being held while scrolling."13996              },13997              {13998               "type": "null"13999              }14000             ]14001            }14002           },14003           "type": "object",14004           "required": [14005            "type",14006            "x",14007            "y",14008            "scroll_x",14009            "scroll_y"14010           ],14011           "title": "Scroll",14012           "description": "A scroll action."14013          },14014          {14015           "properties": {14016            "type": {14017             "type": "string",14018             "enum": [14019              "type"14020             ],14021             "description": "Specifies the event type. For a type action, this property is always set to `type`.",14022             "default": "type",14023             "x-stainless-const": true14024            },14025            "text": {14026             "type": "string",14027             "description": "The text to type."14028            }14029           },14030           "type": "object",14031           "required": [14032            "type",14033            "text"14034           ],14035           "title": "Type",14036           "description": "An action to type in text."14037          },14038          {14039           "properties": {14040            "type": {14041             "type": "string",14042             "enum": [14043              "wait"14044             ],14045             "description": "Specifies the event type. For a wait action, this property is always set to `wait`.",14046             "default": "wait",14047             "x-stainless-const": true14048            }14049           },14050           "type": "object",14051           "required": [14052            "type"14053           ],14054           "title": "Wait",14055           "description": "A wait action."14056          }14057         ],14058         "discriminator": {14059          "propertyName": "type"14060         }14061        }14062       },14063       "pending_safety_checks": {14064        "type": "array",14065        "items": {14066         "properties": {14067          "id": {14068           "type": "string",14069           "description": "The ID of the pending safety check."14070          },14071          "code": {14072           "anyOf": [14073            {14074             "type": "string",14075             "description": "The type of the pending safety check."14076            },14077            {14078             "type": "null"14079            }14080           ]14081          },14082          "message": {14083           "anyOf": [14084            {14085             "type": "string",14086             "description": "Details about the pending safety check."14087            },14088            {14089             "type": "null"14090            }14091           ]14092          }14093         },14094         "type": "object",14095         "required": [14096          "id"14097         ],14098         "description": "A pending safety check for the computer call."14099        },14100        "description": "The pending safety checks for the computer call.\n"14101       },14102       "status": {14103        "type": "string",14104        "description": "The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.\n",14105        "enum": [14106         "in_progress",14107         "completed",14108         "incomplete"14109        ]14110       }14111      },14112      "required": [14113       "type",14114       "id",14115       "call_id",14116       "pending_safety_checks",14117       "status"14118      ]14119     }14120    },14121    {14122     "schema_name": "ComputerToolCallOutput",14123     "type": "computer_call_output",14124     "schema": {14125      "type": "object",14126      "title": "Computer tool call output",14127      "description": "The output of a computer tool call.\n",14128      "properties": {14129       "type": {14130        "type": "string",14131        "description": "The type of the computer tool call output. Always `computer_call_output`.\n",14132        "enum": [14133         "computer_call_output"14134        ],14135        "default": "computer_call_output",14136        "x-stainless-const": true14137       },14138       "id": {14139        "type": "string",14140        "description": "The ID of the computer tool call output.\n"14141       },14142       "call_id": {14143        "type": "string",14144        "description": "The ID of the computer tool call that produced the output.\n"14145       },14146       "acknowledged_safety_checks": {14147        "type": "array",14148        "description": "The safety checks reported by the API that have been acknowledged by the\ndeveloper.\n",14149        "items": {14150         "properties": {14151          "id": {14152           "type": "string",14153           "description": "The ID of the pending safety check."14154          },14155          "code": {14156           "anyOf": [14157            {14158             "type": "string",14159             "description": "The type of the pending safety check."14160            },14161            {14162             "type": "null"14163            }14164           ]14165          },14166          "message": {14167           "anyOf": [14168            {14169             "type": "string",14170             "description": "Details about the pending safety check."14171            },14172            {14173             "type": "null"14174            }14175           ]14176          }14177         },14178         "type": "object",14179         "required": [14180          "id"14181         ],14182         "description": "A pending safety check for the computer call."14183        }14184       },14185       "output": {14186        "type": "object",14187        "description": "A computer screenshot image used with the computer use tool.\n",14188        "properties": {14189         "type": {14190          "type": "string",14191          "enum": [14192           "computer_screenshot"14193          ],14194          "default": "computer_screenshot",14195          "description": "Specifies the event type. For a computer screenshot, this property is \nalways set to `computer_screenshot`.\n",14196          "x-stainless-const": true14197         },14198         "image_url": {14199          "type": "string",14200          "format": "uri",14201          "description": "The URL of the screenshot image."14202         },14203         "file_id": {14204          "type": "string",14205          "description": "The identifier of an uploaded file that contains the screenshot."14206         }14207        },14208        "required": [14209         "type"14210        ]14211       },14212       "status": {14213        "type": "string",14214        "description": "The status of the message input. One of `in_progress`, `completed`, or\n`incomplete`. Populated when input items are returned via API.\n",14215        "enum": [14216         "in_progress",14217         "completed",14218         "incomplete"14219        ]14220       }14221      },14222      "required": [14223       "type",14224       "call_id",14225       "output"14226      ]14227     }14228    }14229   ],14230   "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."14231  },14232  "billing": {14233   "model": "computer-use-preview $3 / 1M input, $12 / 1M output (model page); newer models at their own rates",14234   "source": "https://developers.openai.com/api/docs/models/computer-use-preview"14235  },14236  "limitations": [14237   "Requires `truncation: auto` with computer-use-preview.",14238   "Our key: model computer-use-preview -> 404 model_not_found (tiered/limited access)."14239  ],14240  "security": [14241   "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."14242  ],14243  "beta_header": null,14244  "status": [14245   "DOCUMENTED",14246   "PREVIEW",14247   "ACCOUNT_RESTRICTED"14248  ],14249  "examples": {14250   "curl": "examples/openai/tools/computer-use/computer_use.sh",14251   "python": "examples/openai/tools/computer-use/computer_use.py",14252   "typescript": "examples/openai/tools/computer-use/computer_use.ts"14253  },14254  "verification": {14255   "computer_use_preview_model": {14256    "method": "live_api",14257    "verified_at": "2026-09-18",14258    "result": "restricted",14259    "http_status": 404,14260    "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'"14261   }14262  },14263  "sources": [14264   {14265    "url": "https://developers.openai.com/api/docs/guides/tools-computer-use",14266    "retrieved_at": "2026-09-18"14267   },14268   {14269    "url": "https://developers.openai.com/api/docs/guides/tools-computer-use-integration",14270    "retrieved_at": "2026-09-18"14271   },14272   {14273    "url": "https://developers.openai.com/api/docs/models/computer-use-preview",14274    "retrieved_at": "2026-09-18"14275   },14276   {14277    "url": "https://developers.openai.com/api/reference/resources/responses/methods/create",14278    "retrieved_at": "2026-09-18"14279   },14280   {14281    "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)",14282    "retrieved_at": "2026-09-18"14283   }14284  ],14285  "last_verified": "2026-09-18",14286  "_fragment": "generated/fragments/tools/openai-tools.json"14287 },14288 {14289  "provider": "openai",14290  "name": "Computer tool (current)",14291  "type": "computer",14292  "category": "client",14293  "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.",14294  "compatible_models": [14295   "gpt-5.4",14296   "gpt-5.4-mini",14297   "gpt-5.4-pro",14298   "gpt-5.5",14299   "gpt-5.6-cyber",14300   "gpt-5.6-luna",14301   "gpt-5.6-sol",14302   "gpt-5.6-terra",14303   "gpt-6-astra",14304   "gpt-daybreak-blue-latest",14305   "gpt-daybreak-red-latest"14306  ],14307  "compatible_endpoints": [14308   "POST /v1/responses"14309  ],14310  "parameters_schema": {14311   "properties": {14312    "type": {14313     "type": "string",14314     "enum": [14315      "computer"14316     ],14317     "description": "The type of the computer tool. Always `computer`.",14318     "default": "computer",14319     "x-stainless-const": true14320    }14321   },14322   "type": "object",14323   "required": [14324    "type"14325   ],14326   "title": "Computer",14327   "description": "A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use)."14328  },14329  "tool_choice_support": {14330   "modes": [14331    "none",14332    "auto",14333    "required"14334   ],14335   "allowed_tools": {14336    "type": "allowed_tools",14337    "mode": "auto|required",14338    "tools": [14339     "{type,name,...}"14340    ]14341   },14342   "specific": [14343    {14344     "type": "computer"14345    },14346    {14347     "type": "computer_use"14348    }14349   ]14350  },14351  "parallel": {14352   "supported": false14353  },14354  "streaming_events": [14355   "response.output_item.added",14356   "response.output_item.done"14357  ],14358  "result_shape": {14359   "items": [14360    {14361     "schema_name": "ComputerToolCall",14362     "type": "computer_call",14363     "schema": {14364      "type": "object",14365      "title": "Computer tool call",14366      "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",14367      "properties": {14368       "type": {14369        "type": "string",14370        "description": "The type of the computer call. Always `computer_call`.",14371        "enum": [14372         "computer_call"14373        ],14374        "default": "computer_call"14375       },14376       "id": {14377        "type": "string",14378        "description": "The unique ID of the computer call."14379       },14380       "call_id": {14381        "type": "string",14382        "description": "An identifier used when responding to the tool call with output.\n"14383       },14384       "action": {14385        "oneOf": [14386         {14387          "properties": {14388           "type": {14389            "type": "string",14390            "enum": [14391             "click"14392            ],14393            "description": "Specifies the event type. For a click action, this property is always `click`.",14394            "default": "click",14395            "x-stainless-const": true14396           },14397           "button": {14398            "type": "string",14399            "enum": [14400             "left",14401             "right",14402             "wheel",14403             "back",14404             "forward"14405            ]14406           },14407           "x": {14408            "type": "integer",14409            "description": "The x-coordinate where the click occurred."14410           },14411           "y": {14412            "type": "integer",14413            "description": "The y-coordinate where the click occurred."14414           },14415           "keys": {14416            "anyOf": [14417             {14418              "items": {14419               "type": "string"14420              },14421              "type": "array",14422              "description": "The keys being held while clicking."14423             },14424             {14425              "type": "null"14426             }14427            ]14428           }14429          },14430          "type": "object",14431          "required": [14432           "type",14433           "button",14434           "x",14435           "y"14436          ],14437          "title": "Click",14438          "description": "A click action."14439         },14440         {14441          "properties": {14442           "type": {14443            "type": "string",14444            "enum": [14445             "double_click"14446            ],14447            "description": "Specifies the event type. For a double click action, this property is always set to `double_click`.",14448            "default": "double_click",14449            "x-stainless-const": true14450           },14451           "x": {14452            "type": "integer",14453            "description": "The x-coordinate where the double click occurred."14454           },14455           "y": {14456            "type": "integer",14457            "description": "The y-coordinate where the double click occurred."14458           },14459           "keys": {14460            "anyOf": [14461             {14462              "items": {14463               "type": "string"14464              },14465              "type": "array",14466              "description": "The keys being held while double-clicking."14467             },14468             {14469              "type": "null"14470             }14471            ]14472           }14473          },14474          "type": "object",14475          "required": [14476           "type",14477           "x",14478           "y",14479           "keys"14480          ],14481          "title": "DoubleClick",14482          "description": "A double click action."14483         },14484         {14485          "properties": {14486           "type": {14487            "type": "string",14488            "enum": [14489             "drag"14490            ],14491            "description": "Specifies the event type. For a drag action, this property is always set to `drag`.",14492            "default": "drag",14493            "x-stainless-const": true14494           },14495           "path": {14496            "items": {14497             "properties": {14498              "x": {14499               "type": "integer",14500               "description": "The x-coordinate."14501              },14502              "y": {14503               "type": "integer",14504               "description": "The y-coordinate."14505              }14506             },14507             "type": "object",14508             "required": [14509              "x",14510              "y"14511             ],14512             "title": "Coordinate",14513             "description": "An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`."14514            },14515            "type": "array",14516            "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```"14517           },14518           "keys": {14519            "anyOf": [14520             {14521              "items": {14522               "type": "string"14523              },14524              "type": "array",14525              "description": "The keys being held while dragging the mouse."14526             },14527             {14528              "type": "null"14529             }14530            ]14531           }14532          },14533          "type": "object",14534          "required": [14535           "type",14536           "path"14537          ],14538          "title": "Drag",14539          "description": "A drag action."14540         },14541         {14542          "properties": {14543           "type": {14544            "type": "string",14545            "enum": [14546             "keypress"14547            ],14548            "description": "Specifies the event type. For a keypress action, this property is always set to `keypress`.",14549            "default": "keypress",14550            "x-stainless-const": true14551           },14552           "keys": {14553            "items": {14554             "type": "string",14555             "description": "One of the keys the model is requesting to be pressed."14556            },14557            "type": "array",14558            "description": "The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key."14559           }14560          },14561          "type": "object",14562          "required": [14563           "type",14564           "keys"14565          ],14566          "title": "KeyPress",14567          "description": "A collection of keypresses the model would like to perform."14568         },14569         {14570          "properties": {14571           "type": {14572            "type": "string",14573            "enum": [14574             "move"14575            ],14576            "description": "Specifies the event type. For a move action, this property is always set to `move`.",14577            "default": "move",14578            "x-stainless-const": true14579           },14580           "x": {14581            "type": "integer",14582            "description": "The x-coordinate to move to."14583           },14584           "y": {14585            "type": "integer",14586            "description": "The y-coordinate to move to."14587           },14588           "keys": {14589            "anyOf": [14590             {14591              "items": {14592               "type": "string"14593              },14594              "type": "array",14595              "description": "The keys being held while moving the mouse."14596             },14597             {14598              "type": "null"14599             }14600            ]14601           }14602          },14603          "type": "object",14604          "required": [14605           "type",14606           "x",14607           "y"14608          ],14609          "title": "Move",14610          "description": "A mouse move action."14611         },14612         {14613          "properties": {14614           "type": {14615            "type": "string",14616            "enum": [14617             "screenshot"14618            ],14619            "description": "Specifies the event type. For a screenshot action, this property is always set to `screenshot`.",14620            "default": "screenshot",14621            "x-stainless-const": true14622           }14623          },14624          "type": "object",14625          "required": [14626           "type"14627          ],14628          "title": "Screenshot",14629          "description": "A screenshot action."14630         },14631         {14632          "properties": {14633           "type": {14634            "type": "string",14635            "enum": [14636             "scroll"14637            ],14638            "description": "Specifies the event type. For a scroll action, this property is always set to `scroll`.",14639            "default": "scroll",14640            "x-stainless-const": true14641           },14642           "x": {14643            "type": "integer",14644            "description": "The x-coordinate where the scroll occurred."14645           },14646           "y": {14647            "type": "integer",14648            "description": "The y-coordinate where the scroll occurred."14649           },14650           "scroll_x": {14651            "type": "integer",14652            "description": "The horizontal scroll distance."14653           },14654           "scroll_y": {14655            "type": "integer",14656            "description": "The vertical scroll distance."14657           },14658           "keys": {14659            "anyOf": [14660             {14661              "items": {14662               "type": "string"14663              },14664              "type": "array",14665              "description": "The keys being held while scrolling."14666             },14667             {14668              "type": "null"14669             }14670            ]14671           }14672          },14673          "type": "object",14674          "required": [14675           "type",14676           "x",14677           "y",14678           "scroll_x",14679           "scroll_y"14680          ],14681          "title": "Scroll",14682          "description": "A scroll action."14683         },14684         {14685          "properties": {14686           "type": {14687            "type": "string",14688            "enum": [14689             "type"14690            ],14691            "description": "Specifies the event type. For a type action, this property is always set to `type`.",14692            "default": "type",14693            "x-stainless-const": true14694           },14695           "text": {14696            "type": "string",14697            "description": "The text to type."14698           }14699          },14700          "type": "object",14701          "required": [14702           "type",14703           "text"14704          ],14705          "title": "Type",14706          "description": "An action to type in text."14707         },14708         {14709          "properties": {14710           "type": {14711            "type": "string",14712            "enum": [14713             "wait"14714            ],14715            "description": "Specifies the event type. For a wait action, this property is always set to `wait`.",14716            "default": "wait",14717            "x-stainless-const": true14718           }14719          },14720          "type": "object",14721          "required": [14722           "type"14723          ],14724          "title": "Wait",14725          "description": "A wait action."14726         }14727        ],14728        "discriminator": {14729         "propertyName": "type"14730        }14731       },14732       "actions": {14733        "title": "Computer Action List",14734        "type": "array",14735        "description": "Flattened batched actions for `computer_use`. Each action includes an\n`type` discriminator and action-specific fields.\n",14736        "items": {14737         "oneOf": [14738          {14739           "properties": {14740            "type": {14741             "type": "string",14742             "enum": [14743              "click"14744             ],14745             "description": "Specifies the event type. For a click action, this property is always `click`.",14746             "default": "click",14747             "x-stainless-const": true14748            },14749            "button": {14750             "type": "string",14751             "enum": [14752              "left",14753              "right",14754              "wheel",14755              "back",14756              "forward"14757             ]14758            },14759            "x": {14760             "type": "integer",14761             "description": "The x-coordinate where the click occurred."14762            },14763            "y": {14764             "type": "integer",14765             "description": "The y-coordinate where the click occurred."14766            },14767            "keys": {14768             "anyOf": [14769              {14770               "items": {14771                "type": "string"14772               },14773               "type": "array",14774               "description": "The keys being held while clicking."14775              },14776              {14777               "type": "null"14778              }14779             ]14780            }14781           },14782           "type": "object",14783           "required": [14784            "type",14785            "button",14786            "x",14787            "y"14788           ],14789           "title": "Click",14790           "description": "A click action."14791          },14792          {14793           "properties": {14794            "type": {14795             "type": "string",14796             "enum": [14797              "double_click"14798             ],14799             "description": "Specifies the event type. For a double click action, this property is always set to `double_click`.",14800             "default": "double_click",14801             "x-stainless-const": true14802            },14803            "x": {14804             "type": "integer",14805             "description": "The x-coordinate where the double click occurred."14806            },14807            "y": {14808             "type": "integer",14809             "description": "The y-coordinate where the double click occurred."14810            },14811            "keys": {14812             "anyOf": [14813              {14814               "items": {14815                "type": "string"14816               },14817               "type": "array",14818               "description": "The keys being held while double-clicking."14819              },14820              {14821               "type": "null"14822              }14823             ]14824            }14825           },14826           "type": "object",14827           "required": [14828            "type",14829            "x",14830            "y",14831            "keys"14832           ],14833           "title": "DoubleClick",14834           "description": "A double click action."14835          },14836          {14837           "properties": {14838            "type": {14839             "type": "string",14840             "enum": [14841              "drag"14842             ],14843             "description": "Specifies the event type. For a drag action, this property is always set to `drag`.",14844             "default": "drag",14845             "x-stainless-const": true14846            },14847            "path": {14848             "items": {14849              "properties": {14850               "x": {14851                "type": {14852                 "$comment": "depth-limited"14853                },14854                "description": {14855                 "$comment": "depth-limited"14856                }14857               },14858               "y": {14859                "type": {14860                 "$comment": "depth-limited"14861                },14862                "description": {14863                 "$comment": "depth-limited"14864                }14865               }14866              },14867              "type": "object",14868              "required": [14869               "x",14870               "y"14871              ],14872              "title": "Coordinate",14873              "description": "An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`."14874             },14875             "type": "array",14876             "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```"14877            },14878            "keys": {14879             "anyOf": [14880              {14881               "items": {14882                "type": "string"14883               },14884               "type": "array",14885               "description": "The keys being held while dragging the mouse."14886              },14887              {14888               "type": "null"14889              }14890             ]14891            }14892           },14893           "type": "object",14894           "required": [14895            "type",14896            "path"14897           ],14898           "title": "Drag",14899           "description": "A drag action."14900          },14901          {14902           "properties": {14903            "type": {14904             "type": "string",14905             "enum": [14906              "keypress"14907             ],14908             "description": "Specifies the event type. For a keypress action, this property is always set to `keypress`.",14909             "default": "keypress",14910             "x-stainless-const": true14911            },14912            "keys": {14913             "items": {14914              "type": "string",14915              "description": "One of the keys the model is requesting to be pressed."14916             },14917             "type": "array",14918             "description": "The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key."14919            }14920           },14921           "type": "object",14922           "required": [14923            "type",14924            "keys"14925           ],14926           "title": "KeyPress",14927           "description": "A collection of keypresses the model would like to perform."14928          },14929          {14930           "properties": {14931            "type": {14932             "type": "string",14933             "enum": [14934              "move"14935             ],14936             "description": "Specifies the event type. For a move action, this property is always set to `move`.",14937             "default": "move",14938             "x-stainless-const": true14939            },14940            "x": {14941             "type": "integer",14942             "description": "The x-coordinate to move to."14943            },14944            "y": {14945             "type": "integer",14946             "description": "The y-coordinate to move to."14947            },14948            "keys": {14949             "anyOf": [14950              {14951               "items": {14952                "type": "string"14953               },14954               "type": "array",14955               "description": "The keys being held while moving the mouse."14956              },14957              {14958               "type": "null"14959              }14960             ]14961            }14962           },14963           "type": "object",14964           "required": [14965            "type",14966            "x",14967            "y"14968           ],14969           "title": "Move",14970           "description": "A mouse move action."14971          },14972          {14973           "properties": {14974            "type": {14975             "type": "string",14976             "enum": [14977              "screenshot"14978             ],14979             "description": "Specifies the event type. For a screenshot action, this property is always set to `screenshot`.",14980             "default": "screenshot",14981             "x-stainless-const": true14982            }14983           },14984           "type": "object",14985           "required": [14986            "type"14987           ],14988           "title": "Screenshot",14989           "description": "A screenshot action."14990          },14991          {14992           "properties": {14993            "type": {14994             "type": "string",14995             "enum": [14996              "scroll"14997             ],14998             "description": "Specifies the event type. For a scroll action, this property is always set to `scroll`.",14999             "default": "scroll",15000             "x-stainless-const": true15001            },15002            "x": {15003             "type": "integer",15004             "description": "The x-coordinate where the scroll occurred."15005            },15006            "y": {15007             "type": "integer",15008             "description": "The y-coordinate where the scroll occurred."15009            },15010            "scroll_x": {15011             "type": "integer",15012             "description": "The horizontal scroll distance."15013            },15014            "scroll_y": {15015             "type": "integer",15016             "description": "The vertical scroll distance."15017            },15018            "keys": {15019             "anyOf": [15020              {15021               "items": {15022                "type": "string"15023               },15024               "type": "array",15025               "description": "The keys being held while scrolling."15026              },15027              {15028               "type": "null"15029              }15030             ]15031            }15032           },15033           "type": "object",15034           "required": [15035            "type",15036            "x",15037            "y",15038            "scroll_x",15039            "scroll_y"15040           ],15041           "title": "Scroll",15042           "description": "A scroll action."15043          },15044          {15045           "properties": {15046            "type": {15047             "type": "string",15048             "enum": [15049              "type"15050             ],15051             "description": "Specifies the event type. For a type action, this property is always set to `type`.",15052             "default": "type",15053             "x-stainless-const": true15054            },15055            "text": {15056             "type": "string",15057             "description": "The text to type."15058            }15059           },15060           "type": "object",15061           "required": [15062            "type",15063            "text"15064           ],15065           "title": "Type",15066           "description": "An action to type in text."15067          },15068          {15069           "properties": {15070            "type": {15071             "type": "string",15072             "enum": [15073              "wait"15074             ],15075             "description": "Specifies the event type. For a wait action, this property is always set to `wait`.",15076             "default": "wait",15077             "x-stainless-const": true15078            }15079           },15080           "type": "object",15081           "required": [15082            "type"15083           ],15084           "title": "Wait",15085           "description": "A wait action."15086          }15087         ],15088         "discriminator": {15089          "propertyName": "type"15090         }15091        }15092       },15093       "pending_safety_checks": {15094        "type": "array",15095        "items": {15096         "properties": {15097          "id": {15098           "type": "string",15099           "description": "The ID of the pending safety check."15100          },15101          "code": {15102           "anyOf": [15103            {15104             "type": "string",15105             "description": "The type of the pending safety check."15106            },15107            {15108             "type": "null"15109            }15110           ]15111          },15112          "message": {15113           "anyOf": [15114            {15115             "type": "string",15116             "description": "Details about the pending safety check."15117            },15118            {15119             "type": "null"15120            }15121           ]15122          }15123         },15124         "type": "object",15125         "required": [15126          "id"15127         ],15128         "description": "A pending safety check for the computer call."15129        },15130        "description": "The pending safety checks for the computer call.\n"15131       },15132       "status": {15133        "type": "string",15134        "description": "The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.\n",15135        "enum": [15136         "in_progress",15137         "completed",15138         "incomplete"15139        ]15140       }15141      },15142      "required": [15143       "type",15144       "id",15145       "call_id",15146       "pending_safety_checks",15147       "status"15148      ]15149     }15150    },15151    {15152     "schema_name": "ComputerToolCallOutput",15153     "type": "computer_call_output",15154     "schema": {15155      "type": "object",15156      "title": "Computer tool call output",15157      "description": "The output of a computer tool call.\n",15158      "properties": {15159       "type": {15160        "type": "string",15161        "description": "The type of the computer tool call output. Always `computer_call_output`.\n",15162        "enum": [15163         "computer_call_output"15164        ],15165        "default": "computer_call_output",15166        "x-stainless-const": true15167       },15168       "id": {15169        "type": "string",15170        "description": "The ID of the computer tool call output.\n"15171       },15172       "call_id": {15173        "type": "string",15174        "description": "The ID of the computer tool call that produced the output.\n"15175       },15176       "acknowledged_safety_checks": {15177        "type": "array",15178        "description": "The safety checks reported by the API that have been acknowledged by the\ndeveloper.\n",15179        "items": {15180         "properties": {15181          "id": {15182           "type": "string",15183           "description": "The ID of the pending safety check."15184          },15185          "code": {15186           "anyOf": [15187            {15188             "type": "string",15189             "description": "The type of the pending safety check."15190            },15191            {15192             "type": "null"15193            }15194           ]15195          },15196          "message": {15197           "anyOf": [15198            {15199             "type": "string",15200             "description": "Details about the pending safety check."15201            },15202            {15203             "type": "null"15204            }15205           ]15206          }15207         },15208         "type": "object",15209         "required": [15210          "id"15211         ],15212         "description": "A pending safety check for the computer call."15213        }15214       },15215       "output": {15216        "type": "object",15217        "description": "A computer screenshot image used with the computer use tool.\n",15218        "properties": {15219         "type": {15220          "type": "string",15221          "enum": [15222           "computer_screenshot"15223          ],15224          "default": "computer_screenshot",15225          "description": "Specifies the event type. For a computer screenshot, this property is \nalways set to `computer_screenshot`.\n",15226          "x-stainless-const": true15227         },15228         "image_url": {15229          "type": "string",15230          "format": "uri",15231          "description": "The URL of the screenshot image."15232         },15233         "file_id": {15234          "type": "string",15235          "description": "The identifier of an uploaded file that contains the screenshot."15236         }15237        },15238        "required": [15239         "type"15240        ]15241       },15242       "status": {15243        "type": "string",15244        "description": "The status of the message input. One of `in_progress`, `completed`, or\n`incomplete`. Populated when input items are returned via API.\n",15245        "enum": [15246         "in_progress",15247         "completed",15248         "incomplete"15249        ]15250       }15251      },15252      "required": [15253       "type",15254       "call_id",15255       "output"15256      ]15257     }15258    }15259   ],15260   "summary": "Same as computer_use_preview plus `actions[]` batches."15261  },15262  "billing": {15263   "model": "Token billing (images as input tokens)",15264   "source": "https://developers.openai.com/api/docs/pricing#built-in-tools"15265  },15266  "limitations": [15267   "Not live-tested (cost/safety); docs recommend code-execution integration for GPT-6 Astra."15268  ],15269  "security": [15270   "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."15271  ],15272  "beta_header": null,15273  "status": [15274   "DOCUMENTED",15275   "UNVERIFIED"15276  ],15277  "examples": {15278   "curl": "examples/openai/tools/computer-use/computer_use.sh",15279   "python": "examples/openai/tools/computer-use/computer_use.py",15280   "typescript": "examples/openai/tools/computer-use/computer_use.ts"15281  },15282  "verification": {15283   "docs": {15284    "method": "docs_only",15285    "verified_at": "2026-09-18",15286    "result": "success",15287    "http_status": 0,15288    "request_note": "not called"15289   }15290  },15291  "sources": [15292   {15293    "url": "https://developers.openai.com/api/docs/guides/tools-computer-use",15294    "retrieved_at": "2026-09-18"15295   },15296   {15297    "url": "https://developers.openai.com/api/docs/guides/tools-computer-use-integration",15298    "retrieved_at": "2026-09-18"15299   },15300   {15301    "url": "https://developers.openai.com/api/reference/resources/responses/methods/create",15302    "retrieved_at": "2026-09-18"15303   },15304   {15305    "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)",15306    "retrieved_at": "2026-09-18"15307   }15308  ],15309  "last_verified": "2026-09-18",15310  "_fragment": "generated/fragments/tools/openai-tools.json"15311 },15312 {15313  "provider": "openai",15314  "name": "Image generation tool",15315  "type": "image_generation",15316  "category": "hosted",15317  "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`.",15318  "compatible_models": [15319   "chat-latest",15320   "gpt-4.1",15321   "gpt-4.1-nano",15322   "gpt-4o",15323   "gpt-4o-mini",15324   "gpt-5",15325   "gpt-5-chat-latest",15326   "gpt-5-nano",15327   "gpt-5-pro",15328   "gpt-5.1",15329   "gpt-5.1-chat-latest",15330   "gpt-5.2",15331   "gpt-5.2-chat-latest",15332   "gpt-5.2-pro",15333   "gpt-5.3-chat-latest",15334   "gpt-5.4",15335   "gpt-5.4-mini",15336   "gpt-5.4-nano",15337   "gpt-5.4-pro",15338   "gpt-5.5",15339   "gpt-5.5-pro",15340   "gpt-5.6-cyber",15341   "gpt-5.6-luna",15342   "gpt-5.6-sol",15343   "gpt-5.6-terra",15344   "gpt-6-astra",15345   "gpt-daybreak-blue-latest",15346   "gpt-daybreak-red-latest",15347   "o3",15348   "o3-mini",15349   "o3-pro"15350  ],15351  "compatible_endpoints": [15352   "POST /v1/responses"15353  ],15354  "parameters_schema": {15355   "type": "object",15356   "title": "Image generation tool",15357   "description": "A tool that generates images using the GPT image models.\n",15358   "properties": {15359    "type": {15360     "type": "string",15361     "enum": [15362      "image_generation"15363     ],15364     "description": "The type of the image generation tool. Always `image_generation`.\n",15365     "x-stainless-const": true15366    },15367    "model": {15368     "anyOf": [15369      {15370       "type": "string"15371      },15372      {15373       "type": "string",15374       "enum": [15375        "gpt-image-1",15376        "gpt-image-1-mini",15377        "gpt-image-1.5",15378        "gpt-image-2",15379        "gpt-image-2-2026-04-21",15380        "gpt-image-2.5-sunburst",15381        "gpt-image-2.5-sunburst-2026-09-08",15382        "gpt-image-2.5-flare",15383        "gpt-image-2.5-flare-2026-09-08"15384       ],15385       "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",15386       "default": "gpt-image-1"15387      }15388     ]15389    },15390    "quality": {15391     "type": "string",15392     "enum": [15393      "low",15394      "medium",15395      "high",15396      "xhigh",15397      "max",15398      "auto"15399     ],15400     "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",15401     "default": "auto"15402    },15403    "size": {15404     "anyOf": [15405      {15406       "type": "string"15407      },15408      {15409       "type": "string",15410       "enum": [15411        "1024x1024",15412        "1024x1536",15413        "1536x1024",15414        "auto"15415       ]15416      }15417     ],15418     "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`.",15419     "default": "auto"15420    },15421    "output_format": {15422     "type": "string",15423     "enum": [15424      "png",15425      "webp",15426      "jpeg"15427     ],15428     "description": "The output format of the generated image. One of `png`, `webp`, or\n`jpeg`. Default: `png`.\n",15429     "default": "png"15430    },15431    "output_compression": {15432     "type": "integer",15433     "minimum": 0,15434     "maximum": 100,15435     "description": "Compression level for the output image. Default: 100.\n",15436     "default": 10015437    },15438    "moderation": {15439     "type": "string",15440     "enum": [15441      "auto",15442      "low"15443     ],15444     "description": "Moderation level for the generated image. Default: `auto`.\n",15445     "default": "auto"15446    },15447    "background": {15448     "type": "string",15449     "enum": [15450      "transparent",15451      "opaque",15452      "auto"15453     ],15454     "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",15455     "default": "auto"15456    },15457    "input_fidelity": {15458     "anyOf": [15459      {15460       "type": "string",15461       "enum": [15462        "high",15463        "low"15464       ],15465       "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`."15466      },15467      {15468       "type": "null"15469      }15470     ]15471    },15472    "input_image_mask": {15473     "type": "object",15474     "description": "Optional mask for inpainting. Contains `image_url`\n(string, optional) and `file_id` (string, optional).\n",15475     "properties": {15476      "image_url": {15477       "type": "string",15478       "description": "Base64-encoded mask image.\n"15479      },15480      "file_id": {15481       "type": "string",15482       "description": "File ID for the mask image.\n"15483      }15484     },15485     "required": [],15486     "additionalProperties": false15487    },15488    "partial_images": {15489     "type": "integer",15490     "minimum": 0,15491     "maximum": 3,15492     "description": "Number of partial images to generate in streaming mode, from 0 (default value) to 3.\n",15493     "default": 015494    },15495    "action": {15496     "type": "string",15497     "enum": [15498      "generate",15499      "edit",15500      "auto"15501     ]15502    }15503   },15504   "required": [15505    "type"15506   ]15507  },15508  "tool_choice_support": {15509   "modes": [15510    "none",15511    "auto",15512    "required"15513   ],15514   "allowed_tools": {15515    "type": "allowed_tools",15516    "mode": "auto|required",15517    "tools": [15518     "{type,name,...}"15519    ]15520   },15521   "specific": {15522    "type": "image_generation"15523   }15524  },15525  "parallel": {15526   "supported": false15527  },15528  "streaming_events": [15529   "response.output_item.added",15530   "response.image_generation_call.in_progress",15531   "response.image_generation_call.generating",15532   "response.image_generation_call.partial_image",15533   "response.image_generation_call.completed",15534   "response.output_item.done"15535  ],15536  "result_shape": {15537   "items": [15538    {15539     "schema_name": "ImageGenToolCall",15540     "type": "image_generation_call",15541     "schema": {15542      "properties": {15543       "type": {15544        "type": "string",15545        "enum": [15546         "image_generation_call"15547        ],15548        "description": "The type of the image generation call. Always `image_generation_call`.",15549        "x-stainless-const": true15550       },15551       "id": {15552        "type": "string",15553        "description": "The unique ID of the image generation call."15554       },15555       "status": {15556        "type": "string",15557        "enum": [15558         "in_progress",15559         "completed",15560         "generating",15561         "failed"15562        ],15563        "description": "The status of the image generation call."15564       },15565       "result": {15566        "anyOf": [15567         {15568          "type": "string",15569          "description": "The generated image encoded in base64."15570         },15571         {15572          "type": "null"15573         }15574        ]15575       },15576       "size": {15577        "anyOf": [15578         {15579          "anyOf": [15580           {15581            "type": "string"15582           },15583           {15584            "type": "string",15585            "enum": [15586             "1024x1024",15587             "1024x1536",15588             "1536x1024"15589            ]15590           }15591          ],15592          "description": "The image dimensions as a `WIDTHxHEIGHT` string, for example `1536x864`."15593         },15594         {15595          "type": "null"15596         }15597        ]15598       },15599       "quality": {15600        "anyOf": [15601         {15602          "type": "string",15603          "enum": [15604           "low",15605           "medium",15606           "high",15607           "xhigh",15608           "max",15609           "auto"15610          ],15611          "description": "The quality of the image generated by the image generation tool call. One of `low`, `medium`, `high`, `xhigh`, `max`, or `auto`."15612         },15613         {15614          "type": "null"15615         }15616        ]15617       },15618       "action": {15619        "anyOf": [15620         {15621          "type": "string",15622          "enum": [15623           "generate",15624           "edit",15625           "auto"15626          ]15627         },15628         {15629          "type": "null"15630         }15631        ],15632        "x-openai-go-optional-enum": true15633       },15634       "background": {15635        "anyOf": [15636         {15637          "type": "string",15638          "enum": [15639           "transparent",15640           "opaque",15641           "auto"15642          ]15643         },15644         {15645          "type": "null"15646         }15647        ],15648        "x-openai-go-optional-enum": true15649       },15650       "output_format": {15651        "anyOf": [15652         {15653          "type": "string",15654          "enum": [15655           "png",15656           "webp",15657           "jpeg"15658          ]15659         },15660         {15661          "type": "null"15662         }15663        ],15664        "x-openai-go-optional-enum": true15665       },15666       "revised_prompt": {15667        "anyOf": [15668         {15669          "type": "string",15670          "description": "The prompt that was used after any model prompt rewriting."15671         },15672         {15673          "type": "null"15674         }15675        ]15676       }15677      },15678      "type": "object",15679      "required": [15680       "type",15681       "id",15682       "status",15683       "result"15684      ],15685      "title": "Image generation call",15686      "description": "An image generation request made by the model."15687     }15688    }15689   ],15690   "summary": "Output item `image_generation_call` {id, status: in_progress|generating|completed|failed, result: base64|null, revised_prompt, size, quality, background, output_format, action}."15691  },15692  "billing": {15693   "per_image": "Image model token pricing (see pricing fragment / image generation guide calculator); mainline model tokens billed separately",15694   "source": "https://developers.openai.com/api/docs/pricing#image-generation"15695  },15696  "limitations": [15697   "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).",15698   "Size must be divisible by 16 (live error).",15699   "xhigh/max quality only on gpt-image-2.5-*."15700  ],15701  "security": [15702   "Moderation `low` relaxes filtering; images may be revised by the mainline model (revised_prompt)."15703  ],15704  "beta_header": null,15705  "status": [15706   "DOCUMENTED",15707   "LIVE_VERIFIED"15708  ],15709  "examples": {15710   "curl": "examples/openai/tools/image-generation/image_generation.sh",15711   "python": "examples/openai/tools/image-generation/image_generation.py",15712   "typescript": "examples/openai/tools/image-generation/image_generation.ts"15713  },15714  "verification": {15715   "invalid_size_error": {15716    "method": "live_api",15717    "verified_at": "2026-09-18",15718    "result": "success",15719    "http_status": 400,15720    "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)"15721   }15722  },15723  "sources": [15724   {15725    "url": "https://developers.openai.com/api/docs/guides/tools-image-generation",15726    "retrieved_at": "2026-09-18"15727   },15728   {15729    "url": "https://developers.openai.com/api/reference/resources/responses/methods/create",15730    "retrieved_at": "2026-09-18"15731   },15732   {15733    "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)",15734    "retrieved_at": "2026-09-18"15735   }15736  ],15737  "last_verified": "2026-09-18",15738  "_fragment": "generated/fragments/tools/openai-tools.json"15739 },15740 {15741  "provider": "openai",15742  "name": "Remote MCP servers, connectors and Secure MCP Tunnel",15743  "type": "mcp",15744  "category": "mcp",15745  "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`.",15746  "compatible_models": [15747   "chat-latest",15748   "gpt-4.1",15749   "gpt-4.1-mini",15750   "gpt-4.1-nano",15751   "gpt-4o",15752   "gpt-4o-mini",15753   "gpt-4o-mini-audio-preview",15754   "gpt-5",15755   "gpt-5-chat-latest",15756   "gpt-5-mini",15757   "gpt-5-nano",15758   "gpt-5-pro",15759   "gpt-5.1",15760   "gpt-5.1-chat-latest",15761   "gpt-5.2",15762   "gpt-5.2-chat-latest",15763   "gpt-5.2-pro",15764   "gpt-5.3-chat-latest",15765   "gpt-5.4",15766   "gpt-5.4-mini",15767   "gpt-5.4-nano",15768   "gpt-5.4-pro",15769   "gpt-5.5",15770   "gpt-5.5-pro",15771   "gpt-5.6-cyber",15772   "gpt-5.6-luna",15773   "gpt-5.6-sol",15774   "gpt-5.6-terra",15775   "gpt-6-astra",15776   "gpt-daybreak-blue-latest",15777   "gpt-daybreak-red-latest",15778   "gpt-oss-120b",15779   "gpt-oss-20b",15780   "o1",15781   "o1-mini",15782   "o1-pro",15783   "o3",15784   "o3-deep-research",15785   "o3-mini",15786   "o3-pro",15787   "o4-mini",15788   "o4-mini-deep-research"15789  ],15790  "compatible_endpoints": [15791   "POST /v1/responses",15792   "POST /v1/realtime (mcp tool)",15793   "Agents API (MCP connections)",15794   "Deep research models"15795  ],15796  "parameters_schema": {15797   "type": "object",15798   "title": "MCP tool",15799   "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",15800   "properties": {15801    "type": {15802     "type": "string",15803     "enum": [15804      "mcp"15805     ],15806     "description": "The type of the MCP tool. Always `mcp`.",15807     "x-stainless-const": true15808    },15809    "server_label": {15810     "type": "string",15811     "description": "A label for this MCP server, used to identify it in tool calls.\n"15812    },15813    "server_url": {15814     "type": "string",15815     "format": "uri",15816     "description": "The URL for the MCP server. One of `server_url`, `connector_id`, or\n`tunnel_id` must be provided.\n"15817    },15818    "connector_id": {15819     "type": "string",15820     "deprecated": true,15821     "enum": [15822      "connector_dropbox",15823      "connector_gmail",15824      "connector_googlecalendar",15825      "connector_googledrive",15826      "connector_microsoftteams",15827      "connector_outlookcalendar",15828      "connector_outlookemail",15829      "connector_sharepoint"15830     ],15831     "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"15832    },15833    "tunnel_id": {15834     "type": "string",15835     "pattern": "^tunnel_[a-z0-9]{32}$",15836     "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"15837    },15838    "authorization": {15839     "type": "string",15840     "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"15841    },15842    "server_description": {15843     "type": "string",15844     "description": "Optional description of the MCP server, used to provide more context.\n"15845    },15846    "headers": {15847     "anyOf": [15848      {15849       "type": "object",15850       "additionalProperties": {15851        "type": "string"15852       },15853       "description": "Optional HTTP headers to send to the MCP server. Use for authentication\nor other purposes.\n"15854      },15855      {15856       "type": "null"15857      }15858     ]15859    },15860    "allowed_tools": {15861     "anyOf": [15862      {15863       "description": "List of allowed tool names or a filter object.\n",15864       "oneOf": [15865        {15866         "type": "array",15867         "title": "MCP allowed tools",15868         "description": "A string array of allowed tool names",15869         "items": {15870          "type": "string"15871         }15872        },15873        {15874         "type": "object",15875         "title": "MCP tool filter",15876         "description": "A filter object to specify which tools are allowed.\n",15877         "properties": {15878          "tool_names": {15879           "type": "array",15880           "title": "MCP allowed tools",15881           "items": {15882            "type": "string"15883           },15884           "description": "List of allowed tool names."15885          },15886          "read_only": {15887           "type": "boolean",15888           "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"15889          }15890         },15891         "required": [],15892         "additionalProperties": false15893        }15894       ]15895      },15896      {15897       "type": "null"15898      }15899     ]15900    },15901    "allowed_callers": {15902     "anyOf": [15903      {15904       "type": "array",15905       "minItems": 1,15906       "items": {15907        "type": "string",15908        "enum": [15909         "direct",15910         "programmatic"15911        ]15912       },15913       "description": "The tool invocation context(s)."15914      },15915      {15916       "type": "null"15917      }15918     ]15919    },15920    "require_approval": {15921     "anyOf": [15922      {15923       "description": "Specify which of the MCP server's tools require approval.",15924       "oneOf": [15925        {15926         "type": "object",15927         "title": "MCP tool approval filter",15928         "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",15929         "properties": {15930          "always": {15931           "type": "object",15932           "title": "MCP tool filter",15933           "description": "A filter object to specify which tools are allowed.\n",15934           "properties": {15935            "tool_names": {15936             "type": "array",15937             "title": "MCP allowed tools",15938             "items": {15939              "type": "string"15940             },15941             "description": "List of allowed tool names."15942            },15943            "read_only": {15944             "type": "boolean",15945             "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"15946            }15947           },15948           "required": [],15949           "additionalProperties": false15950          },15951          "never": {15952           "type": "object",15953           "title": "MCP tool filter",15954           "description": "A filter object to specify which tools are allowed.\n",15955           "properties": {15956            "tool_names": {15957             "type": "array",15958             "title": "MCP allowed tools",15959             "items": {15960              "type": "string"15961             },15962             "description": "List of allowed tool names."15963            },15964            "read_only": {15965             "type": "boolean",15966             "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"15967            }15968           },15969           "required": [],15970           "additionalProperties": false15971          }15972         },15973         "additionalProperties": false15974        },15975        {15976         "type": "string",15977         "title": "MCP tool approval setting",15978         "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",15979         "enum": [15980          "always",15981          "never"15982         ]15983        }15984       ],15985       "default": "always"15986      },15987      {15988       "type": "null"15989      }15990     ]15991    },15992    "defer_loading": {15993     "type": "boolean",15994     "description": "Whether this MCP tool is deferred and discovered via tool search.\n"15995    }15996   },15997   "required": [15998    "type",15999    "server_label"16000   ]16001  },16002  "tool_choice_support": {16003   "modes": [16004    "none",16005    "auto",16006    "required"16007   ],16008   "allowed_tools": {16009    "type": "allowed_tools",16010    "mode": "auto|required",16011    "tools": [16012     "{type,name,...}"16013    ]16014   },16015   "specific": {16016    "type": "mcp",16017    "server_label": "<label>",16018    "name": "<tool or null>"16019   }16020  },16021  "parallel": {16022   "supported": false16023  },16024  "streaming_events": [16025   "response.output_item.added",16026   "response.mcp_list_tools.in_progress",16027   "response.mcp_list_tools.completed",16028   "response.mcp_list_tools.failed",16029   "response.mcp_call.in_progress",16030   "response.mcp_call_arguments.delta",16031   "response.mcp_call_arguments.done",16032   "response.mcp_call.completed",16033   "response.mcp_call.failed",16034   "response.output_item.done"16035  ],16036  "result_shape": {16037   "items": [16038    {16039     "schema_name": "MCPListTools",16040     "type": "mcp_list_tools",16041     "schema": {16042      "type": "object",16043      "title": "MCP list tools",16044      "description": "A list of tools available on an MCP server.\n",16045      "properties": {16046       "type": {16047        "type": "string",16048        "enum": [16049         "mcp_list_tools"16050        ],16051        "description": "The type of the item. Always `mcp_list_tools`.\n",16052        "x-stainless-const": true16053       },16054       "id": {16055        "type": "string",16056        "description": "The unique ID of the list.\n"16057       },16058       "server_label": {16059        "type": "string",16060        "description": "The label of the MCP server.\n"16061       },16062       "tools": {16063        "type": "array",16064        "items": {16065         "type": "object",16066         "title": "MCP list tools tool",16067         "description": "A tool available on an MCP server.\n",16068         "properties": {16069          "name": {16070           "type": "string",16071           "description": "The name of the tool.\n"16072          },16073          "description": {16074           "anyOf": [16075            {16076             "type": "string",16077             "description": "The description of the tool.\n"16078            },16079            {16080             "type": "null"16081            }16082           ]16083          },16084          "input_schema": {16085           "type": "object",16086           "description": "The JSON schema describing the tool's input.\n"16087          },16088          "annotations": {16089           "anyOf": [16090            {16091             "type": "object",16092             "description": "Additional annotations about the tool.\n"16093            },16094            {16095             "type": "null"16096            }16097           ]16098          }16099         },16100         "required": [16101          "name",16102          "input_schema"16103         ]16104        },16105        "description": "The tools available on the server.\n"16106       },16107       "error": {16108        "anyOf": [16109         {16110          "type": "string",16111          "description": "Error message if the server could not list tools.\n"16112         },16113         {16114          "type": "null"16115         }16116        ]16117       }16118      },16119      "required": [16120       "type",16121       "id",16122       "server_label",16123       "tools"16124      ]16125     }16126    },16127    {16128     "schema_name": "MCPToolCall",16129     "type": "mcp_call",16130     "schema": {16131      "type": "object",16132      "title": "MCP tool call",16133      "description": "An invocation of a tool on an MCP server.\n",16134      "properties": {16135       "type": {16136        "type": "string",16137        "enum": [16138         "mcp_call"16139        ],16140        "description": "The type of the item. Always `mcp_call`.\n",16141        "x-stainless-const": true16142       },16143       "id": {16144        "type": "string",16145        "description": "The unique ID of the tool call.\n"16146       },16147       "server_label": {16148        "type": "string",16149        "description": "The label of the MCP server running the tool.\n"16150       },16151       "name": {16152        "type": "string",16153        "description": "The name of the tool that was run.\n"16154       },16155       "arguments": {16156        "type": "string",16157        "description": "A JSON string of the arguments passed to the tool.\n"16158       },16159       "output": {16160        "anyOf": [16161         {16162          "type": "string",16163          "description": "The output from the tool call.\n"16164         },16165         {16166          "type": "null"16167         }16168        ]16169       },16170       "error": {16171        "description": "The error from the tool call, if any.",16172        "anyOf": [16173         {16174          "oneOf": [16175           {16176            "properties": {16177             "type": {16178              "type": "string",16179              "enum": [16180               "mcp_protocol_error"16181              ],16182              "default": "mcp_protocol_error",16183              "x-stainless-const": true16184             },16185             "code": {16186              "type": "integer"16187             },16188             "message": {16189              "type": "string"16190             }16191            },16192            "type": "object",16193            "required": [16194             "type",16195             "code",16196             "message"16197            ]16198           },16199           {16200            "properties": {16201             "type": {16202              "type": "string",16203              "enum": [16204               "mcp_tool_execution_error"16205              ],16206              "default": "mcp_tool_execution_error",16207              "x-stainless-const": true16208             },16209             "content": {}16210            },16211            "type": "object",16212            "required": [16213             "type",16214             "content"16215            ]16216           },16217           {16218            "properties": {16219             "type": {16220              "type": "string",16221              "enum": [16222               "http_error"16223              ],16224              "default": "http_error",16225              "x-stainless-const": true16226             },16227             "code": {16228              "type": "integer"16229             },16230             "message": {16231              "type": "string"16232             }16233            },16234            "type": "object",16235            "required": [16236             "type",16237             "code",16238             "message"16239            ]16240           }16241          ],16242          "discriminator": {16243           "propertyName": "type"16244          }16245         },16246         {16247          "type": "null"16248         }16249        ]16250       },16251       "status": {16252        "type": "string",16253        "enum": [16254         "in_progress",16255         "completed",16256         "incomplete",16257         "calling",16258         "failed"16259        ]16260       },16261       "approval_request_id": {16262        "anyOf": [16263         {16264          "type": "string",16265          "description": "Unique identifier for the MCP tool call approval request.\nInclude this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call.\n"16266         },16267         {16268          "type": "null"16269         }16270        ]16271       }16272      },16273      "required": [16274       "type",16275       "id",16276       "server_label",16277       "name",16278       "arguments"16279      ]16280     }16281    },16282    {16283     "schema_name": "MCPApprovalRequest",16284     "type": "mcp_approval_request",16285     "schema": {16286      "type": "object",16287      "title": "MCP approval request",16288      "description": "A request for human approval of a tool invocation.\n",16289      "properties": {16290       "type": {16291        "type": "string",16292        "enum": [16293         "mcp_approval_request"16294        ],16295        "description": "The type of the item. Always `mcp_approval_request`.\n",16296        "x-stainless-const": true16297       },16298       "id": {16299        "type": "string",16300        "description": "The unique ID of the approval request.\n"16301       },16302       "server_label": {16303        "type": "string",16304        "description": "The label of the MCP server making the request.\n"16305       },16306       "name": {16307        "type": "string",16308        "description": "The name of the tool to run.\n"16309       },16310       "arguments": {16311        "type": "string",16312        "description": "A JSON string of arguments for the tool.\n"16313       }16314      },16315      "required": [16316       "type",16317       "id",16318       "server_label",16319       "name",16320       "arguments"16321      ]16322     }16323    },16324    {16325     "schema_name": "MCPApprovalResponse",16326     "type": "mcp_approval_response",16327     "schema": {16328      "type": "object",16329      "title": "MCP approval response",16330      "description": "A response to an MCP approval request.\n",16331      "properties": {16332       "type": {16333        "type": "string",16334        "enum": [16335         "mcp_approval_response"16336        ],16337        "description": "The type of the item. Always `mcp_approval_response`.\n",16338        "x-stainless-const": true16339       },16340       "id": {16341        "anyOf": [16342         {16343          "type": "string",16344          "description": "The unique ID of the approval response\n"16345         },16346         {16347          "type": "null"16348         }16349        ]16350       },16351       "approval_request_id": {16352        "type": "string",16353        "description": "The ID of the approval request being answered.\n"16354       },16355       "approve": {16356        "type": "boolean",16357        "description": "Whether the request was approved.\n"16358       },16359       "reason": {16360        "anyOf": [16361         {16362          "type": "string",16363          "description": "Optional reason for the decision.\n"16364         },16365         {16366          "type": "null"16367         }16368        ]16369       }16370      },16371      "required": [16372       "type",16373       "request_id",16374       "approve",16375       "approval_request_id"16376      ]16377     }16378    }16379   ],16380   "summary": "Items: `mcp_list_tools` {server_label, tools: [{name, description, input_schema, annotations}], error}, `mcp_call` {server_label, name, arguments, output, error: mcp_protocol_error|mcp_tool_execution_error|http_error, status, approval_request_id}, `mcp_approval_request` {id, server_label, name, arguments} answered by input `mcp_approval_response` {approval_request_id, approve, reason}."16381  },16382  "billing": {16383   "per_call": "No OpenAI per-call fee; imported tool definitions and tool outputs are billed as model tokens",16384   "source": "https://developers.openai.com/api/docs/pricing#built-in-tools"16385  },16386  "limitations": [16387   "`mcp_list_tools` is fetched once per response chain; keep the item in context.",16388   "Deep research requires search+fetch MCP servers with require_approval never.",16389   "Connector ids: connector_dropbox, connector_gmail, connector_googlecalendar, connector_googledrive, connector_microsoftteams, connector_outlookcalendar, connector_outlookemail, connector_sharepoint."16390  ],16391  "security": [16392   "Only connect trusted servers; tool outputs are untrusted input (prompt injection, exfiltration through arguments).",16393   "Approvals default to always; `authorization` value is redacted from the stored Response.",16394   "Org/project admins can disable MCP."16395  ],16396  "beta_header": null,16397  "status": [16398   "DOCUMENTED",16399   "LIVE_VERIFIED"16400  ],16401  "examples": {16402   "curl": "examples/openai/tools/mcp-and-connectors/mcp_and_connectors.sh",16403   "python": "examples/openai/tools/mcp-and-connectors/mcp_and_connectors.py",16404   "typescript": "examples/openai/tools/mcp-and-connectors/mcp_and_connectors.ts"16405  },16406  "verification": {16407   "deepwiki_call": {16408    "method": "live_api",16409    "verified_at": "2026-09-18",16410    "result": "success",16411    "http_status": 200,16412    "request_note": "gpt-5.4-nano: server_url https://mcp.deepwiki.com/mcp, require_approval never, allowed_tools [read_wiki_structure] -> mcp_list_tools (1 tool, annotations.read_only=false), mcp_call completed with output, message"16413   },16414   "approval_flow": {16415    "method": "live_api",16416    "verified_at": "2026-09-18",16417    "result": "success",16418    "http_status": 200,16419    "request_note": "require_approval always + tool_choice {type:mcp,...} -> mcp_approval_request; replied mcp_approval_response approve=false reason -> model message acknowledging rejection"16420   },16421   "streaming": {16422    "method": "live_api",16423    "verified_at": "2026-09-18",16424    "result": "success",16425    "http_status": 200,16426    "request_note": "response.mcp_list_tools.in_progress/completed, response.mcp_call.in_progress, response.mcp_call_arguments.delta/done, response.mcp_call.completed"16427   }16428  },16429  "sources": [16430   {16431    "url": "https://developers.openai.com/api/docs/guides/tools-connectors-mcp",16432    "retrieved_at": "2026-09-18"16433   },16434   {16435    "url": "https://developers.openai.com/api/docs/guides/secure-mcp-tunnels",16436    "retrieved_at": "2026-09-18"16437   },16438   {16439    "url": "https://developers.openai.com/api/docs/guides/realtime-mcp",16440    "retrieved_at": "2026-09-18"16441   },16442   {16443    "url": "https://developers.openai.com/api/reference/resources/responses/methods/create",16444    "retrieved_at": "2026-09-18"16445   },16446   {16447    "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)",16448    "retrieved_at": "2026-09-18"16449   }16450  ],16451  "last_verified": "2026-09-18",16452  "_fragment": "generated/fragments/tools/openai-tools.json"16453 },16454 {16455  "provider": "openai",16456  "name": "Shell tool (hosted container or local runtime)",16457  "type": "shell",16458  "category": "hosted",16459  "description": "Model emits `shell_call` {action: {commands[], timeout_ms, max_output_length}}. `environment`: `{type: container_auto, file_ids?, memory_limit?, network_policy?, skills?}` (hosted: OpenAI runs the commands and returns `shell_call_output` automatically), `{type: container_reference, container_id}` (reuse a container from /v1/containers) or `{type: local}` (your runtime executes and returns `shell_call_output` {call_id, output: [{stdout, stderr, outcome: {type: exit, exit_code} | {type: timeout}}]}). Default cwd `/mnt/data`; skills mount under `/home/oai/skills/<name>-<version>`.",16460  "compatible_models": [16461   "gpt-5.2",16462   "gpt-5.2-codex",16463   "gpt-5.3-codex",16464   "gpt-5.4",16465   "gpt-5.4-mini",16466   "gpt-5.4-nano",16467   "gpt-5.5",16468   "gpt-5.5-pro",16469   "gpt-5.6-cyber",16470   "gpt-5.6-luna",16471   "gpt-5.6-sol",16472   "gpt-5.6-terra",16473   "gpt-6-astra",16474   "gpt-daybreak-blue-latest",16475   "gpt-daybreak-red-latest"16476  ],16477  "compatible_endpoints": [16478   "POST /v1/responses"16479  ],16480  "parameters_schema": {16481   "properties": {16482    "type": {16483     "type": "string",16484     "enum": [16485      "shell"16486     ],16487     "description": "The type of the shell tool. Always `shell`.",16488     "default": "shell",16489     "x-stainless-const": true16490    },16491    "environment": {16492     "anyOf": [16493      {16494       "oneOf": [16495        {16496         "properties": {16497          "type": {16498           "type": "string",16499           "enum": [16500            "container_auto"16501           ],16502           "description": "Automatically creates a container for this request",16503           "default": "container_auto",16504           "x-stainless-const": true16505          },16506          "file_ids": {16507           "items": {16508            "type": "string",16509            "example": "file-123"16510           },16511           "type": "array",16512           "maxItems": 50,16513           "description": "An optional list of uploaded files to make available to your code."16514          },16515          "memory_limit": {16516           "anyOf": [16517            {16518             "type": "string",16519             "enum": [16520              "1g",16521              "4g",16522              "16g",16523              "64g"16524             ]16525            },16526            {16527             "type": "null"16528            }16529           ]16530          },16531          "network_policy": {16532           "oneOf": [16533            {16534             "properties": {16535              "type": {16536               "type": {16537                "$comment": "depth-limited"16538               },16539               "enum": {16540                "$comment": "depth-limited"16541               },16542               "description": {16543                "$comment": "depth-limited"16544               },16545               "default": {16546                "$comment": "depth-limited"16547               },16548               "x-stainless-const": {16549                "$comment": "depth-limited"16550               }16551              }16552             },16553             "type": "object",16554             "required": [16555              "type"16556             ]16557            },16558            {16559             "properties": {16560              "type": {16561               "type": {16562                "$comment": "depth-limited"16563               },16564               "enum": {16565                "$comment": "depth-limited"16566               },16567               "description": {16568                "$comment": "depth-limited"16569               },16570               "default": {16571                "$comment": "depth-limited"16572               },16573               "x-stainless-const": {16574                "$comment": "depth-limited"16575               }16576              },16577              "allowed_domains": {16578               "items": {16579                "$comment": "depth-limited"16580               },16581               "type": {16582                "$comment": "depth-limited"16583               },16584               "minItems": {16585                "$comment": "depth-limited"16586               },16587               "description": {16588                "$comment": "depth-limited"16589               }16590              },16591              "domain_secrets": {16592               "items": {16593                "$comment": "depth-limited"16594               },16595               "type": {16596                "$comment": "depth-limited"16597               },16598               "minItems": {16599                "$comment": "depth-limited"16600               },16601               "description": {16602                "$comment": "depth-limited"16603               }16604              }16605             },16606             "type": "object",16607             "required": [16608              "type",16609              "allowed_domains"16610             ]16611            }16612           ],16613           "description": "Network access policy for the container.",16614           "discriminator": {16615            "propertyName": "type"16616           }16617          },16618          "skills": {16619           "items": {16620            "oneOf": [16621             {16622              "properties": {16623               "type": {16624                "$comment": "depth-limited"16625               },16626               "skill_id": {16627                "$comment": "depth-limited"16628               },16629               "version": {16630                "$comment": "depth-limited"16631               }16632              },16633              "type": "object",16634              "required": [16635               {16636                "$comment": "depth-limited"16637               },16638               {16639                "$comment": "depth-limited"16640               }16641              ]16642             },16643             {16644              "properties": {16645               "type": {16646                "$comment": "depth-limited"16647               },16648               "name": {16649                "$comment": "depth-limited"16650               },16651               "description": {16652                "$comment": "depth-limited"16653               },16654               "source": {16655                "$comment": "depth-limited"16656               }16657              },16658              "type": "object",16659              "required": [16660               {16661                "$comment": "depth-limited"16662               },16663               {16664                "$comment": "depth-limited"16665               },16666               {16667                "$comment": "depth-limited"16668               },16669               {16670                "$comment": "depth-limited"16671               }16672              ]16673             }16674            ],16675            "discriminator": {16676             "propertyName": "type"16677            }16678           },16679           "type": "array",16680           "maxItems": 200,16681           "description": "An optional list of skills referenced by id or inline data."16682          }16683         },16684         "type": "object",16685         "required": [16686          "type"16687         ]16688        },16689        {16690         "properties": {16691          "type": {16692           "type": "string",16693           "enum": [16694            "local"16695           ],16696           "description": "Use a local computer environment.",16697           "default": "local",16698           "x-stainless-const": true16699          },16700          "skills": {16701           "items": {16702            "properties": {16703             "name": {16704              "type": "string",16705              "description": "The name of the skill."16706             },16707             "description": {16708              "type": "string",16709              "description": "The description of the skill."16710             },16711             "path": {16712              "type": "string",16713              "description": "The path to the directory containing the skill."16714             }16715            },16716            "type": "object",16717            "required": [16718             "name",16719             "description",16720             "path"16721            ]16722           },16723           "type": "array",16724           "maxItems": 200,16725           "description": "An optional list of skills."16726          }16727         },16728         "type": "object",16729         "required": [16730          "type"16731         ]16732        },16733        {16734         "properties": {16735          "type": {16736           "type": "string",16737           "enum": [16738            "container_reference"16739           ],16740           "description": "References a container created with the /v1/containers endpoint",16741           "default": "container_reference",16742           "x-stainless-const": true16743          },16744          "container_id": {16745           "type": "string",16746           "description": "The ID of the referenced container.",16747           "example": "cntr_123"16748          }16749         },16750         "type": "object",16751         "required": [16752          "type",16753          "container_id"16754         ]16755        }16756       ],16757       "discriminator": {16758        "propertyName": "type"16759       }16760      },16761      {16762       "type": "null"16763      }16764     ]16765    },16766    "allowed_callers": {16767     "anyOf": [16768      {16769       "items": {16770        "type": "string",16771        "enum": [16772         "direct",16773         "programmatic"16774        ]16775       },16776       "type": "array",16777       "minItems": 1,16778       "description": "The tool invocation context(s)."16779      },16780      {16781       "type": "null"16782      }16783     ]16784    }16785   },16786   "type": "object",16787   "required": [16788    "type"16789   ],16790   "title": "Shell tool",16791   "description": "A tool that allows the model to execute shell commands."16792  },16793  "tool_choice_support": {16794   "modes": [16795    "none",16796    "auto",16797    "required"16798   ],16799   "allowed_tools": {16800    "type": "allowed_tools",16801    "mode": "auto|required",16802    "tools": [16803     "{type,name,...}"16804    ]16805   },16806   "specific": {16807    "type": "shell"16808   }16809  },16810  "parallel": {16811   "supported": false16812  },16813  "streaming_events": [16814   "response.output_item.added",16815   "response.shell_call_command.added",16816   "response.shell_call_command.delta",16817   "response.shell_call_command.done",16818   "response.shell_call_output_content.delta",16819   "response.shell_call_output_content.done",16820   "response.output_item.done"16821  ],16822  "result_shape": {16823   "items": [16824    {16825     "schema_name": "FunctionShellCall",16826     "type": "shell_call",16827     "schema": {16828      "properties": {16829       "type": {16830        "type": "string",16831        "enum": [16832         "shell_call"16833        ],16834        "description": "The type of the item. Always `shell_call`.",16835        "default": "shell_call",16836        "x-stainless-const": true16837       },16838       "id": {16839        "type": "string",16840        "description": "The unique ID of the shell tool call. Populated when this item is returned via API."16841       },16842       "call_id": {16843        "type": "string",16844        "description": "The unique ID of the shell tool call generated by the model."16845       },16846       "caller": {16847        "anyOf": [16848         {16849          "oneOf": [16850           {16851            "properties": {16852             "type": {16853              "type": "string",16854              "enum": [16855               "direct"16856              ],16857              "default": "direct",16858              "x-stainless-const": true16859             }16860            },16861            "type": "object",16862            "required": [16863             "type"16864            ]16865           },16866           {16867            "properties": {16868             "type": {16869              "type": "string",16870              "enum": [16871               "program"16872              ],16873              "default": "program",16874              "x-stainless-const": true16875             },16876             "caller_id": {16877              "type": "string",16878              "description": "The call ID of the program item that produced this tool call."16879             }16880            },16881            "type": "object",16882            "required": [16883             "type",16884             "caller_id"16885            ]16886           }16887          ],16888          "description": "The execution context that produced this tool call.",16889          "discriminator": {16890           "propertyName": "type"16891          }16892         },16893         {16894          "type": "null"16895         }16896        ]16897       },16898       "action": {16899        "properties": {16900         "commands": {16901          "items": {16902           "type": "string",16903           "description": "A list of commands to run."16904          },16905          "type": "array"16906         },16907         "timeout_ms": {16908          "anyOf": [16909           {16910            "type": "integer",16911            "description": "Optional timeout in milliseconds for the commands."16912           },16913           {16914            "type": "null"16915           }16916          ]16917         },16918         "max_output_length": {16919          "anyOf": [16920           {16921            "type": "integer",16922            "description": "Optional maximum number of characters to return from each command."16923           },16924           {16925            "type": "null"16926           }16927          ]16928         }16929        },16930        "type": "object",16931        "required": [16932         "commands",16933         "timeout_ms",16934         "max_output_length"16935        ],16936        "title": "Shell exec action",16937        "description": "Execute a shell command."16938       },16939       "status": {16940        "type": "string",16941        "enum": [16942         "in_progress",16943         "completed",16944         "incomplete"16945        ]16946       },16947       "environment": {16948        "anyOf": [16949         {16950          "oneOf": [16951           {16952            "properties": {16953             "type": {16954              "type": "string",16955              "enum": [16956               "local"16957              ],16958              "description": "The environment type. Always `local`.",16959              "default": "local",16960              "x-stainless-const": true16961             }16962            },16963            "type": "object",16964            "required": [16965             "type"16966            ],16967            "title": "Local Environment",16968            "description": "Represents the use of a local environment to perform shell actions."16969           },16970           {16971            "properties": {16972             "type": {16973              "type": "string",16974              "enum": [16975               "container_reference"16976              ],16977              "description": "The environment type. Always `container_reference`.",16978              "default": "container_reference",16979              "x-stainless-const": true16980             },16981             "container_id": {16982              "type": "string"16983             }16984            },16985            "type": "object",16986            "required": [16987             "type",16988             "container_id"16989            ],16990            "title": "Container Reference",16991            "description": "Represents a container created with /v1/containers."16992           }16993          ],16994          "discriminator": {16995           "propertyName": "type"16996          }16997         },16998         {16999          "type": "null"17000         }17001        ]17002       },17003       "created_by": {17004        "type": "string",17005        "description": "The ID of the entity that created this tool call."17006       }17007      },17008      "type": "object",17009      "required": [17010       "type",17011       "id",17012       "call_id",17013       "action",17014       "status",17015       "environment"17016      ],17017      "title": "Shell tool call",17018      "description": "A tool call that executes one or more shell commands in a managed environment."17019     }17020    },17021    {17022     "schema_name": "FunctionShellCallOutputItemParam",17023     "type": "shell_call_output",17024     "schema": {17025      "properties": {17026       "id": {17027        "anyOf": [17028         {17029          "type": "string",17030          "description": "The unique ID of the shell tool call output. Populated when this item is returned via API.",17031          "example": "sho_123"17032         },17033         {17034          "type": "null"17035         }17036        ]17037       },17038       "call_id": {17039        "type": "string",17040        "maxLength": 64,17041        "minLength": 1,17042        "description": "The unique ID of the shell tool call generated by the model."17043       },17044       "caller": {17045        "anyOf": [17046         {17047          "oneOf": [17048           {17049            "properties": {17050             "type": {17051              "type": "string",17052              "enum": [17053               "direct"17054              ],17055              "description": "The caller type. Always `direct`.",17056              "default": "direct",17057              "x-stainless-const": true17058             }17059            },17060            "type": "object",17061            "required": [17062             "type"17063            ]17064           },17065           {17066            "properties": {17067             "type": {17068              "type": "string",17069              "enum": [17070               "program"17071              ],17072              "description": "The caller type. Always `program`.",17073              "default": "program",17074              "x-stainless-const": true17075             },17076             "caller_id": {17077              "type": "string",17078              "maxLength": 64,17079              "minLength": 1,17080              "description": "The call ID of the program item that produced this tool call."17081             }17082            },17083            "type": "object",17084            "required": [17085             "type",17086             "caller_id"17087            ]17088           }17089          ],17090          "description": "The execution context that produced this tool call.",17091          "discriminator": {17092           "propertyName": "type"17093          }17094         },17095         {17096          "type": "null"17097         }17098        ]17099       },17100       "type": {17101        "type": "string",17102        "enum": [17103         "shell_call_output"17104        ],17105        "description": "The type of the item. Always `shell_call_output`.",17106        "default": "shell_call_output",17107        "x-stainless-const": true17108       },17109       "output": {17110        "items": {17111         "properties": {17112          "stdout": {17113           "type": "string",17114           "maxLength": 10485760,17115           "description": "Captured stdout output for the shell call."17116          },17117          "stderr": {17118           "type": "string",17119           "maxLength": 10485760,17120           "description": "Captured stderr output for the shell call."17121          },17122          "outcome": {17123           "oneOf": [17124            {17125             "properties": {17126              "type": {17127               "type": "string",17128               "enum": [17129                "timeout"17130               ],17131               "description": "The outcome type. Always `timeout`.",17132               "default": "timeout",17133               "x-stainless-const": true17134              }17135             },17136             "type": "object",17137             "required": [17138              "type"17139             ],17140             "title": "Shell call timeout outcome",17141             "description": "Indicates that the shell call exceeded its configured time limit."17142            },17143            {17144             "properties": {17145              "type": {17146               "type": "string",17147               "enum": [17148                "exit"17149               ],17150               "description": "The outcome type. Always `exit`.",17151               "default": "exit",17152               "x-stainless-const": true17153              },17154              "exit_code": {17155               "type": "integer",17156               "description": "The exit code returned by the shell process."17157              }17158             },17159             "type": "object",17160             "required": [17161              "type",17162              "exit_code"17163             ],17164             "title": "Shell call exit outcome",17165             "description": "Indicates that the shell commands finished and returned an exit code."17166            }17167           ],17168           "title": "Shell call outcome",17169           "description": "The exit or timeout outcome associated with this shell call.",17170           "discriminator": {17171            "propertyName": "type"17172           }17173          }17174         },17175         "type": "object",17176         "required": [17177          "stdout",17178          "stderr",17179          "outcome"17180         ],17181         "title": "Shell output content",17182         "description": "Captured stdout and stderr for a portion of a shell tool call output."17183        },17184        "type": "array",17185        "description": "Captured chunks of stdout and stderr output, along with their associated outcomes."17186       },17187       "status": {17188        "anyOf": [17189         {17190          "type": "string",17191          "enum": [17192           "in_progress",17193           "completed",17194           "incomplete"17195          ],17196          "title": "Shell call status",17197          "description": "Status values reported for shell tool calls."17198         },17199         {17200          "type": "null"17201         }17202        ]17203       },17204       "max_output_length": {17205        "anyOf": [17206         {17207          "type": "integer",17208          "description": "The maximum number of UTF-8 characters captured for this shell call's combined output."17209         },17210         {17211          "type": "null"17212         }17213        ]17214       }17215      },17216      "type": "object",17217      "required": [17218       "call_id",17219       "type",17220       "output"17221      ],17222      "title": "Shell tool call output",17223      "description": "The streamed output items emitted by a shell tool call."17224     }17225    }17226   ],17227   "summary": "`shell_call` {id, call_id, action.commands, environment: null | {type: local} | {type: container_reference, container_id}, status}; `shell_call_output` items (hosted: server-emitted)."17228  },17229  "billing": {17230   "per_session": "Hosted containers: same rates as code interpreter (1 GB $0.03 … 64 GB $1.92 per 20-min session)",17231   "local": "Token billing only",17232   "source": "https://developers.openai.com/api/docs/pricing#built-in-tools"17233  },17234  "limitations": [17235   "Not available in Chat Completions.",17236   "Hosted shell: no interactive TTY; no outbound network by default; org domain allow-list.",17237   "Model page key: hosted_shell (gpt-5.2, gpt-5.2/5.3-codex, gpt-5.4*, gpt-5.5, gpt-5.6*, gpt-6-astra)."17238  ],17239  "security": [17240   "Local mode: you execute arbitrary commands — sandbox, enforce timeouts, filter dangerous commands; timeout_ms is only a hint.",17241   "Hosted allowlists + domain_secrets reduce credential leakage; prompt injection via fetched content remains."17242  ],17243  "beta_header": null,17244  "status": [17245   "DOCUMENTED",17246   "LIVE_VERIFIED"17247  ],17248  "examples": {17249   "curl": "examples/openai/tools/shell/shell.sh",17250   "python": "examples/openai/tools/shell/shell.py",17251   "typescript": "examples/openai/tools/shell/shell.ts"17252  },17253  "verification": {17254   "local_env": {17255    "method": "live_api",17256    "verified_at": "2026-09-18",17257    "result": "success",17258    "http_status": 200,17259    "request_note": "gpt-5.4-nano: environment local, tool_choice {type:shell} -> shell_call action.commands ['echo OK'], environment null (nothing executed by us)"17260   },17261   "hosted_with_skill": {17262    "method": "live_api",17263    "verified_at": "2026-09-18",17264    "result": "success",17265    "http_status": 200,17266    "request_note": "gpt-5.4-nano: environment container_auto + skills [skill_reference] -> two shell_call/shell_call_output pairs (cat SKILL.md, echo OK) with environment container_reference; final message 'OK'"17267   },17268   "streaming": {17269    "method": "live_api",17270    "verified_at": "2026-09-18",17271    "result": "success",17272    "http_status": 200,17273    "request_note": "response.shell_call_command.added -> .delta -> .done (local env); shell_call_output_content.* not observed locally"17274   }17275  },17276  "sources": [17277   {17278    "url": "https://developers.openai.com/api/docs/guides/tools-shell",17279    "retrieved_at": "2026-09-18"17280   },17281   {17282    "url": "https://developers.openai.com/api/docs/pricing#built-in-tools",17283    "retrieved_at": "2026-09-18"17284   },17285   {17286    "url": "https://developers.openai.com/api/reference/resources/responses/methods/create",17287    "retrieved_at": "2026-09-18"17288   },17289   {17290    "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)",17291    "retrieved_at": "2026-09-18"17292   }17293  ],17294  "last_verified": "2026-09-18",17295  "_fragment": "generated/fragments/tools/openai-tools.json"17296 },17297 {17298  "provider": "openai",17299  "name": "Local shell (legacy, codex-mini-latest)",17300  "type": "local_shell",17301  "category": "client",17302  "description": "Legacy tool for Codex CLI / codex-mini-latest: `local_shell_call` {action: {type: exec, command[], timeout_ms, working_directory, env, user}} answered by `local_shell_call_output` {id, output}. Superseded by `shell` with environment local.",17303  "compatible_models": [17304   "codex-mini-latest"17305  ],17306  "compatible_endpoints": [17307   "POST /v1/responses"17308  ],17309  "parameters_schema": {17310   "properties": {17311    "type": {17312     "type": "string",17313     "enum": [17314      "local_shell"17315     ],17316     "description": "The type of the local shell tool. Always `local_shell`.",17317     "default": "local_shell",17318     "x-stainless-const": true17319    }17320   },17321   "type": "object",17322   "required": [17323    "type"17324   ],17325   "title": "Local shell tool",17326   "description": "A tool that allows the model to execute shell commands in a local environment."17327  },17328  "tool_choice_support": {17329   "modes": [17330    "none",17331    "auto",17332    "required"17333   ],17334   "allowed_tools": {17335    "type": "allowed_tools",17336    "mode": "auto|required",17337    "tools": [17338     "{type,name,...}"17339    ]17340   }17341  },17342  "parallel": {17343   "supported": false17344  },17345  "streaming_events": [],17346  "result_shape": {17347   "items": [17348    {17349     "schema_name": "LocalShellToolCall",17350     "type": "local_shell_call",17351     "schema": {17352      "type": "object",17353      "title": "Local shell call",17354      "description": "A tool call to run a command on the local shell.\n",17355      "properties": {17356       "type": {17357        "type": "string",17358        "enum": [17359         "local_shell_call"17360        ],17361        "description": "The type of the local shell call. Always `local_shell_call`.\n",17362        "x-stainless-const": true17363       },17364       "id": {17365        "type": "string",17366        "description": "The unique ID of the local shell call.\n"17367       },17368       "call_id": {17369        "type": "string",17370        "description": "The unique ID of the local shell tool call generated by the model.\n"17371       },17372       "action": {17373        "properties": {17374         "type": {17375          "type": "string",17376          "enum": [17377           "exec"17378          ],17379          "description": "The type of the local shell action. Always `exec`.",17380          "default": "exec",17381          "x-stainless-const": true17382         },17383         "command": {17384          "items": {17385           "type": "string"17386          },17387          "type": "array",17388          "description": "The command to run."17389         },17390         "timeout_ms": {17391          "anyOf": [17392           {17393            "type": "integer",17394            "description": "Optional timeout in milliseconds for the command."17395           },17396           {17397            "type": "null"17398           }17399          ]17400         },17401         "working_directory": {17402          "anyOf": [17403           {17404            "type": "string",17405            "description": "Optional working directory to run the command in."17406           },17407           {17408            "type": "null"17409           }17410          ]17411         },17412         "env": {17413          "additionalProperties": {17414           "type": "string"17415          },17416          "type": "object",17417          "description": "Environment variables to set for the command."17418         },17419         "user": {17420          "anyOf": [17421           {17422            "type": "string",17423            "description": "Optional user to run the command as."17424           },17425           {17426            "type": "null"17427           }17428          ]17429         }17430        },17431        "type": "object",17432        "required": [17433         "type",17434         "command",17435         "env"17436        ],17437        "title": "Local shell exec action",17438        "description": "Execute a shell command on the server."17439       },17440       "status": {17441        "type": "string",17442        "enum": [17443         "in_progress",17444         "completed",17445         "incomplete"17446        ],17447        "description": "The status of the local shell call.\n"17448       }17449      },17450      "required": [17451       "type",17452       "id",17453       "call_id",17454       "action",17455       "status"17456      ]17457     }17458    },17459    {17460     "schema_name": "LocalShellToolCallOutput",17461     "type": "local_shell_call_output",17462     "schema": {17463      "type": "object",17464      "title": "Local shell call output",17465      "description": "The output of a local shell tool call.\n",17466      "properties": {17467       "type": {17468        "type": "string",17469        "enum": [17470         "local_shell_call_output"17471        ],17472        "description": "The type of the local shell tool call output. Always `local_shell_call_output`.\n",17473        "x-stainless-const": true17474       },17475       "id": {17476        "type": "string",17477        "description": "The unique ID of the local shell tool call generated by the model.\n"17478       },17479       "output": {17480        "type": "string",17481        "description": "A JSON string of the output of the local shell tool call.\n"17482       },17483       "status": {17484        "anyOf": [17485         {17486          "type": "string",17487          "enum": [17488           "in_progress",17489           "completed",17490           "incomplete"17491          ],17492          "description": "The status of the item. One of `in_progress`, `completed`, or `incomplete`.\n"17493         },17494         {17495          "type": "null"17496         }17497        ]17498       }17499      },17500      "required": [17501       "id",17502       "type",17503       "call_id",17504       "output"17505      ]17506     }17507    }17508   ],17509   "summary": "`local_shell_call` / `local_shell_call_output`."17510  },17511  "billing": {17512   "model": "Token billing only",17513   "source": "https://developers.openai.com/api/docs/pricing#built-in-tools"17514  },17515  "limitations": [17516   "Live: gpt-5.4-nano -> 400 'The local_shell tool is no longer supported.' Only codex-mini-latest documented."17517  ],17518  "security": [17519   "Same as shell local mode."17520  ],17521  "beta_header": null,17522  "status": [17523   "DOCUMENTED",17524   "LEGACY",17525   "FAILED_VERIFICATION"17526  ],17527  "examples": {17528   "curl": "examples/openai/tools/shell/shell.sh",17529   "python": "examples/openai/tools/shell/shell.py",17530   "typescript": "examples/openai/tools/shell/shell.ts"17531  },17532  "verification": {17533   "nano": {17534    "method": "live_api",17535    "verified_at": "2026-09-18",17536    "result": "failure",17537    "http_status": 400,17538    "request_note": "gpt-5.4-nano: tools [{type:local_shell}] -> 400 invalid_request_error param=tools 'The local_shell tool is no longer supported.'"17539   }17540  },17541  "sources": [17542   {17543    "url": "https://developers.openai.com/api/docs/guides/tools-local-shell",17544    "retrieved_at": "2026-09-18"17545   },17546   {17547    "url": "https://developers.openai.com/api/reference/resources/responses/methods/create",17548    "retrieved_at": "2026-09-18"17549   },17550   {17551    "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)",17552    "retrieved_at": "2026-09-18"17553   }17554  ],17555  "last_verified": "2026-09-18",17556  "_fragment": "generated/fragments/tools/openai-tools.json"17557 },17558 {17559  "provider": "openai",17560  "name": "Apply patch (structured file diffs)",17561  "type": "apply_patch",17562  "category": "client",17563  "description": "Model emits `apply_patch_call` {operation: {type: create_file|update_file|delete_file, path, diff}}; the app applies it and returns `apply_patch_call_output` {call_id, status: completed|failed, output}. No input schema to declare. Often paired with `shell` for file discovery.",17564  "compatible_models": [17565   "gpt-5.1",17566   "gpt-5.2",17567   "gpt-5.4",17568   "gpt-5.4-mini",17569   "gpt-5.4-nano",17570   "gpt-5.4-pro",17571   "gpt-5.5",17572   "gpt-5.6-cyber",17573   "gpt-5.6-luna",17574   "gpt-5.6-sol",17575   "gpt-5.6-terra",17576   "gpt-6-astra",17577   "gpt-daybreak-blue-latest",17578   "gpt-daybreak-red-latest"17579  ],17580  "compatible_endpoints": [17581   "POST /v1/responses"17582  ],17583  "parameters_schema": {17584   "properties": {17585    "type": {17586     "type": "string",17587     "enum": [17588      "apply_patch"17589     ],17590     "description": "The type of the tool. Always `apply_patch`.",17591     "default": "apply_patch",17592     "x-stainless-const": true17593    },17594    "allowed_callers": {17595     "anyOf": [17596      {17597       "items": {17598        "type": "string",17599        "enum": [17600         "direct",17601         "programmatic"17602        ]17603       },17604       "type": "array",17605       "minItems": 1,17606       "description": "The tool invocation context(s)."17607      },17608      {17609       "type": "null"17610      }17611     ]17612    }17613   },17614   "type": "object",17615   "required": [17616    "type"17617   ],17618   "title": "Apply patch tool",17619   "description": "Allows the assistant to create, delete, or update files using unified diffs."17620  },17621  "tool_choice_support": {17622   "modes": [17623    "none",17624    "auto",17625    "required"17626   ],17627   "allowed_tools": {17628    "type": "allowed_tools",17629    "mode": "auto|required",17630    "tools": [17631     "{type,name,...}"17632    ]17633   },17634   "specific": {17635    "type": "apply_patch"17636   }17637  },17638  "parallel": {17639   "supported": false17640  },17641  "streaming_events": [17642   "response.output_item.added",17643   "response.apply_patch_call_operation_diff.delta",17644   "response.apply_patch_call_operation_diff.done",17645   "response.output_item.done"17646  ],17647  "result_shape": {17648   "items": [17649    {17650     "schema_name": "ApplyPatchToolCall",17651     "type": "apply_patch_call",17652     "schema": {17653      "properties": {17654       "type": {17655        "type": "string",17656        "enum": [17657         "apply_patch_call"17658        ],17659        "description": "The type of the item. Always `apply_patch_call`.",17660        "default": "apply_patch_call",17661        "x-stainless-const": true17662       },17663       "id": {17664        "type": "string",17665        "description": "The unique ID of the apply patch tool call. Populated when this item is returned via API."17666       },17667       "call_id": {17668        "type": "string",17669        "description": "The unique ID of the apply patch tool call generated by the model."17670       },17671       "caller": {17672        "anyOf": [17673         {17674          "oneOf": [17675           {17676            "properties": {17677             "type": {17678              "type": "string",17679              "enum": [17680               "direct"17681              ],17682              "default": "direct",17683              "x-stainless-const": true17684             }17685            },17686            "type": "object",17687            "required": [17688             "type"17689            ]17690           },17691           {17692            "properties": {17693             "type": {17694              "type": "string",17695              "enum": [17696               "program"17697              ],17698              "default": "program",17699              "x-stainless-const": true17700             },17701             "caller_id": {17702              "type": "string",17703              "description": "The call ID of the program item that produced this tool call."17704             }17705            },17706            "type": "object",17707            "required": [17708             "type",17709             "caller_id"17710            ]17711           }17712          ],17713          "description": "The execution context that produced this tool call.",17714          "discriminator": {17715           "propertyName": "type"17716          }17717         },17718         {17719          "type": "null"17720         }17721        ]17722       },17723       "status": {17724        "type": "string",17725        "enum": [17726         "in_progress",17727         "completed"17728        ]17729       },17730       "operation": {17731        "oneOf": [17732         {17733          "properties": {17734           "type": {17735            "type": "string",17736            "enum": [17737             "create_file"17738            ],17739            "description": "Create a new file with the provided diff.",17740            "default": "create_file",17741            "x-stainless-const": true17742           },17743           "path": {17744            "type": "string",17745            "description": "Path of the file to create."17746           },17747           "diff": {17748            "type": "string",17749            "description": "Diff to apply."17750           }17751          },17752          "type": "object",17753          "required": [17754           "type",17755           "path",17756           "diff"17757          ],17758          "title": "Apply patch create file operation",17759          "description": "Instruction describing how to create a file via the apply_patch tool."17760         },17761         {17762          "properties": {17763           "type": {17764            "type": "string",17765            "enum": [17766             "delete_file"17767            ],17768            "description": "Delete the specified file.",17769            "default": "delete_file",17770            "x-stainless-const": true17771           },17772           "path": {17773            "type": "string",17774            "description": "Path of the file to delete."17775           }17776          },17777          "type": "object",17778          "required": [17779           "type",17780           "path"17781          ],17782          "title": "Apply patch delete file operation",17783          "description": "Instruction describing how to delete a file via the apply_patch tool."17784         },17785         {17786          "properties": {17787           "type": {17788            "type": "string",17789            "enum": [17790             "update_file"17791            ],17792            "description": "Update an existing file with the provided diff.",17793            "default": "update_file",17794            "x-stainless-const": true17795           },17796           "path": {17797            "type": "string",17798            "description": "Path of the file to update."17799           },17800           "diff": {17801            "type": "string",17802            "description": "Diff to apply."17803           }17804          },17805          "type": "object",17806          "required": [17807           "type",17808           "path",17809           "diff"17810          ],17811          "title": "Apply patch update file operation",17812          "description": "Instruction describing how to update a file via the apply_patch tool."17813         }17814        ],17815        "title": "Apply patch operation",17816        "description": "One of the create_file, delete_file, or update_file operations applied via apply_patch.",17817        "discriminator": {17818         "propertyName": "type"17819        }17820       },17821       "created_by": {17822        "type": "string",17823        "description": "The ID of the entity that created this tool call."17824       }17825      },17826      "type": "object",17827      "required": [17828       "type",17829       "id",17830       "call_id",17831       "status",17832       "operation"17833      ],17834      "title": "Apply patch tool call",17835      "description": "A tool call that applies file diffs by creating, deleting, or updating files."17836     }17837    },17838    {17839     "schema_name": "ApplyPatchToolCallOutputItemParam",17840     "type": "apply_patch_call_output",17841     "schema": {17842      "properties": {17843       "type": {17844        "type": "string",17845        "enum": [17846         "apply_patch_call_output"17847        ],17848        "description": "The type of the item. Always `apply_patch_call_output`.",17849        "default": "apply_patch_call_output",17850        "x-stainless-const": true17851       },17852       "id": {17853        "anyOf": [17854         {17855          "type": "string",17856          "description": "The unique ID of the apply patch tool call output. Populated when this item is returned via API.",17857          "example": "apco_123"17858         },17859         {17860          "type": "null"17861         }17862        ]17863       },17864       "call_id": {17865        "type": "string",17866        "maxLength": 64,17867        "minLength": 1,17868        "description": "The unique ID of the apply patch tool call generated by the model."17869       },17870       "caller": {17871        "anyOf": [17872         {17873          "oneOf": [17874           {17875            "properties": {17876             "type": {17877              "type": "string",17878              "enum": [17879               "direct"17880              ],17881              "description": "The caller type. Always `direct`.",17882              "default": "direct",17883              "x-stainless-const": true17884             }17885            },17886            "type": "object",17887            "required": [17888             "type"17889            ]17890           },17891           {17892            "properties": {17893             "type": {17894              "type": "string",17895              "enum": [17896               "program"17897              ],17898              "description": "The caller type. Always `program`.",17899              "default": "program",17900              "x-stainless-const": true17901             },17902             "caller_id": {17903              "type": "string",17904              "maxLength": 64,17905              "minLength": 1,17906              "description": "The call ID of the program item that produced this tool call."17907             }17908            },17909            "type": "object",17910            "required": [17911             "type",17912             "caller_id"17913            ]17914           }17915          ],17916          "description": "The execution context that produced this tool call.",17917          "discriminator": {17918           "propertyName": "type"17919          }17920         },17921         {17922          "type": "null"17923         }17924        ]17925       },17926       "status": {17927        "type": "string",17928        "enum": [17929         "completed",17930         "failed"17931        ],17932        "title": "Apply patch call output status",17933        "description": "Outcome values reported for apply_patch tool call outputs."17934       },17935       "output": {17936        "anyOf": [17937         {17938          "type": "string",17939          "maxLength": 10485760,17940          "description": "Optional human-readable log text from the apply patch tool (e.g., patch results or errors)."17941         },17942         {17943          "type": "null"17944         }17945        ]17946       }17947      },17948      "type": "object",17949      "required": [17950       "type",17951       "call_id",17952       "status"17953      ],17954      "title": "Apply patch tool call output",17955      "description": "The streamed output emitted by an apply patch tool call."17956     }17957    }17958   ],17959   "summary": "`apply_patch_call` {id, call_id, status, operation}; input `apply_patch_call_output`."17960  },17961  "billing": {17962   "model": "Token billing only",17963   "source": "https://developers.openai.com/api/docs/pricing#built-in-tools"17964  },17965  "limitations": [17966   "Guide table: Responses only; models GPT-5.1, 5.2, 5.4, 5.5 (model pages also list gpt-5.4-nano/mini, 5.6*, gpt-6-astra)."17967  ],17968  "security": [17969   "Validate paths (no traversal), restrict to allowed dirs, return status failed with a message on error."17970  ],17971  "beta_header": null,17972  "status": [17973   "DOCUMENTED",17974   "LIVE_VERIFIED"17975  ],17976  "examples": {17977   "curl": "examples/openai/tools/apply-patch/apply_patch.sh",17978   "python": "examples/openai/tools/apply-patch/apply_patch.py",17979   "typescript": "examples/openai/tools/apply-patch/apply_patch.ts"17980  },17981  "verification": {17982   "create_file": {17983    "method": "live_api",17984    "verified_at": "2026-09-18",17985    "result": "success",17986    "http_status": 200,17987    "request_note": "gpt-5.4-nano: tool_choice {type:apply_patch} -> apply_patch_call operation {type:create_file, path:'hello.txt', diff:'+OK\\n'} (not applied by us)"17988   },17989   "streaming": {17990    "method": "live_api",17991    "verified_at": "2026-09-18",17992    "result": "success",17993    "http_status": 200,17994    "request_note": "LIVE_DISCOVERED events response.apply_patch_call_operation_diff.delta / .done (absent from OpenAPI ResponseStreamEvent union)"17995   }17996  },17997  "sources": [17998   {17999    "url": "https://developers.openai.com/api/docs/guides/tools-apply-patch",18000    "retrieved_at": "2026-09-18"18001   },18002   {18003    "url": "https://developers.openai.com/api/reference/resources/responses/methods/create",18004    "retrieved_at": "2026-09-18"18005   },18006   {18007    "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)",18008    "retrieved_at": "2026-09-18"18009   }18010  ],18011  "last_verified": "2026-09-18",18012  "_fragment": "generated/fragments/tools/openai-tools.json"18013 },18014 {18015  "provider": "openai",18016  "name": "Skills (attachments for hosted shell / containers) — not a tool type",18017  "type": "skill_reference",18018  "category": "hosted",18019  "description": "Skills are versioned ZIP bundles (SKILL.md + files) uploaded through /v1/skills and mounted into hosted shell containers via `environment.skills[]` = `{type: skill_reference, skill_id, version?}` or `{type: inline, name, description, source: {type: base64, media_type: application/zip, data}}`, or at container creation (`skills[]`). Local shell uses `{name, description, path}` entries instead. The platform adds each skill's name/description/path to the user-prompt context.",18020  "compatible_models": [18021   "gpt-5.2",18022   "gpt-5.2-codex",18023   "gpt-5.3-codex",18024   "gpt-5.4",18025   "gpt-5.4-mini",18026   "gpt-5.4-nano",18027   "gpt-5.5",18028   "gpt-5.6-cyber",18029   "gpt-5.6-luna",18030   "gpt-5.6-sol",18031   "gpt-5.6-terra",18032   "gpt-6-astra",18033   "gpt-daybreak-blue-latest",18034   "gpt-daybreak-red-latest"18035  ],18036  "compatible_endpoints": [18037   "POST /v1/responses (tools[type=shell].environment.skills)",18038   "POST /v1/containers (skills)",18039   "Agents API sandboxes"18040  ],18041  "parameters_schema": {18042   "properties": {18043    "type": {18044     "type": "string",18045     "enum": [18046      "skill_reference"18047     ],18048     "description": "References a skill created with the /v1/skills endpoint.",18049     "default": "skill_reference",18050     "x-stainless-const": true18051    },18052    "skill_id": {18053     "type": "string",18054     "maxLength": 64,18055     "minLength": 1,18056     "description": "The ID of the referenced skill."18057    },18058    "version": {18059     "type": "string",18060     "description": "Optional skill version. Use a positive integer or 'latest'. Omit for default."18061    }18062   },18063   "type": "object",18064   "required": [18065    "type",18066    "skill_id"18067   ]18068  },18069  "tool_choice_support": {18070   "modes": [],18071   "note": "not a tool; no tool_choice"18072  },18073  "parallel": {18074   "supported": false18075  },18076  "streaming_events": [],18077  "result_shape": {18078   "items": [18079    {18080     "schema_name": "FunctionShellCall",18081     "type": "shell_call",18082     "schema": {18083      "properties": {18084       "type": {18085        "type": "string",18086        "enum": [18087         "shell_call"18088        ],18089        "description": "The type of the item. Always `shell_call`.",18090        "default": "shell_call",18091        "x-stainless-const": true18092       },18093       "id": {18094        "type": "string",18095        "description": "The unique ID of the shell tool call. Populated when this item is returned via API."18096       },18097       "call_id": {18098        "type": "string",18099        "description": "The unique ID of the shell tool call generated by the model."18100       },18101       "caller": {18102        "anyOf": [18103         {18104          "oneOf": [18105           {18106            "properties": {18107             "type": {18108              "type": "string",18109              "enum": [18110               "direct"18111              ],18112              "default": "direct",18113              "x-stainless-const": true18114             }18115            },18116            "type": "object",18117            "required": [18118             "type"18119            ]18120           },18121           {18122            "properties": {18123             "type": {18124              "type": "string",18125              "enum": [18126               "program"18127              ],18128              "default": "program",18129              "x-stainless-const": true18130             },18131             "caller_id": {18132              "type": "string",18133              "description": "The call ID of the program item that produced this tool call."18134             }18135            },18136            "type": "object",18137            "required": [18138             "type",18139             "caller_id"18140            ]18141           }18142          ],18143          "description": "The execution context that produced this tool call.",18144          "discriminator": {18145           "propertyName": "type"18146          }18147         },18148         {18149          "type": "null"18150         }18151        ]18152       },18153       "action": {18154        "properties": {18155         "commands": {18156          "items": {18157           "type": "string",18158           "description": "A list of commands to run."18159          },18160          "type": "array"18161         },18162         "timeout_ms": {18163          "anyOf": [18164           {18165            "type": "integer",18166            "description": "Optional timeout in milliseconds for the commands."18167           },18168           {18169            "type": "null"18170           }18171          ]18172         },18173         "max_output_length": {18174          "anyOf": [18175           {18176            "type": "integer",18177            "description": "Optional maximum number of characters to return from each command."18178           },18179           {18180            "type": "null"18181           }18182          ]18183         }18184        },18185        "type": "object",18186        "required": [18187         "commands",18188         "timeout_ms",18189         "max_output_length"18190        ],18191        "title": "Shell exec action",18192        "description": "Execute a shell command."18193       },18194       "status": {18195        "type": "string",18196        "enum": [18197         "in_progress",18198         "completed",18199         "incomplete"18200        ]18201       },18202       "environment": {18203        "anyOf": [18204         {18205          "oneOf": [18206           {18207            "properties": {18208             "type": {18209              "type": "string",18210              "enum": [18211               "local"18212              ],18213              "description": "The environment type. Always `local`.",18214              "default": "local",18215              "x-stainless-const": true18216             }18217            },18218            "type": "object",18219            "required": [18220             "type"18221            ],18222            "title": "Local Environment",18223            "description": "Represents the use of a local environment to perform shell actions."18224           },18225           {18226            "properties": {18227             "type": {18228              "type": "string",18229              "enum": [18230               "container_reference"18231              ],18232              "description": "The environment type. Always `container_reference`.",18233              "default": "container_reference",18234              "x-stainless-const": true18235             },18236             "container_id": {18237              "type": "string"18238             }18239            },18240            "type": "object",18241            "required": [18242             "type",18243             "container_id"18244            ],18245            "title": "Container Reference",18246            "description": "Represents a container created with /v1/containers."18247           }18248          ],18249          "discriminator": {18250           "propertyName": "type"18251          }18252         },18253         {18254          "type": "null"18255         }18256        ]18257       },18258       "created_by": {18259        "type": "string",18260        "description": "The ID of the entity that created this tool call."18261       }18262      },18263      "type": "object",18264      "required": [18265       "type",18266       "id",18267       "call_id",18268       "action",18269       "status",18270       "environment"18271      ],18272      "title": "Shell tool call",18273      "description": "A tool call that executes one or more shell commands in a managed environment."18274     }18275    }18276   ],18277   "summary": "No dedicated item; shell_call commands read /home/oai/skills/<name>-<version>/SKILL.md."18278  },18279  "billing": {18280   "model": "Container session + tokens",18281   "source": "https://developers.openai.com/api/docs/pricing#built-in-tools"18282  },18283  "limitations": [18284   "Exactly one SKILL.md per bundle; <= 500 files; <= 25 MB uncompressed; up to 200 skills per container_auto; default_version cannot be deleted.",18285   "Hosted shell only accepts skill_reference/inline; local shell only paths."18286  ],18287  "security": [18288   "Inspect every skill: SKILL.md instructions are user-level prompt input (prompt injection); do not let end-users attach arbitrary skills."18289  ],18290  "beta_header": null,18291  "status": [18292   "DOCUMENTED",18293   "LIVE_VERIFIED"18294  ],18295  "examples": {18296   "curl": "examples/openai/tools/skills/skills.sh",18297   "python": "examples/openai/tools/skills/skills.py",18298   "typescript": "examples/openai/tools/skills/skills.ts"18299  },18300  "verification": {18301   "mount_and_use": {18302    "method": "live_api",18303    "verified_at": "2026-09-18",18304    "result": "success",18305    "http_status": 200,18306    "request_note": "gpt-5.4-nano: shell container_auto with skills [skill_reference skill_…] -> model listed /home/oai/skills/atlas-hello-1, read SKILL.md, ran echo OK"18307   }18308  },18309  "sources": [18310   {18311    "url": "https://developers.openai.com/api/docs/guides/tools-skills",18312    "retrieved_at": "2026-09-18"18313   },18314   {18315    "url": "https://developers.openai.com/api/reference/resources/skills",18316    "retrieved_at": "2026-09-18"18317   },18318   {18319    "url": "https://developers.openai.com/api/reference/resources/responses/methods/create",18320    "retrieved_at": "2026-09-18"18321   },18322   {18323    "url": "https://github.com/openai/openai-openapi (openapi-master.yaml)",18324    "retrieved_at": "2026-09-18"18325   }18326  ],18327  "last_verified": "2026-09-18",18328  "_fragment": "generated/fragments/tools/openai-tools.json"18329 },18330 {18331  "provider": "xai",18332  "name": "Function calling",18333  "type": "function",18334  "category": "client",18335  "description": "Developer-defined function (JSON Schema parameters, object root or oneOf/anyOf of objects). Model emits tool calls; the app executes and returns results. Arguments always conform to the schema (strict implicit). Responses uses the flat shape {type, name, description, parameters}; Chat Completions the nested {type, function:{…}}. `strict` and `defer_loading` accepted (defer_loading → 403 alpha).",18336  "compatible_models": [18337   "grok-4.6",18338   "grok-4.5",18339   "grok-4.3",18340   "grok-4.20-0309-reasoning",18341   "grok-4.20-0309-non-reasoning",18342   "grok-4.20-multi-agent-0309",18343   "grok-build-0.1"18344  ],18345  "compatible_endpoints": [18346   "POST /v1/chat/completions",18347   "POST /v1/responses",18348   "POST /v1/messages (Anthropic shape: name/description/input_schema)",18349   "Batch API"18350  ],18351  "parameters_schema": {18352   "responses": {18353    "type": "function",18354    "name": "string (required)",18355    "description": "string",18356    "parameters": "JSON Schema object (required)",18357    "strict": "boolean (ignored)",18358    "defer_loading": "boolean (alpha, 403)"18359   },18360   "chat_completions": {18361    "type": "function",18362    "function": {18363     "name": "…",18364     "description": "…",18365     "parameters": {}18366    }18367   }18368  },18369  "tool_choice_support": {18370   "auto": true,18371   "none": true,18372   "required": true,18373   "forced": {18374    "chat": {18375     "type": "function",18376     "function": {18377      "name": "…"18378     }18379    },18380    "responses": {18381     "type": "function",18382     "name": "…"18383    }18384   }18385  },18386  "parallel": true,18387  "streaming_events": [18388   "chat: whole tool call in ONE chunk delta.tool_calls[{index,id,type,function}]",18389   "responses: response.output_item.added(function_call) → response.function_call_arguments.delta (single delta with full JSON) → response.function_call_arguments.done → response.output_item.done"18390  ],18391  "result_shape": {18392   "chat": "choices[].message.tool_calls[] {id:'call-<uuid>-<n>', type:'function', function:{name, arguments}} + finish_reason 'tool_calls'",18393   "responses": "output[] item {type:'function_call', id:'fc_…', call_id:'call-…', name, arguments, status}; reply with {type:'function_call_output', call_id, output}",18394   "messages": "content[] {type:'tool_use', id, name, input} + stop_reason 'tool_use'; reply with tool_result block"18395  },18396  "billing": "Tokens only (no per-call fee).",18397  "limitations": [18398   "≤350 tools per request (128 in batch docs)",18399   "parameters root must be an object or union of objects (400 otherwise)",18400   "max_turns resets after each client-side call"18401  ],18402  "security": "Executed by the caller; validate arguments.",18403  "beta_header": null,18404  "status": [18405   "DOCUMENTED",18406   "LIVE_VERIFIED"18407  ],18408  "examples": {18409   "curl": null,18410   "python": null,18411   "typescript": null18412  },18413  "verification": {18414   "method": "live_api",18415   "verified_at": "2026-09-19",18416   "result": "success",18417   "http_status": 200,18418   "request_note": "chat: forced → 1 call, round trip → '18°C and sunny', tool_choice required → 2 parallel calls, parallel_tool_calls:false → 1, stream → single chunk; responses: forced function_call + function_call_output via previous_response_id → message; messages: tool_use + tool_result"18419  },18420  "sources": [18421   {18422    "url": "https://docs.x.ai/developers/tools/function-calling",18423    "retrieved_at": "2026-09-19"18424   },18425   {18426    "url": "https://docs.x.ai/openapi.json",18427    "retrieved_at": "2026-09-19"18428   }18429  ],18430  "_fragment": "generated/fragments/tools/xai-tools.json"18431 },18432 {18433  "provider": "xai",18434  "name": "Web Search",18435  "type": "web_search",18436  "category": "server",18437  "description": "Server-side web search + page browsing (search, open_page, find_in_page actions; sub-tools web_search, web_search_with_snippets, browse_page, open_page, open_page_with_find; image search via enable_image_search; view_image via enable_image_understanding). Responses API only.",18438  "compatible_models": [18439   "grok-4.6",18440   "grok-4.5",18441   "grok-4.3",18442   "grok-4.20-0309-reasoning",18443   "grok-4.20-0309-non-reasoning",18444   "grok-4.20-multi-agent-0309",18445   "grok-build-0.1"18446  ],18447  "compatible_endpoints": [18448   "POST /v1/responses",18449   "Batch API (responses body)"18450  ],18451  "parameters_schema": {18452   "type": "web_search",18453   "allowed_domains": "string[] ≤5 (exclusive with excluded_domains)",18454   "excluded_domains": "string[] ≤5",18455   "filters": {18456    "allowed_domains": "…",18457    "excluded_domains": "… (OpenAI-compatible nesting, accepted live)"18458   },18459   "enable_image_understanding": "boolean",18460   "enable_image_search": "boolean",18461   "search_context_size": "REJECTED 400 if set (echoed as 'medium' in responses)",18462   "user_location": "rejected (compat only)",18463   "external_web_access": "rejected (compat only)"18464  },18465  "tool_choice_support": {18466   "auto": true,18467   "none": true,18468   "required": "documented for tools generally"18469  },18470  "parallel": true,18471  "streaming_events": [18472   "response.output_item.added(web_search_call) → response.output_item.done (no *.searching events observed; not exercised in stream)"18473  ],18474  "result_shape": {18475   "item": "output[] {type:'web_search_call', id:'ws_…', status:'completed', action:{type:'search', query, sources[]?}|{type:'open_page', url}|{type:'find_in_page', url, pattern}}",18476   "citations": "output_text.annotations[] url_citation {url, start_index, end_index, title} (live: indices 0/0, title=url); inline [[N]](url) markdown by default (disable with include:['no_inline_citations'])",18477   "usage": "usage.server_side_tool_usage_details.web_search_calls, num_server_side_tools_used",18478   "include": "web_search_call.action.sources"18479  },18480  "billing": "$5 per 1k successful calls (+ tokens); image search billed as web search; view_image billed as image tokens.",18481  "limitations": [18482   "allowed_domains xor excluded_domains",18483   "model may answer without searching (first probe answered the date from context without a call)"18484  ],18485  "security": "xAI-hosted browsing; URLs surfaced in citations.",18486  "beta_header": null,18487  "status": [18488   "DOCUMENTED",18489   "LIVE_VERIFIED"18490  ],18491  "examples": {18492   "curl": null,18493   "python": null,18494   "typescript": null18495  },18496  "verification": {18497   "method": "live_api",18498   "verified_at": "2026-09-19",18499   "result": "success",18500   "http_status": 200,18501   "request_note": "grok-4.3 'open https://x.ai/news …' → web_search_call action open_page, web_search_calls=1, annotation url_citation; first probe (date question) produced no call"18502  },18503  "sources": [18504   {18505    "url": "https://docs.x.ai/developers/tools/web-search",18506    "retrieved_at": "2026-09-19"18507   },18508   {18509    "url": "https://docs.x.ai/developers/tools/citations",18510    "retrieved_at": "2026-09-19"18511   },18512   {18513    "url": "https://docs.x.ai/developers/pricing",18514    "retrieved_at": "2026-09-19"18515   },18516   {18517    "url": "https://docs.x.ai/openapi.json",18518    "retrieved_at": "2026-09-19"18519   }18520  ],18521  "_fragment": "generated/fragments/tools/xai-tools.json"18522 },18523 {18524  "provider": "xai",18525  "name": "X Search",18526  "type": "x_search",18527  "category": "server",18528  "description": "Server-side search of X (keyword, semantic, user search, thread fetch; sub-tools x_keyword_search, x_semantic_search, x_user_search, x_thread_fetch; view_image/view_x_video). Responses API only.",18529  "compatible_models": [18530   "grok-4.6",18531   "grok-4.5",18532   "grok-4.3",18533   "grok-4.20-0309-reasoning",18534   "grok-4.20-0309-non-reasoning",18535   "grok-4.20-multi-agent-0309",18536   "grok-build-0.1"18537  ],18538  "compatible_endpoints": [18539   "POST /v1/responses",18540   "Batch API"18541  ],18542  "parameters_schema": {18543   "type": "x_search",18544   "allowed_x_handles": "string[] ≤10 (spec) / ≤20 (guide); exclusive with excluded_x_handles",18545   "excluded_x_handles": "string[]",18546   "from_date": "YYYY-MM-DD",18547   "to_date": "YYYY-MM-DD",18548   "enable_image_understanding": "boolean",18549   "enable_video_understanding": "boolean"18550  },18551  "tool_choice_support": {18552   "auto": true,18553   "none": true18554  },18555  "parallel": true,18556  "streaming_events": [18557   "response.output_item.added/done (not exercised in stream)"18558  ],18559  "result_shape": {18560   "item_documented": "output[] {type:'x_search_call'}",18561   "item_live": "LIVE_DISCOVERED: output[] {type:'custom_tool_call', id:'ctc_…', call_id:'xs_call-…', name:'x_keyword_search'|'x_semantic_search', input:'{\"query\":…,\"limit\":…,\"mode\":\"Latest\"}', status}",18562   "citations": "annotations[] url_citation to https://x.com/i/status/<id>; response.citations in xAI SDK",18563   "usage": "server_side_tool_usage_details.x_search_calls"18564  },18565  "billing": "$5 per 1k calls until 2026-09-21 12:00 PT; then $5 per 1k posts fetched + $10 per 1k user profiles fetched.",18566  "limitations": [18567   "handles list limits",18568   "live item type differs from docs (custom_tool_call)"18569  ],18570  "security": "xAI-hosted.",18571  "beta_header": null,18572  "status": [18573   "DOCUMENTED",18574   "LIVE_VERIFIED",18575   "LIVE_DISCOVERED"18576  ],18577  "examples": {18578   "curl": null,18579   "python": null,18580   "typescript": null18581  },18582  "verification": {18583   "method": "live_api",18584   "verified_at": "2026-09-19",18585   "result": "success",18586   "http_status": 200,18587   "request_note": "allowed_x_handles ['xai'] → 1 x_keyword_search call (custom_tool_call), 3 url_citation annotations, x_search_calls=1; second run 2 calls"18588  },18589  "sources": [18590   {18591    "url": "https://docs.x.ai/developers/tools/x-search",18592    "retrieved_at": "2026-09-19"18593   },18594   {18595    "url": "https://docs.x.ai/developers/pricing",18596    "retrieved_at": "2026-09-19"18597   },18598   {18599    "url": "https://docs.x.ai/openapi.json",18600    "retrieved_at": "2026-09-19"18601   }18602  ],18603  "_fragment": "generated/fragments/tools/xai-tools.json"18604 },18605 {18606  "provider": "xai",18607  "name": "Code Execution (Code Interpreter)",18608  "type": "code_interpreter",18609  "category": "server",18610  "description": "Sandboxed Python execution (NumPy/Pandas/Matplotlib/SciPy available, no network/filesystem persistence). Responses API type `code_interpreter`; alias `code_execution` accepted and normalised to `code_interpreter` in the response echo. xAI SDK name code_execution.",18611  "compatible_models": [18612   "grok-4.6",18613   "grok-4.5",18614   "grok-4.3",18615   "grok-4.20-0309-reasoning",18616   "grok-4.20-0309-non-reasoning",18617   "grok-4.20-multi-agent-0309",18618   "grok-build-0.1"18619  ],18620  "compatible_endpoints": [18621   "POST /v1/responses",18622   "Batch API"18623  ],18624  "parameters_schema": {18625   "type": "code_interpreter | code_execution (alias)",18626   "container": "any (OpenAI compat, not needed)"18627  },18628  "tool_choice_support": {18629   "auto": true,18630   "none": true18631  },18632  "parallel": true,18633  "streaming_events": [18634   "response.output_item.added(code_interpreter_call) → 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"18635  ],18636  "result_shape": {18637   "item": "output[] {type:'code_interpreter_call', id:'ci_…', code, outputs[], status}",18638   "outputs": "only with include:['code_interpreter_call.outputs']: [{type:'logs', logs:'{\"stdout\":\"4\\n\",\"stderr\":\"\",\"exit_code\":0,\"command_timed_out\":false}'}] (JSON string) or {type:'image', url}",18639   "chat_completions": "output_files[] with include code_execution_files_output (docs)",18640   "usage": "server_side_tool_usage_details.code_interpreter_calls"18641  },18642  "billing": "$5 per 1k calls + tokens.",18643  "limitations": [18644   "time/memory limits",18645   "no network"18646  ],18647  "security": "Isolated sandbox.",18648  "beta_header": null,18649  "status": [18650   "DOCUMENTED",18651   "LIVE_VERIFIED"18652  ],18653  "examples": {18654   "curl": null,18655   "python": null,18656   "typescript": null18657  },18658  "verification": {18659   "method": "live_api",18660   "verified_at": "2026-09-19",18661   "result": "success",18662   "http_status": 200,18663   "request_note": "'Run print(2+2)' → code_interpreter_call code 'print(2+2)', logs stdout '4', text '4', code_interpreter_calls=1; streamed variant emitted the 5 code_interpreter events"18664  },18665  "sources": [18666   {18667    "url": "https://docs.x.ai/developers/tools/code-execution",18668    "retrieved_at": "2026-09-19"18669   },18670   {18671    "url": "https://docs.x.ai/developers/tools/streaming-and-sync",18672    "retrieved_at": "2026-09-19"18673   },18674   {18675    "url": "https://docs.x.ai/openapi.json",18676    "retrieved_at": "2026-09-19"18677   }18678  ],18679  "aliases": [18680   "code_execution"18681  ],18682  "_fragment": "generated/fragments/tools/xai-tools.json"18683 },18684 {18685  "provider": "xai",18686  "name": "Collections Search (File Search)",18687  "type": "file_search",18688  "category": "server",18689  "description": "RAG over Collections. Responses API type `file_search` with vector_store_ids = collection ids (`collections_search` accepted as alias but REQUIRES vector_store_ids, echoed as file_search). Citations use collections://<collection_id>/files/<file_id>.",18690  "compatible_models": [18691   "grok-4.6",18692   "grok-4.5",18693   "grok-4.3",18694   "grok-4.20-0309-reasoning",18695   "grok-4.20-0309-non-reasoning",18696   "grok-4.20-multi-agent-0309",18697   "grok-build-0.1"18698  ],18699  "compatible_endpoints": [18700   "POST /v1/responses",18701   "Batch API"18702  ],18703  "parameters_schema": {18704   "type": "file_search | collections_search (alias)",18705   "vector_store_ids": "string[] collection ids (required)",18706   "max_num_results": "integer",18707   "filters": "any",18708   "ranking_options": "any"18709  },18710  "tool_choice_support": {18711   "auto": true,18712   "none": true18713  },18714  "parallel": true,18715  "streaming_events": [18716   "response.output_item.added/done (file_search_call)"18717  ],18718  "result_shape": {18719   "item": "output[] {type:'file_search_call', id:'fs_…', queries[], results[] (include file_search_call.results → {file_id, filename, score, text}), status completed|failed}",18720   "citations": "collections://collection_id/files/file_id",18721   "usage": "server_side_tool_usage_details.file_search_calls (docs also list document_search_calls)"18722  },18723  "billing": "$2.50 per 1k calls + tokens; storage $0.10/GiB/day.",18724  "limitations": [18725   "collection must be indexed (document status PROCESSED) or the call fails"18726  ],18727  "security": "Team-scoped collections.",18728  "beta_header": null,18729  "status": [18730   "DOCUMENTED",18731   "LIVE_VERIFIED"18732  ],18733  "examples": {18734   "curl": null,18735   "python": null,18736   "typescript": null18737  },18738  "verification": {18739   "method": "live_api",18740   "verified_at": "2026-09-19",18741   "result": "success",18742   "http_status": 200,18743   "request_note": "empty / still-indexing collection → file_search_call status 'failed', results [], text 'No documents.'; fake id also 200 with failed call; {type:'collections_search'} without vector_store_ids → 422"18744  },18745  "sources": [18746   {18747    "url": "https://docs.x.ai/developers/tools/collections-search",18748    "retrieved_at": "2026-09-19"18749   },18750   {18751    "url": "https://docs.x.ai/developers/files/collections",18752    "retrieved_at": "2026-09-19"18753   },18754   {18755    "url": "https://docs.x.ai/openapi.json",18756    "retrieved_at": "2026-09-19"18757   }18758  ],18759  "aliases": [18760   "collections_search"18761  ],18762  "_fragment": "generated/fragments/tools/xai-tools.json"18763 },18764 {18765  "provider": "xai",18766  "name": "Remote MCP",18767  "type": "mcp",18768  "category": "mcp",18769  "description": "xAI connects to a remote MCP server (Streamable HTTP or SSE) and exposes its tools to the model; results are always returned in mcp_call items.",18770  "compatible_models": [18771   "grok-4.6",18772   "grok-4.5",18773   "grok-4.3",18774   "grok-4.20-0309-reasoning",18775   "grok-4.20-0309-non-reasoning",18776   "grok-4.20-multi-agent-0309",18777   "grok-build-0.1"18778  ],18779  "compatible_endpoints": [18780   "POST /v1/responses",18781   "Batch API",18782   "Speech-to-Speech API"18783  ],18784  "parameters_schema": {18785   "type": "mcp",18786   "server_url": "string (required)",18787   "server_label": "string (required; prefixes tool names)",18788   "server_description": "string",18789   "allowed_tools": "string[] (empty = all; xAI SDK: allowed_tool_names)",18790   "authorization": "string bearer token for the MCP server",18791   "headers": "object (xAI SDK: extra_headers)",18792   "require_approval": "accepted silently (docs: unsupported)",18793   "connector_id": "docs: unsupported",18794   "defer_loading": "alpha"18795  },18796  "tool_choice_support": {18797   "auto": true,18798   "none": true18799  },18800  "parallel": true,18801  "streaming_events": [18802   "response.output_item.added/done (mcp_call); not exercised in stream"18803  ],18804  "result_shape": {18805   "item": "output[] {type:'mcp_call', id:'mcp_…', server_label, name, arguments (JSON string), output (JSON string, always returned), error:'', status}",18806   "tools_echo": "response.tools[] {type:'mcp', server_label, server_url, allowed_tools:[], headers:{}, server_description:''}",18807   "usage": "server_side_tool_usage_details.mcp_calls"18808  },18809  "billing": "No per-call fee; tokens only (tool outputs count as input tokens).",18810  "limitations": [18811   "no approval flow",18812   "tool list injected into context (use allowed_tools)"18813  ],18814  "security": "Use HTTPS; credentials are forwarded to the MCP server by xAI.",18815  "beta_header": null,18816  "status": [18817   "DOCUMENTED",18818   "LIVE_VERIFIED"18819  ],18820  "examples": {18821   "curl": null,18822   "python": null,18823   "typescript": null18824  },18825  "verification": {18826   "method": "live_api",18827   "verified_at": "2026-09-19",18828   "result": "success",18829   "http_status": 200,18830   "request_note": "deepwiki (https://mcp.deepwiki.com/mcp) → mcp_call name ask_question, output JSON, text 'Python SDK for xAI language models chat.', mcp_calls=1, 4024 total tokens"18831  },18832  "sources": [18833   {18834    "url": "https://docs.x.ai/developers/tools/remote-mcp",18835    "retrieved_at": "2026-09-19"18836   },18837   {18838    "url": "https://docs.x.ai/openapi.json",18839    "retrieved_at": "2026-09-19"18840   }18841  ],18842  "_fragment": "generated/fragments/tools/xai-tools.json"18843 },18844 {18845  "provider": "xai",18846  "name": "Image Generation (tool)",18847  "type": "image_generation",18848  "category": "server",18849  "description": "In-conversation image generation tool (Imagine models). Documented on the tools pages; covered by the images agent. Accepted live in tools[] (echoed) without being called.",18850  "compatible_models": [18851   "grok-4.6",18852   "grok-4.5",18853   "grok-4.3",18854   "grok-4.20-0309-reasoning",18855   "grok-4.20-0309-non-reasoning",18856   "grok-4.20-multi-agent-0309",18857   "grok-build-0.1"18858  ],18859  "compatible_endpoints": [18860   "POST /v1/responses"18861  ],18862  "parameters_schema": {18863   "type": "image_generation",18864   "action": "string|null"18865  },18866  "tool_choice_support": {18867   "auto": true18868  },18869  "parallel": null,18870  "streaming_events": null,18871  "result_shape": {18872   "item": "output[] {type:'image_generation_call', result (bare base64), prompt, status}; chat delta.images[]"18873  },18874  "billing": "Imagine API per-image rates.",18875  "limitations": null,18876  "security": null,18877  "beta_header": null,18878  "status": [18879   "DOCUMENTED",18880   "LIVE_VERIFIED"18881  ],18882  "examples": {18883   "curl": null,18884   "python": null,18885   "typescript": null18886  },18887  "verification": {18888   "method": "live_api",18889   "verified_at": "2026-09-19",18890   "result": "success",18891   "http_status": 200,18892   "request_note": "accepted in tools[] with tool_choice none (no generation)"18893  },18894  "sources": [18895   {18896    "url": "https://docs.x.ai/developers/tools/image-generation",18897    "retrieved_at": "2026-09-19"18898   },18899   {18900    "url": "https://docs.x.ai/openapi.json",18901    "retrieved_at": "2026-09-19"18902   }18903  ],18904  "_fragment": "generated/fragments/tools/xai-tools.json"18905 },18906 {18907  "provider": "xai",18908  "name": "Attachment search (implicit)",18909  "type": "attachment_search",18910  "category": "server-implicit",18911  "description": "Not a tools[] entry: attaching input_file (file_id or file_url) to a Responses message automatically turns the request into an agentic document-search workflow. xAI SDK include value attachment_search_call_output.",18912  "compatible_models": [18913   "grok-4.6",18914   "grok-4.5",18915   "grok-4.3",18916   "grok-4.20-0309-reasoning",18917   "grok-4.20-0309-non-reasoning",18918   "grok-4.20-multi-agent-0309",18919   "grok-build-0.1"18920  ],18921  "compatible_endpoints": [18922   "POST /v1/responses"18923  ],18924  "parameters_schema": {18925   "input": [18926    {18927     "type": "input_file",18928     "file_id": "file_…",18929     "file_url": "https://…"18930    }18931   ]18932  },18933  "tool_choice_support": null,18934  "parallel": null,18935  "streaming_events": null,18936  "result_shape": {18937   "observed": "no visible tool item in output (only reasoning + message); answer grounded in the file ('PINEAPPLE')"18938  },18939  "billing": "$10 per 1k calls (File Attachments).",18940  "limitations": [18941   "not available on /v1/chat/completions (400)",18942   "no batch mode"18943  ],18944  "security": null,18945  "beta_header": null,18946  "status": [18947   "DOCUMENTED",18948   "LIVE_VERIFIED"18949  ],18950  "examples": {18951   "curl": null,18952   "python": null,18953   "typescript": null18954  },18955  "verification": {18956   "method": "live_api",18957   "verified_at": "2026-09-19",18958   "result": "success",18959   "http_status": 200,18960   "request_note": "200-byte txt attached by file_id → correct secret word; chat completions file part → 400"18961  },18962  "sources": [18963   {18964    "url": "https://docs.x.ai/developers/model-capabilities/files/chat-with-files",18965    "retrieved_at": "2026-09-19"18966   },18967   {18968    "url": "https://docs.x.ai/developers/pricing",18969    "retrieved_at": "2026-09-19"18970   }18971  ],18972  "_fragment": "generated/fragments/tools/xai-tools.json"18973 },18974 {18975  "provider": "xai",18976  "name": "Image understanding (view_image / view_x_video sub-tools)",18977  "type": "view_image",18978  "category": "server-subtool",18979  "description": "Not a tools[] type: enabling enable_image_understanding on web_search/x_search (or enable_video_understanding on x_search) lets the agent call view_image / view_x_video on media it finds. Direct image input is a content part (input_image / image_url), not a tool.",18980  "compatible_models": [18981   "grok-4.6",18982   "grok-4.5",18983   "grok-4.3",18984   "grok-4.20-0309-reasoning",18985   "grok-4.20-0309-non-reasoning",18986   "grok-4.20-multi-agent-0309",18987   "grok-build-0.1"18988  ],18989  "compatible_endpoints": [18990   "POST /v1/responses (via web_search / x_search options)"18991  ],18992  "parameters_schema": {18993   "enable_image_understanding": "boolean on web_search|x_search",18994   "enable_video_understanding": "boolean on x_search"18995  },18996  "tool_choice_support": null,18997  "parallel": null,18998  "streaming_events": null,18999  "result_shape": {19000   "usage": "SERVER_SIDE_TOOL_VIEW_IMAGE / SERVER_SIDE_TOOL_VIEW_X_VIDEO counts in the xAI SDK"19001  },19002  "billing": "No invocation fee; image tokens billed.",19003  "limitations": null,19004  "security": null,19005  "beta_header": null,19006  "status": [19007   "DOCUMENTED"19008  ],19009  "examples": {19010   "curl": null,19011   "python": null,19012   "typescript": null19013  },19014  "verification": {19015   "method": "docs_only",19016   "verified_at": "2026-09-19",19017   "result": "success",19018   "http_status": null,19019   "request_note": "flags accepted (enable_image_understanding:false echoed); no view_image call triggered"19020  },19021  "sources": [19022   {19023    "url": "https://docs.x.ai/developers/tools/web-search",19024    "retrieved_at": "2026-09-19"19025   },19026   {19027    "url": "https://docs.x.ai/developers/tools/x-search",19028    "retrieved_at": "2026-09-19"19029   },19030   {19031    "url": "https://docs.x.ai/developers/tools/tool-usage-details",19032    "retrieved_at": "2026-09-19"19033   },19034   {19035    "url": "https://docs.x.ai/developers/pricing",19036    "retrieved_at": "2026-09-19"19037   }19038  ],19039  "_fragment": "generated/fragments/tools/xai-tools.json"19040 },19041 {19042  "provider": "xai",19043  "name": "Shell (local)",19044  "type": "shell",19045  "category": "client",19046  "description": "Model emits shell_call items {action:{commands[], timeout_ms, max_output_length}} for the client to run locally and answer with shell_call_output. Accepted live; not in the tools guide pages (OpenAPI only).",19047  "compatible_models": [19048   "grok-4.6",19049   "grok-4.5",19050   "grok-4.3",19051   "grok-4.20-0309-reasoning",19052   "grok-4.20-0309-non-reasoning",19053   "grok-4.20-multi-agent-0309",19054   "grok-build-0.1"19055  ],19056  "compatible_endpoints": [19057   "POST /v1/responses"19058  ],19059  "parameters_schema": {19060   "type": "shell",19061   "environment": {19062    "type": "local",19063    "skills": "[{name, description, path}]"19064   }19065  },19066  "tool_choice_support": {19067   "auto": true,19068   "none": true19069  },19070  "parallel": null,19071  "streaming_events": null,19072  "result_shape": {19073   "item": "shell_call / shell_call_output"19074  },19075  "billing": "Tokens only.",19076  "limitations": null,19077  "security": "Runs on the caller's machine.",19078  "beta_header": null,19079  "status": [19080   "DOCUMENTED",19081   "LIVE_VERIFIED"19082  ],19083  "examples": {19084   "curl": null,19085   "python": null,19086   "typescript": null19087  },19088  "verification": {19089   "method": "live_api",19090   "verified_at": "2026-09-19",19091   "result": "success",19092   "http_status": 200,19093   "request_note": "tools:[{type:'shell', environment:{type:'local'}}] accepted and echoed; no call triggered"19094  },19095  "sources": [19096   {19097    "url": "https://docs.x.ai/openapi.json",19098    "retrieved_at": "2026-09-19"19099   }19100  ],19101  "_fragment": "generated/fragments/tools/xai-tools.json"19102 },19103 {19104  "provider": "xai",19105  "name": "Tool search (deferred tool loading)",19106  "type": "tool_search",19107  "category": "hosted",19108  "description": "Server-side tool search that loads function definitions marked defer_loading:true on demand (tool_search_call / tool_search_output items). Alpha.",19109  "compatible_models": [19110   "grok-4.6",19111   "grok-4.5",19112   "grok-4.3",19113   "grok-4.20-0309-reasoning",19114   "grok-4.20-0309-non-reasoning",19115   "grok-4.20-multi-agent-0309",19116   "grok-build-0.1"19117  ],19118  "compatible_endpoints": [19119   "POST /v1/responses"19120  ],19121  "parameters_schema": {19122   "type": "tool_search",19123   "execution": "string|null"19124  },19125  "tool_choice_support": null,19126  "parallel": null,19127  "streaming_events": null,19128  "result_shape": {19129   "items": "tool_search_call {arguments:{query, limit}, execution:'server'} → tool_search_output {tools[]}"19130  },19131  "billing": null,19132  "limitations": [19133   "alpha users only"19134  ],19135  "security": null,19136  "beta_header": null,19137  "status": [19138   "DOCUMENTED",19139   "ACCOUNT_RESTRICTED"19140  ],19141  "examples": {19142   "curl": null,19143   "python": null,19144   "typescript": null19145  },19146  "verification": {19147   "method": "live_api",19148   "verified_at": "2026-09-19",19149   "result": "restricted",19150   "http_status": 403,19151   "request_note": "403 permission-denied 'The tool_search tool and defer_loading are only available for alpha users'"19152  },19153  "sources": [19154   {19155    "url": "https://docs.x.ai/openapi.json",19156    "retrieved_at": "2026-09-19"19157   }19158  ],19159  "_fragment": "generated/fragments/tools/xai-tools.json"19160 },19161 {19162  "provider": "xai",19163  "name": "Live Search (legacy chat tool)",19164  "type": "live_search",19165  "category": "server",19166  "description": "Legacy Chat Completions tool variant {type:'live_search', sources:[{type:'web'|'x'|'news'|'rss', …}]} and the search_parameters/web_search_options fields. Retired: every use → 410 'Live search is deprecated. Please switch to the Agent Tools API'.",19167  "compatible_models": [],19168  "compatible_endpoints": [19169   "POST /v1/chat/completions (410)"19170  ],19171  "parameters_schema": {19172   "type": "live_search",19173   "sources": "[{type:'web', allowed_websites, excluded_websites, country, safe_search}, {type:'x', included_x_handles, excluded_x_handles, post_favorite_count, post_view_count}, {type:'news', …}, {type:'rss', links[]}]"19174  },19175  "tool_choice_support": null,19176  "parallel": null,19177  "streaming_events": null,19178  "result_shape": null,19179  "billing": null,19180  "limitations": null,19181  "security": null,19182  "beta_header": null,19183  "status": [19184   "DOCUMENTED",19185   "RETIRED"19186  ],19187  "examples": {19188   "curl": null,19189   "python": null,19190   "typescript": null19191  },19192  "verification": {19193   "method": "live_api",19194   "verified_at": "2026-09-19",19195   "result": "failure",19196   "http_status": 410,19197   "request_note": "410 on live_search tool, search_parameters and web_search_options"19198  },19199  "sources": [19200   {19201    "url": "https://docs.x.ai/developers/rest-api-reference/inference/chat-completions",19202    "retrieved_at": "2026-09-19"19203   },19204   {19205    "url": "https://docs.x.ai/openapi.json",19206    "retrieved_at": "2026-09-19"19207   }19208  ],19209  "_fragment": "generated/fragments/tools/xai-tools.json"19210 }19211]