---
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. If not specified, uses the tool's configured timeout.
  - `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.

- 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.

---

[API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/versions/fca567a46b3a/schema)