Tools and MCP

Concepts: Tools. Guide: MCP servers.

tool

tool(fn: Callable[..., Any]) -> Tool

tool(*, name: str | None = None, description: str | None = None, parallel: bool = True) -> Callable[[Callable[..., Any]], Tool]

tool(fn: Callable[..., Any] | None = None, /, *, name: str | None = None, description: str | None = None, parallel: bool = True) -> Tool | Callable[[Callable[..., Any]], Tool]

Turns a function or method into a tool the model can call.

Type hints become the input schema and the docstring becomes the description. The Args: section of the docstring describes each parameter. A parameter typed State is hidden from the model and receives the current State. The return value is sent to the model: a str as is, None as (done), anything else as JSON.

Use it bare (@tool) or with options (@tool(name=..., description=..., parallel=...)).

Example

@tool
def read_file(path: str) -> str:
    """Read a file's contents

    Args:
        path: Path relative to the repository root
    """
    return Path(path).read_text()

Parameters:

Name	Type	Description	Default
fn	Callable[..., Any] | None	The function or method. Every parameter needs a type hint.	None
name	str | None	The tool name. Must match [A-Za-z0-9_-]{1,64}. Defaults to the function name.	None
description	str | None	Defaults to the docstring's first paragraph.	None
parallel	bool	False runs the tool alone after the turn's other calls finish.	True

Returns:

Type	Description
Tool | Callable[[Callable[..., Any]], Tool]	A Tool, or a decorator that makes one when options are given.

Raises:

Type	Description
TypeError	@tool is applied twice or to something that is not a function, or the function cannot be a tool (see Tool).

Tool

Tool(fn: Callable[..., Any], *, name: str | None = None, description: str | None = None, parallel: bool = True)

A tool made by @tool. Calling it runs the original function as is, without validation.

A @tool method in a class becomes a bound tool when accessed on an object (fs.read_file). The attributes do not change after creation.

Usually created with @tool. A bad tool raises here, before any model call.

Parameters:

Name	Type	Description	Default
fn	Callable[..., Any]	The function or method. Every parameter needs a type hint.	required
name	str | None	The tool name. Must match [A-Za-z0-9_-]{1,64}. Defaults to the function name.	None
description	str | None	Defaults to the docstring's first paragraph.	None
parallel	bool	False runs the tool alone after the turn's other calls finish.	True

Raises:

Type	Description
TypeError	The name is invalid, a parameter has no type hint or an unsupported type, or the function takes *args, **kwargs or positional-only parameters.

name instance-attribute

name: str = _check_tool_name(fn.__name__ if name is None else name, explicit=name is not None)

The name the model calls. Defaults to the function name.

description instance-attribute

description: str = description if description is not None else doc_description

What the model reads. Defaults to the docstring's first paragraph, or an empty string.

parallel instance-attribute

parallel: bool = parallel

True runs the tool together with the turn's other calls. False runs it alone after they finish.

input_schema instance-attribute

input_schema: dict[str, Any] = schema

The JSON Schema object shown to the model. State parameters and self are left out, Args: descriptions become property descriptions, and parameters with defaults are optional.

is_async instance-attribute

is_async: bool = inspect.iscoroutinefunction(fn)

True if the original function is async def.

spec property

spec: ToolSpec

The tool as the model sees it: ToolSpec(name, description, input_schema).

MCP

MCP(command: str | None = None, *, name: str | None = None, url: str | None = None, server: Any = None, env: Mapping[str, str] | None = None, headers: Mapping[str, str] | None = None, cwd: str | None = None, timeout: float | None = None)

An MCP server, put in Agent(tools=[...]) like any other tool. Needs pip install "alpineagents[mcp]".

The model sees the server's tools as {name}__{tool}, e.g. github__create_issue. To give the Agent only one tool, pass gh.search_code, or gh["search-code"] for a name that is not a Python identifier.

agent.run connects the servers and disconnects them when it ends. with agent: (or async with agent:) keeps them connected across runs. Agents and concurrent runs that share one MCP object share one connection.

Example

github = MCP("npx -y @modelcontextprotocol/server-github", name="github", env={"GITHUB_TOKEN": token})
linear = MCP(url="https://mcp.linear.app/mcp", name="linear", headers={"Authorization": f"Bearer {key}"})
agent = Agent(model="claude-sonnet-5", tools=[github, linear.list_issues])

Takes exactly one of command, url or server. Nothing connects until the Agent uses it.

Parameters:

Name	Type	Description	Default
command	str | None	The command that starts a stdio server.	None
name	str | None	Required. Letters, digits, - and single _. Prefixes the tool names.	None
url	str | None	The URL of a Streamable HTTP server.	None
server	Any	Anything mcp.Client accepts, such as an in-process server in tests.	None
env	Mapping[str, str] | None	Extra environment variables for command, added to the MCP SDK's safe default environment.	None
headers	Mapping[str, str] | None	HTTP headers for url, e.g. {"Authorization": "Bearer ..."}.	None
cwd	str | None	The working directory for command.	None
timeout	float | None	Seconds to wait for connecting and for each call. None waits without a limit.	None

Raises:

Type	Description
TypeError	No server or more than one is given, env without command, or headers without url.
ValueError	name is missing or not allowed, or command is empty.

name instance-attribute

name = name

The server name that prefixes its tool names.

command instance-attribute

command = command

The command that starts a stdio server, or None.

url instance-attribute

url = url

The URL of a Streamable HTTP server, or None.

server instance-attribute

server = server

The object given as server=, or None.

env instance-attribute

env = dict(env) if env is not None else None

Extra environment variables for command, or None.

headers instance-attribute

headers = dict(headers) if headers is not None else None

HTTP headers for url, or None.

cwd instance-attribute

cwd = cwd

The working directory for command, or None.

timeout instance-attribute

timeout = timeout

Seconds to wait for connecting and for each call, or None for no limit.