revoke_board_access

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

With no annotations, the description carries the full burden and delivers: required authority (ADMIN ONLY), transport constraint (HTTP transport), immediate and irreversible-looking effect (cookies stop working immediately), and explicit boundaries (role tokens and mailbox untouched). This is rich behavioral context an agent could not infer from the schema.

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 most critical constraint (ADMIN ONLY) and uses tightly packed clauses with zero filler; every sentence (scope, effect, boundary, next step) earns its place.

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 admin action, the description covers authority, mechanism, effect, and untouched resources, and an output schema already exists so return values need no explanation. Nothing an agent needs to invoke it correctly is missing.

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 0% for the single 'channel' parameter, so the description technically owes compensation, but it never clarifies whether the value is an ID, name, or slug. The parameter is largely self-evident by name, keeping this at a minimal-viable baseline.

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 with precise scope: 'revoke EVERY read-only viewing key of a channel'. It also implicitly distinguishes itself from siblings by noting that role tokens (rotate_token) and the mailbox are untouched.

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 a clear motivating scenario ('the answer to a lost or shared phone') and points to the natural follow-up tool ('issue a fresh link with board_link'). It does not explicitly state when NOT to use it or name the alternative revocation tool (rotate_token), so it stops short of full routing guidance.

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