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

Annotations cover read-only safety, but the description adds rich disclosure: verdict taxonomy (registered, partial, nobody, conflict, unknown), dated evidence with as_of and bulk-data provenance, ambiguity flag, confidence levels, and the cost warning that full_record is many times larger. This is substantially beyond what annotations provide.

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 information-dense but long and somewhat run-on, packing many clauses into single sentences. It is front-loaded with the core action, but the sentence covering verdicts and evidence is complex and could be broken up. Every sentence does earn its place, but readability suffers.

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?

Despite high schema coverage and an output schema, the description adds necessary context about verdict semantics, evidence dating, ambiguity handling, and the size trade-off of full_record – all of which an agent needs to interpret results correctly. The combination of high-coverage schema, output schema, and this explanatory text makes the definition complete for a complex lookup.

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%, so baseline is 3. The description adds value by stating the four alternative input modes and 'exactly one of', clarifying mutual exclusivity that the schema does not enforce. It also explains the meaning of verdicts and confidence, though it doesn't exhaustively cover each parameter's syntax beyond what the schema already provides.

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 (ISRC lookup and royalties registration check for one recording) and names what it returns: MLC works, verdicts, MusicBrainz data. Distinguishes itself from siblings like check_catalogue and request_full_report by scoping to a single recording's rights data.

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 input rules: 'Give exactly one of: an ISRC, a Spotify track link, a song title (optionally with the artist), or a YouTube link.' Also advises when to use full_record and notes YouTube matches are low confidence. Lacks explicit when-not-to-use relative to check_catalogue or request_full_report.

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