Custom tools: connect any API
Outcomes
A tool is a doorway out
Many tools are already waiting to attach: the CRM lookup, the calendar, the messaging tools. This step is the other case, the one that makes "connect any API" true: building a custom tool to reach a system the platform does not already connect to.
A tool is how a capability reaches another system, the actual call to its API. The AI decides when to walk through the doorway, and the tool defines what is on the other side and what comes back. Build the doorway well and the AI uses it exactly when its capability says to.
Start from a working call
The fastest reliable way to build a tool is to get the API call working on its own first, outside the platform, in a tool like Postman or from the command line. Once the call returns what you expect, you import it and the platform reads the shape of it for you.
A URL is the address the tool calls, like the phone number the AI dials to reach the other system. The method is what it is asking for:
| Method | What it means |
|---|---|
| GET | Give me some information |
| POST | Create or send something new |
| PUT / PATCH | Change something that exists |
| DELETE | Remove something |
The other system's API documentation tells you which method and URL to use. You are not guessing; you are copying what its docs already spell out. When a system gives you an example as a cURL command (a single line that makes the call), importing it fills in the method, URL, headers, and parameter names automatically.
The four parts of a tool
Every custom tool is four things:
- Description: what the tool does, in plain language. The AI reads this to decide whether this is the right doorway.
- Method and URL: where it calls and what it is asking for, from the table above.
- Headers: the metadata sent with every call, including how the tool proves it is allowed in (below).
- Parameters: the values the call needs. Each parameter has a description (where the value comes from), a Required flag, and a "Set by AI" toggle. Turn Set by AI off when the value is always the same, and the tool uses a fixed value instead of letting the AI fill it.
The parameter descriptions do the heavy lifting. "The order number from the customer's message, eight to ten digits" tells the AI exactly what to put there. When a tool sends the wrong thing, a vague parameter description is usually why.
Authentication: proving the tool is allowed in
Most systems will not open the door without proof of who is knocking. That proof travels with the call, and the system's API docs tell you which kind it expects:
| Strategy | How it travels | When you see it |
|---|---|---|
| API key | A key in a header or in the URL | The most common; simple systems |
| OAuth 2.0 | A token you obtain, then send on each call | Systems with user accounts and permissions |
| Basic auth | A username and password, encoded | Older or internal systems |
Whichever it uses, one rule holds: give the tool the narrowest access that does the job, and keep credentials out of anywhere they could be seen, including screenshots you share.
There is also a newer option, an MCP connection, which links a whole set of tools at once instead of one call at a time. It is offered as a tool type when you add a tool; reach for it when a system publishes an MCP surface.
Read what it actually sent
When a tool misbehaves, do not guess. After the AI uses it, open the Explanation view on the message to see the exact values the tool sent to the API. That tells you whether the tool sent the wrong thing (fix the parameter description) or the API rejected a correct call (fix the connection or the auth).
Test on purpose, not just the happy path: the missing value, the wrong format, the request that names two things at once. If you cannot tell whether the tool or the API is the problem, run the call again on its own outside the platform to isolate it.
Find any public API you can call without an account, like a weather service or a public directory, and get one request working from the command line or Postman. That single working call is exactly the raw material a custom tool imports. You will build one for real in the lab.
Knowledge Check
Three quick questions on when a job needs a tool, choosing authentication, and reading what a tool sent.