Kill switch

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

With no annotations provided, the description carries the full burden and does so well. It discloses that the operation is LOCAL and offline, fail-closed, persists the revocation to the ledger, takes effect on the subject's very next request at the gateway, cascades to bound virtual cards, and is irreversible without an operator. That is exactly the side-effect and reversibility information an agent needs before firing a destructive call.

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 important qualifier (LOCAL, offline, fail-closed) and the mode selection, then layers on effects and the reversal path. Every clause is load-bearing — ledger write, next-request enforcement, card cascade, operator-gated reversal — with no filler or restated boilerplate.

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 no-annotation, four-parameter mutation tool with no output schema, the description covers effects, scope, persistence, and reversibility thoroughly. Gaps remain: no mention of the 'reason' parameter's role, no guidance on what happens with conflicting or missing subject arguments (required count is 0), and no error/idempotency behavior.

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 25%, so the description must compensate and largely does: it explains the semantics of the three subject selectors (agent_did, mandate_id, all) and what each actually revokes, including that agent revocation kills the mandate rather than the agent identity. The 'reason' parameter remains undocumented in both schema and description, and the implicit mutual exclusivity of agent_did/mandate_id/all is only implied.

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 (revoke/kill) against specific resources (one agent, one mandate, or the entire door) and clarifies the distinction between killing an agent versus its mandate. It is immediately distinguishable from siblings like mandare_issue_mandate or mandare_verify, which provision or check credentials rather than revoke them.

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 clear conditions for each mode: an agent, a mandate (with the key note that the agent survives but the permission slip dies), or --all for the whole door. It also names the reversal path (mandare reinstate) and the operator requirement, telling the agent when this is NOT the right recovery tool. It stops short of explicitly contrasting against siblings such as mandare_gateway_health or mandare_budget_status for non-revocation diagnostics.

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