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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds the crucial cost behavior (no credit charged), the retry contract tying requestId to idempotency, and the fact that it surfaces language, sound, duration and one-song cost before commitment. With no output schema, disclosing what the preview returns is genuinely valuable. It stops short of saying whether any server-side state is created by the preparation step.

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?

Four sentences, front-loaded with the no-cost hook, then the preview contents, then the retry rule, then scope limits. The 11-language enumeration is somewhat redundant with the schema enum but adds human-readable confirmation; otherwise there is little waste.

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 tool with a nested 8-field input, 0% schema coverage and no output schema, the description covers the value proposition, cost model and language support but omits the idea-vs-lyrics mode distinction that determines how the whole request is interpreted. Adequate orientation, but an agent could still mis-shape the input.

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 0%, so the description must carry the burden, and it only covers requestId (idempotent retry semantics) and partially language/duration. The nested input's core fields — mode ('idea' vs 'lyrics'), idea, lyrics, direction, instrumental, title — plus uiLocale are never explained, leaving the most decision-relevant parameter (mode) undocumented.

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 ('prepare a song') and immediately qualifies it with 'without spending a credit' plus 'before starting', which distinguishes this preflight step from actually launching generation (the job start_song implies). It also rules out two adjacent capabilities (voice cloning, audio editing). It never names start_song as the follow-up, so the sibling routing is implied rather than stated.

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 operational guidance: call this before starting, and reuse the same requestId when retrying this exact request. Exclusions are stated ('does not clone voices or edit existing audio'). What's missing is an explicit pointer to the tool to call after this preview succeeds.

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