# Custom Tools

Custom tools let you connect OneByZero Neo agents to your own APIs — internal microservices, enterprise data systems, third-party services, or any backend that exposes an HTTP interface. They are created from an OpenAPI specification, which Neo uses to understand the API’s capabilities and invoke it correctly at runtime.

[![Custom Tools panel](../../images/foundry-integrations-custom.png)](../../images/foundry-integrations-custom.png)

## Creating a Custom Tool

Click the **+ Create** button on the **Custom Tools** tab to open the creation form.

**Tool Identity**

- **Name** — the display name shown on the tool card and in the agent builder.
- **Description** — a description of what the tool does. This description is visible to agents when deciding which tool to call, so make it accurate and specific.
- **Logo** — optional emoji or image icon for the tool card.

**API Specification**

Paste or upload your API spec in **OpenAPI format** (JSON or YAML). Neo parses the spec to extract the available operations, their parameters, and their response schemas. The spec must accurately describe the API — Neo uses it as the sole source of truth for how to call the API.

After parsing the spec, Neo lists the detected operations (tools) from the schema. Each operation becomes an individually callable tool within the custom tool. You can edit the **name** and **description** of each extracted operation to make them more useful as agent tool descriptions.

**Endpoint**

The base URL of your API. For internal APIs, this must be accessible from the Neo deployment network. Options include:

- Internal API gateway endpoints
- Cloud-hosted service URLs
- Private microservice endpoints accessible via network peering or a VPN
- External third-party API endpoints

**Authentication**

Most APIs require authentication. Choose one of four options in **Authentication Type**:

- **None** — no authentication. Use for public APIs or APIs where authentication is embedded in the endpoint URL.
- **API Key (Header)** — the API key is sent as an HTTP request header. You configure the header name and key value. For APIs that expect a `Bearer` or `Basic` prefix, set the appropriate prefix in the header configuration.
- **API Key (Query)** — the API key is appended as a query parameter in the request URL. Configure the parameter name and key value.
- **Credential provider** — the tool authenticates with OAuth 2.0 using a credential provider from **Integrations → Providers → Custom Tool Credentials**. Select it in the **Credential provider** field.

Credentials entered here are stored securely in the platform and are used at runtime whenever an agent calls the tool. Individual agents do not store credentials — they reference the Foundry configuration.

**Credential providers**

A credential provider stores an OAuth 2.0 client once so several custom tools can use it. To create one, open **Integrations → Providers → Custom Tool Credentials** and click **+** (**Create Credential Provider**):

[![New credential provider form](../../images/integrations-credential-provider-form.png)](../../images/integrations-credential-provider-form.png)

| Field | Description |
| --- | --- |
| **Name** | A name for the credential provider. Required. |
| **Type** | **OAuth 2.0 — Client credentials** or **OAuth 2.0 — Authorization code**. Required. |
| **Provider** | The identity provider. Required. |
| **Discovery URL** | Optional. Click **Fetch** to fill in the authorization and token URLs from the provider’s discovery document. |
| **Authorization URL** | Required for the authorization code type. |
| **Token URL** | Required. |
| **Client ID** / **Client secret** | The OAuth client registered with the provider. Required. When editing, leave the secret blank to keep the stored value. |
| **Scopes** | Space-separated scopes to request. |
| **Use PKCE** | Turn on if the provider requires PKCE. |
| **Redirect URI** | Shown for you to register with the provider. |

Use **Test connection** to check the configuration, then **Save credential**. For the authorization code type, use **Connect** on the card to sign in to the provider. A credential provider that is attached to a custom tool cannot be deleted — detach it from those tools first.

**Testing**

After entering the spec, endpoint, and authentication, use the **Test API** button to send a test request to a specific operation. This verifies that the endpoint is reachable and the authentication is correct before attaching the tool to agents.

## Managing Custom Tools

Each custom tool card shows:

- Name, description, and logo.
- **Enabled / Disabled** toggle — controls tool availability to agents.
- Tags — apply tags to organise tools by team, use case, or category.
- Last modified timestamp.
- Action menu — **Edit** to update the spec, endpoint, or credentials; **Delete** to remove the tool permanently.

To narrow the list, use the **Ownership** toggle — **All**, **Mine**, or **Shared** — and the **Last Updated** filter (**From** / **To** dates).

Editing a custom tool updates it for all agents that reference it. If you change the API spec in a way that removes or renames operations, agents that call those operations will fail at runtime until the agent flow is updated.

## Best Practices

- Write clear, specific operation descriptions in your OpenAPI spec. Agents use these descriptions to decide when and how to call each operation.
- Version your OpenAPI specs externally (e.g. in a repository) and update the Foundry tool when the API version changes. Avoid letting the tool config drift from the live API.
- Use the Test API feature after any credential rotation or API endpoint change to confirm the tool still works before it is called by production agents.
- For internal APIs, make sure your Neo deployment environment can reach the API endpoint. Test connectivity separately from within the platform network if calls are failing unexpectedly.