Skip to content
Letta Letta Letta Docs
Discord
API Reference

Tools

Delete Tool
client.tools.delete(stringtoolID, RequestOptionsoptions?): ToolDeleteResponse
DELETE/v1/tools/{tool_id}
Retrieve Tool
client.tools.retrieve(stringtoolID, RequestOptionsoptions?): Tool { id, args_json_schema, created_by_id, 15 more }
GET/v1/tools/{tool_id}
Update Tool
client.tools.update(stringtoolID, ToolUpdateParams { args_json_schema, default_requires_approval, description, 9 more } body, RequestOptionsoptions?): Tool { id, args_json_schema, created_by_id, 15 more }
PATCH/v1/tools/{tool_id}
List Tools
client.tools.list(ToolListParams { after, before, exclude_tool_types, 9 more } query?, RequestOptionsoptions?): ArrayPage<Tool { id, args_json_schema, created_by_id, 15 more } >
GET/v1/tools/
Create Tool
client.tools.create(ToolCreateParams { source_code, args_json_schema, default_requires_approval, 8 more } body, RequestOptionsoptions?): Tool { id, args_json_schema, created_by_id, 15 more }
POST/v1/tools/
Upsert Tool
client.tools.upsert(ToolUpsertParams { source_code, args_json_schema, default_requires_approval, 8 more } body, RequestOptionsoptions?): Tool { id, args_json_schema, created_by_id, 15 more }
PUT/v1/tools/
Search Tools
client.tools.search(ToolSearchParams { limit, query, search_mode, 2 more } body, RequestOptionsoptions?): ToolSearchResponse { combined_score, tool, embedded_text, 2 more }
POST/v1/tools/search
ModelsExpand Collapse
NpmRequirement { name, version }
name: string

Name of the npm package.

minLength1
version?: string | null

Optional version of the package, following semantic versioning.

PipRequirement { name, version }
name: string

Name of the pip package.

minLength1
version?: string | null

Optional version of the package, following semantic versioning.

Tool { id, args_json_schema, created_by_id, 15 more }

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

id: string

The human-friendly ID of the Tool

args_json_schema?: Record<string, unknown> | null

The args JSON schema of the function.

created_by_id?: string | null

The id of the user that made this Tool.

default_requires_approval?: boolean | null

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

description?: string | null

The description of the tool.

enable_parallel_execution?: boolean | null

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

json_schema?: Record<string, unknown> | null

The JSON schema of the function.

last_updated_by_id?: string | null

The id of the user that made this Tool.

metadata_?: Record<string, unknown> | null

A dictionary of additional metadata for the tool.

name?: string | null

The name of the function.

npm_requirements?: Array<NpmRequirement { name, version } > | null

Optional list of npm packages required by this tool.

name: string

Name of the npm package.

minLength1
version?: string | null

Optional version of the package, following semantic versioning.

pip_requirements?: Array<PipRequirement { name, version } > | null

Optional list of pip packages required by this tool.

name: string

Name of the pip package.

minLength1
version?: string | null

Optional version of the package, following semantic versioning.

project_id?: string | null

The project id of the tool.

return_char_limit?: number

The maximum number of characters in the response.

maximum1000000
minimum1
source_code?: string | null

The source code of the function.

source_type?: string | null

The type of the source code.

tags?: Array<string>

Metadata tags.

tool_type?: 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"
ToolCreate { source_code, args_json_schema, default_requires_approval, 8 more }
source_code: string

The source code of the function.

args_json_schema?: Record<string, unknown> | null

The args JSON schema of the function.

default_requires_approval?: boolean | null

Whether or not to require approval before executing this tool.

description?: string | null

The description of the tool.

enable_parallel_execution?: boolean | null

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

json_schema?: Record<string, unknown> | null

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

npm_requirements?: Array<NpmRequirement { name, version } > | null

Optional list of npm packages required by this tool.

name: string

Name of the npm package.

minLength1
version?: string | null

Optional version of the package, following semantic versioning.

pip_requirements?: Array<PipRequirement { name, version } > | null

Optional list of pip packages required by this tool.

name: string

Name of the pip package.

minLength1
version?: string | null

Optional version of the package, following semantic versioning.

return_char_limit?: number

The maximum number of characters in the response.

maximum1000000
minimum1
source_type?: string

The source type of the function.

tags?: Array<string> | null

Metadata tags.

ToolReturnMessage { id, date, status, 13 more }

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: string
date: string
Deprecatedstatus: "success" | "error"
One of the following:
"success"
"error"
Deprecatedtool_call_id: string
Deprecatedtool_return: string
is_err?: boolean | null
message_type?: "tool_return_message"

The type of the message.

name?: string | null
otid?: string | null

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?: string | null
sender_id?: string | null
seq_id?: number | null
Deprecatedstderr?: Array<string> | null
Deprecatedstdout?: Array<string> | null
step_id?: string | null
tool_returns?: Array<ToolReturn { status, tool_call_id, tool_return, 3 more } > | null
status: "success" | "error"
One of the following:
"success"
"error"
tool_call_id: string
tool_return: Array<TextContent { text, signature, type } | ImageContent { source, type } > | string

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

One of the following:
Array<TextContent { text, signature, type } | ImageContent { source, type } >
TextContent { text, signature, type }
text: string

The text content of the message.

signature?: string | null

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

type?: "text"

The type of the message.

ImageContent { source, type }
source: URLImage { url, type } | Base64Image { data, media_type, detail, type } | LettaImage { file_id, data, detail, 2 more }

The source of the image.

One of the following:
URLImage { url, type }
url: string

The URL of the image.

type?: "url"

The source type for the image.

Base64Image { data, media_type, detail, type }
data: string

The base64 encoded image data.

media_type: string

The media type for the image.

detail?: string | null

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

type?: "base64"

The source type for the image.

LettaImage { file_id, data, detail, 2 more }
file_id: string

The unique identifier of the image file persisted in storage.

data?: string | null

The base64 encoded image data.

detail?: string | null

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

media_type?: string | null

The media type for the image.

type?: "letta"

The source type for the image.

type?: "image"

The type of the message.

string
stderr?: Array<string> | null
stdout?: Array<string> | null
type?: "tool"

The message type to be created.

ToolSearchRequest { limit, query, search_mode, 2 more }

Request model for searching tools using semantic search.

limit?: number

Maximum number of results to return.

maximum100
minimum1
query?: string | null

Text query for semantic search.

search_mode?: "vector" | "fts" | "hybrid"

Search mode: vector, fts, or hybrid.

One of the following:
"vector"
"fts"
"hybrid"
tags?: Array<string> | null

Filter by tags (match any).

tool_types?: Array<string> | null

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

ToolSearchResult { combined_score, tool, embedded_text, 2 more }

Result from a tool search operation.

combined_score: number

Combined relevance score (RRF for hybrid mode).

tool: Tool { id, args_json_schema, created_by_id, 15 more }

The matched tool.

id: string

The human-friendly ID of the Tool

args_json_schema?: Record<string, unknown> | null

The args JSON schema of the function.

created_by_id?: string | null

The id of the user that made this Tool.

default_requires_approval?: boolean | null

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

description?: string | null

The description of the tool.

enable_parallel_execution?: boolean | null

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

json_schema?: Record<string, unknown> | null

The JSON schema of the function.

last_updated_by_id?: string | null

The id of the user that made this Tool.

metadata_?: Record<string, unknown> | null

A dictionary of additional metadata for the tool.

name?: string | null

The name of the function.

npm_requirements?: Array<NpmRequirement { name, version } > | null

Optional list of npm packages required by this tool.

name: string

Name of the npm package.

minLength1
version?: string | null

Optional version of the package, following semantic versioning.

pip_requirements?: Array<PipRequirement { name, version } > | null

Optional list of pip packages required by this tool.

name: string

Name of the pip package.

minLength1
version?: string | null

Optional version of the package, following semantic versioning.

project_id?: string | null

The project id of the tool.

return_char_limit?: number

The maximum number of characters in the response.

maximum1000000
minimum1
source_code?: string | null

The source code of the function.

source_type?: string | null

The type of the source code.

tags?: Array<string>

Metadata tags.

tool_type?: 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?: string | null

The embedded text content used for matching.

fts_rank?: number | null

Full-text search rank position.

vector_rank?: number | null

Vector search rank position.

ToolType = "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"
ToolDeleteResponse = unknown
ToolSearchResponse = Array<ToolSearchResult { combined_score, tool, embedded_text, 2 more } >
combined_score: number

Combined relevance score (RRF for hybrid mode).

tool: Tool { id, args_json_schema, created_by_id, 15 more }

The matched tool.

id: string

The human-friendly ID of the Tool

args_json_schema?: Record<string, unknown> | null

The args JSON schema of the function.

created_by_id?: string | null

The id of the user that made this Tool.

default_requires_approval?: boolean | null

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

description?: string | null

The description of the tool.

enable_parallel_execution?: boolean | null

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

json_schema?: Record<string, unknown> | null

The JSON schema of the function.

last_updated_by_id?: string | null

The id of the user that made this Tool.

metadata_?: Record<string, unknown> | null

A dictionary of additional metadata for the tool.

name?: string | null

The name of the function.

npm_requirements?: Array<NpmRequirement { name, version } > | null

Optional list of npm packages required by this tool.

name: string

Name of the npm package.

minLength1
version?: string | null

Optional version of the package, following semantic versioning.

pip_requirements?: Array<PipRequirement { name, version } > | null

Optional list of pip packages required by this tool.

name: string

Name of the pip package.

minLength1
version?: string | null

Optional version of the package, following semantic versioning.

project_id?: string | null

The project id of the tool.

return_char_limit?: number

The maximum number of characters in the response.

maximum1000000
minimum1
source_code?: string | null

The source code of the function.

source_type?: string | null

The type of the source code.

tags?: Array<string>

Metadata tags.

tool_type?: 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?: string | null

The embedded text content used for matching.

fts_rank?: number | null

Full-text search rank position.

vector_rank?: number | null

Vector search rank position.