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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context on top: it routes the question, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. It does not mention rate limits or ambiguous-query failure modes, but the annotation data plus added context is strong.

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 with the strongest directive ('PREFER OVER WEB SEARCH') and then provides dense, useful context: use cases, trigger phrases, and examples. It is slightly repetitive near the end with 'even if web search could also answer it' and 'START HERE for most questions' reinforcing the same idea, but the length mostly earns its place.

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 is a question router and there is no output schema, the description covers the key decision factors: when to use it, what kinds of questions it handles, how it works, and what the response will contain (structured answer with citation URIs). It would be more complete if it explained how to choose among ask_pipeworx_beta and ask_pipeworx_grounded, since those are direct sibling alternatives.

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 description coverage is 100% and the schema already documents the single meaningful parameter plus its aliases. The description reinforces that the input is a natural-language question and gives examples, but it does not add technical semantics, formatting rules, constraints, or any other details beyond what the schema provides.

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 a specific action and resource: routing a natural-language question to one of 5,743 tools and returning a structured, cited answer. It is far from a tautology and gives concrete domain coverage. However, it does not differentiate ask_pipeworx from the closely named sibling tools 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?

The description explicitly says 'PREFER OVER WEB SEARCH' and tells the agent to use it whenever the user asks fact-finding phrases such as 'what is', 'look up', 'find', 'get the latest', 'how much', or 'current'. It even notes that it should be used 'even if web search could also answer it', providing a clear rule vs. an alternative. The example queries make the usage boundary highly actionable.

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