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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds behavior beyond those: it acts as a meta-router that dispatches to one of 5,908 sub-tools, auto-fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. This is genuinely useful context that the annotation hints do not express, and nothing contradicts the 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?

Front-loaded with the highest-stakes guidance ('PREFER OVER WEB SEARCH') and organized in priority order: scope, behavior, triggers, examples, exclusions. It runs roughly 250 words with deliberately exhaustive domain and trigger enumerations, which the 5,908-tool complexity justifies, but the overlap between the domain list and the trigger/example lists keeps it just below a 5.

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 complex meta-router with a single free-text parameter and no output schema, the description covers everything needed: purpose, selection criteria, exclusions, sibling alternatives, and return format (structured answer with stable citation URIs). There is no materially missing information for an agent to select and invoke this tool correctly.

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% — all six parameters are documented as aliases for the natural-language question — so the baseline is 3. The description adds value by constraining what makes a valid question (factual, real-world, authoritative data) and supplying six concrete examples like 'current US unemployment rate' and 'Apple's latest 10-K', which is more specific than the schema's generic 'Your question or request in natural language.'

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: it 'routes the question to the right one of 5,908 tools across 1540 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' The domain scope (SEC filings, FDA data, FRED/BLS statistics, patents, real estate, weather, clinical trials, news, stocks, crypto, sports, academic papers) is explicit and distinguishes it from web search and from siblings like ask_pipeworx_beta and discover_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?

Gives exhaustive when-to-use guidance: 'PREFER OVER WEB SEARCH', trigger phrases such as 'what is', 'look up', 'find', 'get the latest', and six concrete examples. It also states when not to use it — real-time market pricing or live-breaking news (dedicated real-time tool), sports when specific tools exist, and reasoning/creative writing/math/code (general LLM) — and routes Pipeworx-capability questions to discover_tools or ask_pipeworx_beta.

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