> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oumi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TOOL IMPLEMENTATION SCHEMA

> Request and response schemas for tool implementations

## OVERVIEW

A tool implementation decides how calls to one tool are answered. This page describes the request bodies used to create, update, and test one, and the responses Oumi returns. For a task-oriented introduction, see [Tool implementations](/guides/agents/tool-implementations).

All routes are under `https://api.oumi.ai/v1/projects/{project_id}/tools/{tool_id}/implementations`. Authenticate with the `X-API-Key` header.

| Method | Path | Description |
| - | - | - |
| `POST` | `/implementations` | Create an implementation of the tool |
| `GET` | `/implementations` | List the tool's implementations |
| `GET` | `/implementations/{implementation_id}` | Get an implementation |
| `GET` | `/implementations/{implementation_id}/config` | Get an implementation's configuration |
| `PATCH` | `/implementations/{implementation_id}` | Rename an implementation or rotate its credential |
| `POST` | `/implementations/{implementation_id}:execute` | Run one tool call through an implementation |
| `DELETE` | `/implementations/{implementation_id}` | Delete an implementation |

***

## CREATE REQUEST

```json theme={null}
{
  "displayName": "Order Lookup",
  "config": {
    "type": "lookup",
    "lookupTable": []
  }
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| displayName | string | ✓ | Display name, 1 to 128 characters, without `<`, `>`, or `&` |
| config | object | ✓ | Implementation configuration; `config.type` selects the shape |

`config.type` accepts `lookup`, `simulated`, `endpoint`, or `interactive`. The type cannot change after creation.

***

## LOOKUP CONFIG

```json theme={null}
{
  "type": "lookup",
  "lookupTable": [
    {"input": {"orderId": "A-100"}, "output": {"status": "shipped"}},
    {"input": {"orderId": "A-101"}, "output": {"status": "processing"}}
  ]
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| type | string | ✓ | Must be `lookup` |
| lookupTable | object\[] | ✓ | Rows that map tool inputs to outputs |

Each `lookupTable` row contains:

| Field | Type | Required | Description |
| - | - | - | - |
| input | object | ✓ | Tool arguments this row matches |
| output | any | ✓ | JSON value returned when a call matches `input`; may be `null` |

A call whose arguments match no row is refused. The refusal reaches the model as the tool's answer.

***

## SIMULATED CONFIG

```json theme={null}
{
  "type": "simulated",
  "toolPersona": "Return a plausible order status. Use realistic order dates and carriers.",
  "modelIdentifier": {"modelType": "ANTHROPIC_API", "modelName": "claude-sonnet-5"},
  "inferenceConfig": {"inferenceTemperature": 0.7},
  "useGuidedDecoding": true,
  "cacheResults": true
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| type | string | ✓ | Must be `simulated` |
| toolPersona | string | ✓ | How the model behaves when it simulates the tool's output |
| modelIdentifier | object | ✓ | Hosted model that generates tool outputs |
| inferenceConfig | object | ✓ | Inference settings for that model; may be `{}` |
| useGuidedDecoding | boolean | | Constrain output to the tool's output schema while generating; defaults to `true` |
| cacheResults | boolean | | Reuse the earlier result for a repeated call with identical arguments; defaults to `true` |

### MODELIDENTIFIER

| Field | Type | Required | Description |
| - | - | - | - |
| modelType | string | ✓ | Hosted model provider |
| modelName | string | ✓ | Provider model name |

`modelType` accepts `ANTHROPIC_API`, `OPENAI_API`, `GEMINI_API`, `VERTEX_API`, or `OUMI_API`. Only hosted models are accepted. Do not set `apiKeys`: Oumi resolves the provider key from the project's API keys for each job.

### INFERENCECONFIG

| Field | Type | Required | Description |
| - | - | - | - |
| inferenceTemperature | number | | Sampling temperature |
| inferenceTopP | number | | Nucleus sampling threshold, greater than `0` and at most `1` |
| inferenceMaxNewTokens | integer | | Maximum number of generated tokens |
| inferenceSeed | integer | | Seed for deterministic generation |
| requestsPerMinute | integer | | Request rate limit |
| guidedDecoding | object | | Not supported; use `useGuidedDecoding` instead |

***

## ENDPOINT CONFIG

```json theme={null}
{
  "type": "endpoint",
  "endpointUrl": "https://tools.example.com/orders/lookup",
  "protocol": {"type": "http", "method": "POST"},
  "auth": {"type": "bearer", "token": "YOUR_SERVICE_TOKEN", "scheme": "Bearer"},
  "timeoutSeconds": 30
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| type | string | ✓ | Must be `endpoint` |
| endpointUrl | string | ✓ | HTTPS URL that receives each tool call |
| protocol | object | | How a call becomes a request; defaults to `{"type": "http", "method": "POST"}` |
| auth | object | | Credential sent with each call; write-only |
| timeoutSeconds | integer | | Seconds to wait for one call, from `1` to `120`; defaults to `30` |

### PROTOCOL

`protocol.type` selects one of two shapes.

| Field | Type | Required | Description |
| - | - | - | - |
| type | string | ✓ | `http` sends one plain HTTP request per call |
| method | string | | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`; defaults to `POST` |

| Field | Type | Required | Description |
| - | - | - | - |
| type | string | ✓ | `mcp` calls the endpoint as an MCP server over Streamable HTTP |

With `http`, `POST`, `PUT`, and `PATCH` send the arguments as the JSON body. `GET` and `DELETE` send them as query parameters. Each request carries the `X-Oumi-Call-Id` and `X-Oumi-Session-Id` headers.

### AUTH

`auth.type` selects one of two shapes.

| Field | Type | Required | Description |
| - | - | - | - |
| type | string | ✓ | `bearer` |
| token | string | ✓ | Credential, up to 255 characters of letters, digits, `_`, `-`, `.`, or `=` |
| scheme | string | | Scheme sent as `Authorization: <scheme> <token>`; defaults to `Bearer` |

| Field | Type | Required | Description |
| - | - | - | - |
| type | string | ✓ | `apiKey` |
| token | string | ✓ | Credential, sent on its own with no scheme |
| headerName | string | ✓ | Header that carries the token, such as `x-api-key` |

`scheme` and `headerName` accept 1 to 64 letters, digits, or hyphens.

***

## INTERACTIVE CONFIG

```json theme={null}
{"type": "interactive"}
```

| Field | Type | Required | Description |
| - | - | - | - |
| type | string | ✓ | Must be `interactive` |

The simulated user in the job answers each call. The served tool's output schema, if it has one, must be an object with exactly one string property and must not require any other property.

***

## IMPLEMENTATION RESPONSE

Create, get, and update requests return the implementation:

```json theme={null}
{
  "id": 412,
  "name": "projects/XFZ7K2/tools/87/implementations/412",
  "displayName": "Order Lookup",
  "implementationType": "lookup",
  "toolId": 87,
  "createdAt": "2026-10-01T17:04:12Z",
  "updatedAt": "2026-10-01T17:04:12Z"
}
```

| Field | Type | Description |
| - | - | - |
| id | integer | Implementation ID |
| name | string | Resource name |
| displayName | string | Display name |
| implementationType | string | `lookup`, `simulated`, `endpoint`, or `interactive` |
| toolId | integer | ID of the tool this implementation serves |
| createdAt | string | Creation timestamp |
| updatedAt | string | Last update timestamp |

The list route returns these objects in `toolImplementations`, with `nextPageToken`, `previousPageToken`, `pageSize`, and `totalCount`. It accepts the query parameters `pagesize` (1 to 100, default 50), `pagetoken`, `sort_by` (`created_at` or `updated_at`, default `updated_at`), and `sort_direction` (`asc` or `desc`, default `desc`).

### CONFIG RESPONSE

`GET .../config` returns the stored configuration in the same shape as the create request, except for endpoint credentials. An endpoint's `auth` omits `token` and returns `stubbedToken` instead:

```json theme={null}
{
  "type": "endpoint",
  "endpointUrl": "https://tools.example.com/orders/lookup",
  "protocol": {"type": "http", "method": "POST"},
  "auth": {"type": "bearer", "stubbedToken": "YOUR...OKEN", "scheme": "Bearer"}
}
```

`stubbedToken` shows the first and last four characters of a longer token and fully redacts a short one.

***

## UPDATE REQUEST

`PATCH` accepts two fields. Omitted fields are left unchanged.

```json theme={null}
{
  "displayName": "Order Lookup v2",
  "auth": {"type": "apiKey", "headerName": "x-api-key", "token": "NEW_SERVICE_TOKEN"}
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| displayName | string | | New display name |
| auth | object | | Replacement credential for an endpoint implementation, in the [AUTH](#auth) shape; applies from the next job onward |

***

## EXECUTE REQUEST

`POST .../implementations/{implementation_id}:execute` runs one tool call the same way a job runs it.

```json theme={null}
{
  "arguments": {"orderId": "A-100"},
  "sessionId": "conversation-1"
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| arguments | object | ✓ | Tool arguments; must match the tool's input schema and serialize to at most 64 KiB |
| sessionId | string | | Groups calls into one conversation; an endpoint receives it with each call; generated when omitted |

### EXECUTE RESPONSE

```json theme={null}
{
  "output": {"status": "shipped"},
  "error": null,
  "callId": "6f1c2e0a9b7d4c3e8a5f2b1d0c9e8f7a",
  "sessionId": "conversation-1"
}
```

| Field | Type | Description |
| - | - | - |
| output | any | The tool's output; absent when the tool refused the call |
| error | string | Why the tool refused the call, in the tool's own words |
| callId | string | Identifies this call; an endpoint receives it with the call |
| sessionId | string | The session the call ran in: the one you gave, or a generated one |

A refusal returns status `200` with `error` set. Check `error` to tell a refusal from a `null` output.

| Status | Meaning |
| - | - |
| `400` | The arguments do not match the tool's input schema, exceed 64 KiB, or the endpoint's answer does not match the tool's output schema |
| `409` | The implementation is interactive, serves no tool, or has an unusable stored configuration |
| `502` | The endpoint did not answer usably |
| `504` | The endpoint did not answer within `timeoutSeconds` |

***

## VALIDATION RULES

* `config.type` must be `lookup`, `simulated`, `endpoint`, or `interactive`.
* Type and configuration cannot change after creation. `PATCH` changes only `displayName` and an endpoint's `auth`.
* `auth` in a `PATCH` is rejected for an implementation that is not an endpoint.
* Lookup rows must have unique inputs, and the table must have at least one row.
* A simulated `modelIdentifier` must be a hosted model and must not include `apiKeys`.
* A simulated `inferenceConfig` must not include `guidedDecoding`.
* `endpointUrl` must use HTTPS, and its host must resolve to a public address.
* With `GET` or `DELETE`, every tool argument must be a scalar or an array of scalars, and no argument can share a name with a query parameter already in `endpointUrl`.
* `timeoutSeconds` must be from `1` to `120`.
* An interactive implementation's tool output schema must be an object with exactly one string property and no other required properties.
* `:execute` requires editor access and a valid payment card on file for the organization. It is not available for interactive implementations.
* Your organization's plan limits the number of tool implementations.
* In a job, attached implementations must serve tools with distinct names, every simulated implementation must use the same model, and any interactive implementation requires a user model.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.