Built-in tool execution

Built-in tools execute with privileged access on the Letta server. Letta maintains these tools, which provide core capabilities like web search, code execution, and filesystem access.

Execution environment

Built-in tools run in a special execution context.

• Where: The Letta server (privileged context)
• Permissions: Full system access (within sandbox boundaries)
• Modifiable: No, Letta fixes the implementation
• Security: Letta manages security with appropriate sandboxing
• Trust: Verified and maintained by the 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

Its capabilities include:

• 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

Its capabilities include:

• 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

Its capabilities include:

• 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 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.

The web search tool:

• Limits network access to search APIs
• Filters and sanitizes results
• Has no arbitrary HTTP requests

The code execution tool:

• Provides an isolated sandbox per execution
• Limits system access
• Comes with an approved package whitelist
• Has timeout and resource limits

The filesystem tool:

• Only allows workspace-scoped access
• Has no access to system files
• Per-agent filesystem isolation
• Has size and quota limits

Limitations

Built-in tools have intentional limitations:

• You can’t modify tool implementation: Tool behavior is fixed.
• You can’t customize tools: There are no configuration options beyond standard tool attachment.
• You can’t access source: Implementation details aren’t exposed.
• Tools have fixed feature sets: New capabilities require Letta platform updates.
• You can’t extend them: You can’t subclass or wrap built-in tools.

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

Comparison with other execution modes

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 tools for Letta’s system capabilities. Use custom tools for your own business logic.

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 tools for server-side operations with low latency. Use client-side tools for local resource access.

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 tools for the core capabilities provided by Letta. Use MCP tools for external service integrations.

Tool discovery

List the 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: Read the web search tool details.
• Code execution: Read the code execution tool details.
• Filesystem: Read the filesystem tool details.
• Prebuilt tools: Learn about all the Letta-provided tools.
• Tool execution overview: Compare all execution modes.
• Custom tools: Create your own tools.