willow_web_search

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

Annotations already indicate read-only, open-world, non-destructive; the description adds that it needs no API key and uses DuckDuckGo HTML. It also discloses the exact output fields and a dependency for include_handoffs (web_net + consent.internet + live egress lease). This goes beyond the annotations without contradicting them, though it omits details like pagination or rate limits.

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 compact, front-loading the core purpose and return format in the first sentence. It then details parameters efficiently without fluff. Each sentence adds value, though the second paragraph could be slightly more structured.

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?

For a web search tool, the description covers the essential points: what it does, what it returns, and key parameter behaviors. But it lacks information on pagination (max_results behavior), error handling, and the required app_id semantics, which are non-obvious. Given the absence of an output schema, more details on result structure would be beneficial, but the tool's simplicity and open annotations reduce the burden.

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 has 5 params but 0% coverage in the schema itself; the description compensates partly by explaining trusted_only and include_handoffs with specific behaviors. However, it does not clarify app_id (which is required), max_results (though default 8 is self-explanatory) or query beyond the obvious. With no other source for these, the description only covers 2 of 5 parameters, leaving the agent to infer the rest.

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?

Purpose is specific and clear: 'Open web search via DuckDuckGo HTML (no API key).' It states the return fields (title, url, snippet, source, hostname) and even signals the intended use cases (current events, tech news, live open web). This distinguishes it from positional siblings like willow_institutional_search and willow_web_fetch, so an agent can quickly select it.

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?

Provides clear use cases: 'Use for current events, tech news, and queries that need the live open web.' It also hints at alternatives by mentioning 'institutional' in a sibling, but does not explicitly say when *not* to use this tool. The parameter-level guidance for trusted_only and include_handoffs is constructive, including the prerequisite for handoffs, but it doesn't contrast with sibling tools explicitly.

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