web_search

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

With no annotations, the description carries the full load and does it reasonably well: it names the backend (DuckDuckGo), discloses that page text is conditional on fetch_page_content, and that content is trimmed to max_chars_per_page. It omits the behavioral cost of the default — fetching N pages of body text per query is slow and heavy — which an agent choosing parameter values would benefit from knowing.

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?

Two sentences, no filler, with the resource and result shape front-loaded before the conditional behavior and the usage rationale. Slightly dense in the first sentence but every clause corresponds to something an agent needs.

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?

An output schema exists, so return values need no explaining, and the description covers the query path, the conditional fetch, and trimming against a 0%-coverage schema. What is missing is cost/latency guidance given fetch_page_content defaults to true — the one decision an agent is most likely to get wrong here.

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 0%, so the description must compensate, and it explains three of the four parameters: query (implicit in "Search the web"), fetch_page_content (page text included only when true), and max_chars_per_page (trimming). max_results is only obliquely covered by "ranked results", so it does not quite earn a 5.

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?

States a specific verb and resource (search the web via DuckDuckGo) plus the exact shape of the result: title, URL, snippet, date, and optional page body as Markdown. The one gap is sibling differentiation — web_to_markdown is clearly adjacent, and nothing in the description tells the agent which to pick for a known URL.

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?

"Use it to ground answers in current sources and cite them" gives a real use case, so the usage is implied clearly enough. But there is no when-not and no named alternative — an agent holding a single URL has no signal to route to web_to_markdown instead.

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