Build the doorway
Outcomes
Start from a call that already works
The fastest reliable way to build a tool is to get the API call working on its own first, outside the platform, and import it once it returns what you expect. Debugging a call and debugging a capability at the same time is two problems; getting the call working first leaves you one.
You are here: Business App, inside your test account.
This build uses Open-Meteo, a public forecast API that needs no account and no key. Any forecast API works the same way. Open its documentation, find the forecast endpoint, and copy the example request it gives you. Most API documentation shows one as a cURL command, and that single line is everything the import needs.
The method tells the other system what you are asking for, and its documentation tells you which one to use:
| Method | What it means |
|---|---|
| GET | Give me some information |
| POST | Create or send something new |
| PUT / PATCH | Change something that exists |
| DELETE | Remove something |
A forecast lookup reads and changes nothing, so it is a GET.
Import the call and name what it does
Labcreate the capability
Go to AI → Workforce, then your employee's Configure page → Capabilities → + Add a capability.
Labimport the call as a tool
Stay on the WeatherCheck capability, under Tools.
Done to keep it.The description is not a label. The AI reads it to decide whether this is the right doorway for the moment in front of it, so it earns real attention when an employee carries several tools.
Parameter descriptions do the heavy lifting
Every custom tool is four things: a description, a method and URL, headers, and parameters. The first three are copied from the other system's documentation. The parameters are where your judgment goes.
Each parameter row carries a Parameter key, a Location, a Type, a Required checkbox, a Set by AI checkbox that is on by default, and a Description. The description is what the AI follows mid-conversation, so write it as an instruction rather than a label:
- The date. "The date the visitor wants, from their message. Convert phrases like next Tuesday to a date formatted YYYY-MM-DD. If no date is given, ask for one." Set by AI stays on, because this value comes from the conversation.
- The location. The business does not move between conversations, so clear
Set by AIand set the value once. The AI should only fill in what genuinely comes from the visitor.
When a tool sends the wrong value, a vague parameter description is almost always why. "The date" tells the AI nothing about format or fallback; the sentence above tells it both.
Proving the tool is allowed in
Open-Meteo opens without proof of who is knocking. Most systems will not, and the proof travels in the headers. The other system's documentation names which kind it expects:
| What the API wants | What goes in Headers | Works as a custom tool |
|---|---|---|
| An API key | Authorization: Bearer YOUR_KEY, or whatever header name it documents | Yes, and 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 <a token you obtained elsewhere> | Only until it expires |
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 renews a token on your behalf. When an API needs a live token exchange, there are two honest routes: ask that provider for a long-lived key 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, give the tool the narrowest access that does the job, and keep credentials out of anywhere they could be read later.
Write the capability prompt
The tool is the hands. The prompt is the judgment, and it is what decides whether the tool fires at the right moment. A reliable capability prompt answers four questions in order: when to act, what to collect first, how to respond, and what to do when something goes wrong.
Labreplace the TBD with a four-part prompt
Go back to the WeatherCheck capability's Prompt field.
Written out, it looks like this:
# Check the weather before outdoor bookings
## When to use
- ONLY use GetForecast when the visitor is booking an outdoor service:
gutter cleaning, lawn care, exterior work.
- Do NOT use it for indoor services or general questions.
## What you need first
- The day the visitor wants, and the service they are booking.
## How to respond
- If the forecast is clear, continue the booking as normal. Do not
mention the check.
- If rain or high wind is forecast, say so and offer the nearest
clear day instead.
## When something goes wrong
- If no forecast comes back, continue the booking and let the visitor
know a team member will confirm the day before.
Write yours in your own words, and keep all four parts. Almost every capability that misfires is missing one of them: no clear trigger, so it fires at the wrong moment, or no error path, so an empty response becomes an awkward answer.
Read your prompt back as if you were briefing a new hire on their first day. Any sentence that would not change what they do is noise. Cut it before you test.
Knowledge Check
Three quick questions on the cURL import, parameter descriptions, authentication, and the four-part prompt.