Place an outbound call

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

Beyond the annotations, the description discloses real-world side effects (money spent, phone rings), credit reservation behavior and the specific insufficient_credits refusal, immediate return status (queued or ringing), and how to track progress via get_call. It also mentions the required calls:write scope. These details go far beyond the bare readOnly/idempotent flags.

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?

The critical warning (spends money, rings phone, confirm with user) is front-loaded, and every sentence carries necessary safety, prerequisite, or behavior information. It is dense but not padded; a bit of redundancy remains in restating the cost/ringing warning, but the structure is effective for such a consequential action.

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 fully covers the immediate result (call record with status queued or ringing), how to get progress/transcript/cost (poll get_call), and the failure mode (insufficient_credits). It also gives auth scope and prerequisites. An agent has everything needed to invoke correctly and interpret the response.

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?

The schema already documents all 7 parameters with 100% coverage, so the baseline is 3. The description adds value by explaining that from_number_id defaults to the agent's outbound_phone_number_id and that the agent_id and from_number_id reference prerequisite resources that must exist. This reinforces parameter relationships rather than just repeating schema text.

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 opens with a specific verb and resource: 'Dial a real phone number over the account's SIP trunk and connect the agent.' This makes the tool's purpose unmistakable and distinguishes it from read-only siblings like get_call and from hangup_call. There is no ambiguity about what action this tool performs.

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 description explicitly warns to confirm with the user before dialing because the action spends money and rings a phone, and it lists prerequisite resources (agent, SIP trunk, phone number) that must already exist. It doesn't name an alternative tool, but since no sibling places outbound calls, the caution and prerequisites provide sufficient decision context.

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