Introduction

A well-prompted agent is a great conversationalist, but an agent with tools is a powerful assistant that actually gets things done. Tools enable your Oration AI agents to interact with your own servers, databases, and third-party APIs in real-time.

Whether you're checking an order status, booking an appointment, or validating a customer's account number, this guide shows you how to build robust tools that bridge the gap between AI and your business logic.

The foundation: understanding tool impact

Adding tools transforms your agent from an information provider into an active participant in your business. Effective tools enable your agent to:

• Access live data: Retrieve real-time information like inventory levels or shipment statuses.
• Update records: Create or modify data in your CRM or database during a call.
• Automate workflows: Trigger external events like sending an email or processing a refund.

Getting started: accessing tools

Follow these steps to create and link your first tool:

1. Navigate to tools: In the Oration dashboard, click Tools in the left navigation bar.
2. Create a new tool: Click the New Tool button.
3. Define actions: Inside your tool configuration, create a new Action to define the specific task the tool will perform.
4. Link to agent: Once your tool and action are configured, navigate to your Agent settings, scroll down to the Tools section, and select your tool to add it to the agent.

Tools vs. Actions

Understanding the hierarchy between tools and actions helps you organize your agent's capabilities:

• Action: A single API call or a specific task that the agent can execute.
• Tool: A container that groups multiple related actions together.

For example, a CRM tool might contain several actions such as get_lead_details and update_lead_status. This structure enables you to manage related functionality as a single unit when assigning it to your agents.

Building an Action

Creating an action in Oration involves three main configuration layers. We'll walk through them using a practical example: an action that schedules a callback at a convenient time.

Layer 1: the interface (what the AI sees)

Before the AI uses an action, it needs to know what the action is called and what information it needs to provide.

Name and method Give your action a clear, descriptive name (e.g., validate_callback_datetime) and select the HTTP method (usually POST or GET).

Input schema Define the parameters the AI should collect from the user. For a callback validator, you might need:

• callback_datetime: The date and time requested by the user.
• conversation_language: The language used in the call (e.g., 'en' for English).

Pro tip: Use the Description field in the schema to tell the AI exactly what format you need (e.g., "ISO format without timezone: 2025-10-02T17:00:00").

Layer 2: the connection (what the server sees)

This layer defines how Oration communicates with your APIs.

Headers You can configure any headers required by the service to which you are sending the API request (e.g., for authentication or content types).

URL and body templates Specify your API endpoint and the JSON payload. Use dynamic variables like {{callback_datetime}} to map the AI's inputs directly into your request.

Example body template:

{
  "userSuggestedDateTime": "{{callback_datetime}}",
  "conversationLanguage": "{{conversation_language}}"
}

Layer 3: the user experience (what the customer hears)

Since API calls can take time, keep the customer informed.

Action messages

• Start message: "Sure, I'll check those hours for you."
• Delay message: "One moment please, this is taking a bit longer than expected."
• Success/error messages: Friendly updates to transition back into the conversation.

Crafting seamless interactions

Use descriptive tool descriptions

The Description field in the tool settings is for the LLM. Explain why and when it should use the tool.

Example: "Checks if the provided date-time string is within business hours (Monday to Saturday, 10 am to 7 pm). Returns whether the slot is valid; if not, asks the user to propose another slot."

Handling latency gracefully

Real-world APIs can be slow. Use Oration's timeout settings to manage this:

• Delay timeout: When should the agent say the Delay message?
• Failure timeout: When should the agent give up and inform the user?

Advanced techniques

Context-aware feedback

Match your action messages to the tone of your agent and the language of the conversation.

[Bilingual action start message]
"Sure, I'll check. (मैं चेक करके बताती हूँ)"

Async operations

If a tool doesn't need to return information to the customer (like logging a finished call or sending a follow-up SMS), toggle Is Async to On. This enables the agent to continue the conversation without waiting for the API response.

Troubleshooting common tool issues

When tools fail to trigger

Problem: AI is unsure when to call the tool

• Solution: Improve the tool description. Explicitly state the conditions when the agent should use it.

Problem: Missing required parameters

• Solution: Update your agent prompt to include a Conversation flow that instructs the agent to ask for specific details before calling the tool.

Problem: API returns an error

• Solution: Check your headers and body template. Ensure you are sending the exact JSON structure the server expects.

Problem: Timeouts occurring frequently

• Solution: Increase the failure timeout duration or optimize your backend API for faster response times.

Problem: AI provides wrong data format

• Solution: Be specific in the schema parameter descriptions. Provide examples of the expected format.

Remember: Tools are the "hands" of your AI agent. Start by building small, reliable actions, and gradually expand to more complex workflows as you refine your agent's conversational flow.