gate_check

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

Annotations already establish readOnlyHint=true and idempotentHint=false, so the safety profile is covered. The description still adds real behavioral context: mode-dependent behavior (changed_ids alone skips whole-KB structure checks; empty changed_ids runs whole KB but skips the commit gate) and that severity_min is bypassed on a pass. It does not say what a failing gate returns, but that gap is minor.

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-loads the identity ('Local gate: validate + lint + commit_gate') before the usage and parameter details, and every clause carries information. The telegraphic semicolon style is dense and slightly cryptic, but nothing is wasted.

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 composite, mode-switching tool with four parameters, no output schema, and moderate annotation coverage, the description covers purpose, invocation moments, and per-parameter behavior adequately. What is missing is the meaning of a gate result (what failure blocks) and any note on cost or ordering of the three sub-checks.

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 coverage is only 50%, so the description must carry weight — and it does, defining changed_ids scoping (just those IDs vs whole KB when empty), scope as a path prefix, and severity_min's default of warning plus its interaction with 'pass'. scope_neighbors is left to its schema text, which is acceptable.

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 the resource (a 'local gate') and immediately decomposes it into the three checks it composes: validate + lint + commit_gate. That distinguishes it from the sibling standalone 'validate' and 'lint' tools, though 'gate' itself is domain jargon and no plain verb (run/check) anchors the action.

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?

It gives concrete trigger conditions: 'Use at session end over the IDs you wrote, or before fast-forwarding to main.' That is clear context for selection, but it never explicitly contrasts this composite gate with calling validate or lint directly, so the agent must infer when the narrower siblings are preferable.

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