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

Annotations declare readOnlyHint=false, idempotentHint=false and destructiveHint=false; the description adds meaningful behavior beyond that — async job semantics, loud refusal when a Brief field cannot be honored, graphics carried verbatim rather than re-authored, and clientNonce-driven dedup. The one gap is that 'saves the winner to the project' doesn't state what happens to any existing composition, which matters for a non-readonly mutation with destructiveHint=false.

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 operation and outcome, then the source-selection rule, then the return and the follow-up call — a sensible information order. It is long and dense, and some of the briefId parenthetical restates the schema description, but almost every clause carries a decision an agent must make.

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 an async, nested-body, multi-path tool this covers the source selection, the prerequisites for each path, the refusal behavior, and the required follow-up job-wait — everything an agent needs to call it correctly. The output-shape sentence is redundant given the output schema exists, but it is not a gap.

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%, but the description adds a constraint the schema does not encode at all: the source fields are a mutually exclusive choice where EXACTLY ONE must be set. It also labels each path's intent (PLANNED/GENERAL/CLIPPING), which is semantic value beyond the raw field descriptions.

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 (start an async Director compose job) and immediately scopes what the job does: author candidates, verify each, save the winner. It also distinguishes the three source paths by name (briefId / fromComposition / suggestionId) so an agent can tell this apart from create_brief, suggest_briefs, apply_composition and create_render without opening other 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 prerequisites per path — 'create_brief first' for the PLANNED path, 'seed it with apply_composition first' for the GENERAL path — and names the pairing tool for the CLIPPING path (suggest_briefs). It also names the immediate follow-up call, wait_job(kind="compose", id=composeJobId, projectId=...), which is exactly the routing an agent needs.

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