---
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 status (Literal["success", "error"]): The status of the tool call tool_call_id (str): A unique identifier for the tool call that generated this message stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation stderr (Optional[List(str)]): Captured stderr from the tool invocation
  - `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

## Other responses

- `422` — Validation Error

---

[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/4d0fc5930af2/schema)