Built-in Tool Execution

Built-in tools execute with privileged access on the Letta server. These tools are maintained by Letta and provide core capabilities like web search, code execution, and filesystem access.

Execution Environment

Built-in tools run in a special execution context:

• Where: Letta server (privileged context)
• Permissions: Full system access (within sandbox boundaries)
• Modifiable: No - implementation is fixed by Letta
• Security: Managed by Letta with appropriate sandboxing
• Trust: Verified and maintained by Letta team

Unlike custom tools that you define or MCP tools from external servers, built-in tools are part of the core Letta platform and cannot be modified or customized.

Available Built-in Tools

Web Search

Search the web and retrieve results directly from your agent.

Tool name: web_search

Capabilities:

• Search engines integration
• Result retrieval and parsing
• Structured search results

Learn more about Web Search

Code Execution

Execute Python code in isolated sandbox environments.

Tool name: run_code

Capabilities:

• Python code execution
• Isolated sandbox environment
• Safe execution of agent-generated code
• Access to approved Python packages

Learn more about Code Execution

Filesystem Access

Read and write files in the agent’s workspace.

Tool name: filesystem

Capabilities:

• File reading and writing
• Directory operations
• Workspace-scoped access
• Persistent file storage per agent

Learn more about Filesystem

When to Use Built-in Tools

Built-in tools work well for common agent capabilities that don’t require customization. If your agents need to search the web, execute Python code, or persist files across conversations, the built-in implementations provide these features without requiring you to write custom tools.

The main advantage is that these tools are maintained by Letta and work out of the box. You can attach them to agents and start using them immediately.

However, built-in tools have a fixed implementation that cannot be modified. If you need custom behavior, different execution logic, or access to the tool’s source code, you’ll need to create a custom tool instead. Built-in tools are designed for standard use cases where Letta’s implementation meets your requirements.

Enabling Built-in Tools

Built-in tools are available by default and can be attached to agents like any other tool:

TypeScript

// Create an agent with built-in tools
const agent = await client.agents.create({
  name: "research-agent",
  memory_blocks: [
    { label: "human", value: "User: Alice" },
    { label: "persona", value: "You are a research assistant" },
  ],
  tools: ["web_search", "run_code", "filesystem"],
  model: "openai/gpt-4o-mini",
  embedding: "openai/text-embedding-3-small",
});

Python

from letta_client import Letta
import os

client = Letta(api_key=os.environ["LETTA_API_KEY"])

# Create an agent with built-in tools
agent = client.agents.create(
    name="research-agent",
    memory_blocks=[
        {"label": "human", "value": "User: Alice"},
        {"label": "persona", "value": "You are a research assistant"}
    ],
    tools=["web_search", "run_code", "filesystem"],
    model="openai/gpt-4o-mini",
    embedding="openai/text-embedding-3-small"
)

Security Model

Built-in tools execute with elevated privileges but within carefully designed security boundaries:

Web Search Security

• Network access limited to search APIs
• Result filtering and sanitization
• No arbitrary HTTP requests

Code Execution Security

• Isolated sandbox per execution
• Limited system access
• Approved package whitelist
• Timeout and resource limits

Filesystem Security

• Workspace-scoped access only
• No access to system files
• Per-agent filesystem isolation
• Size and quota limits

Limitations

Built-in tools have intentional limitations:

• Cannot modify implementation - Tool behavior is fixed
• Cannot customize - No configuration options beyond standard tool attachment
• Cannot access source - Implementation details not exposed
• Fixed feature set - New capabilities require Letta platform updates
• Cannot extend - No subclassing or wrapping built-in tools

If you need custom behavior, create a custom tool or use client-side execution instead.

Comparison with Other Execution Modes

vs Custom Tools (Sandbox)

Feature	Built-in	Custom Sandbox
Execution	Letta server (privileged)	Isolated sandbox
Permissions	Full (within boundaries)	Full
Modifiable	No	Yes
Use case	System operations	Custom logic

Use Built-in for system capabilities that Letta provides. Use Custom for your own business logic.

vs Client-Side Tools

Feature	Built-in	Client-Side
Execution	Letta server	Your application
Setup	Attach to agent	Requires approval flow
Latency	Low	Depends on client response
Local access	No	Yes

Use Built-in for server-side operations with low latency. Use Client-Side for local resource access.

vs MCP Remote Tools

Feature	Built-in	MCP Remote
Location	Letta server	External MCP server
Provider	Letta	Third-party
Modifiable	No	Via MCP server
Examples	web_search	GitHub, Slack APIs

Use Built-in for core capabilities provided by Letta. Use MCP for external service integrations.

Tool Discovery

List available built-in tools using the SDK:

TypeScript

// List all available tools (including built-in)
const tools = await client.tools.list();

// Filter for built-in tools
const builtinTools = tools.items.filter((tool) =>
  ["web_search", "run_code", "filesystem"].includes(tool.name)
);

console.log("Built-in tools:", builtinTools.map((t) => t.name));

Python

# List all available tools (including built-in)
tools = client.tools.list()

# Filter for built-in tools
builtin_names = ["web_search", "run_code", "filesystem"]
builtin_tools = [tool for tool in tools.items if tool.name in builtin_names]

print("Built-in tools:", [t.name for t in builtin_tools])

Related

• Web Search - Web search tool details
• Code Execution - Code execution tool details
• Filesystem - Filesystem tool details
• Prebuilt Tools - Overview of all Letta-provided tools
• Tool Execution Overview - Compare all execution modes
• Custom Tools - Create your own tools