web_search

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

With no annotations provided, the description carries the full burden, but it falls short in some areas. It discloses the return format conceptually (title, link, snippet) and mentions that actual result counts may be less than requested (via schema), but it doesn't clarify key behaviors like rate limits, whether the tool can fail on invalid languages (e.g., 'zh' being rejected is mentioned in the schema not the description), or what happens with offset pagination edge cases. The description does mention filters but doesn't explain the response structure beyond snippets. Given no annotations, a 3 is appropriate for the partial but incomplete behavioral disclosure.

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 a single dense paragraph that front-loads the core purpose (search internet, return titles/links/snippets) before diving into filters and syntax. Every sentence contributes functionality. However, it reads as a wall of text with no visual breaks; a short list format or cleaner sentence segmentation would improve scanability. Still, it is appropriately sized given the tool's complexity and avoids fluff.

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 tool has 11 parameters, no output schema, and no annotations, the description covers the main functional aspects: what it returns, when to use it, filter categories, and query syntax. It doesn't fully cover edge cases like error behavior or rate limiting, and it doesn't explain what each result type contains, but for a search tool the essentials are present. The parameter schema already provides detailed per-parameter descriptions, offsetting the need for more in the description. A 4 reflects strong coverage with minor omissions.

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 description coverage is 100%, so the baseline is 3, but the description adds meaningful value by grouping parameters into semantic categories: time-based filtering (freshness), regional (country), language (search_lang), result type (result_filter), and custom ordering (goggles). It also introduces the query operator syntax that applies to the q parameter, which enriches the schema's minimal examples. The description doesn't repeat every schema detail but adds conceptual clarity that helps an agent choose parameters.

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 states the tool performs internet search via Brave Search and returns titles, links, and snippets, with a specific verb (检索) and resource (互联网/Brave Search). It also enumerates supported filters and query syntax, which distinguishes it from sibling tools, though no siblings are listed. The coverage makes it unambiguous what this tool does.

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 explicitly states when to use it: for current information, news, documents, or any question requiring internet access. It also explains filter usage and query operators, giving actionable guidance. However, it doesn't provide explicit when-not-to-use guidance or alternatives, though with no sibling tools listed, this is a minor gap.

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