beel_delete_invitation

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

Annotations already declare destructive and non-read-only behavior, but the description adds valuable specifics: the 404 response when the invitation is already accepted, revoked, or expired, without disclosing which; and that revocation does not remove the invitation from the list. It also provides the HTTP endpoint. These details go beyond the annotations and help the agent anticipate outcomes.

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 compact, with the key behavior front-loaded in the first sentence and supporting details in the second. The endpoint line is a minor redundancy but adds clarity. There is no fluff; every sentence contributes to understanding the operation.

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 simple delete operation with two parameters, the description covers the core behavior, error conditions, and side effects (non-removal). It does not explain what the invitation_id is, but that is partially inferred. It also does not discuss potential side effects beyond revocation, but given the annotations and schema, it is reasonably complete for an MCP tool.

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?

While the schema provides a detailed description for account_id, the invitation_id parameter has no description and the tool description does not compensate for it. Schema description coverage is 50%, so the description should clarify the invitation_id parameter, but it only mentions it in the endpoint line without adding semantic meaning. This is a notable gap for an agent trying to construct a valid call.

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 clearly states the action ('Revokes a PENDING invitation') and the effect ('its acceptance link stops working'). It distinguishes itself from list/get/create invitation tools by specifying the state constraint and the non-removal behavior. The verb and resource are precise, leaving no ambiguity about what the tool does.

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?

While it does not explicitly name sibling tools, it provides strong contextual guidance: only pending invitations can be revoked, and revocation does not remove the invitation from the list. This implicitly tells an agent when this tool is appropriate (revoking an invitation) and when it is not (if removal is desired). It lacks an explicit 'use X instead' statement, which would merit a 5.

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