Generate a music bed

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

Annotations only declare write/destructive/openWorld, but the description discloses the credit spend magnitude (~$0.06 engine cost, billed with plan margin), the budgetUsd cap semantics (default 2, max 10), the chargedUsd feedback field, and the required write scope. That is exactly the operational context an agent needs before committing to an irreversible spend.

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 purpose, then integration, then cost/scope in a compact three-sentence block with no filler. The first sentence is densely packed with parentheticals, but every clause carries signal.

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 an output schema present, the description needn't explain returns, yet it still names the key artifacts (media key, beat grid, chargedUsd) and covers cost, budget, and auth scope. For a paid, mutating, world-generating media tool, nothing material 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% and the schema already spells out budgetUsd's default/max, allow_vocals' rationale, and duration_seconds' loop-repeating grid behavior. The description largely restates those same points (budget cap, style-as-input, beat-grid length), so it adds little beyond the schema; baseline 3 applies.

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 ('generate an instrumental music bed') and immediately constrains it ('from a style ... never an artist'), which sharply distinguishes it from generate_image and generate_footage. The downstream artifact (media key plus beat grid) reinforces what the tool actually produces.

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?

Explicitly tells the agent what to do with the result ('Pass the key as edit_footage's music') and names the required write scope, which is real routing guidance. It lacks any explicit when-not-to-use or cost-alternative guidance (e.g. prefer find_footage when a free existing track suffices), so it falls short of a full 5.

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