verify_lean

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

With no annotations present, the description carries the full burden and does well: it discloses what categories are examined, that `diff` must be a unified diff, that omitting it checks the working tree against HEAD, and the output contract (gate=pass|block with findings). It does not cover cost, performance, or what 'blocking' versus non-blocking findings look like, leaving a modest gap.

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?

Front-loaded with the trigger condition, then the check categories, then parameter and return semantics. The long enumeration of checks is dense but each item earns its place by defining scope. Slightly list-heavy, but no filler sentences.

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 two-parameter analysis tool with no output schema and no annotations, the description covers purpose, trigger, both check semantics for `diff`, and the gate-based return shape. The only real omission is the `repo` parameter and any note on how the tool relates to the overlapping sibling checkers.

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%, so the description must compensate. It explains `diff` well (unified diff; omit to check working tree against HEAD), but `repo` is never mentioned and its meaning, expected format, or relationship to the working tree is left entirely unexplained.

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 states a specific verb (verify/check) and enumerates exactly what is checked: bloat, error handling, and security, each with concrete sub-items like dead code, swallowed exceptions, and hard-coded secrets. That is far more specific than the name alone. However, it does not differentiate itself from overlapping siblings such as check_reuse or check_dependency, whose domains (duplicate code, unneeded dependencies) are claimed here as part of 'bloat'.

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?

"Call when you finish a change, before you report done or commit" gives a clear temporal trigger for use. It also names a follow-up path (fix or reject via record_feedback), which is helpful. It stops short of explicit exclusions or a comparison to sibling tools like check_reuse, so the agent must infer when this is preferable.

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