get_me_stats_year_by_year

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. However, the description adds no behavioral context beyond the endpoint and parameter list. It does not mention what the response contains, any authentication requirements beyond implicit 'me', or how invalid years are handled. Given the annotations lower the bar, the description still offers minimal added value.

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 extremely brief, which could be seen as concise, but it is under-specification rather than effective conciseness. The endpoint and argument are front-loaded, but the content is far too sparse to be useful. Every word is necessary, but essential information is missing, so this does not merit a higher score.

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?

Even with an output schema available, the description fails to explain the tool's purpose, the meaning of 'year-by-year stats', or how to interpret results. There is no mention of the data source (user listening history?), the kind of statistics returned, or any caveats. For a tool with a single parameter and an output schema, the description should at least clarify the scope and semantics, but it does not.

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 0%, so the description is the only source of parameter meaning. It merely repeats 'year: Path parameter', which is already obvious from the schema and the URL pattern. It does not explain acceptable formats (e.g., 'YYYY'), whether it must be a past year, or how the path parameter maps to the returned data. This is a critical gap given the tool has only one parameter.

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 'Get stats year' is nearly a tautology of the tool name, providing no specificity about what 'stats' refers to (listening stats? server stats?), whose stats (the current user, as implied by 'me' in the name, but not stated), or what 'year by year' means. The endpoint URL reinforces the year parameter but adds no semantic clarity. It fails to distinguish this from many sibling stats tools like get_me_listening_stats or get_stats_server.

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 guidance on when to use this tool versus alternatives. It does not mention that this is for the authenticated user's own stats, nor does it compare with other stats endpoints. No exclusions or alternative conditions are provided, leaving an agent without context for selection.

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