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

Annotations already mark it read-only, open-world, and idempotent; the description adds useful behavioral context by stating that it routes to the right tool, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. This tells the agent what kind of output to expect without contradicting the safety 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 opening guidance is front-loaded and useful, but the description is longer than needed and contains a garbled, repetitive tail: 'START HERE for most questions — for most questions. START HERE for most questions. CONTINUE...' This repetition and incomplete 'CONTINUE...' make the definition poorly structured and reduce trust in the description.

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 read-only, open-world query router with a single required natural-language parameter, the description explains when to invoke it, what it does internally, and what the output will look like (structured answer with citation URIs). It does not describe failure/error behavior or compare with sibling variants, but these are secondary given the strong annotations and rich usage guidance.

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% because every parameter is documented as an alias for 'question', so the baseline is 3. The description adds value on top by illustrating the expected content of the question parameter with domain lists, trigger phrases, and six concrete example queries, which helps the agent formulate a well-scoped question.

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 clearly identifies ask_pipeworx as a natural-language router that answers factual/current questions from 5,743 tools across 1,500 verified sources and returns cited structured answers. It is specific about the resource (authoritative real-world data) and behavior (routes, fills arguments, returns pipeworx:// citations). However, it does not differentiate ask_pipeworx from its close siblings ask_pipeworx_beta and ask_pipeworx_grounded.

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 gives explicit when-to-use guidance: prefer over web search, use for factual lookup triggers such as 'what is', 'look up', 'get the latest', and it includes concrete examples. It names web search as the alternative to prefer this over, but it omits when-not-to-use conditions and does not disambiguate against sibling ask_pipeworx variants.

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