web_search

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden for behavioral disclosure. It adds useful context about full page content retrieval, structured output, and up to 5 parallel queries. However, it does not explicitly state that this is a read-only operation, nor does it disclose rate limits, error behavior, or authentication requirements, leaving some gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loaded with the core action and return type. Every clause adds information: the HTTP method, return structure, parallel query support, filters, and specialized modes. There is no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (13 parameters, no output schema), the description does a good job covering the essential behavior: it states the return format, major capabilities, and special modes. It does omit potential details like result ordering, truncation behavior, and error handling, but for a search tool with this level of schema documentation, it is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description summarizes key parameter groups (domain filters, date filters, academic/SEC modes) and mentions the 5-query limit, but it does not add significant meaning beyond the schema's own parameter descriptions. It serves as a high-level overview rather than adding new semantic details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the action ('Perform a raw web search'), the resource ('POST /search'), and the specific return format ('structured result objects with URL, title, and text content'). It also names distinctive capabilities (parallel queries, filters, academic/SEC modes) that separate it from sibling tools like sonar_chat.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit when-to-use or when-not-to-use guidance. It mentions the tool is a 'raw web search' which implies a direct search function, but it never references alternatives (e.g., sonar_chat for conversational search) or exclusions. Context is implied but not directly stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.