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

Annotations only say readOnly=false, openWorld=true, idempotent=false, destructive=false. The description goes well beyond by disclosing the two-leg ring-then-dial sequence, that a real call is placed, and that call charges apply — the crucial non-obvious side effect that destructiveHint=false does not convey. The POST /calls endpoint is a bonus.

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 short sentences with the WRITE marker and the safety warning front-loaded, then mechanism, then endpoint. Every sentence carries distinct information; nothing is redundant.

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?

Covers mutation semantics, cost, prerequisite intent, and the ring-first flow — enough to call it safely. It omits what the call returns (e.g. a call ID usable with placetel_get_call), which matters given there is no output schema, but that is a minor gap.

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 100%, so the schema already documents sipuid (with an example and a pointer to placetel_list_sip_users), target, and from_name. The description only loosely refers to 'the given SIP user's phone' and 'the target number', adding no format or constraint detail beyond the schema — baseline 3.

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 and resource ('start a real phone call') and explains the exact mechanism: Placetel rings the SIP user first, then dials the target once answered. This is unmistakably distinct from sibling tools like placetel_send_sms or the placetel_list_* readers.

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?

'Do not use without the user's explicit request' is an explicit when-not condition, and the charge warning adds a further gate. It stops short of naming a preferred alternative flow (e.g. confirming via placetel_list_sip_users first), but the guidance is clear and actionable.

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