Skip to content
Letta Letta Letta Docs
Sign up
API Reference

Tools

Delete Tool
tools.delete(strtool_id) -> object
DELETE/v1/tools/{tool_id}
Retrieve Tool
tools.retrieve(strtool_id) -> Tool
GET/v1/tools/{tool_id}
Update Tool
tools.update(strtool_id, ToolUpdateParams**kwargs) -> Tool
PATCH/v1/tools/{tool_id}
List Tools
tools.list(ToolListParams**kwargs) -> SyncArrayPage[Tool]
GET/v1/tools/
Create Tool
tools.create(ToolCreateParams**kwargs) -> Tool
POST/v1/tools/
Upsert Tool
tools.upsert(ToolUpsertParams**kwargs) -> Tool
PUT/v1/tools/
Search Tools
tools.search(ToolSearchParams**kwargs) -> ToolSearchResponse
POST/v1/tools/search
ModelsExpand Collapse
class NpmRequirement: …
name: str

Name of the npm package.

minLength1
version: Optional[str]

Optional version of the package, following semantic versioning.

class PipRequirement: …
name: str

Name of the pip package.

minLength1
version: Optional[str]

Optional version of the package, following semantic versioning.

class Tool: …

Representation of a tool, which is a function that can be called by the agent.

id: str

The human-friendly ID of the Tool

args_json_schema: Optional[Dict[str, object]]

The args JSON schema of the function.

created_by_id: Optional[str]

The id of the user that made this Tool.

default_requires_approval: Optional[bool]

Default value for whether or not executing this tool requires approval.

description: Optional[str]

The description of the tool.

enable_parallel_execution: Optional[bool]

If set to True, then this tool will potentially be executed concurrently with other tools. Default False.

json_schema: Optional[Dict[str, object]]

The JSON schema of the function.

last_updated_by_id: Optional[str]

The id of the user that made this Tool.

metadata: Optional[Dict[str, object]]

A dictionary of additional metadata for the tool.

name: Optional[str]

The name of the function.

npm_requirements: Optional[List[NpmRequirement]]

Optional list of npm packages required by this tool.

name: str

Name of the npm package.

minLength1
version: Optional[str]

Optional version of the package, following semantic versioning.

pip_requirements: Optional[List[PipRequirement]]

Optional list of pip packages required by this tool.

name: str

Name of the pip package.

minLength1
version: Optional[str]

Optional version of the package, following semantic versioning.

project_id: Optional[str]

The project id of the tool.

return_char_limit: Optional[int]

The maximum number of characters in the response.

maximum1000000
minimum1
source_code: Optional[str]

The source code of the function.

source_type: Optional[str]

The type of the source code.

tags: Optional[List[str]]

Metadata tags.

tool_type: Optional[ToolType]

The type of the tool.

One of the following:
"custom"
"letta_core"
"letta_memory_core"
"letta_multi_agent_core"
"letta_sleeptime_core"
"letta_voice_sleeptime_core"
"letta_builtin"
"letta_files_core"
"external_langchain"
"external_composio"
"external_mcp"
class ToolCreate: …
source_code: str

The source code of the function.

args_json_schema: Optional[Dict[str, object]]

The args JSON schema of the function.

default_requires_approval: Optional[bool]

Whether or not to require approval before executing this tool.

description: Optional[str]

The description of the tool.

enable_parallel_execution: Optional[bool]

If set to True, then this tool will potentially be executed concurrently with other tools. Default False.

json_schema: Optional[Dict[str, object]]

The JSON schema of the function (auto-generated from source_code if not provided)

npm_requirements: Optional[List[NpmRequirement]]

Optional list of npm packages required by this tool.

name: str

Name of the npm package.

minLength1
version: Optional[str]

Optional version of the package, following semantic versioning.

pip_requirements: Optional[List[PipRequirement]]

Optional list of pip packages required by this tool.

name: str

Name of the pip package.

minLength1
version: Optional[str]

Optional version of the package, following semantic versioning.

return_char_limit: Optional[int]

The maximum number of characters in the response.

maximum1000000
minimum1
source_type: Optional[str]

The source type of the function.

tags: Optional[List[str]]

Metadata tags.

class ToolReturnMessage: …

A message representing the return value of a tool call (generated by Letta executing the requested tool).

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal[“success”, “error”]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support

id: str
date: datetime
Deprecatedstatus: Literal["success", "error"]
One of the following:
"success"
"error"
Deprecatedtool_call_id: str
Deprecatedtool_return: str
is_err: Optional[bool]
message_type: Optional[Literal["tool_return_message"]]

The type of the message.

name: Optional[str]
otid: Optional[str]

The offline threading id (OTID). Set by the client to deduplicate requests. Used for idempotency in background streaming mode — each message in a request must have a unique OTID. Retries of the same request should reuse the same OTIDs.

run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
Deprecatedstderr: Optional[List[str]]
Deprecatedstdout: Optional[List[str]]
step_id: Optional[str]
tool_returns: Optional[List[ToolReturn]]
status: Literal["success", "error"]
One of the following:
"success"
"error"
tool_call_id: str
tool_return: Union[List[ToolReturnUnionMember0], str]

The tool return value - either a string or list of content parts (text/image)

One of the following:
List[ToolReturnUnionMember0]
One of the following:
class TextContent: …
text: str

The text content of the message.

signature: Optional[str]

Stores a unique identifier for any reasoning associated with this text content.

type: Optional[Literal["text"]]

The type of the message.

class ImageContent: …
source: Source

The source of the image.

One of the following:
class SourceURLImage: …
url: str

The URL of the image.

type: Optional[Literal["url"]]

The source type for the image.

class SourceBase64Image: …
data: str

The base64 encoded image data.

media_type: str

The media type for the image.

detail: Optional[str]

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type: Optional[Literal["base64"]]

The source type for the image.

class SourceLettaImage: …
file_id: str

The unique identifier of the image file persisted in storage.

data: Optional[str]

The base64 encoded image data.

detail: Optional[str]

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media_type: Optional[str]

The media type for the image.

type: Optional[Literal["letta"]]

The source type for the image.

type: Optional[Literal["image"]]

The type of the message.

str
stderr: Optional[List[str]]
stdout: Optional[List[str]]
type: Optional[Literal["tool"]]

The message type to be created.

class ToolSearchRequest: …

Request model for searching tools using semantic search.

limit: Optional[int]

Maximum number of results to return.

maximum100
minimum1
query: Optional[str]

Text query for semantic search.

search_mode: Optional[Literal["vector", "fts", "hybrid"]]

Search mode: vector, fts, or hybrid.

One of the following:
"vector"
"fts"
"hybrid"
tags: Optional[List[str]]

Filter by tags (match any).

tool_types: Optional[List[str]]

Filter by tool types (e.g., ‘custom’, ‘letta_core’).

class ToolSearchResult: …

Result from a tool search operation.

combined_score: float

Combined relevance score (RRF for hybrid mode).

tool: Tool

The matched tool.

id: str

The human-friendly ID of the Tool

args_json_schema: Optional[Dict[str, object]]

The args JSON schema of the function.

created_by_id: Optional[str]

The id of the user that made this Tool.

default_requires_approval: Optional[bool]

Default value for whether or not executing this tool requires approval.

description: Optional[str]

The description of the tool.

enable_parallel_execution: Optional[bool]

If set to True, then this tool will potentially be executed concurrently with other tools. Default False.

json_schema: Optional[Dict[str, object]]

The JSON schema of the function.

last_updated_by_id: Optional[str]

The id of the user that made this Tool.

metadata: Optional[Dict[str, object]]

A dictionary of additional metadata for the tool.

name: Optional[str]

The name of the function.

npm_requirements: Optional[List[NpmRequirement]]

Optional list of npm packages required by this tool.

name: str

Name of the npm package.

minLength1
version: Optional[str]

Optional version of the package, following semantic versioning.

pip_requirements: Optional[List[PipRequirement]]

Optional list of pip packages required by this tool.

name: str

Name of the pip package.

minLength1
version: Optional[str]

Optional version of the package, following semantic versioning.

project_id: Optional[str]

The project id of the tool.

return_char_limit: Optional[int]

The maximum number of characters in the response.

maximum1000000
minimum1
source_code: Optional[str]

The source code of the function.

source_type: Optional[str]

The type of the source code.

tags: Optional[List[str]]

Metadata tags.

tool_type: Optional[ToolType]

The type of the tool.

One of the following:
"custom"
"letta_core"
"letta_memory_core"
"letta_multi_agent_core"
"letta_sleeptime_core"
"letta_voice_sleeptime_core"
"letta_builtin"
"letta_files_core"
"external_langchain"
"external_composio"
"external_mcp"
embedded_text: Optional[str]

The embedded text content used for matching.

fts_rank: Optional[int]

Full-text search rank position.

vector_rank: Optional[int]

Vector search rank position.

Literal["custom", "letta_core", "letta_memory_core", 8 more]
One of the following:
"custom"
"letta_core"
"letta_memory_core"
"letta_multi_agent_core"
"letta_sleeptime_core"
"letta_voice_sleeptime_core"
"letta_builtin"
"letta_files_core"
"external_langchain"
"external_composio"
"external_mcp"
combined_score: float

Combined relevance score (RRF for hybrid mode).

tool: Tool

The matched tool.

id: str

The human-friendly ID of the Tool

args_json_schema: Optional[Dict[str, object]]

The args JSON schema of the function.

created_by_id: Optional[str]

The id of the user that made this Tool.

default_requires_approval: Optional[bool]

Default value for whether or not executing this tool requires approval.

description: Optional[str]

The description of the tool.

enable_parallel_execution: Optional[bool]

If set to True, then this tool will potentially be executed concurrently with other tools. Default False.

json_schema: Optional[Dict[str, object]]

The JSON schema of the function.

last_updated_by_id: Optional[str]

The id of the user that made this Tool.

metadata: Optional[Dict[str, object]]

A dictionary of additional metadata for the tool.

name: Optional[str]

The name of the function.

npm_requirements: Optional[List[NpmRequirement]]

Optional list of npm packages required by this tool.

name: str

Name of the npm package.

minLength1
version: Optional[str]

Optional version of the package, following semantic versioning.

pip_requirements: Optional[List[PipRequirement]]

Optional list of pip packages required by this tool.

name: str

Name of the pip package.

minLength1
version: Optional[str]

Optional version of the package, following semantic versioning.

project_id: Optional[str]

The project id of the tool.

return_char_limit: Optional[int]

The maximum number of characters in the response.

maximum1000000
minimum1
source_code: Optional[str]

The source code of the function.

source_type: Optional[str]

The type of the source code.

tags: Optional[List[str]]

Metadata tags.

tool_type: Optional[ToolType]

The type of the tool.

One of the following:
"custom"
"letta_core"
"letta_memory_core"
"letta_multi_agent_core"
"letta_sleeptime_core"
"letta_voice_sleeptime_core"
"letta_builtin"
"letta_files_core"
"external_langchain"
"external_composio"
"external_mcp"
embedded_text: Optional[str]

The embedded text content used for matching.

fts_rank: Optional[int]

Full-text search rank position.

vector_rank: Optional[int]

Vector search rank position.