Cancel a pending number release

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

Annotations already declare it a non-read-only, idempotent, open-world mutation, and the description adds substantial context beyond them: the restore-to-active effect, the fee refund, the 24-hour cooldown window, the env-var and confirm gating, and the side effect that detached trunks/applications must be re-linked. The destructiveHint=true flag is not explicitly reconciled, but the described restorative behavior is not contradicted by it.

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?

Four dense sentences, front-loaded with the action and its effect, then preconditions, then side effects. The parenthetical endpoint and env-var gating add useful precision rather than filler, though the middle sentences are packed tightly enough to be slightly heavy.

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 two-parameter mutation tool with no output schema, the description covers the essential gates, time window, state effects and follow-up remediation. The only real gap is that phone_number's expected format is left to the endpoint placeholder and the schema pattern.

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 50%: confirm is fully documented in the schema ('Must be true, set only after the user explicitly approved'), while phone_number carries only a pattern. The description partially compensates by embedding the {e164} placeholder in the endpoint path and reiterating the confirm: true gate, but adds no meaning beyond what schema plus endpoint already convey.

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 precise verb and resource ('Keep a number that is in pending_release'), names the exact API endpoint, and spells out the resulting state change (restored to active, fee refunded). It is unmistakably the inverse of the sibling release_phone_number, so an agent can select it without opening 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?

Gives clear preconditions for use: only valid during the 24-hour cooldown, requires VOBIZ_ENABLE_PROVISIONING and confirm: true. It also routes the agent to update_phone_number for the follow-up re-linking of detached trunks/apps, but it never names release_phone_number as the counterpart decision, so alternative routing is only implied.

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