evaluate_patch

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

Annotations already declare readOnlyHint=false and idempotentHint=false; the description goes beyond them by disclosing concrete write side effects (immutable audit records EVL-... in SweGateStore, sealed cryptographic blocks in TraceKitStore), which tells the agent this call mutates state and is not a dry run. It does not say whether records are still appended when the verdict fails, which is the remaining unknown for a mutation tool.

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?

Two sentences with no filler, front-loaded on the verification purpose with side effects and sibling routing deferred to the second sentence. The parenthetical parameter lists make it dense but each clause carries distinct information.

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?

With an output schema present, the description correctly avoids restating return values and instead covers the axes of evaluation, persistence side effects, and where to read results back. The open question of whether failed patches are still recorded in the audit ledger is the one behavior an agent would want before calling it repeatedly.

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 100%, so the baseline is 3, but the description adds semantic grouping the schema lacks: it clusters max_cyclomatic_delta, forbid_type_ignores and disallowed_import_modules as the architectural constraint set, and tests_passed, tests_failed, functional_verdict as the functional evidence. It stops short of explaining how diff_text is parsed or whether diff_size_bytes is derived or trusted.

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 names a specific verb and resource ('Verify a unified git diff patch') and enumerates the exact validation axes it applies (cyclomatic delta, type ignores, banned imports, functional verdict). It also clearly separates itself from siblings by assigning record retrieval to query_audit_ledger.

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 gating context is explicit ('before allowing merge'), and it routes the agent to the correct sibling for retrieval/verification of persisted records. There is no explicit when-not guidance or distinction from evaluate_spec_axioms / resolve_context_bundle, which is the only gap.

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