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

While annotations already declare readOnlyHint true and idempotentHint true, the description adds rich behavioral context that annotations can't convey: the full return shape {count, categories: {...}}, the explicit exclusion ("without the build configuration"), the grouping-by-category mechanism, and the conditional behavior when called with no arguments. This discloses what the agent should expect from the response beyond what structured annotations could possibly capture.

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?

Dense with information but poorly structured — it's a single run-on sentence for the first half, followed by a wall of text with no paragraph breaks. Every sentence earns its place, but the lack of any structural swallowing (the parenthetical return type without examples or whitespace) hurts scannability. A list of usage scenarios or sentence breaks would turn this into a 5.

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 tool with no output schema, the description fully compensates by embedding the response structure inline, covering the no-argument call path, single-and-double-filter scenarios, the follow-up tools (riddleTemplate_get and riddleTemplate_use), and what's excluded (build config). For a read-only list endpoint with 2 optional params, this is complete — nothing material is left undisclosed.

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% with already-excellent field descriptions (including the type enum list and snake_case slug guidance for category), so baseline is 3. The description adds marginal value by framing the concept of grouping ("the tag the Creator sorts them by") and how omitting category reveals available categories. Slightly redundant with the schema but reinforces the interplay between the two params; not quite the baseline-3 floor, hence a 4.

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?

Opens with a specific verb+resource construction ("Lists Riddle's public templates") and immediately clarifies scope ("ready-made ones available to every account"). Explicitly names and contrasts the sibling riddleTemplate_list, making the differentiation crystal clear. The distinction between public templates and project-made ones leaves zero ambiguity about what this tool does.

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?

Goes beyond stating what it does to explain when: it distinguishes from riddleTemplate_list (the alternative), explains the no-arguments call as the way to discover categories, and provides a follow-up workflow ("hand the id straight to riddleTemplate_use"). Explicit when/why guidance is present throughout.

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