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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered; the description adds real context by saying the payload is varied, range-bearing advice from a curated corpus rather than generated music, and that it should be used once at song start. What it does not disclose is the shape or volume of the returned advice (no output schema backs it up).

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 trigger condition and densely packed, with no filler about the tool's importance. The trailing 'Schema 3b8fe45c' duplicates the schema's own description field and earns no place in the prompt.

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 6-parameter, nested-object research tool with no output schema, the description covers trigger, exclusions, stage coverage, provenance, and next step. Remaining gaps are the return shape and the meaning of the less obvious inputs (seed, limit, facets), and the stage list it does give is one enum value short.

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 67%, and the description reinforces the stage dimension by naming 'plan, harmony, melody, layers, mix' – but it omits 'review', which the enum does allow, so the enumeration is incomplete rather than additive. It adds no meaning for 'seed', 'limit', or 'facets' beyond what the schema already says, so this sits at the baseline for a well-covered schema.

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 ('research composition advice ... from a curated corpus') and immediately scopes it ('starting a real song (sections, a story, over ~20 s)'). It also contrasts with the adjacent capability: 'No AI composes music here' and 'not for simple sounds', which separates it from the generative 'song' and 'sfx' siblings without needing their schemas.

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 ('when starting a real song'), explicit when-not ('not for simple sounds'), a call-frequency rule ('once'), and a downstream sequencing step ('Then song(plan)'). An agent knows both whether to call this and what to do with the result.

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