Local Tools

A local tool is a Python function in your application that the model may call. By the end of this page you will have an agent that calls two of your functions in one step, and you will know what the model sees of them, what it gets back, and how a failure reaches it.

Every output on this page is what the code printed when it was run. The model’s wording, and sometimes the arguments it chooses, will differ on your run.

Two tools, one agent

import asyncio
from omnicoreagent import OmniCoreAgent, ToolRegistry

tools = ToolRegistry()

@tools.register_tool("get_weather")
def get_weather(city: str) -> dict:
    """Get the current weather for a city."""
    return {"city": city, "temperature": "25C", "condition": "Sunny"}

@tools.register_tool("room_area")
async def room_area(length: float, width: float, unit: str = "m") -> dict:
    """Calculate the floor area of a rectangular room."""
    return {"area": length * width, "unit": f"{unit}2"}

async def main():
    agent = OmniCoreAgent(
        name="tool_agent",
        system_instruction="Use tools when they help answer the user. Answer in plain text.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
        local_tools=tools,
    )
    result = await agent.run(
        "What is the weather in Lagos, and what is the area of a 12 by 8 metre room?"
    )
    print(result["response"])

    trajectory = await agent.get_trajectory(result["trace_id"])
    for step in trajectory["steps"]:
        for call in step["tool_calls"]:
            print("step", step["step"], "->", call["tool_name"], call["arguments"], call["outcome"])

    await agent.cleanup()

asyncio.run(main())

In Lagos, it is currently 25°C and sunny.

The area of a 12 by 8 metre room is 96 square metres.
step 1 -> get_weather {'city': 'Lagos'} success
step 1 -> room_area {'length': 12, 'width': 8, 'unit': 'metre'} success

Both calls happened in step 1: the model asked for them together and the runtime ran them as one batch. One tool is a plain function and the other is async; both work. A plain function runs in a worker thread, so a slow one does not block the agent.

How it works

@tools.register_tool("name") adds the function to the registry and returns it unchanged, so you can still call it yourself. Without a name, the function’s own name is used.

The schema is inferred

Type hints become the JSON Schema the model is sent. A parameter with no default is required; unknown arguments are rejected.

The docstring is the description

The model reads it to decide when to call the tool. A docstring line name: text also becomes that parameter’s description.

Each call is checked, then run

The runtime validates the model’s arguments against the schema, asks the policy if governance is on, runs the function under tool_call_timeout, passes the result through the guardrail, and records the call in the run’s trajectory.

What the model sees

This registry is never given to an agent; it only prints what the model would be sent:

import json
from typing import Literal
from omnicoreagent import ToolRegistry

tools = ToolRegistry()

@tools.register_tool("search_orders")
def search_orders(
    customer: str,
    status: Literal["open", "shipped", "refunded"] = "open",
    limit: int | None = None,
    tags: list[str] | None = None,
) -> list[dict]:
    """Find a customer's orders.

    customer: the customer's email address
    status: which orders to return
    """
    return []

print(json.dumps(tools.get_available_tools()[0], indent=2))

{
  "name": "search_orders",
  "description": "Find a customer's orders.\n\n    customer: the customer's email address\n    status: which orders to return",
  "inputSchema": {
    "type": "object",
    "properties": {
      "customer": {
        "type": "string",
        "description": "the customer's email address"
      },
      "status": {
        "enum": [
          "open",
          "shipped",
          "refunded"
        ],
        "description": "which orders to return"
      },
      "limit": {
        "anyOf": [
          {
            "type": "integer"
          },
          {
            "type": "null"
          }
        ]
      },
      "tags": {
        "anyOf": [
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          {
            "type": "null"
          }
        ]
      }
    },
    "required": [
      "customer"
    ],
    "additionalProperties": false
  },
  "type": "local"
}

str, int, float, bool, list[...], dict[...], Literal[...], unions and Optional map to their JSON Schema types. Any other annotation, or none, is sent as string. When inference is not enough, pass your own schema: register_tool("name", inputSchema={...}, description="...").

Tools that hold state: `Tool` and `get_tool()`

When a tool needs a connection, a client or configuration, build it as a Tool from an object. registry.register(obj) accepts a Tool, or any object with a get_tool() method that returns one.

import asyncio
from omnicoreagent import Tool, ToolRegistry

class InvoiceLookup:
    def __init__(self, invoices: dict):
        self.invoices = invoices

    def get_tool(self) -> Tool:
        return Tool(
            name="fetch_invoice",
            description="Fetch an invoice by its number.",
            inputSchema={
                "type": "object",
                "properties": {"number": {"type": "string", "description": "Invoice number"}},
                "required": ["number"],
                "additionalProperties": False,
            },
            function=self.fetch,
            idempotent=True,
        )

    def fetch(self, number: str) -> dict:
        return self.invoices.get(number, {"error": f"No invoice {number}"})

registry = ToolRegistry()
registry.register(InvoiceLookup({"INV-7": {"number": "INV-7", "total": 120.0}}))

async def main():
    print(await registry.execute_tool("fetch_invoice", {"number": "INV-7"}))
    print(await registry.execute_tool("fetch_invoice", {"number": "INV-9"}))

asyncio.run(main())

{'number': 'INV-7', 'total': 120.0}
{'error': 'No invoice INV-9'}

Pass local_tools=registry to the agent as before. execute_tool is how you test a tool without a model. local_tools also accepts a list of Tool objects (or objects with get_tool()), and registry.merge(other) copies another registry’s tools in.

What a tool returns

Return any value: a string, a number, a list, a dictionary. The model receives it as the call’s data. A dictionary is read as a result envelope only when it has exactly that shape:

Returned	The call is
`{"status": "success" \| "partial" \| "error", ...}` with only `data`, `message` and `error` beside `status`	that status, with that data and message
`{"error": "..."}`, optionally with `message`	an error
any other dictionary, such as `{"status": "shipped", "id": 7}`	a success whose data is the whole dictionary

So {"error": f"No invoice {number}"} above is an error the model sees as one. To return a business dictionary that happens to have an envelope’s shape, wrap it: {"status": "success", "data": your_dict}. Raising is the other way to fail. The exception’s message goes to the model, and the call is recorded as an error:

import asyncio
from omnicoreagent import OmniCoreAgent, ToolRegistry

tools = ToolRegistry()
INVOICES = {"INV-7": 120.0}

@tools.register_tool("fetch_invoice")
def fetch_invoice(number: str) -> dict:
    """Fetch an invoice by its number."""
    if number not in INVOICES:
        raise LookupError(f"No invoice {number}")
    return {"number": number, "total": INVOICES[number]}

async def main():
    agent = OmniCoreAgent(
        name="billing",
        system_instruction="Use tools to answer. Answer in plain text, in one sentence.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
        local_tools=tools,
    )
    result = await agent.run("What is the total of invoice INV-9?")
    print(result["response"])

    trajectory = await agent.get_trajectory(result["trace_id"])
    for step in trajectory["steps"]:
        for call in step["tool_calls"]:
            print(call["tool_name"], call["outcome"], call["error"])
    await agent.cleanup()

asyncio.run(main())

Invoice INV-9 was not found.
fetch_invoice error {'type': 'ToolError', 'message': 'No invoice INV-9'}

A result too large for the context is saved to the workspace as an artifact, and the model gets a preview it can read further with read_artifact (tool_offload in the agent settings). Your tool does not write to the conversation history itself: the runtime stores one result per call.

Options

Where	Option	Default	What it does
`register_tool`	`name`	the function’s name	The name the model calls. Letters, digits, `_` and `-`, up to 64 characters, or the runtime exposes it under a safe alias.
`register_tool`	`description`	the docstring	What the model reads to decide when to call it.
`register_tool`	`inputSchema`	inferred from type hints	A JSON Schema object for the arguments.
`register_tool`, `Tool`	`idempotent`	`False`	Running it twice with the same arguments does no harm. A run recovered after a crash re-runs an idempotent call whose result was not saved; any other such call is not run again, and the model is told its outcome is unknown.
`agent_config`	`tool_call_timeout`	`180`	Seconds one call may take (2 to 1000).
`agent_config`	`tool_offload`	on	When a large result is saved as an artifact instead.

Every agent setting is in the agent settings reference.

Names the runtime reserves

Workspace files are on by default, and they bring their own tools: ls, read_file, write_file, edit_file, insert_file, delete_file, move_file, clear_files, glob and grep. Result offloading adds read_artifact, tail_artifact, search_artifact and list_artifacts. Give your tools names from your domain, such as fetch_invoice or query_knowledge_base.

When things go wrong

ValueError: Tool name conflict: built-in workspace tools reserve these names

Raised when the agent prepares its tools (the first run, or list_all_available_tools) if one of yours is named like a workspace tool:

ValueError: Tool name conflict: built-in workspace tools reserve these names when enable_workspace_files=True: read_file. Rename the app tool or disable workspace files for this agent.

Rename your tool, or set agent_config={"enable_workspace_files": False}.

TypeError: Expected Tool object or object with get_tool() method

local_tools was given a list of plain functions, or register() was given one:

TypeError: Expected Tool object or object with get_tool() method, got <class 'builtin_function_or_method'>

Decorate plain functions with @tools.register_tool(...) and pass the registry; a list must hold Tool objects or objects with get_tool().

The call failed with 'Tool execution exceeded its time limit'

The tool ran longer than tool_call_timeout. With agent_config={"tool_call_timeout": 2} and a tool that sleeps for ten seconds, the run carried on and the trajectory showed:

The monthly report build timed out, so I couldn’t complete it this turn.
slow_report timeout {'type': 'TimeoutError', 'message': 'Tool execution exceeded its time limit'}

A timed-out call may still finish and take effect: a plain (synchronous) function runs in a thread that cannot be stopped, so it carries on after the limit. The model is told so (“it may still take effect… Check before calling it again”), not that it failed; the trace records it as timeout. Give a tool with side effects a way to check (a list or lookup tool), and raise the timeout or make the tool return sooner (start the work and return a handle the model can check later).

The model's arguments were rejected

Arguments that do not match the schema never reach your function; the model is told why and usually corrects itself. Called directly, a missing argument reads:

ValueError: Invalid tool arguments: missing a required argument: 'number'

If the model keeps getting it wrong, make the docstring say what each parameter is (name: description lines), or use Literal for fixed choices.

MCP tools

Tools from MCP servers, next to your own.

Code mode

Let the model call your tools from a short Python program.

Many tools

Dozens or hundreds of tools: the model searches for the ones it needs.

Ask before a tool runs

A policy that asks a person before a refund.

Get Started

Make It Safe

Run It

See and Improve

Build

How It Works

Reference

HTTP API (OmniServe)

Releases

Local Tools

Local Tools

Two tools, one agent

How it works

What the model sees

Tools that hold state: `Tool` and `get_tool()`

What a tool returns

Options

Names the runtime reserves

When things go wrong

Next

MCP tools

Code mode

Many tools

Ask before a tool runs

​Local Tools

​Two tools, one agent

​How it works

​What the model sees

​Tools that hold state: Tool and get_tool()

​What a tool returns

​Options

​Names the runtime reserves

​When things go wrong

​Next

MCP tools

Code mode

Many tools

Ask before a tool runs

Local Tools

Two tools, one agent

How it works

What the model sees

Tools that hold state: `Tool` and `get_tool()`

What a tool returns

Options

Names the runtime reserves

When things go wrong

Next