saved_albums_by_year

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

With no annotations at all, the description carries the full disclosure burden, and 'Read-only' is a meaningful safety declaration that this tool performs no mutations. Beyond that, however, it does not disclose how the histogram is shaped in return, how albums without a release year are handled, or that the tool walks the full saved-album library subject to scan_cap. These are material behaviors for an aggregation tool, so 3 is appropriate.

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?

Two sentences totaling nine words, with the purpose front-loaded and the read-only qualifier appended. Every word earns its place and nothing is redundant or padded; this is an appropriately sized description for a tool whose parameters are already fully documented in the schema.

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 simple aggregation tool with three fully documented optional parameters and no output schema, the description conveys the core purpose and the non-destructive nature. The clear gaps are the lack of differentiation from saved_albums_by_decade and the absence of edge-case behavior such as albums missing a release year or partial scans under scan_cap, making it minimally viable rather than 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?

Schema description coverage is 100%, so the schema already documents all three parameters (scan_cap, max_results, response_format) and the baseline is 3. The description adds only marginal context by identifying 'your saved albums' as the data source, which lightly ties scan_cap to the saved-library walk, but it adds no new meaning 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 a specific operation — produce a histogram of saved albums grouped by release year — naming both the resource (saved albums) and the grouping key. However, it does not explicitly distinguish itself from the closely related sibling saved_albums_by_decade, which buckets the same data at a coarser granularity; the name, not the description, carries that differentiation.

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?

There is no when-to-use guidance, no prerequisites, and no mention of the natural alternatives (saved_albums_by_decade, saved_albums_by_label, saved_albums_by_type) for other grouping needs. The 'Read-only' sentence conveys safety, not selection criteria, so an agent is left to infer when this tool is the right choice among roughly a dozen saved-album analysis siblings.

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