Search tracks

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and external-network behavior are covered. The description adds genuinely useful downstream context (output is URIs destined for edit_draft add_track), but says nothing about result ordering, return shape beyond URIs, pagination, or provider auth requirements.

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?

Three tight sentences, front-loaded with what the tool does, then the fallback condition, then the filter example and the return contract. No filler.

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?

With no output schema, the description correctly states what comes back (URIs) and where they go. For a 3-parameter, no-auth-documented search tool this is nearly sufficient; only the limit parameter and provider-connection prerequisites remain unaddressed.

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 only 33% — provider carries a description while query and limit are bare. The description compensates by showing the filter syntax ('track:Marea artist:Fred again'), which is real value beyond the schema, but it never explains the limit cap of 10 or clarifies that query accepts free text versus filter operators.

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?

States a specific verb (search) and resource (track) and names the concrete consumer of the result ('Returns URIs for edit_draft add_track'). It also distinguishes its two providers and the condition selecting the Deezer fallback, so an agent can tell this apart from other tools in the lineup/draft family.

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?

Gives clear context: use it to find a track to add manually, use Deezer when working a Deezer draft or when Spotify is not connected, and the schema note 'Match the draft you will add to' reinforces the routing. There is no explicit exclusion against sibling tools such as parse_lineup or expand_playlist for bulk discovery, so it stops short of a full when/when-not rule.

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