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

# TOOLS

> Define the function contracts your agent can call during synthesis and evaluation

A tool is a function contract that a model can call. It has the name the model calls it by (`toolName`), a description written for the model, a JSON Schema for its parameters, and an optional JSON Schema for its output. Create a tool for each function your agent uses, so that Oumi can present it to the model during synthesis and evaluation.

A tool is only the interface. It does nothing in a job until a [tool implementation](/guides/agents/tool-implementations) answers its calls. Define the tool first, then give it at least one implementation.

> [!NOTE]
>
> Tools are immutable. After you create a tool, you can change only its display name. To change the function name, description, parameters, or output schema, duplicate the tool and edit the copy.

***

## WHAT A TOOL CONTAINS

| Field | Purpose |
| - | - |
| `displayName` | The name shown in Oumi. This is the only field you can change later. |
| `toolName` | The name the model emits when it calls the tool, for example `get_weather`. |
| `description` | Model-facing text. The model reads it to decide when to call the tool. |
| `parameters` | A JSON Schema of `type: "object"` that describes the arguments the model passes. |
| `outputSchema` | Optional. A JSON Schema for the value the tool returns. |

For every field, constraint, and API route, see the [tool schema reference](/reference/schema/tools).

***

## WRITE GOOD TOOL DEFINITIONS

The model never sees your implementation. It sees only the tool's name, description, and parameter schema, and it decides from those alone whether to call the tool and what arguments to pass. A vague definition produces wrong calls in every job that uses the tool. Datasets that you generate with tools also carry these definitions in each row, so they become part of your training data.

### NAME THE TOOL FOR WHAT IT DOES

Use a short verb and noun in lowercase snake\_case, such as `get_order_status` or `cancel_booking`. The model emits this name in every call, so a name that states the action helps it pick the right tool among several. The web app requires lowercase snake\_case for this field.

### SAY WHAT THE TOOL DOES AND WHEN TO CALL IT

Write the description for the model, not for a person browsing the **Tools** page. State what the tool returns and the situation in which the model should call it. When two tools could apply to the same request, also say when not to call this one.

| | Description |
| - | - |
| Weak | `Order lookup.` |
| Strong | `Return the current status and expected delivery date of one order. Call this when the user asks where an order is or when it will arrive. Do not call it to change an order. Use update_order instead.` |

### DESCRIBE EVERY PARAMETER

The model fills each argument from the conversation, so it needs to know what each one means and what format it takes:

* Give every property a `type` and a `description`. Include an example value when the format matters, such as an ID pattern or a date format.
* List every argument the tool cannot work without in `required`.
* Use `enum` when an argument takes one of a fixed set of values.

### USE SUPPORTED SCHEMA KEYWORDS

Oumi constrains the model's output to your schema with guided decoding, and guided decoding cannot compile every JSON Schema keyword. Oumi therefore rejects a schema that uses `oneOf`, `allOf`, `not`, or `if`/`then`/`else` anywhere, and a schema whose root is `anyOf`. A nested `anyOf` is allowed.

When you need one of these keywords, restructure the tool instead. Use an `enum` for a choice between values, or split one tool into two tools with simpler signatures. For the full set of rules, see [Validation rules](/reference/schema/tools#validation-rules). For JSON Schema itself, see [Understanding JSON Schema](https://json-schema.org/understanding-json-schema).

### DEFINE THE OUTPUT WHEN ITS SHAPE MATTERS

An `outputSchema` tells Oumi what a correct result looks like. Oumi checks every implementation's output against it, so a simulated implementation returns data in that shape and an endpoint that returns something else is caught. For an endpoint implementation, the output schema describes the whole response body, not a field within it. Leave `outputSchema` out only when the result is free-form text.

### CONFIRM THE CONTRACT BEFORE YOU CREATE IT

Because a tool is immutable, the only fix for a wrong signature is a new tool. Check the function name, parameters, and output schema before you create it, especially when you derived them from existing code or logs.

### EXAMPLE

```json theme={null}
{
  "displayName": "Get Order Status",
  "toolName": "get_order_status",
  "description": "Return the current status and expected delivery date of one order. Call this when the user asks where an order is or when it will arrive. Do not call it to change an order. Use update_order instead.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {"type": "string", "description": "The order ID, for example \"A-48213\". Ask the user for it if they have not given it."}
    },
    "required": ["order_id"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "status": {"type": "string", "enum": ["processing", "shipped", "delivered", "cancelled"]},
      "expected_delivery": {"type": "string", "description": "ISO 8601 date"}
    },
    "required": ["status"]
  }
}
```

***

## THE TOOL DETAIL PAGE

Your tools are listed on the **Tools** page, under **AGENT BUILDER** in the sidebar. Click a tool to open its detail page. The page shows the tool's **General Info**, its **Parameters** and **Output schema**, and an **Implementations** section that lists every implementation that answers the tool's calls. Click `Create implementation` in that section to add one. See [Tool implementations](/guides/agents/tool-implementations).

The actions menu (the three-dot button at the top right of the page) contains these actions:

* `Rename` changes the display name.
* `Duplicate` opens the create form prefilled with this tool's definition. Edit the fields you want to change, then click `Create Tool` to create a new tool.
* `Delete` removes the tool. See [Deleting a tool](#deleting-a-tool).

***

## DELETING A TOOL

You cannot delete a tool while implementations still serve it. Oumi returns `409 Conflict` and names the implementations that block the deletion. Delete those implementations first, then delete the tool.

***

## HOW TOOLS ARE USED

A job does not reference tools directly. A synthesis or evaluation job with tools takes a list of tool implementations, and each implementation serves one tool. The model in the job sees the tools that those implementations serve, and the implementations answer the model's calls.

> **[Tool implementations](/guides/agents/tool-implementations)**
>
> Decide what the model gets back when it calls a tool.

> **[Generate data with tools](/guides/synthesis/how-it-works#add-tools-and-a-simulated-user)**
>
> Generate tool-calling conversations for training.

> **[Evaluate with tools](/guides/evaluations/running#add-tools-and-a-simulated-user)**
>
> Evaluate how well a model uses its tools.


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