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

Annotations only cover readOnlyHint and openWorldHint; the description adds substantial behavior beyond them: cost model ('same 1 quota unit, charged only on a served result'), no audio upload/no extra compute, and a full taxonomy of tag confidence/provenance semantics (measured vs derived vs model-estimated vs catalog-genre) plus which sources are reached per identifier type (7.5M+ AcousticBrainz recordings only when MBID/ISRC is supplied). This is well beyond annotation coverage.

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-loaded with the core purpose, then structured into the confidence/provenance bullets and identifier guidance, so the important material comes first. It is dense and leans on ALL-CAPS emphasis and a long single flowing paragraph in places, which costs a little readability, but nearly every sentence carries information an agent needs.

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 read-only, output-schema-backed lookup tool, the description covers the gaps that matter: cost/quota, confidence semantics, identifier precedence, ambiguous-spotify_id failure mode, and coverage limits of each identifier path. Nothing an agent needs in order to call it correctly and interpret the labels is missing.

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 100%, so the baseline is 3. The description consolidates the resolution precedence chain and the 'send them all, we ignore the rest' behavior in one place, and flags that `artist` is only meaningful with `track`. This adds usable invocation guidance, though much of the precedence detail is already duplicated in the schema descriptions, keeping it short of a 5.

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 ('Get a compact, honestly-labelled tag list for a track') and enumerates exactly which tags come back (energy/danceability/valence/acousticness/instrumentalness + mood + genre). It explicitly positions itself against siblings: 'It is a tag-shaped projection of the same open-data analysis get_audio_features returns' and names get_audio_features and a discovery tool as the alternatives. An agent can distinguish it from get_audio_features without opening either 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 explicit routing: 'For the full numeric feature set use get_audio_features; for nearest tracks use a discovery tool.' It also spells out the identifier strategy with precedence (track > isrc > track_id > mbid > spotify_id) and tells the agent to send several rather than choose. Both when-to-use and when-to-use-something-else are covered.

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