AgentCall defines 11 tools with complete JSON schemas and descriptions. Naming follows verb_noun convention (dial, answer, reject, hangup, speak, send_dtmf). Descriptions are present (avg ~100 chars) but lack depth on WHEN to use each tool and dependencies between them. All parameters have type definitions and descriptions with format constraints (e.g., E.164 for phone, 1-128 chars for IDs). However, output schemas are not documented, callers cannot see what dial() or speak() return. Error handling is absent: no guidance on retryability, recovery steps, or what happens on network failure. Idempotency keys are present on write operations (good pattern), but no explicit documentation of idempotent semantics. Tool composition is sound (each does one thing), but descriptions don't explain call sequencing (e.g., must wait_for_incoming_call before answer).

• Document output schemas for all tools. E.g., dial() should return {callId: string, status: 'ringing'|'connected', timestamp: ISO8601}. This enables tool chaining and LLM planning.
• Enhance descriptions with WHEN-to-use guidance. E.g., wait_for_incoming_call: 'Call this first to detect an incoming call. Must complete before calling answer() or reject().'
• Add error handling guidance to descriptions. E.g., wait_for_turn: 'Returns timeout error if no turn within timeoutMs. Retryable, call again to wait for the next turn.'
• Clarify prepare_speech vs speak. Rename prepare_speech to queue_speech or document that prepare_speech buffers audio while speak() plays immediately. Add examples.
• Document idempotency semantics. E.g., 'Idempotency keys prevent duplicate calls for 24 hours. Reusing the same key within this window returns the original result without side effects.'