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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds value beyond that by disclosing the return shape: category-bucketed example questions with the exact tool and argument shape for each, drawn from the live catalog of thousands of tools. This is useful behavioral context not present in 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 a single dense paragraph, but every clause contributes: example questions, categories, return details, argument usage, and onboarding use-case. It is not as crisp as a two-sentence example (e.g., TDQS 4.3), but it is well-structured and front-loaded with the core question phrases. No redundancy; the schema and description complement without duplication.

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?

With no output schema, the description fully carries the burden of explaining return values, and it does: 'Returns category-bucketed example questions... each with the exact tool + argument shape.' It also covers argument behaviors, the onboarding context, and how to learn about meta-tools. For a zero-required-parameter tool with rich scope, this is complete.

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 covers the single 'topic' parameter at 100% with a description enumerating allowed focus areas. The description adds only slight reinforcement by giving examples ('finance', 'pharma', 'betting') and stating 'Omit for a cross-category spread,' which aligns with the schema. This is baseline for high schema coverage; the description does not introduce new parameter semantics beyond the schema.

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 the tool's substantive purpose with a specific verb and resource: it is the onboarding entry point to discover what can be asked of Pipeworx, returning category-bucketed example questions. It clearly distinguishes itself from potential siblings like discover_tools by framing itself as the meta-level 'what can I ask' entry point and explicitly mentioning the meta-tools (ask_pipeworx, entity_profile, compare_entities) it can teach.

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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This is a clear when-to-use directive. It also explains that omitting the topic gives the full spread and passing a topic focuses the results, providing actionable usage guidance. No exclusions are given, but the guiding context is strong.

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