Get a dashboard widget

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

No annotations are provided, so the description carries the burden. It discloses that results are 'pre-computed' and each kind's semantic meaning (e.g., reading-rhythm is a 14-day series), which gives insight into behavior. However, it does not explicitly state that this is a read-only, side-effect-free operation, though 'Get' and 'pre-computed' strongly imply it.

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 well-structured with a front-loaded purpose statement followed by a clear bulleted list of categories. Every sentence adds value—no filler—and the length is justified given the need to explain 11 distinct kinds. It remains highly scannable.

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 adequately explains what to expect (a headline card) and covers all possible kinds. It also provides a cross-reference to a sibling tool for the 'currently reading' case, making the tool's context within the broader API clear. For a single-parameter getter, 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 description significantly enriches the sole parameter 'kind' beyond the schema's minimal 'Which dashboard widget to fetch.' It groups the enum values into meaningful categories (Goals & momentum, Reading profile, etc.) and explains what each kind represents (e.g., 'neglected-gems (highly-rated but unread)'), giving agents deep semantic understanding.

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 states it 'Get[s] one pre-computed dashboard headline card' and distinguishes it as the compact sibling of the richer get_reading_statistic charts. It also enumerates the specific kinds, making the tool's purpose unambiguous and differentiated from sibling tools.

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?

Explicit usage guidance is provided: it positions this tool as the 'compact, at-a-glance sibling' of get_reading_statistic, implying use for quick overviews versus richer charts. It also gives a direct alternative: 'For the currently reading card use list_currently_reading.' This clearly tells when to use this tool vs. alternatives.

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