build_motion_manifest

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

Beyond the annotations (which only cover safety/idempotency/purity), it discloses the mapping heuristic (band tag + first #id/.class token), the known limitation that no markup is available so DOM initial-state hints are empty, and that census triggers still attribute by token. It also states the return shape, the specific condition where manifest.measured stays false, and that the tool never throws ({ error } on invalid input).

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 purpose and inputs, then the mapping rules, then the return contract and failure behavior; every clause carries substance. It is dense and the middle sentence runs long, but nothing is redundant enough to cut.

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?

With no output schema, the description supplies the return shape ({ manifest, measured, censusAnims, warnings, note }), the semantics of the measured flag, error behavior, and the pure/offline constraint. For a 3-parameter, fully documented tool, an agent has everything needed to call it and interpret the result.

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 explains that sections[].selector supplies the #id/.class tokens in place of a band label and that overrides are applied in build order. The relationship between bands and the analyze_page_structure output is also articulated beyond the schema's terse 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 and artifact ("Build a motion.manifest.json scaffold") plus the exact inputs it consumes, naming the two sibling producers (analyze_page_structure bands and analyze_scroll_map census). It does not explicitly contrast itself with nearby builders like build_gsap_stub or build_project, so sibling differentiation is implied by inputs rather than stated.

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?

The description makes the usage context clear: it is a downstream step that requires the outputs of analyze_page_structure and analyze_scroll_map, with section overrides as an optional input. There is no explicit when-not guidance or pointer to alternative tools for related scaffolding tasks, which keeps it below a 5.

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