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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, and the description adds behavior beyond that: it returns category-bucketed examples 'drawn from the live catalog of thousands of tools' and notes that each example includes the exact tool + argument shape. This immediately communicates the tool's open-world, advisory nature without contradicting the annotations.

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 every sentence carries meaningful information: entry-point purpose, example queries, return structure, parameter options, and explicit first-use guidance. It is front-loaded with example user questions, making the tool's intent instantly recognizable, and remains dense without redundancy.

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?

Given the tool's open-ended onboarding role and lack of an output schema, the description is fully complete: it explains what output to expect (category-bucketed examples with tool+argument shape), how to adjust scope (topic vs. no args), and when to use it (first contact, meta-tool learning). No critical use-case 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?

Schema description coverage is 100%, and the schema already explains `topic` as an optional focus area with a list of values and the omit-for-spread behavior. The description's mention of 'e.g. finance, pharma, betting' adds small illustrative value but does not fundamentally extend the schema semantics; the description and schema essentially say the same thing.

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 identifies the tool as the onboarding entry point for a newly connected agent, with specific verbs ('Returns category-bucketed example questions') and resource ('example questions... with the exact tool + argument shape'). It distinguishes itself from siblings by stating 'Use this FIRST' and by focusing on the discovery of what Pipeworx can do, rather than executing a specific query.

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 says when to use it: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also provides usage variants: 'Call with no arguments for the full spread, or pass `topic`... to focus'. It names alternative meta-tools (ask_pipeworx, entity_profile, compare_entities), giving clear guidance on this tool's role.

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