---
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.
    - `max_memory_mb` integer — Maximum memory usage in megabytes.
  - `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.
  - `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.

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

---

[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/revisions/83554494d7f8/schema)