Intercom
Shopify
Stripe
Slack
Notion
Google Workspace
Confluence
How Do You Build a Custom API Tool for an AI Agent? A Practical Guide
A custom API tool lets an AI agent call any REST endpoint mid-conversation, such as an order system, a shipping tracker or an internal CRM. You define the URL, method, authentication and parameters once, test the tool, and assign it to the agents that need it.
Key takeaways
- A Macha custom API tool is defined by a label and description, an HTTP method and URL with placeholders, an authentication type, parameters and an optional response mapping.
- Macha custom tools support four authentication types: none, an API key in a custom header, a bearer token, or basic auth, with credentials encrypted at rest.
- The tool editor's Test button sends a real request with sample values, which catches auth errors, wrong URLs and malformed body templates before an agent uses the tool.
- Response mapping takes a dot path such as data.results, so the agent sees only the array it needs instead of the full nested API response.
- A WISMO agent on Zendesk can chain four tools: Get Ticket, Get Ticket Custom Fields, a custom shipping status tool, and Add Internal Note.
To give a Macha AI agent a custom API tool, you define five things once: a label and description, an HTTP method and URL with {{param}} placeholders, an authentication type (none, API key, bearer token or basic auth), the parameters the agent fills in, and an optional response mapping. The agent then calls that endpoint mid-conversation and uses what comes back in its reply. No code is required, and custom API tools are included on every Macha plan (pricing).
| Setting | What you enter |
|---|---|
| Label and description | What the tool does and when to call it |
| Type | Read (fetches data) or Write (creates, updates or deletes) |
| Method and URL | GET, POST, PUT, PATCH or DELETE; placeholders in double curly braces |
| Authentication | None, API key (custom header), bearer token or basic auth |
| Parameters | Name, type, description and required flag for each placeholder |
| Body template | JSON with placeholders, for POST, PUT and PATCH |
| Response mapping | A dot path, such as data.results, that trims the response |
What is a custom API tool?
A custom API tool is an HTTP endpoint your AI agent can call during a conversation. You create it once for the organization and assign it to any agent that needs it.
You're teaching the agent one rule: "when you need shipping status, call this URL with the order number, and here's what the response means." Credentials are encrypted at rest and never shown to the AI model. Write tools ask for user confirmation before they run in chat.
If you'd rather not fill in the form yourself, the AI Tool Builder (in Macha Experiment Labs) and Sidekick can build the tool from a description: you name the API, paste a credential and a test ID, and it proposes the endpoints, tests them and creates the tools.
What does a shipping status tool look like?
- Method: GET
- URL:
https://www.example.com/api/order/{{order_number}}/shipping-status - Auth: none (public tracking endpoint)
- Parameter:
order_number(string, required): "The 12-digit order number including leading zeros"
When the agent needs an order's status, it takes the order number from the ticket or a custom field, calls the URL, and gets back the carrier, tracking events and delivery date.
How do you make a custom tool reliable?
- Write descriptive labels. Include the service and resource: "Shop: Get Order Shipping Status", not "Get Status". The agent picks between tools by label when several are assigned.
- State the parameter format. "12-digit number starting with 01, preserve leading zeros."
- Test before you assign. The tool editor's Test button sends a real request with sample values, so you catch auth errors, wrong URLs and malformed body templates before an agent does.
- Use response mapping. If the API wraps its data, set the dot path (for example
data.resultsororder) so the agent sees only the part it needs.
How do custom tools combine with help desk tools?
Custom tools sit next to the built-in connector tools on an agent's Tools tab, and an agent can only use tools assigned to it. A WISMO agent on Zendesk might use:
- Get Ticket (Zendesk): read the customer's message
- Get Ticket Custom Fields (Zendesk): pull the order number from a ticket field
- Get Shipping Status (custom tool): call the shop's API with that number
- Add Internal Note (Zendesk): post the drafted reply for human review
Four tools, one agent, and no one copies an order number between tabs. The same pattern works on Zendesk, Freshdesk, Gorgias, Front, HubSpot or Intercom. The full field reference is in the custom tools docs.
Resolve tickets automatically with AI agents
Macha's AI agents work on top of the help desk you already use — no code.
