---
title: "Tools"
description: "Tool, the @tool decorator that records a function as one, and McpServer, an MCP server the agent uses."
source: "Guardian Agent SDK"
---
The tools an agent can call are part of its definition: each one's name, description and input schema. Tools can be recorded from functions with `@tool`, and an agent's MCP servers are recorded as `McpServer`s.

## Tool

{/* generated api guardian_agent.Tool */}

A tool an agent can call: its name, description and input schema.

Usually made by `tool` from a function. Build one yourself for a
tool that isn't a Python function, such as one served elsewhere.

Example:

```python
lookup = ga.Tool(
    "lookup_ticket",
    "Fetch a support ticket by ID.",
    {"type": "object", "properties": {"id": {"type": "string"}}},
)
```

**Attributes:**

- **name** (`str`) – What the model calls the tool.
- **description** (`str`) – What the tool does, for the model.
- **input_schema** (`dict[str, Any]`) – A JSON Schema for the tool's arguments.
- **source_hash** (`str | None`) – `sha256:<hex>` of the tool's source, so editing it
  gives the agent a new definition; `None` to leave it out.

**Functions:**

- [**from_function**](#toolfrom_function) – Describe a function as a tool, as `tool` does.

### `Tool.from_function`

```python
from_function(function: Callable[..., Any], *, name: str | None = None, description: str | None = None, hash_source: bool = True) -> Tool
```

Describe a function as a tool, as `tool` does.

**Parameters:**

- **function** (`Callable[..., Any]`) – The function, sync or async.
- **name** (`str | None`) – The tool's name; defaults to the function's.
- **description** (`str | None`) – What the tool does; defaults to the docstring's
  summary, the text before any `Args:`-style section.
- **hash_source** (`bool`) – Record a hash of the function's source.

**Raises:**

- `TypeError` – The function takes `*args` or `**kwargs`, or a
  parameter's type has no JSON Schema.
- `ValueError` – There is no description, from the argument or a
  docstring.

{/* end generated */}

{/* generated api guardian_agent.tool */}

### `tool`

```python
tool(function: F | None = None, /, *, name: str | None = None, description: str | None = None, hash_source: bool = True) -> F | Callable[[F], F]
```

Record a function as a tool, and return it unchanged.

The tool's name is the function's, its description the docstring's
summary, and its input schema comes from the type hints through Pydantic,
with each Google-style `Args:` entry as that parameter's description
(an `Annotated[..., Field(description=...)]` wins over it). Its source is
hashed, so editing the tool gives the agent a new definition.

The function keeps working exactly as before; the description is read
when the decorator runs, so a mistake fails at the function.

Example:

```python
@ga.tool
def search_docs(query: str, limit: int = 10) -> list[str]:
    """Search the internal documentation."""

@ga.tool(name="search", hash_source=False)
async def wiki_search(query: str) -> list[str]:
    """Full-text search over the wiki."""
```

**Parameters:**

- **function** (`F | None`) – The function, when used as `@ga.tool`.
- **name** (`str | None`) – The tool's name; defaults to the function's.
- **description** (`str | None`) – What the tool does; defaults to the docstring's summary.
- **hash_source** (`bool`) – Record a hash of the function's source.

**Raises:**

- `TypeError` – The function takes `*args` or `**kwargs`, or a
  parameter's type has no JSON Schema.
- `ValueError` – There is no description.

{/* end generated */}

## McpServer

{/* generated api guardian_agent.McpServer */}

An MCP server the agent uses.

Build one with `stdio`, `http` or `sse`. Headers and
environment variables can't be recorded, and a credential in the URL or
arguments is refused.

**Attributes:**

- **name** (`str`) – The server's name.
- **transport** (`Literal['stdio', 'sse', 'streamable_http']`) – `"stdio"`, `"sse"` or `"streamable_http"`.
- **url** (`str | None`) – The server's URL, for `sse` and `streamable_http`.
- **command** (`str | None`) – The command that starts it, for `stdio`.
- **args** (`Iterable[str]`) – The command's arguments.

**Functions:**

- [**stdio**](#mcpserverstdio) – A server the agent starts as a process, such as `npx`.
- [**http**](#mcpserverhttp) – A server reached over streamable HTTP.
- [**sse**](#mcpserversse) – A server reached over server-sent events.

### `McpServer.stdio`

```python
stdio(name: str, command: str, *args: str) -> McpServer
```

A server the agent starts as a process, such as `npx`.

### `McpServer.http`

```python
http(name: str, url: str) -> McpServer
```

A server reached over streamable HTTP.

### `McpServer.sse`

```python
sse(name: str, url: str) -> McpServer
```

A server reached over server-sent events.

{/* end generated */}