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

Annotations only declare the mutation safety profile; the description adds the real behavioral payload: 3 credits per second with a worked example, a 30-second cap, the confirm-gated quote-then-spend flow, the added 'AI generated' label, and a defaulted resolution at flat price. These are exactly the traits an agent needs and none are in 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?

Front-loaded with the core action, then prerequisites, cost, and restrictions in a logical order; each sentence carries information. It is slightly dense and could compress the credit arithmetic, but there is little true filler.

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 costed, confirm-gated mutation tool that depends on two other tools, the description covers the dependency chain, the spend gate, the cost model, and the eligibility restriction. An output schema exists, so return values need no explanation, leaving nothing material 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 100%, so the baseline is 3, but the description adds genuine meaning: it clarifies confirm's quote-vs-spend semantics, ties image to a 'look id' sourced from list_images and driver_upload to list_uploads, and states the 30s/50MB constraint. This goes beyond the schema without fully documenting every field's edge cases.

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+resource: it replaces the person in the user's own video with an AI influencer, rendered in its own room/light/camera with an 'AI generated' label. This is clearly distinct from siblings like create_clip or create_motion_clip, so an agent can route correctly without opening a 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 prerequisites and the workflow (request_upload, then list_uploads to get driver_upload) and a when-not condition ('Only AI influencers designed in ClipUGC work, not ones made from an uploaded photo'). It does not explicitly compare against sibling clip-creation tools, so it stops just short of a full when/when-not/alternatives map.

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