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

Annotations only convey readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false — a bare mutation profile. The description carries the full behavioral burden and exceeds it: it reveals the PROJECT-SCOPED guarantee, the degraded-but-explicit fallback ('With neither, it still places the clip and tells you plainly that nothing was synced'), the constraint that no zoom is invented without a position, and precise default behaviors (at_output_s at END, zoom_strength 0.4). No contradiction with 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?

The description is long, but every sentence carries load-bearing information for a 7-parameter, no-output-schema tool. It is front-loaded with the PROJECT-SCOPED constraint, then flows logically through purpose, behavioral specifics, parameter guidance, and follow-up tools. The only deduction is length — it is at the upper edge of density and could benefit from tighter phrasing, though no sentence is wasted.

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 mutating 7-param tool with no output schema and 14% schema coverage, the description is thorough: scope, input-type handling, defaults, edge cases, and follow-up tools are all covered. The one gap is that the return value is only glossed as 'the project identity with its result' without detailing its structure or whether the edit state is the full return. Minor against an otherwise complete picture.

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 description coverage is only 14% (solely project_id has a description), so the description must compensate — and it does exhaustively. It gives units and format for click_times ('seconds into the clip'), a numeric range plus rationale for zoom_strength ('0.05-4.5 (0.4 default — screen text needs a real push to read)'), and semantic intent for zooms and click_sounds ('opt-in'). It even explains the failure mode of timing without position, which the schema cannot express.

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 precise verb-resource pair: 'PLACE A SCREEN RECORDING AND CUT IT LIKE A PRODUCT VIDEO — one call. Splices the clip into the edit, then puts a zoom on each run of POSITIONED clicks.' This is specific and distinguishes it from siblings like add_zoom and add_zoom_path, which perform single zoom operations. It also clarifies scope with 'Works on ANY video clip, not just a record_website_demo capture,' removing any ambiguity about applicable inputs.

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?

Explicitly names alternatives and the conditions that select them: 'Follow up with add_zoom_path to make the frame travel on a user recording, and enhance_cursor if the pointer is too small to follow.' It also distinguishes when click_times is needed ('On a recording the USER made') versus when it isn't ('On a capture I made'), and explains the zooms=false mode. Nothing is left to inference.

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