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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes well beyond them with pricing, the daily free allowance, refund behavior for failed or cancelled reads, the midnight-UTC quota window, caption granularity limits, and the idempotency key tuple. The one material gap is concurrency/unknown-outcome handling beyond naming the 'outcome_unknown' error, and it never says whether a refunded retry re-bills. Strong content, but a notch below exhaustive for a paid, quota-limited operation.

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 decision-critical fact (cost and the confirm_cents gate) before the mechanics, then a compact Returns/Errors block. Information density is high, though the confirm_cents semantics appear twice (prose and Args) and the caption line about word sync is tangential to invocation.

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 carries the full return contract: the {ok, job_id, status, poll_after_s, cents} shape, the next step in the polling chain, the no-job short-circuit, and named error variants. For a paid asynchronous tool with four parameters, nothing an agent needs to call it correctly 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 coverage is 75%, and the description adds meaning that the schema lacks: 'lyrics ... to align instead of listening for words' explains the behavioral effect of that parameter, and the idempotency key scope is spelled out as (this token, this tool, idempotency_key). The confirm_cents and song_id explanations largely restate schema text, which caps this slightly below the top.

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 plus the actual work performed: 'Listens to the song for its beats, sections and lyrics'. It also distinguishes itself from the downstream retrieval path (wait_for_job, then song_get) and notes the short-circuit when 'analysis_ready' is true, so an agent can tell it apart from song_get 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 when-to-use conditions and alternatives: use the lyrics argument to align pasted text 'instead of listening for words'; a repeat of the same song is free; a paid song with confirm_cents 0 answers price_changed; an already-read song returns next_tool 'song_get' with no job to poll. It also names the prerequisite source for song_id (song_from_library).

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