Title99/100
Web search
The title clearly communicates the tool’s action and subject. Keep it concise.
Description91/100
Purpose: Perform web searches and return LLM-friendly results, including excerpts that are usually sufficient to answer directly without a follow-up fetch. Ideal Use Cases: - Answering questions that require fresh or current information - Research, comparison, documentation, and troubleshooting questions - Broad tasks where multiple `search_queries` can be issued in a single call For multiple independent objectives, make one web_search call per objective concurrently. Put related query variations for the same objective in a single call's search_queries list.
The description explains the capability, when to use it, and what to expect.
Inputs81/100
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
objective
Natural-language description of what the web search is trying to find. Try to make the search objective atomic, looking for a specific piece of information. May include guidance about preferred sources or freshness.
Clear enough to supply this argument.
search_queries
Concise keyword search queries, 3-6 words each, which may include search operators. At least one query is required; provide 2-3 for best results. For broad tasks, you can include multiple related queries in a single call instead of chaining web_search calls. The queries should be related to the objective.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
session_id
Stable identifier for the current conversation. Generate a random value (UUID or 32+ character hex string) at the start of your session and reuse the exact same value on every web_search / web_fetch call. Do NOT change it between turns. Used for free-tier rate limiting and correlating your tool calls in our logs; ignored on paid-tier keys.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
model_name
The identifier of the LLM model making this tool call (e.g. 'claude-opus-4.7', 'gpt-5.5', 'gemini-2.5-pro'). Before the first call, verify the exact active model slug from trusted runtime/session metadata or active client configuration. Pass the full slug verbatim; never shorten or substitute a model-family alias like 'gpt-5'. Used for product analytics only; does not affect search behavior.
Remove validation rules already expressed in this field’s schema; describe its meaning and usage instead.
Annotations100/100
All four behavior hints are declared.
{
"title": "Web search",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}Output schema91/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$defs": {
"Warning": {
"type": "object",
"title": "Warning",
"required": [
"type",
"message"
],
"properties": {
"type": {
"enum": [
"spec_validation_warning",
"input_validation_warning",
"warning"
],
"type": "string",
"title": "Type",
"examples": [
"spec_validation_warning",
"input_validation_warning"
],
"description": "Type of warning. Note that adding new warning types is considered a backward-compatible change."
},
"detail": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"title": "Detail",
"default": null,
"description": "Optional detail supporting the warning."
},
"message": {
"type": "string",
"title": "Message",
"description": "Human-readable message."
}
},
"description": "Human-readable message for a task."
},
"UsageItem": {
"type": "object",
"title": "UsageItem",
"required": [
"name",
"count"
],
"properties": {
"name": {
"type": "string",
"title": "Name",
"examples": [
"sku_search",
"sku_extract_excerpts"
],
"description": "Name of the SKU."
},
"count": {
"type": "integer",
"title": "Count",
"examples": [
1
],
"description": "Count of the SKU."
}
},
"description": "Usage item for a single operation."
},
"V1WebSearchResult": {
"type": "object",
"title": "V1WebSearchResult",
"required": [
"url",
"excerpts"
],
"properties": {
"url": {
"type": "string",
"title": "Url",
"description": "URL associated with the search result."
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Title",
"default": null,
"description": "Title of the webpage, if available."
},
"excerpts": {
"type": "array",
"items": {
"type": "string"
},
"title": "Excerpts",
"description": "Relevant excerpted content from the URL, formatted as markdown."
},
"publish_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Publish Date",
"default": null,
"description": "Publish date of the webpage in YYYY-MM-DD format, if available."
}
},
"description": "A single search result from the web search API."
}
},
"title": "V1SearchResponse",
"required": [
"search_id",
"results",
"session_id"
],
"properties": {
"usage": {
"anyOf": [
{
"type": "array",
"items": {
"$ref": "#/$defs/UsageItem"
}
},
{
"type": "null"
}
],
"title": "Usage",
"default": null,
"description": "Usage metrics for the search request."
},
"results": {
"type": "array",
"items": {
"$ref": "#/$defs/V1WebSearchResult"
},
"title": "Results",
"description": "A list of search results, ordered by decreasing relevance."
},
"warnings": {
"anyOf": [
{
"type": "array",
"items": {
"$ref": "#/$defs/Warning"
}
},
{
"type": "null"
}
],
"title": "Warnings",
"default": null,
"description": "Warnings for the search request, if any."
},
"search_id": {
"type": "string",
"title": "Search Id",
"description": "Search ID. Example: `search_cad0a6d2dec046bd95ae900527d880e7`"
},
"session_id": {
"type": "string",
"title": "Session Id",
"examples": [
"session_8a911eb27c7a4afaa20d0d9dc98d07c0"
],
"description": "Session identifier, echoed back from the request if provided, otherwise generated by the server. Should be passed to future search and extract calls made by the agent as part of the same larger task."
}
},
"description": "Search response."
}