Skip to main content
A tool is something your agent can do mid-conversation that it could not do with words alone: check a calendar, look up an account, write a record back to your CRM. You build a tool, then tag it into every prompt that should call it. The examples here build tools for a front desk agent at Northwind Dental, a fictional practice.

​
Prerequisites

  • An agent to tag tools into, from Agent builder
  • The API you want to call, and a key for it if it needs one

​
Where tools live

Tools appears at two scopes, and they are not the same view. The selector at the top of the sidebar decides which one you are on. It reads All agents for the whole organization, or the agent’s name when you are inside one. Switching it leaves you on Tools. At All agents, under Resources, you get four tabs: Inside an agent, under Build, you get only that agent’s tools, and no tabs: the other three live at All agents. Which scope you create from decides which list the tool appears in. Create from inside an agent and the tool shows on that agent’s Tools page. Create from All agents and it shows only there, on no agent’s page, though any agent can still tag it in a prompt. On an agent’s Tools page, the Library toggle beside the search lists tools from your other agents, each with a + that copies it onto this one. It appears once the organization has more than one agent.

​
Three kinds of tool

Which one you want depends on what is on the other end.

​
Webhook

Calls an HTTP endpoint you already have. You supply the request, and you describe what comes back. This is the common case. Start here unless you know you need one of the other two.
Searching for custom APIs? That is a webhook tool.

​
Custom code

Runs code you write, for the cases a single HTTP call cannot cover: reshaping a response, calling two services and combining them, or a calculation the agent should not be doing in its head. This is not the custom code node you place inside a pathway. Same name, different thing: a tool is called from a prompt, a node is a step inside a pathway.

​
Integration

Talks to a service you have connected, like a CRM. Pick the connection and the action, and the fields come from the service rather than from you. You connect an account once with Add connection, under Connections, and then build as many tools on it as you need. One CRM connection can power a tool that creates a contact, another that looks one up, and a third that logs a call. The integration builder also offers New connection at the top of its connection list, which opens the same flow without leaving the tool. Bland’s own actions need no connection. Ending a call, transferring one, pressing a button and sending an SMS are integration tools like any other, but they act on the call the agent is already in, so there is no account to connect. That is why End Call sits in your tool list carrying an icon of its own.

​
Build a webhook tool

From inside your agent, open Tools, then Create tool, and choose Webhook. If you already have a working curl, choose Import from cURL instead, in the same list. Paste the command and it opens the builder with the request filled in.
1

Name it

The name is what you type after @ in a prompt, so make it the thing it does. Check calendar reads better in a prompt than GET /availability.
2

Describe when to use it

The description is not documentation. The agent reads it to decide whether this is the moment to call the tool.Write the trigger, not the mechanism:
Look up open appointment slots for a given day. Use this when the caller asks what times are available, before offering any specific time.
A vague description is the most common cause of a tool firing at the wrong moment.Agent speech, directly below it, is what the agent says out loud while the tool runs. “One moment while I look that up” costs nothing and is the difference between a pause and dead air.
3

Point it at your endpoint

URL, method, headers, body. Anywhere a value should change per call, write a variable: {{date}}, {{phone}}.The tabs under the URL are Query, Authorization, Headers and Body. Query mirrors whatever is already in the URL, and Body is not there at all until you pick a method that has one.The method list offers five verbs. Webhook tools run GET and POST. Pick one of the other three and the tool tests fine and then refuses to save, with a message that says only Failed to create tool. The reason is the method.For an API key, do not type it here. Reference a secret, and create it before you reach the test step.
4

Say which variables the agent fills in

The variables you wrote into the request are collected under Detected variables, below the request tabs. Each one gets a row, and each row is a decision about where its value comes from.Add input variable means the agent fills it from the conversation. It moves into the Variables table, where you give it instructions, a type, and whether it is required. The instructions are what the agent reads, so write them for a person: “The day to check, as YYYY-MM-DD.”The Audio column on that table pulls the value from what the caller said rather than from the transcript. It costs latency and it is worth it for the things transcription gets wrong: spoken numbers, dates, spellings.Leave a variable alone, or dismiss it with the X, and it resolves from variables already on the call instead. The agent never fills it.
5

Declare what comes back

Output fields, sometimes called request variables, name the parts of the response the agent can use. Each row is a name, a type, and a path into the response.Only the fields you check are available to the agent. Everything else is ignored.The table opens on three rows, ok, message and data. The data row has a chevron: expand it for the three below.ok and message come pre-checked. The rest is yours to choose, and the rows below the table are yours to write: give one a name and a JSONPath and you can pull a single field straight out of the response body.The builder lists these rest_api_get_* paths whatever method you pick. A POST tool returns the same three fields named rest_api_post_*. So on a POST tool, take ok and message now. Save it, reopen, and check the rest_api_post_* rows then.Keep ok checked. A failed call returns ok and message and nothing else, so every path under data comes back empty. ok is the only signal that the call did not work.Each row shows its name wrapped as {{output.name}}. That is the table’s label, not the reference. What you write in a prompt is the bare name, {{name}}.
Checking at least one output field is what makes the tool wait for a response.Check nothing and the tool fires and moves on, which is right for logging and wrong for anything the agent needs an answer from.
6

Test it

Run the tool with sample values and check the response before you attach it to anything.
Three settings sit below the output fields. Timeout is how long to wait before giving up, in milliseconds, from 1,000 to 60,000. Cooldown is the minimum gap between calls, in seconds, from 1 to 30, and a tool with the field left empty still gets 4 seconds. Cache responses is the third, and it does nothing on a tool. The switch saves, and nothing at call time reads it. Leave it alone and assume every call reaches your endpoint.

​
Store credentials as secrets

Do not paste an API key into a tool. Put it in Secrets and reference it. Secrets live at All agents, under Tools, on the Secrets tab. Add Secret creates one, and the value is never shown again after you save it. Creating a secret needs the owner, admin or operator role. Without one, Add Secret is visible but disabled. The same secrets under Settings, in Developer, sit behind a page only an owner or admin can open. There are two kinds, and each row on the tab is labelled with which it is. Static is a value you paste in, like an API key. It changes only when you change it. Refresh is a value Bland fetches on a schedule, so the agent never holds an expired token mid-call. You give it a URL, a method, headers or body, how often to refresh, and the path to the value in the response. The interval runs from 10 minutes to 24 hours. Three ways to reference one. The Authorization tab starts on No Auth, and the secret picker only appears once you choose Bearer Token or API Key. Choose a secret there and the builder stores a reference to it. API Key adds a Header name field, which falls back to X-API-Key if you leave it blank. The picker also has a Create New Secret link, which opens the same dialog without leaving the tool. It stays clickable without the role, and the server refuses the save. In a header, paste the reference. Every row on the Secrets tab shows its own reference beside the name, with a button that copies it. Copy it rather than typing it: the copied reference points at the secret by id, so a rename leaves every header working. In a body field, the copied reference does not work. Write {{secret.NAME}} instead, using the secret’s name. Headers resolve both forms. Bodies resolve the name form only: an id reference reaches your endpoint as the literal text {{secret.id.…}}. Nothing flags it, and the builder’s test passes, because the test takes a different path from a real call. The name form is the one a rename breaks, so a secret referenced from a body is worth renaming carefully. Secrets are organization-wide. Store one and every agent can use it. Rotate the value and every tool that references it follows.

​
Tag a tool into a prompt

Building a tool does not give it to an agent. Tag it. In the agent’s Prompt, type @ and pick the tool by name. The Tool references section below the prompt then lists it. Tools attach per prompt, not per agent. A tool tagged in the agent’s prompt is available while the conversation is on the agent, and it does not follow the agent into a pathway, a branch of the agent’s behavior with instructions of its own. If booking lives in its own pathway, tag the calendar tool there too.
Tagging gives the agent its own copy of the tool.To change a tool an agent already uses, open it from that agent’s Tool references row. That saves both.Editing the same tool from the Tools page changes only the original. The agent keeps running its copy, and opening the tool from the agent afterwards shows you the original, so the change looks like it applied when it has not.
The check is Tool references itself. Only tagged tools appear there, so the list is the attachment. A tool you built that is missing from it is tagged in no prompt and will never be called. Knowledge references, directly below it, is not that kind of list. A source can be attached without being tagged, so what it shows is not the whole set. See Knowledge.

​
Watch how tools perform

Analytics shows call volume and failure rate per tool. The number worth watching is the failure rate. A tool that fails quietly leaves the agent improvising in the middle of a call, and the caller hears an agent that has lost the thread rather than an error.

​
Common failures

Look at Tool references under the prompt. If the tool is not listed, it is not tagged, and it will never be called. Tag it in the prompt where it should run.
Tools do not follow the agent into pathways. Tag it again inside that pathway.
Tagging attached a copy. An edit made on the Tools page changes the library only, and nothing on the agent pulls it in. Open the tool from Tool references and make the same change there. That saves the agent’s copy and the library together. Keep editing it there from then on: an edit made from the agent writes its copy over the library row.
The agent chooses from the description. Rewrite it to say when to use the tool and when not to, rather than what the endpoint does.
Check Output fields. Only the fields you checked are available to the agent, so a path you left unticked is not there to be read. Check the paths too: a path that does not match the response resolves to nothing, and the agent gets an empty value rather than an error.
The tool is reaching your API and your API is refusing it. If the credential is in a body, check whether the secret has been renamed, because a body reference names the secret and a rename breaks it. If it is in a header, check the secret still exists at all. On a Refresh secret, check that the interval is shorter than the token’s lifetime.
Raise Timeout, or make the endpoint faster. Then fill in Agent speech, because a caller with nothing to listen to hears dead air rather than a wait.

​
Next steps

Agent builder

Tag tools into a prompt, and the rest of building an agent.

Knowledge

Answer from documents rather than by calling an API.
Docs for agents: llms.txt