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

The description discloses the experimental behavior ('candidate routing improvements enabled live') and the current state (no active candidate, so it matches ask_pipeworx exactly), which is beyond what the annotations provide. It also clarifies the fallback semantics: 'Falls back to nothing — this IS a full working router, just the experimental edge.' The annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description aligns with these without contradiction.

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 three sentences and front-loads the beta identification and current status, making it easy to scan. It contains some redundancy (e.g., 'identical router' and 'full working router' communicate the same idea), but every sentence contributes to understanding the tool's experimental nature and usage. It is appropriately sized but could be slightly tighter.

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?

The description covers the key contextual points: current state (no active candidate), usage guidance, and relationship to the stable router, including the response shape via 'same response shape.' Since there is no output schema, the pointer to ask_pipeworx is sufficient for an agent familiar with that sibling. It does not need to restate the schema, and no critical invocation information is missing.

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 documents all six parameters with 100% coverage, including aliases and a full description of the question parameter, so the baseline is 3. The description only adds 'same arguments' pointing to ask_pipeworx, offering no per-parameter meaning beyond what the schema already states. It neither improves nor harms parameter understanding.

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 states that ask_pipeworx_beta is a beta version of ask_pipeworx, a universal router with identical tool access and response shape, differing only by experimental candidate routing improvements. It explicitly distinguishes itself from its stable sibling ask_pipeworx and frames its purpose as the experimental edge. The specificity (5,798 tools, same arguments, same response shape) leaves no ambiguity about the tool's role.

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 a clear usage condition: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' This tells an agent when to select it relative to the stable alternative. However, it does not explicitly state when not to use it (e.g., for production stability) or mention other sibling alternatives like ask_pipeworx_grounded, so it falls short of a full 5.

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