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 answers its calls. Define the tool first, then give it at least one implementation.
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
For every field, constraint, and API route, see the tool schema reference.
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 asget_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.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
typeand adescription. 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
enumwhen 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 usesoneOf, 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. For JSON Schema itself, see Understanding JSON Schema.
DEFINE THE OUTPUT WHEN ITS SHAPE MATTERS
AnoutputSchema 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
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. ClickCreate implementation in that section to add one. See Tool implementations.
The actions menu (the three-dot button at the top right of the page) contains these actions:
Renamechanges the display name.Duplicateopens the create form prefilled with this tool’s definition. Edit the fields you want to change, then clickCreate Toolto create a new tool.Deleteremoves the tool. See Deleting a tool.
DELETING A TOOL
You cannot delete a tool while implementations still serve it. Oumi returns409 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
Decide what the model gets back when it calls a tool.
Generate data with tools
Generate tool-calling conversations for training.
Evaluate with tools
Evaluate how well a model uses its tools.