Delete trunk credential

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

Beyond the destructive/idempotent annotations, it discloses concrete effects: any PBX or device authenticating with the credential is denied afterward, and the operation may be refused mid-call. It also exposes the feature-flag gate and the confirm requirement, which are non-obvious runtime behaviors.

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?

Three short sentences, no padding: purpose, blast radius, then gating requirements. The most decision-relevant fact (devices are refused) is front-loaded right after the verb.

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 destructive tool with no output schema, it covers effects, preconditions and the feature gate, which is most of what an agent needs. The remaining omission is how to source the credential_id and whether related trunk/ACL state is affected.

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 documented in the schema and the description only restates 'confirm: true'. The credential_id parameter has no description and the tool text never explains where to obtain it (e.g., list_trunk_credentials) or its UUID format, so the gap is only partly compensated.

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 gives a specific verb plus resource ('Delete a trunk credential') and names the account scope, so it is trivially separable from create_trunk_credential, update_trunk_credential, and the SIP-endpoint deletes.

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?

It states the two preconditions (VOBIZ_ENABLE_PROVISIONING and confirm: true) and the operational consequence that authenticating devices are refused, which signals when the call is appropriate. It stops short of naming alternatives (e.g., use update_trunk_credential to rotate instead of delete) or an explicit when-not-to-use.

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