> ## 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 SCHEMA

> Request and response schemas for tools

A tool is the function contract a model can call. This page describes the request body that creates a tool and the tool resource that the API returns. For a task-oriented walkthrough, see [Tools](/guides/agents/tools).

All tool endpoints are under `https://api.oumi.ai/v1/projects/{project_id}/tools`. Request and response fields use camelCase.

***

## CREATE TOOL REQUEST

`POST /v1/projects/{project_id}/tools`

```json theme={null}
{
  "displayName": "Get Weather",
  "toolName": "get_weather",
  "description": "Return the current weather for a city. Call this when the user asks about current conditions in a specific place.",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {"type": "string", "description": "City name, for example \"Paris\"."},
      "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
    },
    "required": ["city"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {"forecast": {"type": "string"}},
    "required": ["forecast"]
  }
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| displayName | string | ✓ | Name shown in Oumi. 1 to 128 characters. The characters `<`, `>`, and `&` are not allowed. |
| toolName | string | ✓ | Name the model calls the tool by. 1 to 128 characters from letters, digits, `_`, `-`, spaces, `/`, `.`, and `@`. |
| description | string | ✓ | Model-facing description of what the tool does and when to call it. 1 to 10,000 characters. HTML markup is not allowed. |
| parameters | object | ✓ | JSON Schema of `type: "object"` for the tool's input arguments. |
| outputSchema | object | | JSON Schema for the tool's output. For an endpoint implementation, this describes the whole response body, not a field within it. |

> [!NOTE]
>
> The web app's create form accepts a narrower `toolName` than the API. It requires lowercase snake\_case that starts with a letter, for example `get_weather`. The form also requires an output schema, when you provide one, to be an object schema.

***

## UPDATE TOOL REQUEST

`PATCH /v1/projects/{project_id}/tools/{tool_id}`

Tools are immutable. The update request accepts only a new display name.

```json theme={null}
{
  "displayName": "Get Current Weather"
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| displayName | string | ✓ | New display name. Same constraints as on create. |

To change any other field, create a new tool.

***

## TOOL

The API returns this object from create, get, update, and list requests.

| Field | Type | Description |
| - | - | - |
| id | integer | Tool ID. Use it to create implementations for the tool. |
| name | string | Resource name, for example `projects/{project_id}/tools/{tool_id}`. |
| displayName | string | Name shown in Oumi. |
| toolName | string | Name the model calls the tool by. |
| description | string | Model-facing description. |
| parameters | object | JSON Schema for the tool's input arguments. |
| outputSchema | object | JSON Schema for the tool's output, or `null`. |
| implementationIds | integer\[] | IDs of the implementations that serve this tool. |
| implementations | object\[] | The tool's implementations. Set only when you list tools with `include_implementations=true`. See [Tool implementation schema](/reference/schema/tool-implementations). |
| createdAt | string | Creation timestamp. |
| updatedAt | string | Last update timestamp. |

***

## LIST TOOLS

`GET /v1/projects/{project_id}/tools`

| Query parameter | Type | Default | Description |
| - | - | - | - |
| pagesize | integer | `50` | Number of tools to return. Maximum `100`. |
| pagetoken | string | | Token from a previous response's `nextPageToken` or `previousPageToken`. |
| sort\_by | string | `updated_at` | `created_at` or `updated_at`. |
| sort\_direction | string | `desc` | `asc` or `desc`. |
| include\_implementations | boolean | `false` | Embeds each tool's implementations in the `implementations` field. |

The response contains `tools`, `nextPageToken`, `previousPageToken`, `pageSize`, and `totalCount`.

***

## VALIDATION RULES

* `parameters` must be a valid JSON Schema (Draft 2020-12) of `type: "object"`.
* Every name in `parameters.required` must be declared in `parameters.properties`.
* `outputSchema`, when present, must be a valid JSON Schema (Draft 2020-12).
* `oneOf`, `allOf`, `not`, `if`, `then`, and `else` are rejected anywhere in `parameters` or `outputSchema`. Property names are exempt, so a property named `not` is allowed.
* `anyOf` is allowed in nested schemas but rejected at the root of `parameters` or `outputSchema`.
* An update request accepts only `displayName`. All other fields are immutable.
* A delete request returns `409 Conflict` while implementations still serve the tool. Delete those implementations first.
* Requests that fail schema validation return `422`.


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