itunes_get_track_metadata

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

There are no annotations, so the description must fully disclose behavior. 'Inspect' implies a read-only operation but does not explicitly state non-mutating behavior or mention potential errors (e.g., if no track is playing). It does explain the default behavior when 'song' is empty, which is useful, but fails to note prerequisites or edge cases.

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 two sentences: a purpose sentence stating what metadata is inspected, and an Args sentence for the parameter. Both are concise, front-loaded, and free of fluff, making it easy to parse quickly.

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's simplicity (one optional parameter, no output schema), the description is fairly complete. It lists the main metadata fields and explains the parameter behavior, but could be more thorough by enumerating all returned fields or clarifying the return value format. Still, for a straightforward inspection tool, it meets the minimum bar.

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 schema description coverage is 0%, so the description must explain the param. It does so effectively: 'song: Optional track title. If empty, inspects currently playing track.' This adds meaning beyond the schema, clarifying the parameter's purpose and default behavior.

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 starts with a specific verb 'Inspect' and a clear resource 'metadata for a track', listing exact fields like genre, composer, comment, track/disc numbers, compilation, date added, unplayed. This distinguishes it from siblings like itunes_get_track_audio_info or itunes_get_lyrics, making the purpose unambiguous.

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 provides clear context on how to use the tool, including the optional 'song' parameter and the fallback to the currently playing track when empty. It does not explicitly mention when not to use this tool or contrast with alternatives, but the listed fields imply its scope, which is sufficient for a read-only metadata tool.

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