ae_repair_motion_blueprint

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

With no annotations, the description carries the full burden. It does add useful behavioral details: 'deterministic,' 'safe,' and the return of a before/after audit. However, it does not disclose whether the blueprint is mutated in place, what side effects occur, or what the audit contains, so transparency remains partial.

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 description is a single, front-loaded sentence that conveys the action, scope, and output without wasted words. Every phrase earns its place.

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 mutation tool with no annotations and no output schema, the description gives the essential action and result but omits details like whether the input is modified in place and what the returned audit contains. It is acceptable but not fully self-sufficient.

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?

The schema provides only a bare 'blueprint' object with no property documentation (0% coverage). The description partially compensates by naming the relevant dimensions—scene timing, template ids, and graphic text limits—but it does not describe the object shape or any additional semantics needed to construct the input.

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?

The description states a clear action—applying deterministic safe repairs to scene timing, template ids, and graphic text limits—and names the output as a before/after coherence audit. This is a specific verb+resource+scope, though it does not explicitly differentiate itself from sibling tools like ae_validate_motion_blueprint or ae_audit_motion_coverage.

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?

There is no guidance on when this tool should be used versus alternatives, nor any mention of prerequisites such as running validation or audit first. The intended workflow position is implied by the tool names but never stated.

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