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

Goes well beyond the annotations: discloses atomicity ('the same operations and validations as the studio chat are applied atomically'), the outcome semantics ('status ready = recap ready; rejected = nothing saved'), the error payload shape (`problem.section` / `problem.message`), and that it neither generates nor charges. That is precisely the non-obvious behavior (no billing, nothing persisted on rejection) an agent needs before calling a mutating-but-non-destructive tool.

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?

Purpose and prerequisites are front-loaded, but the core is one very long sentence with deeply nested parentheses ('who appears — catalogue actor, library person or a new person with 1-5 uploaded photos —, outfit, place, ...') followed by a large raw JSON blob, which is dense to parse. It is information-rich rather than wasteful, but structure could be broken into scannable clauses.

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 complex nested generator-scene payload with no output schema, the description covers the required workflow (upload first, call once), failure semantics and the downstream steps. The only real gap is that the returned recap/ready payload is only described indirectly via `status` and `problem.section`, but the atomicity framing largely compensates.

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?

Top-level schema coverage is 0% (the two top-level params path/body carry no descriptions), but the nested definitions are richly described, and the description supplies a concrete end-to-end body example showing version, dry_run, kind, actors with catalog_id+wardrobe, lines with who/text, location, product_ids and camera. The `dry_run: true` in the example implicitly signals a validate-first pattern that pairs with the schema's dry_run field, adding real usage value over the schema text alone.

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 the whole scene') plus a clear scope distinction: 'Espace Expert in one call, without conversation', which separates it from the conversational studio path and from kelpo_apply_operations. The parenthetical enumerates exactly what the scene is composed of (actors, outfit, place, products, lines/seen, voice, camera, music, format), so an agent knows what this tool builds without opening the 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 an explicit ordering precondition ('Upload the files first to this conversation (role unassigned, project_id), then call this once') and an explicit postcondition ('Never generates nor charges: then quote and generate as usual, after the user's approval'), implying kelpo_quote_scene/kelpo_generate come next. It does not say when to prefer this over the chat/operations route or when a free `scenario` should win over `lines`, so alternatives are only partly addressed.

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