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

The main body adds substantial behavioral context beyond the annotations: auth/paid tiers, parallel tool routing, output packet fields, gaps[], contradictions[], citation URIs, semantic excerpting, and latency. However, the later 'This tool is dangerous: ... NOT sandboxed and has NO GUARANTEED OUTPUT FORMATTING. Use with caution. If you don't know what this is, do not call it' directly contradicts the earlier documented findings packet and undermines the readOnly/openWorld/idempotent annotations. This makes the overall description misleading despite its useful core.

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 dense and front-loads the account requirement, then explains the core behavior and output structure efficiently. However, the final paragraph is redundant, contradictory, and discourages invocation, adding noise without value. It is longer than necessary and contains an internal inconsistency.

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 complex tool with no output schema, the description covers return fields, auth, depth semantics, latency, and gap handling quite well. But the contradictory 'dangerous / NOT sandboxed / no guaranteed output formatting' passage means an agent cannot fully trust the specification, leaving a serious completeness gap.

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 both parameters and provides a detailed description of the depth enum, including hops, gap recovery, contradictions scan, and paid tier. The description repeats much of this and adds the account/sign-in requirement, but it does not add substantial new parameter-level meaning beyond what the schema already covers.

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 defines a grounded multi-source research tool over Pipeworx's structured data sources, explaining facet decomposition, parallel routing, and the findings packet. It distinguishes itself from open-web search and ask_pipeworx. However, the appended 'dangerous / retrieve live internet data / no guaranteed output formatting' sentence muddles that purpose and contradicts the earlier definition, preventing a 5.

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 is explicit about when to use this tool vs alternatives: use ask_pipeworx when not signed in or for a single lookup; use deep_research for broad, multi-part questions over structured data. It also states the paid-plan requirement for 'thorough' depth, leaving no ambiguity about invocation conditions.

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