itunes_search

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

With no annotations, the description carries the burden of behavioral disclosure. It does disclose that the tool returns a list formatted as "Track Name - Artist", which is helpful. It does not mention whether the search is read-only, case-sensitive, limited/paginated, or how it behaves when no tracks match, but the search action is reasonably inferable.

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 and wastes no words. It states the purpose in the first sentence and the output format in the second, 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?

This is a simple one-parameter search tool with no output schema, and the description provides both the search semantics and the output format, which is sufficient for most usage. It could be more complete with guidance about no-match behavior or the relationship to catalog search, but for the tool's low complexity this is adequate.

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%, and the schema only names the query field. The description compensates by explaining that the query is matched against track names via containment, which adds meaningful semantics beyond the bare input schema. It could give an example or formatting details, but the single-parameter case is well covered.

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 specifies a search over the Music library for tracks whose names match a query, and it specifies the return format as "Track Name - Artist". This distinguishes it from sibling tools like itunes_search_catalog by indicating a local-library search rather than a catalog search.

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 when to use the tool: to find tracks in the Music Library by name. However, it does not explicitly rule out or compare against alternatives such as itunes_search_catalog or other browse-by-chart tools, so the usage guidance is implied rather than explicit.

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