Building Custom API Tools for AI Agents: A Practical Guide
Your AI agent can read Zendesk tickets and search your knowledge base. But what about your order management system? Your shipping provider's tracking API? Your internal CRM? Custom API tools let you connect any REST endpoint to your AI agent — so it can look up orders, check inventory, verify payments, or call any service your business runs on.
What is a custom API tool?
A custom API tool is a configured HTTP endpoint that your AI agent can call during a conversation. You define the URL (with parameter placeholders), the HTTP method, authentication, and a description that tells the AI when to use it. The agent calls the tool, gets the response, and uses the data in its reply.
No code required. You're essentially teaching the agent: "when you need shipping status, call this URL with the order number, and here's what the response means."
Anatomy of a custom tool
Every custom tool has:
- Name and description — the AI reads this to decide when to call the tool. Be specific: "Look up the shipping status of a your shop order by order number" is better than "Get order status".
- Method + URL — e.g.,
GET https://api.yourshop.com/orders/{{order_number}}/status. Parameters in double curly braces are replaced at runtime. - Parameters — each placeholder gets a name, type, description, and required flag. The AI fills these from the conversation context.
- Authentication — none, API key, bearer token, or basic auth. Credentials are encrypted and never exposed.
Example: shipping status lookup
A real-world example — connecting a shipping-status endpoint:
- 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 to check an order's status, it extracts the order number from the ticket (or custom field), calls this URL, and gets back the carrier, tracking events, and delivery date. It then formats a customer-friendly response.
Best practices
- Write descriptive tool labels. Include the service name and resource: "your shop: Get Order Shipping Status" not "Get Status". The AI uses the label to decide which tool to call when multiple are available.
- Keep parameter descriptions clear. Tell the AI the format: "12-digit number starting with 01, preserve leading zeros." The AI is surprisingly good at following format instructions.
- Test before attaching to agents. Use the built-in test endpoint to verify the URL, auth, and response shape before adding the tool to a production agent.
- Use response mapping. If the API returns a deeply nested response, set the response-mapping field (e.g.,
order) to strip the outer wrapper. The AI sees cleaner data and makes better decisions.
Combining custom tools with Zendesk
The power of custom tools is in combination. A WISMO agent might use:
- Get Ticket (Zendesk) — read the customer's message
- Get Custom Fields (Zendesk) — extract the order number from a Zendesk field
- Get Shipping Status (custom tool) — call the shop's API with the order number
- Add Internal Note (Zendesk) — post the drafted response for human review
Four tools, one agent, fully automated. The custom tool bridges the gap between your support platform and your business systems.
