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

With no annotations, the description carries the full weight of explaining behavior, and it explains almost nothing. It does not say whether an audit is final, repeatable, or able to be overwritten, which permissions are needed, or what recording a 'dangerous' verdict triggers. Only the word 'record' hints at a write operation.

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?

A single short sentence is front-loaded and free of obvious padding, so the structure is fine. But the sentence is too short to deliver the information needed for the tool to be called (underspecified), rather than dense.

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?

This is a write tool with four required parameters, one enum, no annotations, and no output schema, and the description leaves nearly all of that unexplained. An agent cannot tell from the description what a valid session or project value is, or how the clean/dangerous verdict is consumed downstream.

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 0% across four required parameters (project, session, verdict, summary), and the description explains none of them. Worse, it refers to 'this commit' even though no commit parameter exists, which could lead the agent to look for or expect one when it is not there.

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 verb 'record' and the object 'your safety check of this commit' give a rough idea of the action, but what the check consists of, and which commit is meant, remain undefined. The description never arrives at the concrete output (a verdict of clean or dangerous), so the agent has to infer a purpose the schema spells out.

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?

No indication of when this tool should be used instead of the sibling tools (mark_task_done, mark_complete, report_project). It implies use after inspection, but it gives no context, no prerequisites, and no exclusions.

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