---
title: "Test Lambda tool without creation"
method: POST
path: "/v2/tools/test"
tags: ["Tools"]
---

# Test Lambda tool without creation

`POST /v2/tools/test`

Tests a Lambda tool without creating it.

Use this to:
- Validate Python code syntax and security constraints
- Discover input/output schemas from type annotations
- Test execution with sample input
- Verify schema compatibility
- Exercise the lambda tool's `tool_configurations` with a stand-in `test_context` that supplies the agent metadata, secrets, and session metadata its `$ref`s resolve against

The function runs in the same secure sandbox environment as production tools.

## Headers

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

## Request body

- TestLambdaToolRequest — Request to test a Lambda tool before creating it. Use this endpoint to: - Validate Python code syntax and security constraints - Discover input/output schemas from type annotations - Test execution with sample input - Verify schema compatibility
  - `language` 'python' — The programming language. Currently only 'python' (Python 3.12) is supported.
  - `code` string, required — The Python 3.12 code for the function. Must define a `process()` entry point. Object parameters must use `TypedDict`; validation rejects bare `dict` and `Dict[K, V]` parameters. See the `code` field on `CreateLambdaToolRequest` for full details and examples.
  - `execution_configuration` ExecutionConfiguration — Execution configuration for the function.
    - `max_execution_time_seconds` integer — Maximum execution time in seconds, up to 21600. When `execution_configuration` is omitted entirely, a lambda that declares `tool_configurations` resolves to 300 seconds and any other lambda resolves to 30. When `execution_configuration` is supplied without this field, the declared default of 30 applies. `max_execution_time_seconds` on the agent's tool-configuration entry takes precedence over this field.
    - `max_memory_mb` integer — Deprecated and ignored. Memory is fixed by the execution environment and cannot be configured per function.
  - `test_input` object, required — The input parameters to test the function with. The platform validates them against the discovered input schema.
  - `timeout_seconds` integer — Maximum execution time in seconds for this test. Overrides `execution_configuration` if specified. When omitted, the supplied `execution_configuration` timeout applies in full — up to 21600 seconds — and a request 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`.
  - `tool_configurations` object — Named configurations of other tools the code under test may invoke through its built-in `tool` module. See the `tool_configurations` field on `CreateLambdaToolRequest` for semantics and constraints.
  - `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 validation and execution results, or the streamed events when `stream_response` is true.

- TestLambdaToolResponse — Response from testing a Lambda tool before creation. Contains validation, schema discovery, and execution results.
  - `validation` object, required — Results of code validation (static and sandbox).
    - `status` 'valid' | 'invalid' | 'pending', required — Overall validation status.
    - `errors` string[] — List of validation errors if the code is invalid.
  - `input_schema` object — The discovered input schema from type annotations. May be null if validation failed or the code has no type hints.
  - `output_schema` object — The discovered output schema from type annotations. May be null if validation failed or the code has no type hints.
  - `execution` object — Results of executing the function with test input. Only present if validation passed.
    - `success` boolean, required — Whether the execution was successful.
    - `output` object — The output returned by the function.
    - `error` object — Error information if execution failed.
      - `message` string — The error message.
      - `traceback` string — Stack trace for debugging.
    - `latency_millis` integer — 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 test input matched the discovered schema.
      - `output_valid` boolean — Whether the output matched the discovered schema.
      - `validation_errors` string[] — Details of any schema validation errors.

## Other responses

- `400` — Invalid request or malformed code.
- `403` — Permissions do not allow testing tools.

## Changes

- **2026-09-04** `05ae305c8d84` — 18 info
  - added the new optional request property `stream_response`
  - the `execution_configuration/max_execution_time_seconds` request property's max was increased from `300.00` to `21600.00`
  - the `timeout_seconds` request property's max was increased from `300.00` to `21600.00`
  - the `tool_configurations/additionalProperties/oneOf[#/components/schemas/ArtifactGrepToolConfiguration]/allOf[#/components/schemas/ToolConfigurationBase]/max_execution_time_seconds` request property's max was increased from `3600.00` to `21600.00`
  - …14 more
- **2026-08-27** `0d51a9e3a0b3` — 1 info
  - request property `execution_configuration/max_memory_mb` deprecated

[Change history](https://skmtc.dev/vectara/apis/vectara-rest-api-v2/changes/v2/tools/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.dev/vectara/apis/vectara-rest-api-v2/revisions/4557c44ba062?raw)