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

# Tools

> Create tools for agents to take action

## Python Functions

Create tools from any async function using the `@tool` decorator:

```python theme={null}
from a1 import tool

@tool
async def search(query: str) -> list[str]:
    """Search the web."""
    return results

@tool
async def calculate(expression: str) -> float:
    """Evaluate math expression."""
    return eval(expression)
```

Or pass functions directly to Agent (auto-converted to tools):

```python theme={null}
async def divide(a: float, b: float) -> float:
    """Divide two numbers."""
    return a / b

agent = Agent(tools=[search, divide])  # Both @tool and raw functions work
```

Supports primitive and complex return types (Pydantic models, lists, dicts).

## Descriptions

Add descriptions to help LLMs understand tools:

```python theme={null}
@tool(
    name="api_call",
    description="Make an HTTP request to an endpoint"
)
async def api_call(url: str, method: str = "GET") -> str:
    ...
```

**Note**: The `name` parameter sets the tool name (defaults to the function name), and the `description` parameter sets the tool description (defaults to the function's docstring).

## OpenAPI

Create tools from OpenAPI 3.0 specifications:

```python theme={null}
from a1 import ToolSet

tools = await ToolSet.from_openapi("https://api.example.com")
```

Auto-detects spec at `/openapi.json`, `/openapi.yaml`, `/swagger.json`, or `/swagger.yaml`.

## Model Context Protocol (MCP)

Create tools from MCP servers:

```python theme={null}
from a1 import ToolSet

config = {
    "mcpServers": {
        "filesystem": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
        }
    }
}

tools = await ToolSet.from_mcp_servers(config)
```

## LLM

LLMs are tools that call language models with structured output and retry logic:

```python theme={null}
from a1 import LLM, RetryStrategy
from pydantic import BaseModel

class Answer(BaseModel):
    result: float
    explanation: str

# Basic LLM tool
llm = LLM("gpt-4.1")

# With structured output
llm = LLM(
    model="gpt-4.1",
    output_schema=Answer
)

# Custom retry strategy (default: 3 candidates × 3 retries)
llm = LLM(
    model="gpt-4.1",
    retry_strategy=RetryStrategy(max_iterations=5, num_candidates=2)
)
```

**Supported providers**: OpenAI, Anthropic, Google, Groq (via `groq:model-name`)

Use LLM tools like any other tool in agents.

## EM

EMs are tools that call embedding models for semantic similarity. The use-case for this is classification. If any enum in your agent/tool schemas (input/output) has >100 values, the compiler translates all relevant LLM calls into a fused EM-LLM pipeline that first filters to semantically relevant enum options and then invokes the LLM with its output constrained to be one of the filtered options.

A1 statically detects enums that are too large and will require an EM tool if detected. A1 transparently owns adaptive rate limit handling, chunk-parallelism, and caching vectors within the current Runtime.

Semantic classification example:

```python theme={null}
from enum import Enum
from pydantic import BaseModel, Field

# Large enum (1M values)
Category = Enum('Category', {f'CAT_{i}': f'cat_{i}' for i in range(1_000_000)})

class Output(BaseModel):
    category: Category

agent = Agent(
    output_schema=Output,
    tools=[EM("text-embedding-3-small"), LLM("gpt-4.1")]  # EM required
)
```

## RAG

RAG provides readonly or full access to databases and filesystems:

```python theme={null}
from a1 import RAG, Database, FileSystem

# Readonly database access (SELECT only)
rag = RAG(database="sqlite:///data.db")

# Readonly filesystem access (ls, grep, cat)
rag = RAG(filesystem="/path/to/files")

agent = Agent(
    name="safe_agent",
    tools=[rag.get_toolset(), LLM("gpt-4.1")]
)
```

**Readonly tools**: `sql` (SELECT), `ls` (list), `grep` (search), `cat` (read)

For full read/write access, use `Database` or `FileSystem` directly:

```python theme={null}
# Full database access (SELECT, INSERT, UPDATE, DELETE)
db = Database("postgresql://user:pass@host/db")

# Full filesystem access (ls, grep, cat, write_file, delete_file)
fs = FileSystem("s3://bucket/path")

agent = Agent(
    tools=[db.get_toolset(), fs.get_toolset(), LLM("gpt-4.1")]
)
```

**Supported databases**: PostgreSQL, MySQL, SQLite, DuckDB, SQL Server, Oracle

**Supported paths**: Local filesystems, S3, Google Cloud Storage, Azure Blob Storage

## ToolSet

Group related tools together to organize hierarchically:

```python theme={null}
from a1 import ToolSet

math_tools = ToolSet(
    name="math",
    description="Mathematical operations",
    tools=[add, multiply, divide]
)

agent = Agent(
    tools=[math_tools, LLM("gpt-4.1")]
)
```

## Done

Built-in `is_terminal=True` tool for marking workflow completion:

```python theme={null}
from a1 import Done

done = Done()  # Agent can call this to signal completion
```


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