> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authoring OpenAPI based tools

OpenAPI tools provide a quick way to consume remote web services that include an OpenAPI specification file.

For watsonx Orchestrate to use an OpenAPI tool, the following conditions must be met:

* Endpoints must accept and return **JSON**.
* The specification must include a **servers** block with exactly one URL. This URL cannot contain parameterization.
* Each path that exposes an endpoint must include an **`operationId`**. This value becomes the tool name. For best results, use snake\_case for `operationId` values.
* Each path that exposes an endpoint must include a **description**. The agent uses this description to decide when to use the tool and what the tool does.
* The OpenAPI version must be 3.0.

Here is an example of a minimal OpenAPI specification:

```yaml YAML theme={null}
servers:
- url: mytoolserver
paths:
/:
   get:
      operationId: my_tool
      description: The description of the tool that clearly explains its purpose to an LLM
      requestBody:
         ...
      responses:
         ...
```

## Importing OpenAPI based tools

To import an OpenAPI tool, run:

```bash BASH theme={null}
orchestrate tools import -k openapi -f <file-path> -a <app-id>
```

<Expandable title="command flags">
  | Flag              | Type   | Required | Description                                                                                                                        |
  | ----------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
  | `--kind` / `-k`   | string | Yes      | The kind of tool to import, this is always `openapi` for OpenAPI based tools.                                                      |
  | `--file` / `-f`   | string | Yes      | The path to the file of the openapi spec you want to import (or a URL containing the file).                                        |
  | `--app-id` / `-a` | string | No       | The application id of a [connection](/connections/overview) which can be used to authenticate against this endpoint (at most one). |
</Expandable>

## Additional features of OpenAPI tools

<AccordionGroup>
  <Accordion title="Securely providing credentials">
    OpenAPI tools are fully compatible with the watsonx Orchestrate Connections framework. A connection represents a dependency on an external service and provides a way to associate credentials with a tool. Supported authentication methods include Basic, Bearer, API Key, OAuth, and IDP SSO flows.

    Connections are referenced using an application ID (app\_id), which serves as the unique identifier for a connection. Each OpenAPI tool can be associated with only one connection app\_id.

    For more information, see [Connections](/connections/overview).
  </Accordion>

  <Accordion title="Asynchronous tools with callbacks">
    OpenAPI tools are one of the two tool types that support **asynchronous operations**. These tools perform an action and then poll a status endpoint until the long-running process completes. Unlike synchronous tools, asynchronous tools can exceed the **40-second execution timeout** in the UI.

    To create an asynchronous OpenAPI tool, your OpenAPI specification must include a **`callbackUrl`** header parameter as defined in the [OpenAPI Callback Specification](https://swagger.io/docs/specification/v3_0/callbacks/).

    * Use **`callbackUrl`** exactly as the header parameter name; other names are not supported.
    * The only supported content type for the callback response is **`application/json`**.

    ```yaml YAML theme={null}
    servers:
      - url: mytoolserver
    paths:
    /:
       post:
          operationId: myTool
          summary: myName
          description: the description
          parameters:
            - in: header
              name: callbackUrl
              description: The callback URL
              required: true
              schema:
                type: string
          requestBody:
             ...
          callbacks:
            callback:
              '{$request.header.callbackUrl}':
                post:
                  requestBody:
                  ...
                  responses:
                  ...
    ```
  </Accordion>
</AccordionGroup>

## Limitations and considerations

Using OpenAPI tools with your agents is straightforward, but default OpenAPI specifications often perform poorly as agent tools for the following reasons. If any of these issues apply to your use case, consider adjusting your OpenAPI specification or using [Python tools](/tools/create_tool) instead.

1. **OpenAPI endpoints are designed for developers, not agents.**
   * Developers can rely on context from other endpoints and external documentation to understand an endpoint's purpose. **Agents cannot**. **All necessary context** *must* be included within the endpoint itself.
   * OpenAPI endpoints often include large sets of input arguments. In contrast, tools should have focused inputs and outputs that resolve a single task. For more information, see [Designing agents and tools for best performance ](../getting_started/guidelines#designing-agents-and-tools-for-best-performance).
2. **Agents require a highly descriptive semantic layer.**
3. **OpenAPI tools do not support `x-ibm-` extensions** used in older watsonx Orchestrate Skills.