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

Annotations flag destructiveHint=true, but the description makes the destruction concrete: the call replaces the entire grant list, so anything omitted is revoked, and an empty list removes all access. It also imposes a consent rule ('Ask the user before widening this') and names the upstream sources for valid ids — context annotations cannot carry.

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?

Four tight sentences, front-loaded with the verb and the destructive replace semantics before the sourcing and confirmation details. No filler, no restatement of the title.

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 destructive mutation with no output schema, the description covers what is destroyed, what constitutes valid input, and the consent expectation. It leaves the confirmation/approvalId round-trip to the schema rather than describing the needs_confirmation flow, which is the only real omission.

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 75% and already documents kind/version/targetId/workspace/approvalId, so the baseline is 3. The description adds non-obvious semantics the schema only gestures at: the list is complete and authoritative, and the version must be a published revision sourced from the flows/shims list tools.

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?

States a specific verb and resource ('Set what an interface may run — flows and shims'), and the object model is precise: each grant is pinned to a published version. It clearly distinguishes itself from the other napkin_interfaces_* siblings, which create, publish, write content, or grant data access rather than execution reach.

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?

Gives strong operational context: it replaces the whole list, so you must include everything to keep; empty list removes all access; ids/versions come from workbench_flows_list / workbench_shim_list and their revisions; and it explicitly says to ask the user before widening. It never names a sibling alternative for narrowing vs widening, but the surrounding guidance is unusually actionable.

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