Retell Function Calling Custom Tools

Agent defines a custom function check_appointment with a parameter schema, but omits a clear description, so the model invokes it with wrong/empty arguments.

Define the custom function with a precise name, description, and parameter schema (types + required fields) so the model knows when and how to call it. Validate arguments server-side before executing; ambiguous descriptions cause mis-invocation.

A custom function's backend hangs past its timeout. The agent waits indefinitely with the caller on the line.

Set a function timeout and, on expiry, return a graceful fallback to the model ('I couldn't reach that system; can I take a message?') rather than hanging. Bound the wait so the call stays responsive.

A function fetches an order status and the result must be spoken. The raw payload contains codes (status: 'IN_TRANSIT_HUB_3') the agent reads verbatim.

Map fetched data into natural language before speaking ('Your order is on its way'); do not read internal status codes/IDs aloud. The function result feeds the model, which should verbalize it for a phone caller.