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

Annotations already cover the safety profile (readOnly, openWorld, idempotent, non-destructive), and the description adds genuinely non-obvious behavior: routing breadth, stable pipeworx:// citation URIs in the response, and the fallback semantics when pack slugs are unknown ('never an empty answer', _meta.pack_scope reported back). It does not discuss latency, rate limits, or result-quality caveats beyond the unverified 'one fast call' claim, which is marketing rather than disclosure.

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 routing purpose and the escalation alternatives are correctly front-loaded, but the text is padded with promotional fragments — 'PREFER OVER WEB SEARCH', 'works on every tier, one fast call', 'START HERE' — and the long enumeration of data domains partly duplicates the example questions and the pack-slug note already in the schema. Every sentence is on-topic; not every sentence 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?

For a 9-parameter, no-output-schema, open-world routing tool, the description is nearly sufficient: it explains what routing does, what comes back (structured answer + citation URIs), and what happens with bad pack input. The remaining gap is response shape detail — there is no output schema, so fields like _meta.pack_scope are only encountered, never described.

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%, so the baseline is 3 and the aliases, `packs` slug rules, and ignored-slug behavior are already documented in the schema. The description contributes only the intent framing ('answer this using THESE packs') and the instruction to omit `packs` for full-catalog routing, which is largely restatement.

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 states a specific action (route a natural-language question to one of 7,174 tools across 1863 sources and return a cited structured answer), and explicitly separates itself from siblings ask_pipeworx_grounded ('hallucination-resistant single answer with verbatim evidence + confidence') and deep_research ('broad/multi-part question that should fan out'). An agent can pick this tool without opening any schema.

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?

Gives an explicit preferred-over-web-search rule, lists the query phrasings that should trigger it ('what is', 'look up', 'how much', 'current'), names concrete example questions, and states a default-entry-point posture ('START HERE for most questions'). It also names the two escalation alternatives and the exact conditions that select them, plus covers the breaking-news case that would otherwise be ambiguous.

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