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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context: it routes questions across 5,738 tools, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. No contradiction with annotations is present.

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 key preference and domain list, making the core purpose immediately clear. It is somewhat dense and contains minor redundancy around web search preference, but the examples and skip guidance earn their place given the tool's broad scope.

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?

Despite having no output schema, the description compensates by stating that the result is a structured answer with stable citation URIs. It covers main use cases, examples, parameter intent, and exclusions, though it does not explicitly differentiate ask_pipeworx_beta or ask_pipeworx_grounded.

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 documents the 'question' parameter and aliases with 100% coverage. The description adds value by clarifying the expected input is a natural-language factual query and providing multiple concrete examples of valid questions, which goes beyond the schema's brief examples.

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 the tool as a preferred router for factual and current/historical data questions, listing specific domains and examples. It distinguishes itself from web search and points to alternatives like deep_research, so its role among siblings is clear.

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 factual questions, and provides trigger phrases and examples. It also gives when-not-to-use direction by mentioning multi-step workflows and directing broad/multi-part questions to deep_research.

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