> For the full page index, fetch https://echonova.ai/llms.txt

# OpenAPI tools

Import a Swagger or OpenAPI document once so the agent can reach a whole API, and follow the import through its three states.

An OpenAPI tool is one imported Swagger or OpenAPI document. The whole API becomes a
single row in the workspace tool library, and the agent finds the right operation
inside it during a conversation. Import the document once instead of hand building
one [webhook tool](/docs/agents/webhook-tools) per operation.

## What you need

- A Swagger or OpenAPI document as JSON, either as a file or at a public HTTPS URL.
  YAML is not accepted.
- The base URL the API is actually served from. It is required, and it is where
  every call goes.
- Membership of the workspace. Importing needs no further permission.
- Any credential the API requires, saved first as an
  [auth connection](/docs/agents/auth-connections).

## Steps

### Step 1: Open the import form

On an agent, go to the **Tools** tab and press **Add Tool**, then pick the
**OpenAPI** tab. The same dialog is on the **Tool Library** page, described there as
"Create and manage reusable tools for your workspace."

### Step 2: Name the tool

**Name** is required, unique in the workspace and capped at 120 characters. It is
the row you will see in the library, so name it after the API rather than after one
of its operations.

### Step 3: Give the document

Two pill tabs choose the source, and you use exactly one of them.

**Upload Json** opens a drop zone reading "Drop a file here or click to browse" with
"Up to 5 MB per file" underneath. The file is read in your browser before anything
is sent, so a bad file is caught immediately.

**URL** takes a public HTTPS URL to the document. EchoNova fetches it under the same
rules as any outbound call: HTTPS only, public hosts only, JSON only, 5 MB maximum
and a 30 second timeout.

### Step 4: Set the base URL

**Base URL** is required. The hint under it says why: "Base URL is required — the
portal calls the API with it." The document's own `servers` entry is kept as a
fallback, but the value you type is what every call uses, so a document whose
`servers` block points at a staging host does not quietly send traffic there.

The value must be a full public HTTPS URL, matching the placeholder
`https://api.example.com`. A trailing slash is stripped.

### Step 5: Press Add

EchoNova reads the document and creates the library row, which lands with an
endpoint count chip and a status pill.

## Get it right

The agent finds an operation by matching what the caller said against the
operation's description, so that description is what decides whether the operation
is ever reached. Write it in the caller's words, not the API's.

**Recommended**

```text
Check where a customer's order is. Use when the caller asks about delivery, a
missing parcel, a tracking number, or when an order will arrive.
```

**Less effective**

```text
GET /v2/orders/{orderId}/shipment-status
```

## What happens next

The tool appears in **Workspace tools** with its API title, an endpoint count and a
status pill. Select it on an agent the same way as any workspace tool, and the agent
can reach its operations from the next conversation onwards.

Open the row to see what was imported. The detail sheet lists every operation on
its **Endpoints** tab, in a rail on the left, and shows the picked operation's parameters and request body on the right. That
list, the per-operation auth modes and the enable switch are covered on
[OpenAPI tool operations](/docs/agents/openapi-tool-operations).

## The three import states

| State       | Pill          | What it means                                                                  |
| ----------- | ------------- | ------------------------------------------------------------------------------ |
| `importing` | **Importing** | The tool is still being prepared and the agent cannot reach its operations yet |
| `ready`     | **Ready**     | The agent can reach the operations                                             |
| `failed`    | **Failed**    | The import broke. The detail sheet shows **Import failed** with the reason     |

An import is usually **Ready** by the time the dialog closes. While any tool in the
list still shows **Importing**, the portal refreshes the list on its own until none
do. A tool can also turn **Failed** after it first appeared, and the reason is shown
on the row.

An import can also fail before any row is created, which is the common case: a
document that cannot be read, a URL that does not answer, or a selection above the
operation limit. Nothing is saved then, and the dialog shows the error.

## How the agent reaches an operation

An imported API is not put in front of the agent as a list of operations. Webhook,
integration and system tools are in front of it on every turn; imported operations
are not. Each turn the agent searches your imported operations for the ones closest
to what the caller just said, keeps the top 5, and ignores anything scoring below
0.5.

That is what makes a large API workable. A document with two hundred operations
would drown the agent if all of them were listed, so it sees a handful of relevant
ones instead, and asks a clarifying question when nothing clears the threshold.

It also changes what a missed call means. A webhook tool that never fires has a
wording problem in its description. An imported operation has to win a search first,
so it can also miss because the caller's phrasing appears nowhere in the operation's
description.

Database questions are searched in the same pass, so an agent with both a database
and an imported API is choosing between them each turn.

## Testing what the agent would reach

Open the tool from an agent's **Tools** tab, then open its **Tests** tab. Type what a
caller might say and press **Run**. The hint explains the point: "Type what a caller
might say. This runs the same semantic search the agent runs each time, so you can
detect an incorrect match before launch."

Results are ranked with a score, which is a similarity rather than a probability.
Nothing above the threshold is a result too: "There is no match above the specified
minimum threshold. The agent will ask a clarifying question instead of calling an
endpoint."

Two conditions have to hold or there is nothing to search. The tool must be
**Ready**, and it must be selected on the agent you are testing from. The standalone
**Tool Library** page has no agent in scope, so the test is offered on an agent's
**Tools** tab only.

## Updating a changed document

An imported tool keeps the operations it was created with. A document that gains,
loses or renames an operation needs a fresh import:

1. Import the new document as a new tool.
2. Select it on the agents that need it.
3. Check it on its **Tests** tab.
4. Delete the old row.

Deleting removes the tool and its operations and unselects it from every agent that
used it, so do it last. The auth connection is reusable and is not deleted with the
tool.

Two changes do not need a fresh import: switching an operation off and on again, and
changing the credential the tool uses.

## Limits

| Limit                       | Value                                   | Applies to                                 |
| --------------------------- | --------------------------------------- | ------------------------------------------ |
| Document size               | 5 MB                                    | Uploaded files and URL fetches alike       |
| Document format             | JSON object                             | OpenAPI 3.x and Swagger 2.0                |
| URL fetch timeout           | 30 seconds                              | URL sources                                |
| URL scheme                  | HTTPS only, public hosts only           | URL sources and the base URL               |
| Operations per import       | 2000                                    | Refused above it, before anything is saved |
| Tool name                   | 120 characters, unique in the workspace | Import                                     |
| Tool description            | 500 characters                          | Import                                     |
| Operations reached per turn | Top 5, score threshold 0.5              | Shared with database questions             |
| Base URL                    | Fixed at import                         | A different host means a fresh import      |

## Troubleshooting

### "The OpenAPI file must be 5 MB or smaller."

The file picker refuses anything larger before it is read. A document that big
usually carries generated examples. Export it without them, or import a trimmed
document covering the operations the agent needs.

### "Choose a JSON OpenAPI document." or "The selected file is not a valid OpenAPI object."

The file is not JSON, or it reads as something other than a JSON object, such as an
array. Convert a YAML document to JSON first.

### "The URL did not return a JSON OpenAPI document"

The URL answered, but the body was not a JSON object. Point at the raw document
rather than at a documentation page that renders it.

### "Fetching the OpenAPI document failed with status 404"

The URL answered with a non-success status, which appears in the message. The URL is
fetched without any credentials, so a document behind authentication has to be
uploaded as a file instead.

### "Fetching the OpenAPI document failed or timed out"

The host did not answer inside 30 seconds, or it is not publicly reachable over
HTTPS.

### "Base URL is required"

The field was empty or whitespace. An API cannot be imported without knowing where
to call it.

### "This import would persist 2400 operations, which exceeds the 2000-operation limit"

The document is larger than one tool may hold. Import a document that covers fewer
paths. Importing a subset of a document's operations is not available from the
portal today.

### The row shows Failed

Open it and read the reason under **Import failed**. The tool stays in the library
and stays selectable, but the agent cannot reach any of its operations. Fix the
document and import it again.

## FAQ

### Does one import equal one tool?

Yes. One document becomes one library row holding the whole API, and a large
document cannot outgrow that row.

### Are all the operations imported?

Yes. Importing a subset of a document's operations is not available from the portal
today. To stop the agent calling an operation after the import, switch that
operation off.

### Can the agent call an API over plain HTTP?

No. The base URL, the document URL and every outbound call are HTTPS only and public
hosts only.

### Is the document kept?

The operations EchoNova read are kept, with their parameters and request body
fields, so the detail sheet can show a contract without going back to the document.
Deleting the tool removes them.

### Why does the agent ask a clarifying question instead of calling the API?

Nothing cleared the threshold for that turn. Run the same sentence on the tool's
**Tests** tab. If it scores below the threshold, the operation's description is the
thing to change.

### Can I change the base URL later?

The base URL is fixed when you import. To move the API to a different host, import
the document again as a new tool, select it on the agents that need it, and delete
the old row.

## Related

- [OpenAPI tool operations](/docs/agents/openapi-tool-operations): per-operation auth, fixed values and switches
- [The retrieval bench](/docs/agents/tool-bench): check what a caller's wording would reach
- [Auth connections](/docs/agents/auth-connections): the credential this tool sends
- [Webhook tools](/docs/agents/webhook-tools): the right shape for a single endpoint
- [Tools overview](/docs/agents/tools-overview): how the four kinds differ