save_pr_review

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

With no annotations present, the description is the sole source of behavioral information. It discloses that the tool writes a markdown file to a folder, which is a useful side‑effect detail, but it omits any mention of overwrite behavior, file naming, error handling, or whether the action is reversible. For a write operation, this is a moderate disclosure.

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 a single, grammatically clean sentence that conveys the essential information without any fluff. It is appropriately front-loaded with the action and includes only the necessary details about format and destination.

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 tool with just two simple scalar parameters and no nested objects, the description covers the high-level behavior adequately but falls short on parameter-level detail and its role in the broader workflow with sibling tools. The mention of a 'configured output folder' assumes background knowledge that is not elaborated, yet the overall simplicity of the tool keeps the description from being grossly incomplete.

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?

Since the schema has 0% description coverage, the description bears the responsibility of clarifying parameters, but it fails to explain either 'content' or 'commitHash'. While 'content' is somewhat self-evident as the review text, 'commitHash' is left to the reader's inference, and the description offers no additional context about the relationship between the two.

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 action ('save'), the resource ('a completed review'), the output format ('markdown report'), and the destination ('configured output folder'), making the tool's purpose immediately understandable. It is distinct from siblings like get_pr_review_template or generate_pr_diff, although it doesn't explicitly name them.

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 implies usage after a review is complete ('a completed review') and mentions a 'configured output folder,' giving some contextual clue. However, it provides no explicit when-to-use guidance, prerequisites, or alternatives, leaving the agent to infer the appropriate context from limited evidence.

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