Review Draft

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

Annotations indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds crucial behavioral details: 'Opens a browser window with an editor and live preview. Blocks until the user approves or rejects.' This discloses the interactive nature and UI behavior. It also explains the consequences of approval/rejection, which goes beyond 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 well-structured with a concise opening sentence, bullet points for outcomes, and clear examples. Every sentence adds value, and the length is appropriate for the complexity of the tool. It is front-loaded with the essential purpose.

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?

Given the interactive nature of the tool (no output schema), the description thoroughly covers the behavior: opening an editor, blocking for approval/rejection, and next steps. It also mentions clipboard fallback. The description is complete for the tool's complexity and context signals.

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 input schema already describes all parameters. The description adds value by providing examples showing how to use the parameters (e.g., app='github', mcp='github:create_pull_request') and context for 'format' and 'app'. This goes beyond the schema's descriptions, enhancing parameter understanding.

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 clearly states the tool's purpose: 'Let the user review and edit a draft before it goes anywhere.' It specifies the action (review and edit) and the resource (draft). There are no sibling tools to differentiate, but the description is specific and includes examples that reinforce the purpose.

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 explicitly states when to use the tool: 'When creating PR descriptions, Linear tickets, Slack messages, or emails: call this tool first, then use the approved content with the target tool.' It also explains the flow (blocks until approve/reject) and what to do on each outcome, providing clear usage guidance.

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