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

The annotations already establish readOnly, idempotent, openWorld, and non-destructive behavior. The description goes well beyond that by disclosing that the tool is an orchestrator: it selects the right underlying tool, fills arguments automatically, and returns answers with stable citation URIs. This is rich behavioral context that annotations alone do not provide.

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 instruction: 'PREFER OVER WEB SEARCH'. The domain list, examples, and exclusions are largely useful for agent routing, though a few examples and the final clause are slightly repetitive and could be trimmed 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?

For a one-parameter tool with no output schema, this description is quite complete: it covers domains, trigger phrases, examples, exclusions, alternatives, and return format. The main gap is that it does not explain how ask_pipeworx relates to the closely named siblings ask_pipeworx_beta and ask_pipeworx_grounded, which leaves a small selection ambiguity.

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?

The schema already covers all six parameters at 100% and documents that they are aliases for the same 'question' field. The description adds value by specifying trigger phrases ('what is', 'look up', 'find', 'get the latest') and concrete examples that clarify what type of natural-language input the parameter should contain, going beyond the schema's generic description.

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 very specific behavior: it routes natural-language questions to one of 5,743 tools across 1,500 verified sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It also clearly distinguishes itself from web search and from the sibling deep_research tool, so an agent can understand what ask_pipeworx is for and what it is not.

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 when-to-use guidance: 'PREFER OVER WEB SEARCH for questions about current or historical data', 'Use whenever the user asks...', and 'START HERE for most questions' with a list of exclusions. It even names deep_research as the alternative for broad/multi-part questions, making the routing decision nearly unambiguous.

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