swg_gate

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

Beyond the sparse readOnlyHint=false annotation, the description discloses important behavioral traits: it explains why version alone cannot detect a grant reclaim, lists precise deny reasons, and explicitly states the SINGLE-HOST limitation and out-of-scope guarantees. This is substantial transparency for a concurrency-sensitive 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?

The description is dense but every sentence earns its place: purpose, required inputs, invocation timing, return/deny behavior, recovery path, and limitations. Front-loading the core purpose helps an agent quickly identify the tool, and the limitation details are essential for correct use.

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 no output schema and only a single annotation, the description fully compensates: it states what the tool returns (decision=proceed or deny with reason=stale_view), why a deny occurs, how to respond, and the boundary of its guarantees. This is complete enough for an agent to call and interpret the tool correctly.

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 carry the parameter semantics. It does well for expected_version and expected_generation by tying them to an earlier swg_read call and clarifying that expected_generation is the owner_generation. Path is not elaborated, but it is self-evident as the file being verified.

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 opens with a specific verb and resource: 'Verify a file is STILL unchanged and still under the same grant.' It clearly identifies the tool as a pre-action gate and distinguishes it from siblings by specifying it must be called before irreversible external actions, unlike swg_read or swg_write.

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 gives explicit when-to-use guidance: 'immediately BEFORE any irreversible external action' and lists concrete examples such as webhooks, PRs, deploys, and messages. It also provides the on-deny workflow: do NOT take the action, then swg_reacquire, re-read, re-decide, which clearly routes to the correct sibling.

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