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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral detail: it routes to one of 5,743 tools, fills arguments automatically, returns structured answers with stable citation URIs, and is a single call with no multi-step research loop. It also notes cost/risk differences for alternatives ('deep_research costs more', 'ask_pipeworx_beta more experimental'). 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 long but front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and then organizes supporting details: domain list, routing behavior, trigger phrases, examples, and alternative tool guidance. Each sentence contributes functional value. Slightly more verbose than strictly necessary, particularly the parenthetical notes, but every part aids tool selection and invocation.

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 role as a router across thousands of sources, the description is thoroughly complete. It tells the agent what the tool does, what input to supply, what the output will contain (structured answer with stable citation URIs), when to prefer it, and exactly when to choose each named sibling. There is no output schema, so the description's statement of return format is essential and sufficient.

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 parameter semantics baseline is 3. The description goes slightly beyond the schema by providing a rich set of example questions and explaining that the parameter is a natural-language question ('even if web search could also answer it'), which clarifies what kind of input is appropriate. The schema already documents the aliases, so the description does not need to repeat that.

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 states a clear verb and resource: it routes a natural-language question to the right specialized tool and returns a structured answer with stable pipeworx:// citation URIs. It also explicitly differentiates itself from siblings by naming ask_pipeworx_grounded, ask_pipeworx_beta, and deep_research and describing how each is used. The scope ('SEC filings, FDA drug data, FRED/BLS economic statistics...') makes the purpose concrete and non-tautological.

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 gives explicit direction: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', then lists the exact alternative tools with their selection conditions (ask_pipeworx_beta for iterative research, deep_research for multi-part questions, ask_pipeworx_grounded for a single grounded answer). It also provides query trigger phrases ('what is', 'look up', 'find', 'get the latest') and real examples, giving an agent unambiguous guidance on when to invoke this tool versus its siblings.

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