TOOL SCHEMA

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. 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

{
  "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.

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.

{
  "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.
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.

Resources

Recipe configs

Agent schemas

Recipe examples

TOOL SCHEMA

CREATE TOOL REQUEST

UPDATE TOOL REQUEST

TOOL

LIST TOOLS

VALIDATION RULES

​CREATE TOOL REQUEST

​UPDATE TOOL REQUEST

​TOOL

​LIST TOOLS

​VALIDATION RULES

CREATE TOOL REQUEST

UPDATE TOOL REQUEST

TOOL

LIST TOOLS

VALIDATION RULES