genre_trends_over_time

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

With no annotations, the description carries the full burden and does disclose the read-only nature and the derivation approach (per-period top genres via artist tags, deltas, emerging/declining tags). However, it omits caveats such as sparse-history behavior, data freshness, or how genre tags are aggregated, which would be useful for a report 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?

Two compact sentences with the core purpose front-loaded and the read-only caveat appended. The opening 'How your taste shifts' is slightly colloquial but not wasteful; every clause earns its place.

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?

The schema documents all four optional parameters with defaults and enums, and the description covers the read-only safety profile and output concepts. What is missing is usage context — which scenario calls for this tool over the genre/taste-report siblings — and any indication of the detailed/json response shapes, since no output schema exists.

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% — period, lookback, max_results, and response_format all have descriptions and enums/defaults. The description aligns conceptually ('per-period' maps to period, 'deltas' maps to output) but adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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 purpose: analyzing how taste shifts over time via per-period top genres, deltas, and emerging/declining tags. It names the data source (artist genres/tags) and output concepts, making it reasonably distinct from similar analytics siblings like top_genre_census or taste_shift_report, though it never explicitly names them.

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?

No guidance is given on when to use this tool versus the many overlapping genre/taste analytics siblings (taste_shift_report, top_genre_census, era_preference_report). There are no when-to-use, when-not-to-use, or alternative-routing statements, leaving tool selection to inference.

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