motion review feedback

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds meaningful constraints beyond them: no inferred preferences, a hard watched-preview prerequisite, and the warning that 'accept' is a user preference rather than a quality judgment. It adds real behavioral context, though it says nothing about stale-write rejection (only in the schema) or the response.

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?

Three short sentences, front-loaded with the core action, and every clause carries a distinct rule (real feedback only, no inference, watch confirmed, acceptance is not a certificate). No filler.

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 a nested payload and an output schema already covering return values, the description supplies the key semantic guardrails (authentic user feedback, watch prerequisite, acceptance semantics). The remaining gap is the undocumented feedback sub-fields, but the safety profile is carried by annotations and return shape by the output schema.

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 33%: only 'revision' is documented, while the large nested 'feedback' object (overall enum, watchedPreview const, liked, changes, answers) is undescribed. The description gestures at 'accepted' and 'watching the preview' but never maps these to the actual feedback fields, so it fails to compensate for the coverage gap on a complex nested payload.

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 ('Record feedback') scoped to 'this exact review revision', so the agent knows it is a write of user feedback for a specific revision. It does not, however, name or distinguish itself from siblings like motion_review_read or motion_review_start, leaving selection to inference.

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 clear conditions for use: feedback must be actually user-provided, never inferred, and the user must have confirmed watching the preview. It stops short of naming an alternative sibling to call when these conditions are not met, so it is strong context without explicit routing.

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