Skip to main content

​
Two ways to give agents capabilities

MCP servers

Remote servers you connect by URL. Tools are discovered automatically at startup. The server can be in any language.

Python tools

Local Python functions. You write the implementation; the engine binds them to agents that declare them.
From the agent’s (and the LLM’s) perspective, both look identical — they’re just tools the model can call. By default, both local and MCP tool calls pause for human approval before they run. See Human-in-the-Loop to configure approval behavior and auto mode.

​
MCP servers

Declare a server by URL. The engine connects and discovers its tools automatically at startup.
Then give agents access to the servers they need:
Each agent only sees the MCP tools from its own declared servers.
MCP connections are created once at startup, not per request. If a server is unreachable, the engine logs a warning and continues — local tools still work.

​
Tool tags

If your MCP server groups tools into categories, you can limit which tools an agent sees:
Tags are sent as the X-MCP-Tool-Tag header during tool discovery. The server filters — the engine binds only what comes back. The LLM never sees the tags. Multiple tags are sent comma-joined: X-MCP-Tool-Tag: orders,returns Custom transport — if your server expects a different header or a query param, tool_tag_transport supports two types:

​
MCP auth

To add auth headers to outgoing MCP requests, use a before_mcp_request hook. The token never appears in the YAML or in prompts. See Runtime Hooks.

​
Python tools

Declare a tool with a description. That description is what the LLM uses to decide whether to call it.
Agents declare which tools they have access to:
An agent can only call tools it explicitly declares. The engine enforces this — the model cannot reach a tool that isn’t in its list.

​
Implementing a tool

Run generate (see Quickstart) to create stubs. Then fill in the logic:
The docstring becomes the tool description the LLM sees. The engine wraps the function automatically.
Write clear descriptions and typed parameters. The LLM reads both when deciding how to call a tool. Vague descriptions lead to wrong or missed tool calls.

​
Resolvers vs. tools

Both are Python code. The difference is when they run and who calls them. Use a resolver for context the prompt always needs: current date, user name, account info. Use a tool for actions the user may or may not need: look up an order, create a return, send a message.

​
Tool call tracing

Every tool call is tracked in the run result — agent, tool name, provider (local or MCP), success or failure, latency. You can see this in logs and in Langfuse if tracing is enabled.