Browse the catalog

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

With no annotations, the description carries behavioral burden. It adds the auth requirement (paid tier, 403) and the mandatory-filter constraint. However, it omits details like default sorting (schema has 'randomize' but description doesn't explain default order), pagination, or response structure. It doesn't contradict but leaves gaps.

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 short sentences, each essential. First sentence lists filters and constraint; second sentence states authorization requirement. No wasted words, front-loads the action and key conditions.

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 6 parameters, no output schema, and no annotations, the description covers the input constraints and authorization well but lacks details on output format, pagination, default ordering (randomize is implied but not default), and any limits. It provides sufficient high-level understanding but not full operational completeness.

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?

Description covers 5 of 6 parameters (all except randomize) and adds meaning beyond schema: 'genre ID (from list_genres)' implies a valid source. Also adds the constraint that at least one filter is required, which is not in the schema's optional parameters. This compensates for the 50% schema coverage.

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 uses 'Discover tracks by filter' as a specific verb+resource. It lists concrete filter fields (label ID, artist ID, genre name, genre ID, release year) and includes critical usage constraints ('At least one filter is required'). This clearly distinguishes it from sibling tools like search_tracks, which presumably do text-based 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?

Explicitly states the requirement of at least one filter, guiding when to use. Also notes the paid-tier prerequisite and potential 403 for free keys, which is a clear when-to-use/not-use boundary. Does not explicitly name alternative tools, but the required-filter constraint implies it's for filtered browsing, not free-form search.

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