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

Annotations already flag destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description adds genuinely new context: the operation is a reversible soft delete scoped to tenant-owned resources and demands explicit confirmation. It stops short of saying whether the endpoint ID can be re-activated later or what happens to in-flight deliveries, which keeps it off a 5.

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?

Two short sentences, front-loaded with the action and immediately followed by the most decision-relevant trait (reversibility, confirmation). Nothing is padded, though the confirmation constraint could have been stated more concretely as a parameter-level instruction.

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?

With an output schema present, return values need no explanation, and annotations cover the safety profile. However, for a mutation with three required params at zero schema coverage, the description leaves the endpointId format and idempotencyKey purpose unaddressed, and does not say how an endpoint is re-enabled.

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%, so the description must carry all parameter meaning, but it only indirectly addresses one of three params ('explicit confirmation' maps to confirm=true). The endpointId format (whk_ prefix) and the idempotencyKey contract are not explained or hinted at anywhere.

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 (disables) and resource (tenant-owned webhook endpoint), and clarifies that the 'delete' in the name is actually a soft disable. It does not differentiate from the sibling update_webhook_endpoint, which may also toggle endpoint state, so an agent cannot fully resolve the pair without the schema.

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 phrase 'requires explicit confirmation' implies the confirm=true precondition, giving a hint about how to invoke it, but there is no explicit when-to-use guidance, no when-NOT-to-use, and no mention of update_webhook_endpoint as the alternative for re-enabling or editing.

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