Skip to main content
This page walks through Tools → New Tool from an empty form to a tool your agent calls in a test conversation. Read Custom tools overview first if you have not decided what the tool should do.

​
Before you start

  • The API endpoint: an https:// address, the method, and which values it expects in the path, query string, or body.
  • Any key or token the API needs, to put in a header. Keys go in Headers, never in the URL.
  • A clear sentence about when the agent should use the tool. You will put it in Description.

​
Optional: start from the API documentation

The AI-Assisted Tool Creation card at the top of New Tool can fill the form for you from a public documentation page.
1

Paste the documentation address

Enter the page in Documentation URL and click Extract API Information. The page must be publicly reachable; local or private addresses, and addresses with a username and password, are refused with Unsupported documentation URL. Use Sample Data fills the form with an example instead, if you want to see what the extractor produces.
2

Wait for the extraction

Extraction takes up to 60 seconds. When it finishes, Tool parameters extracted! appears and the name, description, method, URL, headers, query parameters and body parameters are filled in. If it takes longer, you get API extraction timed out; try again or fill the form by hand.
3

Review everything

Check each field against the documentation. Placeholders such as Bearer <token> in Headers must be replaced with your real value, and parameters the extractor guessed may need better descriptions.

​
Basic Information

​
API Configuration

1

Method and URL

Choose the HTTP Method (GET, POST, PUT, DELETE) and enter the URL. For values that belong in the path, use curly braces: https://api.example.com/tickets/{ticketId}. Do not add a query string to the URL; define query parameters instead.
2

Headers

Enter each header as a Key and Value, for example Authorization and Bearer sk_live_…. Click Add for more rows.
3

Query Parameters

Click Add Query Parameter for each value that goes in the query string. Path values written as {name} in the URL are also defined here, with Path Param ticked.
4

Body Parameters

For any method other than GET, click Add Body Parameter for each field of the JSON body.

​
Parameter fields

​
Parameter Source Configuration

Each parameter has a source that decides where its value comes from at call time: For the last two sources, a Preview: line under the parameter restates the choice in plain words.

​
Save the tool

Click Save Tool. The toast Tool Saved confirms it, and the tool appears in Tools. Two checks run first:
  • Path Parameter Error: the URL contains a {name} with no matching parameter. Add the parameter and tick Path Param.
  • Unused Path Parameters: a parameter has Path Param ticked but the URL has no {name} for it. Add it to the URL or untick the box.
Header values are hidden after saving. When you reopen a tool, a header with a stored value shows Saved — leave blank to keep in its Value field. Leave it blank to keep the stored value, type a new value to replace it, or remove the row to clear it. The key is matched regardless of capitalisation, so retyping x-api-key for a stored X-API-Key keeps the value.

​
Edit a saved tool

Open the tool from Tools (the pencil on its card), change what you need, and click Save Tool. You can edit a tool while agents have it turned on: the tool is updated in place, and every copy your agents hold in this workspace is updated with it. A header value you type applies to those copies too; a value you leave blank stays as each copy has it stored. A tool that was public stays public, with the same image. A new URL, method or header value applies to the agents’ next calls. A new name, description or parameter set is part of each agent’s published version, so click Save & review and Publish changes on the agent for those to reach customers.

​
Connect the tool to an agent

1

Open the agent

Go to Agents and open the agent that should use the tool.
2

Turn the tool on

In the Tools section, turn on the tool. The tool does not need to be public. Add Tool and Open Marketplace are shortcuts to create or fetch one if the list is empty.
3

Publish

Click Save & review, then Publish changes. Until you publish, live conversations do not have the tool. See Test and publish. If a tool could not be enabled, saving shows Could not enable … The rest of your changes were saved. instead of Draft saved; switch the tool on again and click Save & review.

​
Test it

  1. On the agent page, click Test Agent.
  2. Ask for something only the tool can answer, the way a customer would: Where is my repair? Ticket 482913.
  3. Check the reply against your system, then open the test conversation in the Inbox and click the tool name under the reply. Message Source shows the Source Tool that ran.
If the agent never calls the tool, sharpen the Description and the parameter descriptions; that is all the agent has to go on. If it calls the tool but replies with an error, check that the URL is https:// with no query string and no username or password in it, that it is not a private or internal address, that the header value is correct, and that your API returns JSON.

​
Delete a tool

On Tools, click the trash icon on the tool’s card and confirm Confirm Deletion. Deletion is refused with Failed to delete tool … Make sure it’s not connected to any AI Agents. while an agent has the tool turned on; turn it off in the Tools section of each agent and publish those agents first.