---
title: "Test Lambda tool"
method: POST
path: "/v2/tools/{tool_id}/test"
tags: ["Tools"]
---

# Test Lambda tool

`POST /v2/tools/{tool_id}/test`

Tests an existing Lambda tool by executing it with test inputs.
Use this to verify a function works correctly before agents use it.
Optionally supply a `test_context` with stand-in agent metadata, secrets, and session metadata. The `$ref`s in the tool's stored `tool_configurations` resolve against these values.
The function runs in a secure sandbox environment with the same constraints as production.

## Path parameters

- `tool_id` string, required

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Request body

- TestToolRequest — Request to test a Lambda tool with sample input.
  - `input` object, required — The input parameters to pass to the function. Must match the tool's input schema.
  - `timeout_seconds` integer — Maximum execution time in seconds for this test. Overrides `execution_configuration` if specified. When omitted, the tool's stored `execution_configuration` timeout applies in full — up to 21600 seconds — and a tool with none runs at 30 seconds. A budget longer than 300 seconds requires `stream_response` to be true; a non-streaming request with a larger budget is rejected.
  - `stream_response` boolean — When true, the response is streamed as Server-sent Events. While the test runs the platform sends zero or more `heartbeat` events, then exactly one terminal `result` event carrying the same object the non-streaming response returns. A platform failure after the stream has started closes the connection without a `result`.
  - `test_context` TestLambdaToolContext — Stand-in values for the hosting agent and session, used to resolve `agent.*` and `session.*` `$ref`s inside the tool configurations under test. Accepted by both `POST /v2/tools/test` and `POST /v2/tools/{tool_id}/test`.
    - `agent` TestLambdaToolContextAgent — Values that substitute for the hosting agent during a lambda test run.
      - `metadata` object — Stand-in for the hosting agent's metadata. Each entry resolves a `$ref` of the form `agent.metadata.<key>` in the tool configurations under test; values may be any JSON.
      - `secrets` object — Stand-in for the hosting agent's secrets. Each entry resolves a `$ref` of the form `agent.secrets.<key>`; values must be strings.
    - `session` TestLambdaToolContextSession — Values that substitute for the hosting session during a lambda test run.
      - `metadata` object — Stand-in for the hosting session's metadata. Each entry resolves a `$ref` of the form `session.metadata.<key>` in the tool configurations under test; values may be any JSON.

## Response `200`

The test execution results, or the streamed events when `stream_response` is true.

- union — Response from testing a Lambda tool. The `type` field discriminates between success and error responses.
  - TestToolSuccessResponse — Successful execution response from testing a Lambda tool.
    - `type` string, required — Response type indicator. Always "success" for successful executions.
    - `output` object, required — The output returned by the function.
    - `latency_millis` integer, required — Time taken to execute the function in milliseconds.
    - `memory_used_mb` integer — Memory used during execution in megabytes.
    - `validation_results` object — Results of input/output schema validation.
      - `input_valid` boolean — Whether the input matched the expected schema.
      - `output_valid` boolean — Whether the output matched the expected schema.
      - `validation_errors` string[] — Details of any validation errors.
  - TestToolErrorResponse — Error response from testing a Lambda tool.
    - `type` string, required — Response type indicator. Always "error" for failed executions.
    - `error` object, required — Error information from the failed execution.
      - `message` string, required — The error message.
      - `traceback` string — Stack trace for debugging.
    - `latency_millis` integer, required — Time taken before the error occurred in milliseconds.
    - `memory_used_mb` integer — Memory used before the error occurred in megabytes.

## Other responses

- `400` — Invalid test input or tool configuration.
- `403` — Permissions do not allow testing this tool.
- `404` — Tool not found or not a Lambda tool.
- `500` — The execution failed due to errors or resource limits.

## Changes

- **2026-09-04** `05ae305c8d84` — 3 info
  - added the new optional request property `stream_response`
  - the `timeout_seconds` request property's max was increased from `300.00` to `21600.00`
  - added the media type `text/event-stream` for the response with the status `200`

[Change history](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/changes/v2/tools/:tool_id/test/post.md)

---

[API](https://skmtc.dev/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/revisions/05ae305c8d84/schema)