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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context beyond them: empty mood searches are not evidence of absence, mood matches may be owner-set rather than analysed and must be labelled, and only recordings of works listed by the owner or a confirmed writer are returned. These are non-obvious result-semantics caveats an agent could not infer from the schema.

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?

Front-loads the trigger examples and the primary exclusion before caveats, and every sentence carries operational information. It is dense and slightly long, and the enumerated user-quote examples could be trimmed, but nothing is 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?

For a 20-parameter, zero-required tool with no output schema, the description covers coverage limits, mood caveats, and the follow-up tool, which is the important missing context. It stops short of describing result shape or pagination behaviour beyond the limit parameter, which is a minor gap.

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 coverage is 100% and the schema already documents filter semantics in depth (including ignored filters and mood_note behaviour), so the description's parameter content is largely duplicative. It adds the useful framing that measured filters match analysed audio only, but it also advertises 'danceability' as a searchable facet even though the schema marks that parameter as ignored — a minor internal inconsistency. Baseline 3.

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 and resource ('AUDIO-FEATURE search' of recordings by BPM, key, energy, duration, mood) and explicitly distinguishes itself from name/title searches by naming directory_lookup_work, directory_lookup_isrc, and directory_list_people. An agent can route without opening any schema.

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 concrete user phrasings that trigger the tool, an explicit exclusion rule for title-shaped queries, an exclusion for theme/subject queries routed to directory_list_works, and a named next step (directory_lookup_work). When-to-use, when-not-to-use, and alternatives are all present.

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