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

Annotations already disclose destructive, idempotent, and open-world behavior, and the description adds useful context: permanent revocation, no payment requirement, principal/broker authorization, and broker-side cancellation behavior on halt. It still does not fully explain the authorization flow or exact side effects of revocation, and parts of the description concern the broader mandate system rather than this operation.

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 relevant purpose is front-loaded, but the description then includes substantial unrelated system context about issue/amend payment rails, treasury caps, registrar timestamps, and halt behavior. Much of that text does not help an agent invoke revoke correctly and dilutes the definition.

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?

The tool has a complex nested action schema with no schema descriptions and no output schema, so the description should carry more of the invocation burden. It gives useful high-level context and a contract documentation pointer, but it leaves the actual parameter structure and expected response behavior largely unexplained.

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%, and the description does not explain mandate_id, action, wallet_signature, or the nested signed/unsigned action structures. The pointer to /api/mandate-contract is not a substitute for parameter semantics in the tool definition.

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 first sentence states a specific verb and resource: 'Record permanent revocation' by the principal or broker for cause. This distinguishes the tool from a generic update, though differentiation from the sibling halt tool is only implied through the word 'permanent' rather than stated explicitly.

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 indicates revocation is for cause and free, which gives some usage context. However, it does not explicitly say when to use revoke instead of halt, status, amend, or issue, and it does not state exclusions or prerequisites beyond pointing to the contract endpoint.

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