> ## Documentation Index
> Fetch the complete documentation index at: https://docs-omnicoreagent.omnirexfloralabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Tools

> Register Python functions as AI-callable tools with ToolRegistry

# Local Tools System

Register any Python function as an AI tool using the `ToolRegistry`.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import asyncio
from omnicoreagent import OmniCoreAgent, ToolRegistry

tools = ToolRegistry()

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

@tools.register_tool("calculate_area")
def calculate_area(length: float, width: float) -> dict:
    """Calculate rectangle area."""
    return {"area": length * width, "unit": "square units"}

async def main():
    agent = OmniCoreAgent(
        name="tool_agent",
        system_instruction="Use local tools when they help answer the user.",
        model_config={"provider": "openai", "model": "gpt-4o"},
        local_tools=tools,
    )

    result = await agent.run(
        "What is the weather in Lagos, and what is the area of a 12 by 8 room?"
    )
    print(result["response"])
    await agent.cleanup()

asyncio.run(main())
```

***

## How It Works

1. **Decorate** any Python function with `@tools.register_tool("tool_name")`
2. **Type hints** are automatically converted into JSON Schema for the LLM
3. **Docstrings** become tool descriptions the LLM uses to decide when to call the tool
4. **Pass** the `ToolRegistry` to your agent via `local_tools=`

Workspace files are enabled by default and reserve these built-in tool names:
`ls`, `read_file`, `write_file`, `edit_file`, `insert_file`, `delete_file`,
`move_file`, `clear_files`, `glob`, and `grep`. Use domain-specific names for
application tools, such as `fetch_invoice` or `query_knowledge_base`.

***

## Async Tools

Async functions work seamlessly:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
@tools.register_tool("fetch_data")
async def fetch_data(url: str) -> dict:
    """Fetch data from a URL."""
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
        return response.json()
```

***

## Class-Based Tools

For more complex tools, use a class with a `get_tool()` method:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from omnicoreagent import Tool

class DatabaseTool:
    def __init__(self, connection_string: str):
        self.conn = connection_string

    def get_tool(self) -> Tool:
        return Tool(
            name="query_db",
            description="Run a SQL query against the database.",
            inputSchema={
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "SQL query to execute"}
                },
                "required": ["query"]
            },
            function=self._query,
        )

    async def _query(self, query: str) -> dict:
        # Your database logic
        return {"status": "success", "data": [...], "message": "Query executed"}
```

Register class-based tools:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
registry = ToolRegistry()
registry.register(DatabaseTool(connection_string="postgresql://..."))
```

***

## Composing Local Tools

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from omnicoreagent import OmniCoreAgent, ToolRegistry

tools = ToolRegistry()

@tools.register_tool("greet")
def greet(name: str) -> str:
    """Greet someone."""
    return f"Hello, {name}!"

@tools.register_tool("calculate_total")
def calculate_total(price: float, quantity: int) -> float:
    """Calculate an order total."""
    return price * quantity

agent = OmniCoreAgent(
    name="local_tools_agent",
    system_instruction="Use local tools when they help answer the user.",
    model_config={"provider": "openai", "model": "gpt-4o"},
    local_tools=tools,
)
```

<Tip>
  Use Local Tools for custom business logic, internal APIs, or Python functionality
  that belongs to your application. Use MCP for shared external services.
</Tip>