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

Even though annotations already declare readOnlyHint/idempotentHint/openWorldHint, the description substantially exceeds them: it discloses account and plan requirements, latency ranges, parallel decomposition behavior, the findings-packet shape (verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[]), semantic excerpting rather than head-truncation, and the guarantee that citations are fetchable. It also warns about likely empty results for non-catalog topics. This is far more than the annotations alone provide.

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 long but information-dense, and nearly every sentence adds a distinct fact an agent needs for correct invocation: auth, alternatives, latency, return format, citation semantics, depth behavior, and limitations. It is front-loaded with the most decision-critical constraint (account required/no sign-in fallback) before explaining what the tool does. Slight structural improvement would come from line breaks or bullet separation, but the content earns its length.

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 is unusually complete: it covers authentication requirements, cost/plan implications, expected latency by depth, when results will be empty, what the findings packet contains, how citation URIs behave, how large records are handled, and the contradiction/gap semantics. An agent has enough information to set expectations, choose depth, and decide between this tool and its closest sibling without needing to open the schema.

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 coverage is 100%, so the input schema already fully documents the 'question' and 'depth' parameters. The description adds useful context around depth behavior ('standard re-angles unanswered gaps', 'thorough chases best leads') and the paid requirement for thorough, but most parameter meaning is already present in the schema. Baseline 3 is appropriate because the description reinforces rather than compensates for structured documentation.

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 uses a specific verb phrase ('grounded multi-source research') tied to a concrete resource (Pipeworx's structured data sources and 5,743 internal tools) and clearly distinguishes itself from open-web search and from ask_pipeworx. It also gives concrete example questions, making the scope immediately recognizable to an agent.

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 explicitly names when to use deep_research (broad/multi-part structured-data questions) and when not to: single lookups and breaking/colloquial current-news topics should go to ask_pipeworx. It also provides an account-tier conditional ('if you are not signed in, use ask_pipeworx instead') and depth-level guidance, leaving little room for mis-selection among the many siblings.

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