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

Annotations already flag destructiveHint=true and readOnlyHint=false. The description adds meaningful behavioral details beyond that: the same ID is revoked, the old secret subsequently fails with 401 invalid_api_key, and there is an explicit auth preference. It also asserts a non-action ('No ops file-edit'), which is useful for understanding scope.

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 three sentences with a clear logical order: action, effect, and usage caveats. Every sentence adds distinct information—endpoint, invalidation result, auth preference, and non-goal—with no filler or repetition.

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 tool with no input parameters, no output schema, and strong destructive annotations, the description covers all essential aspects: the operation, its consequence, authentication method, and a scope boundary. Minor missing details such as idempotency or error handling could be added, but they are not critical given the simplicity.

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?

With zero parameters in the schema, the baseline for this dimension is 4. The description's mention of 'the presented secret' and auth headers confirms that the key is obtained from the request context, but since there are no parameters to document, the description cannot add much more. The baseline is appropriate.

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 the specific verb 'Invalidate' and the resource 'the presented secret', plus the explicit HTTP endpoint 'POST /keys/revoke'. It further clarifies the effect ('old secret then fails 401 invalid_api_key'), which leaves no doubt about the tool's purpose even before considering sibling tools.

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 implies usage through its action but provides no explicit guidance on when to choose revoke_key over alternatives like rotate_key or issue_key. It does supply auth-related usage advice ('Prefer Authorization: Bearer') and a negative boundary ('No ops file-edit'), but these do not directly distinguish this tool from its siblings.

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