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

Annotations already declare non-read-only, non-idempotent, destructive creation; the description adds the important trait that each call is billable and that 'Backend validation is authoritative' with no inferred mode/model/default/voice injection. It also discloses rejection/retry behavior. It stops short of saying what a failed or partial submission leaves behind, but the added cost and validation context is substantive beyond the annotations.

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 core instruction is front-loaded, but a large share of the text is reply-formatting policy about redacting task_id/session_id/user IDs, which does not help an agent decide or invoke this tool. Sentences are run together in a dense block, forcing the reader to sift operational rules from presentation rules.

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 nested, 7-parameter creation tool with annotations and an output schema, the definition covers model selection, schema discovery, attachment binding, session continuation, versioning and resubmission policy. An agent can invoke it correctly without additional external documentation.

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?

With 100% schema coverage the baseline is 3, and the description genuinely adds semantics: input carries original model parameters and must follow get_model_schema, flat parameters and legacy reference_images/reference_audio are rejected, file_bindings must use fields from schema.mcp.attachments with zero-based indices, and session_title is ignored when session_id is supplied. It reinforces rather than merely restates the 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?

Opens with a concrete verb and resource: 'Create one independent billable Studio task', and clarifies the routing to list_models.defaults and get_model_schema. It distinguishes shortcuts from generate_task ('generate_task requires model; shortcuts may omit it') but never states that the task is a music generation task nor contrasts itself with generate_image/generate_video/generate_speech, so the domain comes only from the tool name.

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 selection rules for the session family: session_title for a new topic, session_id to continue, session_id plus base_run_id for a version, and omit base_run_id for an independent work. It also sets prerequisites (read list_models.defaults, then get_model_schema) and a hard 'never automatically resubmit after rejection' rule. Missing is any guidance on when to pick this tool over the other generation siblings.

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