Why it matters
Custom tools let agents interact with your internal systems or third-party platforms that are not supported by built-in tools. This allows agents to retrieve data, trigger workflows, or update external services in real time during conversations or calls. To be effective, the tool must also be explicitly enabled and referenced in agent instructions.
Key Concepts
Custom Tool: A tool that calls a user-defined API endpoint using HTTP methods and a JSON schema.
Endpoint URL: The HTTP or HTTPS address the tool sends requests to.
HTTP Method: The request type used to interact with the API, such as GET, POST, PUT, PATCH, or DELETE.
JSON Schema: A structured definition of the parameters the agent can send to the API.
Response Variables: Mapped values from the API response that can be referenced after execution.
Step-by-Step: Get an Agent to Use a Tool
If you want your agent to use a custom tool, you must both create the tool and explicitly instruct the agent to use it.
Create and configure the tool in the Tools section.
Open Agents and select the agent you want to update.
Click Edit agent.
Scroll to the Agent instructions section.
Add the tool in the Select tools field so the agent has access to it.
In the instructions text, explicitly name the tool.
Describe when the tool should be used.
Define any rules or constraints around its usage.
Save the agent configuration.
Step-by-Step: Create a Custom Tool
Open Agents from the left-hand navigation.
Click Tools.
Select Create tool.
Choose Custom tool as the tool type.
Enter a Tool name and optional description.
Click Save to open the configuration page.
Configure Basic Info
Review or update the tool label and description.
Click Save if changes are made.
Configure Tool Settings
Enter the API URL for the endpoint.
Select the HTTP method required by your API.
Set the Timeout (ms) for how long the agent should wait for a response.
Enable Speak after execution if the agent should respond with results.
Enable Speak during execution for long-running requests.
Enter an Execution message if speaking during execution is enabled.
Configure Request Details
Add Headers as JSON if required by your API.
Add Query parameters as JSON if needed.
Configure Response Variables
Define Response variables to map paths in the API response to usable variables.
Define the JSON Schema
Add schema fields using the visual editor or JSON editor.
Specify each field’s type, description, enum values, and whether it is required.
Reorder or delete fields as needed.
Click Save tool to finish creating the custom tool.
Tips and Best Practices
Always reference the custom tool by name in agent instructions.
Write clear trigger conditions so the agent knows exactly when to use the tool.
Keep schemas minimal and only include required fields.
Validate your API endpoint independently before connecting it to a tool.
Use response variables to return meaningful results to the agent.
Troubleshooting
Issue | Possible Cause | Fix |
Agent never uses the tool | Tool not referenced in instructions | Explicitly name the tool and define triggers |
Tool execution fails | Invalid URL or HTTP method | Verify endpoint and method |
Incorrect request data | JSON schema misconfigured | Review field types and required flags |
Tool times out | Timeout too low | Increase timeout value |
Agent has no access | Tool not selected for agent | Add the tool in the Select tools field |