Tools

Tools are what the agent can call during a step (one round of the agent thinking and acting). There are two kinds, and both go in the harness's tools=[...] slot:

• Custom tools - your own Python functions, run in your process.
• Sandbox tools (coming soon) - functions whose source runs inside the sandbox.

For external systems over MCP, see Connectors & MCP.

from mistralai.agents import agents

from mistralai.agents import agents

A custom tool lets the agent call into your own code - your APIs, your database, your business logic. You write a Python function, decorate it with @agents.tool(...), and pass it to the harness in tools=[...].

You describe the tool to the model explicitly. name, description and input_schema are all required keyword arguments - nothing is derived from the function. The input schema is a Pydantic model, and the handler takes it as a single parameter:

from pydantic import BaseModel

from mistralai.agents import agents


class WeatherArgs(BaseModel):
    city: str


@agents.tool(
    name="get_weather",
    description="Weather for a city.",
    input_schema=WeatherArgs,
)
async def get_weather(args: WeatherArgs) -> dict[str, str]:
    return {"weather": f"sunny in {args.city}"}

from pydantic import BaseModel

from mistralai.agents import agents


class WeatherArgs(BaseModel):
    city: str


@agents.tool(
    name="get_weather",
    description="Weather for a city.",
    input_schema=WeatherArgs,
)
async def get_weather(args: WeatherArgs) -> dict[str, str]:
    return {"weather": f"sunny in {args.city}"}

:::info Decorate module-level functions @agents.tool expects a function defined at module scope. The SDK reads its source and schema to describe it to the model. A nested closure or lambda has no importable source, so it cannot be restored when a session resumes in another process. :::

A tool that needs a value the model should not choose, such as the repository a Session works on, takes it as a Session input instead of an argument.

Tools live on the harness, the object that holds everything the agent can use. Put your decorated functions in tools=[...] and run:

async def main() -> str:
    harness = agents.Harness(tools=[get_weather])
    agent = agents.Agent(model="mistral-medium-3-5", instructions="Use the tool, then answer.", harness=harness)
    result = await agent.run("What's the weather in Paris?")
    return result.text

async def main() -> str:
    harness = agents.Harness(tools=[get_weather])
    agent = agents.Agent(model="mistral-medium-3-5", instructions="Use the tool, then answer.", harness=harness)
    result = await agent.run("What's the weather in Paris?")
    return result.text

Tools coming from Connectors are not registered into the tools=[...] list, but through the connectors=[...] slot :

agents.Harness(tools=[get_weather], connectors=[agents.connector("deepwiki")])

agents.Harness(tools=[get_weather], connectors=[agents.connector("deepwiki")])

:::note Built-in tools need a sandbox The runtime's built-ins — read_file, write_file, search_replace, bash and the process.* tools — are installed by the sandbox. A default agents.Agent(model=...) has NoSandbox() and therefore none of them. See Sandbox. :::

Work in progress.

• Connectors & MCP - external systems exposed to the agent.
• Sandbox - the sandbox a sandbox tool runs in.
• Programmatic tool calling - let the model orchestrate tools by writing code.
• Custom hooks - rewrite a tool's arguments or its result, or refuse the call.