How do I create a custom tool for an AI agent?

Last updated: November 5, 2026

Custom tools let an AI agent call your own API endpoint during a conversation or call. After creating the custom tool, you must also add it to the agent and instruct the agent when to use it.

Before you start

  • Confirm the API endpoint you want the tool to call is available and tested.

  • Prepare any required headers, query parameters, and request fields.

  • Know which response values the agent needs after the tool runs.

Steps

  1. Open Agents.

  2. Click Tools.

  3. Select Create tool.

  4. Choose Custom tool.

  5. Enter a tool name and optional description.

  6. Click Save to open the configuration page.

  7. Enter the API URL.

  8. Select the HTTP method required by your API.

  9. Set the timeout.

  10. Add headers or query parameters if your API requires them.

  11. Define response variables for values the agent should use later.

  12. Define the JSON schema for the inputs the agent can send.

  13. Save the tool.

  14. Open the agent that should use the tool.

  15. Add the tool in Select tools and describe when to use it in the agent instructions.

Tips

  • Keep the JSON schema focused on the fields the API truly needs.

  • Use field descriptions that explain what each value should contain.

  • Reference the custom tool by exact name in agent instructions.

  • Use response variables for outputs the agent should mention or use in follow-up logic.

Troubleshooting

  • Tool execution fails: Verify the endpoint URL, HTTP method, headers, and request schema.

  • The request sends incorrect data: Review the JSON schema field types and required fields.

  • The tool times out: Increase the timeout or optimize the API response time.

  • The agent does not use the tool: Add the tool to the agent and explicitly describe its trigger conditions.