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

Annotations already communicate read-only, open-world, idempotent, non-destructive behavior; the description adds valuable context that it routes the question, fills arguments, and returns stable pipeworx:// citation URIs. It does not discuss potential failure modes or accuracy limits, but the behavior is not obscured. No contradiction with annotations.

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 front-loaded and uses helpful examples, but it is verbose and repeats the 'even if web search could also answer it' idea. The long domain list and multiple routing hints could be tightened without losing meaning.

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's routing complexity and lack of an output schema, the description covers what it does, when to reach for it, examples, citation behavior, and the main alternative (deep_research). An agent has enough context to invoke it correctly and understand what kind of answer to expect.

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 covers all six parameters at 100%, describing 'question' and aliases. The description adds meaning by defining what constitutes an acceptable question (factual, about real-world entities/events/numbers) and supplying concrete examples. This helps an agent compose the required parameter even though the schema already names it.

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 gives a specific verb and resource: it answers factual questions by routing them to one of 5,798 tools across 1,517 verified sources and returning citations. It also differentiates itself from web search and deep_research by stating it should be preferred for authoritative structured data. The scope is concrete and distinguishable from sibling tools.

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?

It opens with 'PREFER OVER WEB SEARCH' and lists explicit triggers ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'). It further instructs 'START HERE for most questions' and explicitly routes broad/multi-part questions to deep_research, providing when-not-to-use guidance. This leaves little to inference.

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