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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds valuable context beyond that: it explains the beta nature, that routing behavior may change whenever a candidate is under test, and that currently it matches the stable router. This is a meaningful disclosure of volatility that annotations cannot capture.

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 four sentences and front-loaded with the core information: the beta relationship to ask_pipeworx and its identical behavior. Each sentence contributes distinct value—purpose, current state, usage instruction, and a reassurance that it is fully functional. While slightly verbose, nothing is redundant.

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 tool with one required parameter and no output schema, the description is sufficient. It covers the tool's role, its relationship to the stable version, when to use it, and that the response shape matches ask_pipeworx. This is complete given the complexity and the existing annotations.

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% — all six parameters are documented in the schema, including aliases and the required 'question' field. The description adds no additional parameter information, but the schema already fully explains them, so a baseline of 3 is appropriate. No extra semantics are needed.

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 explicitly identifies the tool as a beta version of ask_pipeworx, a universal router with 5,724 tools, and distinguishes it from its stable sibling. It is not a tautology; it adds the beta context and clearly states the resource and action (ask a router). The specificity allows an agent to differentiate it from ask_pipeworx and ask_pipeworx_grounded without deeper inspection.

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 provides a clear condition: use it exactly like ask_pipeworx when you want the newest routing. This implies the alternative (use ask_pipeworx for stable) and clarifies that this tool is fully functional, not a placeholder. Exclusions are not explicit but are strongly implied by the 'beta' label and the comparison against the stable router.

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