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:
| What the API wants | What you put in Headers | Works as a custom tool? |
|---|---|---|
| An API key | Authorization: Bearer YOUR_KEY, or whatever header name the API documents | Yes. This is the common case. |
| Basic auth | Authorization: Basic <base64 of user:password> | Yes, as a static value. |
| A short-lived OAuth token | Authorization: Bearer <token you obtained elsewhere> | Only until it expires. The platform will not refresh it for you. |
A custom tool authenticates by sending headers. It does not run a login flow, so there is nowhere to put a client ID and secret and nothing that renews a token on your behalf. If the API you want needs a live token exchange, you have two honest options: get a long-lived key from that provider instead, or put a small service of your own in between that holds the credentials and exposes one simple endpoint your tool can call.
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. Isolate the call: take the same method, URL, headers, and parameter values the tool would send, and run that exact call again on its own outside the platform. If it succeeds there, the tool sent the wrong thing (fix the parameter description). If it fails the same way, the API is rejecting 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.
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.