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

The description adds behavioral detail beyond the annotations: it states 'Read-only; no side effects and no writes' and explains that it returns a severity-ranked list and a Markdown verdict with location and fix info. It also reveals that it can list available repositories if repository is omitted, which is a behavioral quirk. Annotations already declare readOnlyHint: true, destructiveHint: false, so the description reinforces and adds specifics about output format and the repo listing behavior. This is more than baseline, so a 4 is appropriate, though it could also mention any rate limits or other constraints but that's not necessary.

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, starting with the primary action and context ('Self-review a change...'), then the input requirements, then the output format, then the usage instruction. It is comprehensive yet concise, using bullet points implicitly. It front-loads the purpose and constraints, and every sentence adds value. It's a bit long but appropriate for the complexity. No fluff.

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 tool's complexity (multiple parameters, output description, side effects-free), the description is complete. It explains the input, output format, the process, and the usage flow. It also handles edge cases like repository scoping and deleted paths. Even without an output schema, it clearly describes the Markdown verdict and its contents. The description fully compensates for any lack of structured output information. For a tool with such detailed documentation, this is a top score.

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 description explains the key parameter 'changedFiles' by saying 'Pass the proposed new state of each changed file (and any deleted paths)' and that it returns findings. However, the input schema already covers parameters comprehensively with descriptions at 100% coverage. The description does clarify that 'changedFiles' should be in proposed new state, and mentions max 20 files per call, which is additional detail. It also explains how deletedPaths work. Since the schema is thorough and the description supplements with usage context, a 4 is justified. It doesn't describe the 'repository' parameter in depth but the schema does; the description's instruction about repository missing behavior is useful but not essential.

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: 'Self-review a change you are about to commit BEFORE opening the PR.' It specifies the verb ('review'), resource ('change'), and actionable scope (pre-PR commit step). It also distinguishes from siblings by emphasizing 'read-only' and 'no side effects' and the review of violations. Sibling tools like get_doc_impact or list_docs are read-only but not for pre-commit self-review, so it is differentiated.

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 says 'Call this as the final step of the edit flow, then fix findings and re-run.' This gives clear when-to-use guidance. It also mentions that it should be used before opening a PR, and implies it's for editing content. While it doesn't explicitly say when NOT to use it, the final-step instruction and the highlighted purpose are sufficient for usage guidance. It also contrasts with siblings by implying other read tools (like get_conventions or get_doc_gaps) are for gathering context, not reviewing changes. Overall, this is strong guidance.

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