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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the bar is lower, yet the description still adds real behavioral context: provisioning is asynchronous, so results are eventually consistent and may need polling, and a 404 specifically means calling was never enabled rather than a transient error. The possible status values and the last_error field further characterize the failure surface.

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: purpose and return shape first, then the timing/polling instruction, then the error semantics. Every sentence carries distinct information and none repeats the name or the annotations.

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 no output schema, the description correctly compensates by naming the returned fields and the status enum. For a simple single-parameter read tool that is nearly sufficient; only the transition from 'failed' to the retry tool is left unstated.

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 100%, so both parameters are already documented, including the crucial 'NOT the trunk id' warning on number_id. The description adds no parameter-level meaning beyond that (it does not, for example, explain that number_id comes from list_numbers), so the baseline of 3 applies.

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 uses a specific verb+resource combination ("Read a number's WhatsApp Business Calling trunk") and enumerates the exact returned fields (status, provisioning step, last_error) with the status vocabulary spelled out. It separates this from the write-side siblings by framing it as a read of provisioning state, though it never names the adjacent reads (get_whatsapp_call_settings, get_whatsapp_call_permission) that an agent could confuse it with.

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?

"Poll this after enabling — provisioning is asynchronous" gives an explicit trigger condition and pairs it with the enable_whatsapp_calling workflow. The 404 clause adds a clear not-enabled interpretation. It stops short of naming retry_whatsapp_provisioning as the follow-up when status is 'failed', leaving the remediation path to inference.

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