---
title: "Run Tool From Source"
method: POST
path: "/v1/tools/run"
tags: ["tools"]
---

# Run Tool From Source

`POST /v1/tools/run`

Attempt to build a tool from source, then run it on the provided arguments

## Request body

- ToolRunFromSource
  - `source_code` string, required — The source code of the function.
  - `args` object, required — The arguments to pass to the tool.
  - `env_vars` object — The environment variables to pass to the tool.
  - `name` string, nullable — The name of the tool to run.
  - `source_type` string, nullable — The type of the source code.
  - `args_json_schema` object, nullable — The args JSON schema of the function.
  - `json_schema` object, nullable — The JSON schema of the function (auto-generated from source_code if not provided)
  - `pip_requirements` PipRequirement[], nullable — Optional list of pip packages required by this tool.
    - `name` string, required — Name of the pip package.
    - `version` string, nullable — Optional version of the package, following semantic versioning.
  - `npm_requirements` NpmRequirement[], nullable — Optional list of npm packages required by this tool.
    - `name` string, required — Name of the npm package.
    - `version` string, nullable — Optional version of the package, following semantic versioning.

## Response `200`

Successful Response

- 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` string, required
  - `date` string, date-time, required
  - `name` string, nullable
  - `message_type` 'tool_return_message' — The type of the message.
  - `otid` string, nullable
  - `sender_id` string, nullable
  - `step_id` string, nullable
  - `is_err` boolean, nullable
  - `seq_id` integer, nullable
  - `run_id` string, nullable
  - `tool_return` string, required
  - `status` 'success' | 'error', required
  - `tool_call_id` string, required
  - `stdout` string[], nullable
  - `stderr` string[], nullable
  - `tool_returns` LettaSchemasLettaMessageToolReturn[], nullable
    - `tool_return` string, required
    - `status` 'success' | 'error', required
    - `tool_call_id` string, required
    - `stdout` string[], nullable
    - `stderr` string[], nullable

## Other responses

- `422` — Validation Error

## Changes

- **2025-10-08** `1bed3816dfe2` — 6 info
  - added the optional property `tool_returns` to the response with the `200` status
  - response property `status` deprecated
  - response property `stderr` deprecated
  - response property `stdout` deprecated
  - …2 more

[Change history](https://skmtc.dev/yu-code666/apis/letta-api/changes/v1/tools/run/post.md)

---

[API](https://skmtc.dev/yu-code666/apis/letta-api.md) · [All operations](https://skmtc.dev/yu-code666/apis/letta-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/yu-code666/letta-api/revisions/6cec99480c13/schema)