itunes_get_stats

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It does not specify whether the operation is read-only, what constitutes 'hours' (listening time or track total duration), how favorites are counted, or whether it excludes non-music items (like movies or podcasts). This is a read-only analytic tool, but the lack of safety/behavioral detail is a gap.

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 concise and front-loaded, stating the core purpose first. It is a single sentence with no wasted words, but it could be broken into a lead sentence with a brief open/close note for clarity.

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?

Given the tool has simple output (a summary) and zero parameters, the description is largely complete. However, it does not clarify whether the stats are library-wide or device-specific, nor what exact metrics are included beyond the examples. The sibling tool itunes_get_listening_stats_by_date exists, so clarifying scope would help. Overall, adequate for a 0-param tool.

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 tool has 0 parameters, so there is no parameter semantics to explain. This is a baseline 4 for parameter-less tools, as there is nothing to add 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 clearly states the tool generates an analytics summary of the Music library and enumerates the key metric categories (tracks, playlists, favorites, hours). It is specific enough to distinguish it from sibling tools like itunes_get_listening_stats_by_date or itunes_get_listening_history, which focus on usage data rather than library-wide stats.

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 implies the tool is used for library-level analytics but does not explicitly state when to prefer this over similar tools (e.g., itunes_get_listening_stats_by_date). Since it takes no parameters, the context is clear, but there is no guidance on when to use it versus alternatives.

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