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

Annotations already declare readOnlyHint and idempotentHint, but the description goes well beyond them: it discloses pagination behavior (25 Riddles per page, hasMore indicator), the error-not-silent policy for unviewable project IDs, the project-key failure mode, and that sortBy spans the whole account/project set rather than the current page. These behavioral details materially affect how the agent calls and interprets the tool.

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, well-front-loaded paragraph where every sentence earns its place; the core purpose and pagination are near the front, with the sibling routing and auth note at the end. It could still be slightly tightened, but there is no wasted or redundant content.

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?

Since there is no output schema, the description takes responsibility for the return shape and does so thoroughly: per-Riddle metrics, totals, sorting, 25-per-page slicing, and the hasMore flag. Combined with auth requirements, error behavior, and the overall summary-vs-breakdown intent, an agent has everything needed to call this tool correctly.

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% and each of the five parameters carries a clear description, default, and format in the schema itself. The tool description adds only lightweight context like 'narrow the scope with projectIds' and restates sortBy ranking semantics, which maps naturally to the baseline 3 for high-coverage schemas.

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 begins with a concrete, scoped result: 'Returns an account-wide stats summary for the authenticated user,' then enumerates the exact content (one row per Riddle with views, starts, submissions, active time, plus totals). It explicitly contrasts itself with stats_riddle_breakdown and stats_project_breakdown, so an agent can immediately tell which sibling is which.

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 gives routing guidance, not just a purpose: 'for a Riddle's blocks, choices and form fields call stats_riddle_breakdown... and for one project's full breakdown call stats_project_breakdown.' It also adds a when-to-scope hint ('On accounts with many projects, narrow the scope with projectIds') and a hard precondition ('Requires a user API key — will fail with project API keys').

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