--- title: "Create tool" method: POST path: "/v2/tools" tags: ["Tools"] --- # Create tool `POST /v2/tools` Creates a tool that agents can call. Tools give agents capabilities to interact with external systems, process data, query corpora, or run custom logic. Agents select and invoke tools dynamically based on their instructions and the current session. The platform provides several built-in tools, and you can also create your own. This endpoint supports two tool types: - **Lambda tools**, which run user-defined Python functions in a secure sandbox. - **Client tools**, which the calling client executes. The platform emits a `tool_input` event, and the client submits the result as a `tool_output` input. A lambda tool can declare its own `tool_configurations`. These are named configurations of other tools. The lambda tool's Python code calls them as functions through the built-in `tool` module. They stay private to the tool. `$ref` values in their `argument_override` resolve against the hosting agent and session. See `CreateLambdaToolRequest.tool_configurations` for the contract and examples. Each tool includes: - A unique tool ID - A description of its purpose - An input schema that describes accepted parameters - Optional metadata - An enabled flag that controls runtime availability ## Artifact-based tools Some built-in tools work with artifacts stored in a session: - **Document conversion tool**: Converts file artifacts (PDF, Word, PowerPoint, images with OCR support) to markdown and produces new artifacts that contain the extracted content. These tools operate on artifact references rather than file content. This supports multi-step workflows where agents process or index user-uploaded documents. ## Headers - `Request-Timeout` integer - `Request-Timeout-Millis` integer ## Request body - union — Request to create a tool. Supports lambda tools for user-defined functions and client tools that the calling client executes. - CreateLambdaToolRequest — Request to create a new lambda tool. Lambda tools are user-defined functions that run in a secure, sandboxed environment with Python 3.12. Input and output schemas are automatically discovered from function parameter type annotations in your code. When `tool_configurations` is set, each configured tool is callable from the lambda tool's code as a function on the built-in `tool` module. `$ref` values in those configurations resolve against the hosting agent and session at execution time. - `type` string, required — This should always be `lambda`. - `name` string, required — The unique name of the tool (used as the function identifier). - `title` string — Human-readable title of the tool displayed in the UI. - `description` string, required — A detailed description of what the function does, when to use it, and what it returns. - `language` 'python' — The programming language. Currently only 'python' (Python 3.12) is supported. - `code` string, required — The Python 3.12 code for the function. **Required**: Must define a `process()` entry point function. Use type annotations on parameters for automatic schema discovery. **Parameters**: Passed as keyword arguments matched to the function signature. **Return types**: Can return any JSON-serializable type (strings, numbers, booleans, lists, or objects). **Parameter Descriptions**: Use docstrings to provide descriptions for parameters (Google, NumPy, ReST, and Epydoc styles are supported). The platform extracts these descriptions and includes them in the input schema. This gives agents better context about how to use each parameter. **Example with Google-style docstring:** ```python def process(order_count: int, total_revenue: float, days_active: int = 1) -> dict: """Calculate customer engagement score. Args: order_count: The number of orders placed by the customer. total_revenue: Total revenue in USD from the customer. days_active: Number of days the customer was active (default: 1). Returns: A dict with the calculated score. """ score = (order_count * 10 + total_revenue * 0.1) / days_active return {'score': round(score, 2)} ``` This produces an input schema with descriptions: ```json { "type": "object", "properties": { "order_count": { "type": "integer", "description": "The number of orders placed by the customer." }, "total_revenue": { "type": "number", "description": "Total revenue in USD from the customer." }, "days_active": { "type": "integer", "description": "Number of days the customer was active (default: 1)." } }, "required": ["order_count", "total_revenue"] } ``` **Example: Returning a number** ```python def process(x: int, y: int) -> int: return x + y ``` **Example: Returning a string** ```python def process(name: str) -> str: return f"Hello, {name}!" ``` **Example: Returning a boolean** ```python def process(value: int, threshold: int) -> bool: return value > threshold ``` **Example: Returning a list** ```python from typing import List def process(items: List[str]) -> List[str]: return sorted(items) ``` **Example: Returning an object (dict)** ```python def process(order_count: int, total_revenue: float, days_active: int = 1) -> dict: score = (order_count * 10 + total_revenue * 0.1) / days_active return {'score': round(score, 2), 'rating': 'high' if score > 100 else 'low'} ``` For complex types, use the `typing` module: ```python from typing import List def process(items: List[str], count: int) -> dict: return {'total': len(items) * count} ``` **Object parameters must use TypedDict**: Validation rejects bare `dict` and `Dict[K, V]` parameters. All object-typed parameters must use `TypedDict` to define explicit fields. This ensures the agent receives a clear schema for each parameter. ```python from typing import TypedDict, Optional class Adjustment(TypedDict, total=False): monthly_premium: float target_income_age: int illustrated_rate: float def process(client_id: str, adjustment: Adjustment) -> dict: return {"client_id": client_id, "adjustment": adjustment} ``` TypedDict supports inheritance, `Optional` fields, nested TypedDicts, and `total=False` to make all fields optional. **Constraining parameters to specific values with Literal**: Use `Literal` to restrict a parameter to a fixed set of allowed values. This generates an `enum` constraint in the JSON schema, helping the agent choose valid options. ```python from typing import Literal def process(status: Literal["active", "inactive", "pending"], priority: Literal[1, 2, 3]) -> dict: return {"status": status, "priority": priority} ``` When `tool_configurations` is set, the code can call those tools through the built-in `tool` module; see the `tool_configurations` field. - `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. - `tool_configurations` object — Named configurations of other tools this lambda may invoke from its Python code through the built-in `tool` module. Each entry is exposed as `tool.(param=value)`; `tool.list()` returns their names and schemas, and failures raise `tool.ToolError`. `$ref` values inside `argument_override` resolve against the hosting agent and session at execution time — `agent.metadata.*`, `agent.secrets.*`, and `session.metadata.*` only. These configurations are private to the tool: they never appear on the hosting agent's callable tools, and their calls produce no session events. A configured tool may itself be a lambda with its own `tool_configurations`, nested up to three levels deep. Each configuration name is how the code calls it (`tool.`), so it must be a valid identifier: a letter followed by letters, digits, or underscores. See `POST /v2/tools/test` for exercising these calls without persisting the tool. - CreateClientToolRequest — Request to create a new client tool. When invoked, the platform emits a `tool_input` event; the client performs the work and submits a `tool_output` input via `createAgentInput`. - `type` string, required — This should always be `client`. - `name` string, required — The unique name of the tool. - `title` string — Human-readable title of the tool displayed in the UI. - `description` string, required — A detailed description of what the tool does, when the agent should invoke it, and what the expected output represents. - `input_schema` union — A JSON Schema definition that describes a data structure. Covers the smallest subset of JSON Schema that all LLM providers support. Unknown keywords are kept and passed through to the provider. `properties`, `required`, and `additionalProperties` are valid only when `type` is `object`. `enum`, `format`, `items`, and `anyOf` are valid for every other `type`, and for an element with no `type`, such as one that only combines schemas with `anyOf`. - object — Keywords shared by every JSON Schema element. - `title` string — A short label for this schema element. - `description` string — A description of this schema element. - `default` unknown - `type` string, required — The JSON type of this schema element. Always `object`. - `properties` object — The object's properties. Each key maps to a nested schema. - `required` string[] — The property names that must be present. - `additionalProperties` boolean — Whether the object may have properties beyond those listed in `properties`. - object — Keywords shared by every JSON Schema element. - `title` string — A short label for this schema element. - `description` string — A description of this schema element. - `default` unknown - `type` string — The JSON type of this schema element. One of `array`, `string`, `number`, `integer`, `boolean`, or `null`. Omit it when the element only combines other schemas with `anyOf`. - `enum` unknown[] — The allowed values for this element. - unknown - `format` string — A semantic format hint, such as date-time, date, email, uri, or uuid. Provider support varies. - `items` JsonSchemaDefinition — recursive - `anyOf` JsonSchemaDefinition[] — A list of schemas. The value must match at least one of them. - `output_schema` union — A JSON Schema definition that describes a data structure. Covers the smallest subset of JSON Schema that all LLM providers support. Unknown keywords are kept and passed through to the provider. `properties`, `required`, and `additionalProperties` are valid only when `type` is `object`. `enum`, `format`, `items`, and `anyOf` are valid for every other `type`, and for an element with no `type`, such as one that only combines schemas with `anyOf`. - object — Keywords shared by every JSON Schema element. - `title` string — A short label for this schema element. - `description` string — A description of this schema element. - `default` unknown - `type` string, required — The JSON type of this schema element. Always `object`. - `properties` object — The object's properties. Each key maps to a nested schema. - `required` string[] — The property names that must be present. - `additionalProperties` boolean — Whether the object may have properties beyond those listed in `properties`. - object — Keywords shared by every JSON Schema element. - `title` string — A short label for this schema element. - `description` string — A description of this schema element. - `default` unknown - `type` string — The JSON type of this schema element. One of `array`, `string`, `number`, `integer`, `boolean`, or `null`. Omit it when the element only combines other schemas with `anyOf`. - `enum` unknown[] — The allowed values for this element. - unknown - `format` string — A semantic format hint, such as date-time, date, email, uri, or uuid. Provider support varies. - `items` JsonSchemaDefinition — recursive - `anyOf` JsonSchemaDefinition[] — A list of schemas. The value must match at least one of them. ## Response `201` The tool is created. - union — A tool that agents use to perform specific actions or operations. - object — Base properties shared by all tool types. - `id` string, required — Unique identifier for a tool. - `name` string, required — Unique identifier for the tool. - `title` string — Human-readable title of the tool. - `description` string, required — The description provided to the agent to guide tool selection. This is what the agent sees when deciding which tool to use. - `description_template` string — Velocity template for generating dynamic tool descriptions. When set, the template renders at runtime to produce the tool description. Available Velocity variables: - `$agent.name` - Agent name - `$agent.metadata` - Agent metadata map - `$session.key` - Session key - `$session.metadata` - Session metadata map - `$currentDate` - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z") Example: "Search tool configured for agent $agent.name on $currentDate" - `documentation` string — User-facing documentation describing the tool and how to configure it for an agent. Intended for developers and administrators browsing the tool catalog. Defaults to the agent-facing description if not explicitly set. - `enabled` boolean, required — Whether the tool is currently enabled and available for use. - `experimental` boolean — Whether this tool is experimental and may change or be removed without notice. - `created_at` string, date-time — Timestamp when the tool was created. - `updated_at` string, date-time — Timestamp when the tool was last updated. - `input_schema` object, required — The schema that defines the expected input structure for the tool. - `output_schema` object — The JSON schema that describes the structure of the tool's output. Clients may use it to understand the shape of tool responses and to author `default_output_transform` jq expressions. - `default_output_transform` string — An optional jq expression applied to the tool's JSON output before the agent receives it. Use this to project, filter, or summarize tool output to keep responses concise and on-topic. The expression operates on the tool's response JSON and the result replaces the original output. If the expression fails to compile or evaluate at runtime, the tool call returns an error to the agent so the agent can react. Examples: - `.results | map({title, url})` — keep only title/url for each result - `.items[0:5]` — first 5 items - `del(.debug)` — drop a noisy field - `default_input_transform` string — An optional jq expression applied to the tool's input after argument overrides merge with the agent's arguments and before the tool runs. Use this to inject server-side context (session metadata, agent secrets) into the tool input, or to reshape the agent's arguments. The expression receives the standard runtime context: the same `agent`, `session`, `tools`, and `currentDate` values exposed to `argument_override` `$ref`s. It also receives an `args` field that contains the merged tool input. The output of the expression replaces `args` as the tool input. The pre-transform `args` is what appears in audit events (with secrets masked); the post-transform value goes only to the tool. If the expression fails to compile or evaluate, the tool call returns an error to the agent. Examples: - `.args + { auth: ("Bearer " + .agent.secrets.token) }` — inject a bearer header - `.args | .corpus_key = .session.metadata.corpus_key` — pull a corpus key from session metadata - `.args | .query = (.args.query + " " + .session.metadata.query_suffix)` — augment the agent's query - `default_argument_override` object — Optional hardcoded arguments for tool calls. The key specifies the location in the tool arguments to override. The value specifies what to override with. The agent cannot change these parameters and does not know these values exist. The values can also be dynamic references to context values using $ref with dot notation path syntax: - Static value: "fixed_value" or 123 - Dynamic reference: `{"$ref": "session.metadata.field_name"}` References resolve at runtime from context: - session.metadata.* - Access session metadata fields - agent.metadata.* - Access agent metadata fields - agent.secrets.* - Access agent secrets (masked in audit events) - tools.* - Access prior tool outputs (resolved after the dependent tool runs) - currentDate - The current date/time in ISO 8601 format A bracket index may reference another context value. The resolved value becomes the lookup key. The inner path may optionally carry a leading $ root marker: - Indirect reference: `{"$ref": "agent.secrets[session.metadata.user_id]"}` looks up the per-user secret named by `session.metadata.user_id` - Equivalent forms: `agent.secrets[$session.metadata.user_id]` and `agent.secrets[$.session.metadata.user_id]` Example: `{"query": {"$ref": ".session.metadata.query"}}` To use a literal `"$ref"` value, write `"$$ref"`. The $$ escapes the first $. - `category` string — Functional category of the tool (e.g., retrieval, artifacts, indexing, utilities, orchestration). - `lineage` string — The base tool name without version suffix. Groups versioned variants of the same tool together. - `version` string — Date-based version identifier in YYYY-MM-DD format. Null for unversioned tools. - `tool_groups` string[] — Groups this tool belongs to. Tools in the same group form a functional set and should be added or removed together by default. - `type` string, required — This should always be `dynamic_vectara`. - object — Base properties shared by all tool types. - `id` string, required — Unique identifier for a tool. - `name` string, required — Unique identifier for the tool. - `title` string — Human-readable title of the tool. - `description` string, required — The description provided to the agent to guide tool selection. This is what the agent sees when deciding which tool to use. - `description_template` string — Velocity template for generating dynamic tool descriptions. When set, the template renders at runtime to produce the tool description. Available Velocity variables: - `$agent.name` - Agent name - `$agent.metadata` - Agent metadata map - `$session.key` - Session key - `$session.metadata` - Session metadata map - `$currentDate` - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z") Example: "Search tool configured for agent $agent.name on $currentDate" - `documentation` string — User-facing documentation describing the tool and how to configure it for an agent. Intended for developers and administrators browsing the tool catalog. Defaults to the agent-facing description if not explicitly set. - `enabled` boolean, required — Whether the tool is currently enabled and available for use. - `experimental` boolean — Whether this tool is experimental and may change or be removed without notice. - `created_at` string, date-time — Timestamp when the tool was created. - `updated_at` string, date-time — Timestamp when the tool was last updated. - `input_schema` object, required — The schema that defines the expected input structure for the tool. - `output_schema` object — The JSON schema that describes the structure of the tool's output. Clients may use it to understand the shape of tool responses and to author `default_output_transform` jq expressions. - `default_output_transform` string — An optional jq expression applied to the tool's JSON output before the agent receives it. Use this to project, filter, or summarize tool output to keep responses concise and on-topic. The expression operates on the tool's response JSON and the result replaces the original output. If the expression fails to compile or evaluate at runtime, the tool call returns an error to the agent so the agent can react. Examples: - `.results | map({title, url})` — keep only title/url for each result - `.items[0:5]` — first 5 items - `del(.debug)` — drop a noisy field - `default_input_transform` string — An optional jq expression applied to the tool's input after argument overrides merge with the agent's arguments and before the tool runs. Use this to inject server-side context (session metadata, agent secrets) into the tool input, or to reshape the agent's arguments. The expression receives the standard runtime context: the same `agent`, `session`, `tools`, and `currentDate` values exposed to `argument_override` `$ref`s. It also receives an `args` field that contains the merged tool input. The output of the expression replaces `args` as the tool input. The pre-transform `args` is what appears in audit events (with secrets masked); the post-transform value goes only to the tool. If the expression fails to compile or evaluate, the tool call returns an error to the agent. Examples: - `.args + { auth: ("Bearer " + .agent.secrets.token) }` — inject a bearer header - `.args | .corpus_key = .session.metadata.corpus_key` — pull a corpus key from session metadata - `.args | .query = (.args.query + " " + .session.metadata.query_suffix)` — augment the agent's query - `default_argument_override` object — Optional hardcoded arguments for tool calls. The key specifies the location in the tool arguments to override. The value specifies what to override with. The agent cannot change these parameters and does not know these values exist. The values can also be dynamic references to context values using $ref with dot notation path syntax: - Static value: "fixed_value" or 123 - Dynamic reference: `{"$ref": "session.metadata.field_name"}` References resolve at runtime from context: - session.metadata.* - Access session metadata fields - agent.metadata.* - Access agent metadata fields - agent.secrets.* - Access agent secrets (masked in audit events) - tools.* - Access prior tool outputs (resolved after the dependent tool runs) - currentDate - The current date/time in ISO 8601 format A bracket index may reference another context value. The resolved value becomes the lookup key. The inner path may optionally carry a leading $ root marker: - Indirect reference: `{"$ref": "agent.secrets[session.metadata.user_id]"}` looks up the per-user secret named by `session.metadata.user_id` - Equivalent forms: `agent.secrets[$session.metadata.user_id]` and `agent.secrets[$.session.metadata.user_id]` Example: `{"query": {"$ref": ".session.metadata.query"}}` To use a literal `"$ref"` value, write `"$$ref"`. The $$ escapes the first $. - `category` string — Functional category of the tool (e.g., retrieval, artifacts, indexing, utilities, orchestration). - `lineage` string — The base tool name without version suffix. Groups versioned variants of the same tool together. - `version` string — Date-based version identifier in YYYY-MM-DD format. Null for unversioned tools. - `tool_groups` string[] — Groups this tool belongs to. Tools in the same group form a functional set and should be added or removed together by default. - `type` string, required — This should always be `mcp`. - `server_id` string — Unique identifier for a tool server. - `annotations` McpToolAnnotations — Optional hints about tool behavior and metadata. - `read_only_hint` boolean — If true, the tool does not modify its environment. - `destructive_hint` boolean — If true, the tool may perform destructive updates. - `idempotent_hint` boolean — If true, repeated calls with same args have no additional effect. - `open_world_hint` boolean — If true, tool interacts with external entities. - object — Base properties shared by all tool types. - `id` string, required — Unique identifier for a tool. - `name` string, required — Unique identifier for the tool. - `title` string — Human-readable title of the tool. - `description` string, required — The description provided to the agent to guide tool selection. This is what the agent sees when deciding which tool to use. - `description_template` string — Velocity template for generating dynamic tool descriptions. When set, the template renders at runtime to produce the tool description. Available Velocity variables: - `$agent.name` - Agent name - `$agent.metadata` - Agent metadata map - `$session.key` - Session key - `$session.metadata` - Session metadata map - `$currentDate` - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z") Example: "Search tool configured for agent $agent.name on $currentDate" - `documentation` string — User-facing documentation describing the tool and how to configure it for an agent. Intended for developers and administrators browsing the tool catalog. Defaults to the agent-facing description if not explicitly set. - `enabled` boolean, required — Whether the tool is currently enabled and available for use. - `experimental` boolean — Whether this tool is experimental and may change or be removed without notice. - `created_at` string, date-time — Timestamp when the tool was created. - `updated_at` string, date-time — Timestamp when the tool was last updated. - `input_schema` object, required — The schema that defines the expected input structure for the tool. - `output_schema` object — The JSON schema that describes the structure of the tool's output. Clients may use it to understand the shape of tool responses and to author `default_output_transform` jq expressions. - `default_output_transform` string — An optional jq expression applied to the tool's JSON output before the agent receives it. Use this to project, filter, or summarize tool output to keep responses concise and on-topic. The expression operates on the tool's response JSON and the result replaces the original output. If the expression fails to compile or evaluate at runtime, the tool call returns an error to the agent so the agent can react. Examples: - `.results | map({title, url})` — keep only title/url for each result - `.items[0:5]` — first 5 items - `del(.debug)` — drop a noisy field - `default_input_transform` string — An optional jq expression applied to the tool's input after argument overrides merge with the agent's arguments and before the tool runs. Use this to inject server-side context (session metadata, agent secrets) into the tool input, or to reshape the agent's arguments. The expression receives the standard runtime context: the same `agent`, `session`, `tools`, and `currentDate` values exposed to `argument_override` `$ref`s. It also receives an `args` field that contains the merged tool input. The output of the expression replaces `args` as the tool input. The pre-transform `args` is what appears in audit events (with secrets masked); the post-transform value goes only to the tool. If the expression fails to compile or evaluate, the tool call returns an error to the agent. Examples: - `.args + { auth: ("Bearer " + .agent.secrets.token) }` — inject a bearer header - `.args | .corpus_key = .session.metadata.corpus_key` — pull a corpus key from session metadata - `.args | .query = (.args.query + " " + .session.metadata.query_suffix)` — augment the agent's query - `default_argument_override` object — Optional hardcoded arguments for tool calls. The key specifies the location in the tool arguments to override. The value specifies what to override with. The agent cannot change these parameters and does not know these values exist. The values can also be dynamic references to context values using $ref with dot notation path syntax: - Static value: "fixed_value" or 123 - Dynamic reference: `{"$ref": "session.metadata.field_name"}` References resolve at runtime from context: - session.metadata.* - Access session metadata fields - agent.metadata.* - Access agent metadata fields - agent.secrets.* - Access agent secrets (masked in audit events) - tools.* - Access prior tool outputs (resolved after the dependent tool runs) - currentDate - The current date/time in ISO 8601 format A bracket index may reference another context value. The resolved value becomes the lookup key. The inner path may optionally carry a leading $ root marker: - Indirect reference: `{"$ref": "agent.secrets[session.metadata.user_id]"}` looks up the per-user secret named by `session.metadata.user_id` - Equivalent forms: `agent.secrets[$session.metadata.user_id]` and `agent.secrets[$.session.metadata.user_id]` Example: `{"query": {"$ref": ".session.metadata.query"}}` To use a literal `"$ref"` value, write `"$$ref"`. The $$ escapes the first $. - `category` string — Functional category of the tool (e.g., retrieval, artifacts, indexing, utilities, orchestration). - `lineage` string — The base tool name without version suffix. Groups versioned variants of the same tool together. - `version` string — Date-based version identifier in YYYY-MM-DD format. Null for unversioned tools. - `tool_groups` string[] — Groups this tool belongs to. Tools in the same group form a functional set and should be added or removed together by default. - `type` string, required — This should always be `corpora_search`. - object — Base properties shared by all tool types. - `id` string, required — Unique identifier for a tool. - `name` string, required — Unique identifier for the tool. - `title` string — Human-readable title of the tool. - `description` string, required — The description provided to the agent to guide tool selection. This is what the agent sees when deciding which tool to use. - `description_template` string — Velocity template for generating dynamic tool descriptions. When set, the template renders at runtime to produce the tool description. Available Velocity variables: - `$agent.name` - Agent name - `$agent.metadata` - Agent metadata map - `$session.key` - Session key - `$session.metadata` - Session metadata map - `$currentDate` - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z") Example: "Search tool configured for agent $agent.name on $currentDate" - `documentation` string — User-facing documentation describing the tool and how to configure it for an agent. Intended for developers and administrators browsing the tool catalog. Defaults to the agent-facing description if not explicitly set. - `enabled` boolean, required — Whether the tool is currently enabled and available for use. - `experimental` boolean — Whether this tool is experimental and may change or be removed without notice. - `created_at` string, date-time — Timestamp when the tool was created. - `updated_at` string, date-time — Timestamp when the tool was last updated. - `input_schema` object, required — The schema that defines the expected input structure for the tool. - `output_schema` object — The JSON schema that describes the structure of the tool's output. Clients may use it to understand the shape of tool responses and to author `default_output_transform` jq expressions. - `default_output_transform` string — An optional jq expression applied to the tool's JSON output before the agent receives it. Use this to project, filter, or summarize tool output to keep responses concise and on-topic. The expression operates on the tool's response JSON and the result replaces the original output. If the expression fails to compile or evaluate at runtime, the tool call returns an error to the agent so the agent can react. Examples: - `.results | map({title, url})` — keep only title/url for each result - `.items[0:5]` — first 5 items - `del(.debug)` — drop a noisy field - `default_input_transform` string — An optional jq expression applied to the tool's input after argument overrides merge with the agent's arguments and before the tool runs. Use this to inject server-side context (session metadata, agent secrets) into the tool input, or to reshape the agent's arguments. The expression receives the standard runtime context: the same `agent`, `session`, `tools`, and `currentDate` values exposed to `argument_override` `$ref`s. It also receives an `args` field that contains the merged tool input. The output of the expression replaces `args` as the tool input. The pre-transform `args` is what appears in audit events (with secrets masked); the post-transform value goes only to the tool. If the expression fails to compile or evaluate, the tool call returns an error to the agent. Examples: - `.args + { auth: ("Bearer " + .agent.secrets.token) }` — inject a bearer header - `.args | .corpus_key = .session.metadata.corpus_key` — pull a corpus key from session metadata - `.args | .query = (.args.query + " " + .session.metadata.query_suffix)` — augment the agent's query - `default_argument_override` object — Optional hardcoded arguments for tool calls. The key specifies the location in the tool arguments to override. The value specifies what to override with. The agent cannot change these parameters and does not know these values exist. The values can also be dynamic references to context values using $ref with dot notation path syntax: - Static value: "fixed_value" or 123 - Dynamic reference: `{"$ref": "session.metadata.field_name"}` References resolve at runtime from context: - session.metadata.* - Access session metadata fields - agent.metadata.* - Access agent metadata fields - agent.secrets.* - Access agent secrets (masked in audit events) - tools.* - Access prior tool outputs (resolved after the dependent tool runs) - currentDate - The current date/time in ISO 8601 format A bracket index may reference another context value. The resolved value becomes the lookup key. The inner path may optionally carry a leading $ root marker: - Indirect reference: `{"$ref": "agent.secrets[session.metadata.user_id]"}` looks up the per-user secret named by `session.metadata.user_id` - Equivalent forms: `agent.secrets[$session.metadata.user_id]` and `agent.secrets[$.session.metadata.user_id]` Example: `{"query": {"$ref": ".session.metadata.query"}}` To use a literal `"$ref"` value, write `"$$ref"`. The $$ escapes the first $. - `category` string — Functional category of the tool (e.g., retrieval, artifacts, indexing, utilities, orchestration). - `lineage` string — The base tool name without version suffix. Groups versioned variants of the same tool together. - `version` string — Date-based version identifier in YYYY-MM-DD format. Null for unversioned tools. - `tool_groups` string[] — Groups this tool belongs to. Tools in the same group form a functional set and should be added or removed together by default. - `type` string, required — This should always be `web_search`. - object — Base properties shared by all tool types. - `id` string, required — Unique identifier for a tool. - `name` string, required — Unique identifier for the tool. - `title` string — Human-readable title of the tool. - `description` string, required — The description provided to the agent to guide tool selection. This is what the agent sees when deciding which tool to use. - `description_template` string — Velocity template for generating dynamic tool descriptions. When set, the template renders at runtime to produce the tool description. Available Velocity variables: - `$agent.name` - Agent name - `$agent.metadata` - Agent metadata map - `$session.key` - Session key - `$session.metadata` - Session metadata map - `$currentDate` - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z") Example: "Search tool configured for agent $agent.name on $currentDate" - `documentation` string — User-facing documentation describing the tool and how to configure it for an agent. Intended for developers and administrators browsing the tool catalog. Defaults to the agent-facing description if not explicitly set. - `enabled` boolean, required — Whether the tool is currently enabled and available for use. - `experimental` boolean — Whether this tool is experimental and may change or be removed without notice. - `created_at` string, date-time — Timestamp when the tool was created. - `updated_at` string, date-time — Timestamp when the tool was last updated. - `input_schema` object, required — The schema that defines the expected input structure for the tool. - `output_schema` object — The JSON schema that describes the structure of the tool's output. Clients may use it to understand the shape of tool responses and to author `default_output_transform` jq expressions. - `default_output_transform` string — An optional jq expression applied to the tool's JSON output before the agent receives it. Use this to project, filter, or summarize tool output to keep responses concise and on-topic. The expression operates on the tool's response JSON and the result replaces the original output. If the expression fails to compile or evaluate at runtime, the tool call returns an error to the agent so the agent can react. Examples: - `.results | map({title, url})` — keep only title/url for each result - `.items[0:5]` — first 5 items - `del(.debug)` — drop a noisy field - `default_input_transform` string — An optional jq expression applied to the tool's input after argument overrides merge with the agent's arguments and before the tool runs. Use this to inject server-side context (session metadata, agent secrets) into the tool input, or to reshape the agent's arguments. The expression receives the standard runtime context: the same `agent`, `session`, `tools`, and `currentDate` values exposed to `argument_override` `$ref`s. It also receives an `args` field that contains the merged tool input. The output of the expression replaces `args` as the tool input. The pre-transform `args` is what appears in audit events (with secrets masked); the post-transform value goes only to the tool. If the expression fails to compile or evaluate, the tool call returns an error to the agent. Examples: - `.args + { auth: ("Bearer " + .agent.secrets.token) }` — inject a bearer header - `.args | .corpus_key = .session.metadata.corpus_key` — pull a corpus key from session metadata - `.args | .query = (.args.query + " " + .session.metadata.query_suffix)` — augment the agent's query - `default_argument_override` object — Optional hardcoded arguments for tool calls. The key specifies the location in the tool arguments to override. The value specifies what to override with. The agent cannot change these parameters and does not know these values exist. The values can also be dynamic references to context values using $ref with dot notation path syntax: - Static value: "fixed_value" or 123 - Dynamic reference: `{"$ref": "session.metadata.field_name"}` References resolve at runtime from context: - session.metadata.* - Access session metadata fields - agent.metadata.* - Access agent metadata fields - agent.secrets.* - Access agent secrets (masked in audit events) - tools.* - Access prior tool outputs (resolved after the dependent tool runs) - currentDate - The current date/time in ISO 8601 format A bracket index may reference another context value. The resolved value becomes the lookup key. The inner path may optionally carry a leading $ root marker: - Indirect reference: `{"$ref": "agent.secrets[session.metadata.user_id]"}` looks up the per-user secret named by `session.metadata.user_id` - Equivalent forms: `agent.secrets[$session.metadata.user_id]` and `agent.secrets[$.session.metadata.user_id]` Example: `{"query": {"$ref": ".session.metadata.query"}}` To use a literal `"$ref"` value, write `"$$ref"`. The $$ escapes the first $. - `category` string — Functional category of the tool (e.g., retrieval, artifacts, indexing, utilities, orchestration). - `lineage` string — The base tool name without version suffix. Groups versioned variants of the same tool together. - `version` string — Date-based version identifier in YYYY-MM-DD format. Null for unversioned tools. - `tool_groups` string[] — Groups this tool belongs to. Tools in the same group form a functional set and should be added or removed together by default. - `type` string, required — This should always be `web_get`. - object — Base properties shared by all tool types. - `id` string, required — Unique identifier for a tool. - `name` string, required — Unique identifier for the tool. - `title` string — Human-readable title of the tool. - `description` string, required — The description provided to the agent to guide tool selection. This is what the agent sees when deciding which tool to use. - `description_template` string — Velocity template for generating dynamic tool descriptions. When set, the template renders at runtime to produce the tool description. Available Velocity variables: - `$agent.name` - Agent name - `$agent.metadata` - Agent metadata map - `$session.key` - Session key - `$session.metadata` - Session metadata map - `$currentDate` - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z") Example: "Search tool configured for agent $agent.name on $currentDate" - `documentation` string — User-facing documentation describing the tool and how to configure it for an agent. Intended for developers and administrators browsing the tool catalog. Defaults to the agent-facing description if not explicitly set. - `enabled` boolean, required — Whether the tool is currently enabled and available for use. - `experimental` boolean — Whether this tool is experimental and may change or be removed without notice. - `created_at` string, date-time — Timestamp when the tool was created. - `updated_at` string, date-time — Timestamp when the tool was last updated. - `input_schema` object, required — The schema that defines the expected input structure for the tool. - `output_schema` object — The JSON schema that describes the structure of the tool's output. Clients may use it to understand the shape of tool responses and to author `default_output_transform` jq expressions. - `default_output_transform` string — An optional jq expression applied to the tool's JSON output before the agent receives it. Use this to project, filter, or summarize tool output to keep responses concise and on-topic. The expression operates on the tool's response JSON and the result replaces the original output. If the expression fails to compile or evaluate at runtime, the tool call returns an error to the agent so the agent can react. Examples: - `.results | map({title, url})` — keep only title/url for each result - `.items[0:5]` — first 5 items - `del(.debug)` — drop a noisy field - `default_input_transform` string — An optional jq expression applied to the tool's input after argument overrides merge with the agent's arguments and before the tool runs. Use this to inject server-side context (session metadata, agent secrets) into the tool input, or to reshape the agent's arguments. The expression receives the standard runtime context: the same `agent`, `session`, `tools`, and `currentDate` values exposed to `argument_override` `$ref`s. It also receives an `args` field that contains the merged tool input. The output of the expression replaces `args` as the tool input. The pre-transform `args` is what appears in audit events (with secrets masked); the post-transform value goes only to the tool. If the expression fails to compile or evaluate, the tool call returns an error to the agent. Examples: - `.args + { auth: ("Bearer " + .agent.secrets.token) }` — inject a bearer header - `.args | .corpus_key = .session.metadata.corpus_key` — pull a corpus key from session metadata - `.args | .query = (.args.query + " " + .session.metadata.query_suffix)` — augment the agent's query - `default_argument_override` object — Optional hardcoded arguments for tool calls. The key specifies the location in the tool arguments to override. The value specifies what to override with. The agent cannot change these parameters and does not know these values exist. The values can also be dynamic references to context values using $ref with dot notation path syntax: - Static value: "fixed_value" or 123 - Dynamic reference: `{"$ref": "session.metadata.field_name"}` References resolve at runtime from context: - session.metadata.* - Access session metadata fields - agent.metadata.* - Access agent metadata fields - agent.secrets.* - Access agent secrets (masked in audit events) - tools.* - Access prior tool outputs (resolved after the dependent tool runs) - currentDate - The current date/time in ISO 8601 format A bracket index may reference another context value. The resolved value becomes the lookup key. The inner path may optionally carry a leading $ root marker: - Indirect reference: `{"$ref": "agent.secrets[session.metadata.user_id]"}` looks up the per-user secret named by `session.metadata.user_id` - Equivalent forms: `agent.secrets[$session.metadata.user_id]` and `agent.secrets[$.session.metadata.user_id]` Example: `{"query": {"$ref": ".session.metadata.query"}}` To use a literal `"$ref"` value, write `"$$ref"`. The $$ escapes the first $. - `category` string — Functional category of the tool (e.g., retrieval, artifacts, indexing, utilities, orchestration). - `lineage` string — The base tool name without version suffix. Groups versioned variants of the same tool together. - `version` string — Date-based version identifier in YYYY-MM-DD format. Null for unversioned tools. - `tool_groups` string[] — Groups this tool belongs to. Tools in the same group form a functional set and should be added or removed together by default. - `type` string, required — This should always be `lambda`. - `language` 'python', required — The programming language of the lambda function. Currently only Python 3.12 is supported. - `function_definition` FunctionDefinition, required — Definition of a function to be executed as a tool in a sandboxed environment. **Python Environment:** - Python version: 3.12 - Execution: Sandboxed for security isolation - **Allowed modules**: `json`, `math`, `datetime`, `collections`, `itertools`, `functools`, `re`, `time`, `typing` - Memory limit: 100MB (configurable up to 1GB) - Execution timeout: 30 seconds (configurable up to 300 seconds) - Network access: Disabled for security - File system access: Read-only temporary workspace - No custom package installation supported (security constraint) **Type Annotations:** - Use type annotations for automatic input/output schema discovery - Supported typing constructs: `List`, `Dict`, `Optional`, `Union`, `Literal` - Import from `typing` module when using complex types **Docstring Parameter Descriptions:** - Use docstrings to provide descriptions for parameters (Google, NumPy, ReST, and Epydoc styles are supported) - The platform extracts parameter descriptions and includes them in the input schema - This gives agents better context about how to use each parameter - `language` 'python', required — The programming language of the function. Currently only Python 3.12 is supported. - `code` string, required — The function code. **Required**: Must define a `process()` entry point function. Use type annotations on parameters for automatic schema discovery. Parameters are passed as keyword arguments matched to the function signature. - `validation_status` 'pending' | 'valid' | 'invalid' — The validation status of the code. - `validation_errors` string[] — List of validation errors if the code is invalid. - `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. - `tool_configurations` object — Named tool configurations private to this lambda tool, each callable from the tool's code as `tool.(...)`. They do not appear on the hosting agent's tool surface, and their calls produce no session events. `$ref`s in `argument_override` resolve against the hosting agent and session at execution time. - object — Base properties shared by all tool types. - `id` string, required — Unique identifier for a tool. - `name` string, required — Unique identifier for the tool. - `title` string — Human-readable title of the tool. - `description` string, required — The description provided to the agent to guide tool selection. This is what the agent sees when deciding which tool to use. - `description_template` string — Velocity template for generating dynamic tool descriptions. When set, the template renders at runtime to produce the tool description. Available Velocity variables: - `$agent.name` - Agent name - `$agent.metadata` - Agent metadata map - `$session.key` - Session key - `$session.metadata` - Session metadata map - `$currentDate` - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z") Example: "Search tool configured for agent $agent.name on $currentDate" - `documentation` string — User-facing documentation describing the tool and how to configure it for an agent. Intended for developers and administrators browsing the tool catalog. Defaults to the agent-facing description if not explicitly set. - `enabled` boolean, required — Whether the tool is currently enabled and available for use. - `experimental` boolean — Whether this tool is experimental and may change or be removed without notice. - `created_at` string, date-time — Timestamp when the tool was created. - `updated_at` string, date-time — Timestamp when the tool was last updated. - `input_schema` object, required — The schema that defines the expected input structure for the tool. - `output_schema` object — The JSON schema that describes the structure of the tool's output. Clients may use it to understand the shape of tool responses and to author `default_output_transform` jq expressions. - `default_output_transform` string — An optional jq expression applied to the tool's JSON output before the agent receives it. Use this to project, filter, or summarize tool output to keep responses concise and on-topic. The expression operates on the tool's response JSON and the result replaces the original output. If the expression fails to compile or evaluate at runtime, the tool call returns an error to the agent so the agent can react. Examples: - `.results | map({title, url})` — keep only title/url for each result - `.items[0:5]` — first 5 items - `del(.debug)` — drop a noisy field - `default_input_transform` string — An optional jq expression applied to the tool's input after argument overrides merge with the agent's arguments and before the tool runs. Use this to inject server-side context (session metadata, agent secrets) into the tool input, or to reshape the agent's arguments. The expression receives the standard runtime context: the same `agent`, `session`, `tools`, and `currentDate` values exposed to `argument_override` `$ref`s. It also receives an `args` field that contains the merged tool input. The output of the expression replaces `args` as the tool input. The pre-transform `args` is what appears in audit events (with secrets masked); the post-transform value goes only to the tool. If the expression fails to compile or evaluate, the tool call returns an error to the agent. Examples: - `.args + { auth: ("Bearer " + .agent.secrets.token) }` — inject a bearer header - `.args | .corpus_key = .session.metadata.corpus_key` — pull a corpus key from session metadata - `.args | .query = (.args.query + " " + .session.metadata.query_suffix)` — augment the agent's query - `default_argument_override` object — Optional hardcoded arguments for tool calls. The key specifies the location in the tool arguments to override. The value specifies what to override with. The agent cannot change these parameters and does not know these values exist. The values can also be dynamic references to context values using $ref with dot notation path syntax: - Static value: "fixed_value" or 123 - Dynamic reference: `{"$ref": "session.metadata.field_name"}` References resolve at runtime from context: - session.metadata.* - Access session metadata fields - agent.metadata.* - Access agent metadata fields - agent.secrets.* - Access agent secrets (masked in audit events) - tools.* - Access prior tool outputs (resolved after the dependent tool runs) - currentDate - The current date/time in ISO 8601 format A bracket index may reference another context value. The resolved value becomes the lookup key. The inner path may optionally carry a leading $ root marker: - Indirect reference: `{"$ref": "agent.secrets[session.metadata.user_id]"}` looks up the per-user secret named by `session.metadata.user_id` - Equivalent forms: `agent.secrets[$session.metadata.user_id]` and `agent.secrets[$.session.metadata.user_id]` Example: `{"query": {"$ref": ".session.metadata.query"}}` To use a literal `"$ref"` value, write `"$$ref"`. The $$ escapes the first $. - `category` string — Functional category of the tool (e.g., retrieval, artifacts, indexing, utilities, orchestration). - `lineage` string — The base tool name without version suffix. Groups versioned variants of the same tool together. - `version` string — Date-based version identifier in YYYY-MM-DD format. Null for unversioned tools. - `tool_groups` string[] — Groups this tool belongs to. Tools in the same group form a functional set and should be added or removed together by default. - `type` string, required — This should always be `sub_agent`. - object — Base properties shared by all tool types. - `id` string, required — Unique identifier for a tool. - `name` string, required — Unique identifier for the tool. - `title` string — Human-readable title of the tool. - `description` string, required — The description provided to the agent to guide tool selection. This is what the agent sees when deciding which tool to use. - `description_template` string — Velocity template for generating dynamic tool descriptions. When set, the template renders at runtime to produce the tool description. Available Velocity variables: - `$agent.name` - Agent name - `$agent.metadata` - Agent metadata map - `$session.key` - Session key - `$session.metadata` - Session metadata map - `$currentDate` - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z") Example: "Search tool configured for agent $agent.name on $currentDate" - `documentation` string — User-facing documentation describing the tool and how to configure it for an agent. Intended for developers and administrators browsing the tool catalog. Defaults to the agent-facing description if not explicitly set. - `enabled` boolean, required — Whether the tool is currently enabled and available for use. - `experimental` boolean — Whether this tool is experimental and may change or be removed without notice. - `created_at` string, date-time — Timestamp when the tool was created. - `updated_at` string, date-time — Timestamp when the tool was last updated. - `input_schema` object, required — The schema that defines the expected input structure for the tool. - `output_schema` object — The JSON schema that describes the structure of the tool's output. Clients may use it to understand the shape of tool responses and to author `default_output_transform` jq expressions. - `default_output_transform` string — An optional jq expression applied to the tool's JSON output before the agent receives it. Use this to project, filter, or summarize tool output to keep responses concise and on-topic. The expression operates on the tool's response JSON and the result replaces the original output. If the expression fails to compile or evaluate at runtime, the tool call returns an error to the agent so the agent can react. Examples: - `.results | map({title, url})` — keep only title/url for each result - `.items[0:5]` — first 5 items - `del(.debug)` — drop a noisy field - `default_input_transform` string — An optional jq expression applied to the tool's input after argument overrides merge with the agent's arguments and before the tool runs. Use this to inject server-side context (session metadata, agent secrets) into the tool input, or to reshape the agent's arguments. The expression receives the standard runtime context: the same `agent`, `session`, `tools`, and `currentDate` values exposed to `argument_override` `$ref`s. It also receives an `args` field that contains the merged tool input. The output of the expression replaces `args` as the tool input. The pre-transform `args` is what appears in audit events (with secrets masked); the post-transform value goes only to the tool. If the expression fails to compile or evaluate, the tool call returns an error to the agent. Examples: - `.args + { auth: ("Bearer " + .agent.secrets.token) }` — inject a bearer header - `.args | .corpus_key = .session.metadata.corpus_key` — pull a corpus key from session metadata - `.args | .query = (.args.query + " " + .session.metadata.query_suffix)` — augment the agent's query - `default_argument_override` object — Optional hardcoded arguments for tool calls. The key specifies the location in the tool arguments to override. The value specifies what to override with. The agent cannot change these parameters and does not know these values exist. The values can also be dynamic references to context values using $ref with dot notation path syntax: - Static value: "fixed_value" or 123 - Dynamic reference: `{"$ref": "session.metadata.field_name"}` References resolve at runtime from context: - session.metadata.* - Access session metadata fields - agent.metadata.* - Access agent metadata fields - agent.secrets.* - Access agent secrets (masked in audit events) - tools.* - Access prior tool outputs (resolved after the dependent tool runs) - currentDate - The current date/time in ISO 8601 format A bracket index may reference another context value. The resolved value becomes the lookup key. The inner path may optionally carry a leading $ root marker: - Indirect reference: `{"$ref": "agent.secrets[session.metadata.user_id]"}` looks up the per-user secret named by `session.metadata.user_id` - Equivalent forms: `agent.secrets[$session.metadata.user_id]` and `agent.secrets[$.session.metadata.user_id]` Example: `{"query": {"$ref": ".session.metadata.query"}}` To use a literal `"$ref"` value, write `"$$ref"`. The $$ escapes the first $. - `category` string — Functional category of the tool (e.g., retrieval, artifacts, indexing, utilities, orchestration). - `lineage` string — The base tool name without version suffix. Groups versioned variants of the same tool together. - `version` string — Date-based version identifier in YYYY-MM-DD format. Null for unversioned tools. - `tool_groups` string[] — Groups this tool belongs to. Tools in the same group form a functional set and should be added or removed together by default. - `type` string, required — This should always be `artifact_create`. - object — Base properties shared by all tool types. - `id` string, required — Unique identifier for a tool. - `name` string, required — Unique identifier for the tool. - `title` string — Human-readable title of the tool. - `description` string, required — The description provided to the agent to guide tool selection. This is what the agent sees when deciding which tool to use. - `description_template` string — Velocity template for generating dynamic tool descriptions. When set, the template renders at runtime to produce the tool description. Available Velocity variables: - `$agent.name` - Agent name - `$agent.metadata` - Agent metadata map - `$session.key` - Session key - `$session.metadata` - Session metadata map - `$currentDate` - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z") Example: "Search tool configured for agent $agent.name on $currentDate" - `documentation` string — User-facing documentation describing the tool and how to configure it for an agent. Intended for developers and administrators browsing the tool catalog. Defaults to the agent-facing description if not explicitly set. - `enabled` boolean, required — Whether the tool is currently enabled and available for use. - `experimental` boolean — Whether this tool is experimental and may change or be removed without notice. - `created_at` string, date-time — Timestamp when the tool was created. - `updated_at` string, date-time — Timestamp when the tool was last updated. - `input_schema` object, required — The schema that defines the expected input structure for the tool. - `output_schema` object — The JSON schema that describes the structure of the tool's output. Clients may use it to understand the shape of tool responses and to author `default_output_transform` jq expressions. - `default_output_transform` string — An optional jq expression applied to the tool's JSON output before the agent receives it. Use this to project, filter, or summarize tool output to keep responses concise and on-topic. The expression operates on the tool's response JSON and the result replaces the original output. If the expression fails to compile or evaluate at runtime, the tool call returns an error to the agent so the agent can react. Examples: - `.results | map({title, url})` — keep only title/url for each result - `.items[0:5]` — first 5 items - `del(.debug)` — drop a noisy field - `default_input_transform` string — An optional jq expression applied to the tool's input after argument overrides merge with the agent's arguments and before the tool runs. Use this to inject server-side context (session metadata, agent secrets) into the tool input, or to reshape the agent's arguments. The expression receives the standard runtime context: the same `agent`, `session`, `tools`, and `currentDate` values exposed to `argument_override` `$ref`s. It also receives an `args` field that contains the merged tool input. The output of the expression replaces `args` as the tool input. The pre-transform `args` is what appears in audit events (with secrets masked); the post-transform value goes only to the tool. If the expression fails to compile or evaluate, the tool call returns an error to the agent. Examples: - `.args + { auth: ("Bearer " + .agent.secrets.token) }` — inject a bearer header - `.args | .corpus_key = .session.metadata.corpus_key` — pull a corpus key from session metadata - `.args | .query = (.args.query + " " + .session.metadata.query_suffix)` — augment the agent's query - `default_argument_override` object — Optional hardcoded arguments for tool calls. The key specifies the location in the tool arguments to override. The value specifies what to override with. The agent cannot change these parameters and does not know these values exist. The values can also be dynamic references to context values using $ref with dot notation path syntax: - Static value: "fixed_value" or 123 - Dynamic reference: `{"$ref": "session.metadata.field_name"}` References resolve at runtime from context: - session.metadata.* - Access session metadata fields - agent.metadata.* - Access agent metadata fields - agent.secrets.* - Access agent secrets (masked in audit events) - tools.* - Access prior tool outputs (resolved after the dependent tool runs) - currentDate - The current date/time in ISO 8601 format A bracket index may reference another context value. The resolved value becomes the lookup key. The inner path may optionally carry a leading $ root marker: - Indirect reference: `{"$ref": "agent.secrets[session.metadata.user_id]"}` looks up the per-user secret named by `session.metadata.user_id` - Equivalent forms: `agent.secrets[$session.metadata.user_id]` and `agent.secrets[$.session.metadata.user_id]` Example: `{"query": {"$ref": ".session.metadata.query"}}` To use a literal `"$ref"` value, write `"$$ref"`. The $$ escapes the first $. - `category` string — Functional category of the tool (e.g., retrieval, artifacts, indexing, utilities, orchestration). - `lineage` string — The base tool name without version suffix. Groups versioned variants of the same tool together. - `version` string — Date-based version identifier in YYYY-MM-DD format. Null for unversioned tools. - `tool_groups` string[] — Groups this tool belongs to. Tools in the same group form a functional set and should be added or removed together by default. - `type` string, required — This should always be `artifact_read`. - object — Base properties shared by all tool types. - `id` string, required — Unique identifier for a tool. - `name` string, required — Unique identifier for the tool. - `title` string — Human-readable title of the tool. - `description` string, required — The description provided to the agent to guide tool selection. This is what the agent sees when deciding which tool to use. - `description_template` string — Velocity template for generating dynamic tool descriptions. When set, the template renders at runtime to produce the tool description. Available Velocity variables: - `$agent.name` - Agent name - `$agent.metadata` - Agent metadata map - `$session.key` - Session key - `$session.metadata` - Session metadata map - `$currentDate` - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z") Example: "Search tool configured for agent $agent.name on $currentDate" - `documentation` string — User-facing documentation describing the tool and how to configure it for an agent. Intended for developers and administrators browsing the tool catalog. Defaults to the agent-facing description if not explicitly set. - `enabled` boolean, required — Whether the tool is currently enabled and available for use. - `experimental` boolean — Whether this tool is experimental and may change or be removed without notice. - `created_at` string, date-time — Timestamp when the tool was created. - `updated_at` string, date-time — Timestamp when the tool was last updated. - `input_schema` object, required — The schema that defines the expected input structure for the tool. - `output_schema` object — The JSON schema that describes the structure of the tool's output. Clients may use it to understand the shape of tool responses and to author `default_output_transform` jq expressions. - `default_output_transform` string — An optional jq expression applied to the tool's JSON output before the agent receives it. Use this to project, filter, or summarize tool output to keep responses concise and on-topic. The expression operates on the tool's response JSON and the result replaces the original output. If the expression fails to compile or evaluate at runtime, the tool call returns an error to the agent so the agent can react. Examples: - `.results | map({title, url})` — keep only title/url for each result - `.items[0:5]` — first 5 items - `del(.debug)` — drop a noisy field - `default_input_transform` string — An optional jq expression applied to the tool's input after argument overrides merge with the agent's arguments and before the tool runs. Use this to inject server-side context (session metadata, agent secrets) into the tool input, or to reshape the agent's arguments. The expression receives the standard runtime context: the same `agent`, `session`, `tools`, and `currentDate` values exposed to `argument_override` `$ref`s. It also receives an `args` field that contains the merged tool input. The output of the expression replaces `args` as the tool input. The pre-transform `args` is what appears in audit events (with secrets masked); the post-transform value goes only to the tool. If the expression fails to compile or evaluate, the tool call returns an error to the agent. Examples: - `.args + { auth: ("Bearer " + .agent.secrets.token) }` — inject a bearer header - `.args | .corpus_key = .session.metadata.corpus_key` — pull a corpus key from session metadata - `.args | .query = (.args.query + " " + .session.metadata.query_suffix)` — augment the agent's query - `default_argument_override` object — Optional hardcoded arguments for tool calls. The key specifies the location in the tool arguments to override. The value specifies what to override with. The agent cannot change these parameters and does not know these values exist. The values can also be dynamic references to context values using $ref with dot notation path syntax: - Static value: "fixed_value" or 123 - Dynamic reference: `{"$ref": "session.metadata.field_name"}` References resolve at runtime from context: - session.metadata.* - Access session metadata fields - agent.metadata.* - Access agent metadata fields - agent.secrets.* - Access agent secrets (masked in audit events) - tools.* - Access prior tool outputs (resolved after the dependent tool runs) - currentDate - The current date/time in ISO 8601 format A bracket index may reference another context value. The resolved value becomes the lookup key. The inner path may optionally carry a leading $ root marker: - Indirect reference: `{"$ref": "agent.secrets[session.metadata.user_id]"}` looks up the per-user secret named by `session.metadata.user_id` - Equivalent forms: `agent.secrets[$session.metadata.user_id]` and `agent.secrets[$.session.metadata.user_id]` Example: `{"query": {"$ref": ".session.metadata.query"}}` To use a literal `"$ref"` value, write `"$$ref"`. The $$ escapes the first $. - `category` string — Functional category of the tool (e.g., retrieval, artifacts, indexing, utilities, orchestration). - `lineage` string — The base tool name without version suffix. Groups versioned variants of the same tool together. - `version` string — Date-based version identifier in YYYY-MM-DD format. Null for unversioned tools. - `tool_groups` string[] — Groups this tool belongs to. Tools in the same group form a functional set and should be added or removed together by default. - `type` string, required — This should always be `artifact_grep`. - object — Base properties shared by all tool types. - `id` string, required — Unique identifier for a tool. - `name` string, required — Unique identifier for the tool. - `title` string — Human-readable title of the tool. - `description` string, required — The description provided to the agent to guide tool selection. This is what the agent sees when deciding which tool to use. - `description_template` string — Velocity template for generating dynamic tool descriptions. When set, the template renders at runtime to produce the tool description. Available Velocity variables: - `$agent.name` - Agent name - `$agent.metadata` - Agent metadata map - `$session.key` - Session key - `$session.metadata` - Session metadata map - `$currentDate` - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z") Example: "Search tool configured for agent $agent.name on $currentDate" - `documentation` string — User-facing documentation describing the tool and how to configure it for an agent. Intended for developers and administrators browsing the tool catalog. Defaults to the agent-facing description if not explicitly set. - `enabled` boolean, required — Whether the tool is currently enabled and available for use. - `experimental` boolean — Whether this tool is experimental and may change or be removed without notice. - `created_at` string, date-time — Timestamp when the tool was created. - `updated_at` string, date-time — Timestamp when the tool was last updated. - `input_schema` object, required — The schema that defines the expected input structure for the tool. - `output_schema` object — The JSON schema that describes the structure of the tool's output. Clients may use it to understand the shape of tool responses and to author `default_output_transform` jq expressions. - `default_output_transform` string — An optional jq expression applied to the tool's JSON output before the agent receives it. Use this to project, filter, or summarize tool output to keep responses concise and on-topic. The expression operates on the tool's response JSON and the result replaces the original output. If the expression fails to compile or evaluate at runtime, the tool call returns an error to the agent so the agent can react. Examples: - `.results | map({title, url})` — keep only title/url for each result - `.items[0:5]` — first 5 items - `del(.debug)` — drop a noisy field - `default_input_transform` string — An optional jq expression applied to the tool's input after argument overrides merge with the agent's arguments and before the tool runs. Use this to inject server-side context (session metadata, agent secrets) into the tool input, or to reshape the agent's arguments. The expression receives the standard runtime context: the same `agent`, `session`, `tools`, and `currentDate` values exposed to `argument_override` `$ref`s. It also receives an `args` field that contains the merged tool input. The output of the expression replaces `args` as the tool input. The pre-transform `args` is what appears in audit events (with secrets masked); the post-transform value goes only to the tool. If the expression fails to compile or evaluate, the tool call returns an error to the agent. Examples: - `.args + { auth: ("Bearer " + .agent.secrets.token) }` — inject a bearer header - `.args | .corpus_key = .session.metadata.corpus_key` — pull a corpus key from session metadata - `.args | .query = (.args.query + " " + .session.metadata.query_suffix)` — augment the agent's query - `default_argument_override` object — Optional hardcoded arguments for tool calls. The key specifies the location in the tool arguments to override. The value specifies what to override with. The agent cannot change these parameters and does not know these values exist. The values can also be dynamic references to context values using $ref with dot notation path syntax: - Static value: "fixed_value" or 123 - Dynamic reference: `{"$ref": "session.metadata.field_name"}` References resolve at runtime from context: - session.metadata.* - Access session metadata fields - agent.metadata.* - Access agent metadata fields - agent.secrets.* - Access agent secrets (masked in audit events) - tools.* - Access prior tool outputs (resolved after the dependent tool runs) - currentDate - The current date/time in ISO 8601 format A bracket index may reference another context value. The resolved value becomes the lookup key. The inner path may optionally carry a leading $ root marker: - Indirect reference: `{"$ref": "agent.secrets[session.metadata.user_id]"}` looks up the per-user secret named by `session.metadata.user_id` - Equivalent forms: `agent.secrets[$session.metadata.user_id]` and `agent.secrets[$.session.metadata.user_id]` Example: `{"query": {"$ref": ".session.metadata.query"}}` To use a literal `"$ref"` value, write `"$$ref"`. The $$ escapes the first $. - `category` string — Functional category of the tool (e.g., retrieval, artifacts, indexing, utilities, orchestration). - `lineage` string — The base tool name without version suffix. Groups versioned variants of the same tool together. - `version` string — Date-based version identifier in YYYY-MM-DD format. Null for unversioned tools. - `tool_groups` string[] — Groups this tool belongs to. Tools in the same group form a functional set and should be added or removed together by default. - `type` string, required — This should always be `image_read`. - object — Base properties shared by all tool types. - `id` string, required — Unique identifier for a tool. - `name` string, required — Unique identifier for the tool. - `title` string — Human-readable title of the tool. - `description` string, required — The description provided to the agent to guide tool selection. This is what the agent sees when deciding which tool to use. - `description_template` string — Velocity template for generating dynamic tool descriptions. When set, the template renders at runtime to produce the tool description. Available Velocity variables: - `$agent.name` - Agent name - `$agent.metadata` - Agent metadata map - `$session.key` - Session key - `$session.metadata` - Session metadata map - `$currentDate` - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z") Example: "Search tool configured for agent $agent.name on $currentDate" - `documentation` string — User-facing documentation describing the tool and how to configure it for an agent. Intended for developers and administrators browsing the tool catalog. Defaults to the agent-facing description if not explicitly set. - `enabled` boolean, required — Whether the tool is currently enabled and available for use. - `experimental` boolean — Whether this tool is experimental and may change or be removed without notice. - `created_at` string, date-time — Timestamp when the tool was created. - `updated_at` string, date-time — Timestamp when the tool was last updated. - `input_schema` object, required — The schema that defines the expected input structure for the tool. - `output_schema` object — The JSON schema that describes the structure of the tool's output. Clients may use it to understand the shape of tool responses and to author `default_output_transform` jq expressions. - `default_output_transform` string — An optional jq expression applied to the tool's JSON output before the agent receives it. Use this to project, filter, or summarize tool output to keep responses concise and on-topic. The expression operates on the tool's response JSON and the result replaces the original output. If the expression fails to compile or evaluate at runtime, the tool call returns an error to the agent so the agent can react. Examples: - `.results | map({title, url})` — keep only title/url for each result - `.items[0:5]` — first 5 items - `del(.debug)` — drop a noisy field - `default_input_transform` string — An optional jq expression applied to the tool's input after argument overrides merge with the agent's arguments and before the tool runs. Use this to inject server-side context (session metadata, agent secrets) into the tool input, or to reshape the agent's arguments. The expression receives the standard runtime context: the same `agent`, `session`, `tools`, and `currentDate` values exposed to `argument_override` `$ref`s. It also receives an `args` field that contains the merged tool input. The output of the expression replaces `args` as the tool input. The pre-transform `args` is what appears in audit events (with secrets masked); the post-transform value goes only to the tool. If the expression fails to compile or evaluate, the tool call returns an error to the agent. Examples: - `.args + { auth: ("Bearer " + .agent.secrets.token) }` — inject a bearer header - `.args | .corpus_key = .session.metadata.corpus_key` — pull a corpus key from session metadata - `.args | .query = (.args.query + " " + .session.metadata.query_suffix)` — augment the agent's query - `default_argument_override` object — Optional hardcoded arguments for tool calls. The key specifies the location in the tool arguments to override. The value specifies what to override with. The agent cannot change these parameters and does not know these values exist. The values can also be dynamic references to context values using $ref with dot notation path syntax: - Static value: "fixed_value" or 123 - Dynamic reference: `{"$ref": "session.metadata.field_name"}` References resolve at runtime from context: - session.metadata.* - Access session metadata fields - agent.metadata.* - Access agent metadata fields - agent.secrets.* - Access agent secrets (masked in audit events) - tools.* - Access prior tool outputs (resolved after the dependent tool runs) - currentDate - The current date/time in ISO 8601 format A bracket index may reference another context value. The resolved value becomes the lookup key. The inner path may optionally carry a leading $ root marker: - Indirect reference: `{"$ref": "agent.secrets[session.metadata.user_id]"}` looks up the per-user secret named by `session.metadata.user_id` - Equivalent forms: `agent.secrets[$session.metadata.user_id]` and `agent.secrets[$.session.metadata.user_id]` Example: `{"query": {"$ref": ".session.metadata.query"}}` To use a literal `"$ref"` value, write `"$$ref"`. The $$ escapes the first $. - `category` string — Functional category of the tool (e.g., retrieval, artifacts, indexing, utilities, orchestration). - `lineage` string — The base tool name without version suffix. Groups versioned variants of the same tool together. - `version` string — Date-based version identifier in YYYY-MM-DD format. Null for unversioned tools. - `tool_groups` string[] — Groups this tool belongs to. Tools in the same group form a functional set and should be added or removed together by default. - `type` string, required — This should always be `document_conversion`. - object — Base properties shared by all tool types. - `id` string, required — Unique identifier for a tool. - `name` string, required — Unique identifier for the tool. - `title` string — Human-readable title of the tool. - `description` string, required — The description provided to the agent to guide tool selection. This is what the agent sees when deciding which tool to use. - `description_template` string — Velocity template for generating dynamic tool descriptions. When set, the template renders at runtime to produce the tool description. Available Velocity variables: - `$agent.name` - Agent name - `$agent.metadata` - Agent metadata map - `$session.key` - Session key - `$session.metadata` - Session metadata map - `$currentDate` - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z") Example: "Search tool configured for agent $agent.name on $currentDate" - `documentation` string — User-facing documentation describing the tool and how to configure it for an agent. Intended for developers and administrators browsing the tool catalog. Defaults to the agent-facing description if not explicitly set. - `enabled` boolean, required — Whether the tool is currently enabled and available for use. - `experimental` boolean — Whether this tool is experimental and may change or be removed without notice. - `created_at` string, date-time — Timestamp when the tool was created. - `updated_at` string, date-time — Timestamp when the tool was last updated. - `input_schema` object, required — The schema that defines the expected input structure for the tool. - `output_schema` object — The JSON schema that describes the structure of the tool's output. Clients may use it to understand the shape of tool responses and to author `default_output_transform` jq expressions. - `default_output_transform` string — An optional jq expression applied to the tool's JSON output before the agent receives it. Use this to project, filter, or summarize tool output to keep responses concise and on-topic. The expression operates on the tool's response JSON and the result replaces the original output. If the expression fails to compile or evaluate at runtime, the tool call returns an error to the agent so the agent can react. Examples: - `.results | map({title, url})` — keep only title/url for each result - `.items[0:5]` — first 5 items - `del(.debug)` — drop a noisy field - `default_input_transform` string — An optional jq expression applied to the tool's input after argument overrides merge with the agent's arguments and before the tool runs. Use this to inject server-side context (session metadata, agent secrets) into the tool input, or to reshape the agent's arguments. The expression receives the standard runtime context: the same `agent`, `session`, `tools`, and `currentDate` values exposed to `argument_override` `$ref`s. It also receives an `args` field that contains the merged tool input. The output of the expression replaces `args` as the tool input. The pre-transform `args` is what appears in audit events (with secrets masked); the post-transform value goes only to the tool. If the expression fails to compile or evaluate, the tool call returns an error to the agent. Examples: - `.args + { auth: ("Bearer " + .agent.secrets.token) }` — inject a bearer header - `.args | .corpus_key = .session.metadata.corpus_key` — pull a corpus key from session metadata - `.args | .query = (.args.query + " " + .session.metadata.query_suffix)` — augment the agent's query - `default_argument_override` object — Optional hardcoded arguments for tool calls. The key specifies the location in the tool arguments to override. The value specifies what to override with. The agent cannot change these parameters and does not know these values exist. The values can also be dynamic references to context values using $ref with dot notation path syntax: - Static value: "fixed_value" or 123 - Dynamic reference: `{"$ref": "session.metadata.field_name"}` References resolve at runtime from context: - session.metadata.* - Access session metadata fields - agent.metadata.* - Access agent metadata fields - agent.secrets.* - Access agent secrets (masked in audit events) - tools.* - Access prior tool outputs (resolved after the dependent tool runs) - currentDate - The current date/time in ISO 8601 format A bracket index may reference another context value. The resolved value becomes the lookup key. The inner path may optionally carry a leading $ root marker: - Indirect reference: `{"$ref": "agent.secrets[session.metadata.user_id]"}` looks up the per-user secret named by `session.metadata.user_id` - Equivalent forms: `agent.secrets[$session.metadata.user_id]` and `agent.secrets[$.session.metadata.user_id]` Example: `{"query": {"$ref": ".session.metadata.query"}}` To use a literal `"$ref"` value, write `"$$ref"`. The $$ escapes the first $. - `category` string — Functional category of the tool (e.g., retrieval, artifacts, indexing, utilities, orchestration). - `lineage` string — The base tool name without version suffix. Groups versioned variants of the same tool together. - `version` string — Date-based version identifier in YYYY-MM-DD format. Null for unversioned tools. - `tool_groups` string[] — Groups this tool belongs to. Tools in the same group form a functional set and should be added or removed together by default. - `type` string, required — This should always be `get_document_text`. - object — Base properties shared by all tool types. - `id` string, required — Unique identifier for a tool. - `name` string, required — Unique identifier for the tool. - `title` string — Human-readable title of the tool. - `description` string, required — The description provided to the agent to guide tool selection. This is what the agent sees when deciding which tool to use. - `description_template` string — Velocity template for generating dynamic tool descriptions. When set, the template renders at runtime to produce the tool description. Available Velocity variables: - `$agent.name` - Agent name - `$agent.metadata` - Agent metadata map - `$session.key` - Session key - `$session.metadata` - Session metadata map - `$currentDate` - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z") Example: "Search tool configured for agent $agent.name on $currentDate" - `documentation` string — User-facing documentation describing the tool and how to configure it for an agent. Intended for developers and administrators browsing the tool catalog. Defaults to the agent-facing description if not explicitly set. - `enabled` boolean, required — Whether the tool is currently enabled and available for use. - `experimental` boolean — Whether this tool is experimental and may change or be removed without notice. - `created_at` string, date-time — Timestamp when the tool was created. - `updated_at` string, date-time — Timestamp when the tool was last updated. - `input_schema` object, required — The schema that defines the expected input structure for the tool. - `output_schema` object — The JSON schema that describes the structure of the tool's output. Clients may use it to understand the shape of tool responses and to author `default_output_transform` jq expressions. - `default_output_transform` string — An optional jq expression applied to the tool's JSON output before the agent receives it. Use this to project, filter, or summarize tool output to keep responses concise and on-topic. The expression operates on the tool's response JSON and the result replaces the original output. If the expression fails to compile or evaluate at runtime, the tool call returns an error to the agent so the agent can react. Examples: - `.results | map({title, url})` — keep only title/url for each result - `.items[0:5]` — first 5 items - `del(.debug)` — drop a noisy field - `default_input_transform` string — An optional jq expression applied to the tool's input after argument overrides merge with the agent's arguments and before the tool runs. Use this to inject server-side context (session metadata, agent secrets) into the tool input, or to reshape the agent's arguments. The expression receives the standard runtime context: the same `agent`, `session`, `tools`, and `currentDate` values exposed to `argument_override` `$ref`s. It also receives an `args` field that contains the merged tool input. The output of the expression replaces `args` as the tool input. The pre-transform `args` is what appears in audit events (with secrets masked); the post-transform value goes only to the tool. If the expression fails to compile or evaluate, the tool call returns an error to the agent. Examples: - `.args + { auth: ("Bearer " + .agent.secrets.token) }` — inject a bearer header - `.args | .corpus_key = .session.metadata.corpus_key` — pull a corpus key from session metadata - `.args | .query = (.args.query + " " + .session.metadata.query_suffix)` — augment the agent's query - `default_argument_override` object — Optional hardcoded arguments for tool calls. The key specifies the location in the tool arguments to override. The value specifies what to override with. The agent cannot change these parameters and does not know these values exist. The values can also be dynamic references to context values using $ref with dot notation path syntax: - Static value: "fixed_value" or 123 - Dynamic reference: `{"$ref": "session.metadata.field_name"}` References resolve at runtime from context: - session.metadata.* - Access session metadata fields - agent.metadata.* - Access agent metadata fields - agent.secrets.* - Access agent secrets (masked in audit events) - tools.* - Access prior tool outputs (resolved after the dependent tool runs) - currentDate - The current date/time in ISO 8601 format A bracket index may reference another context value. The resolved value becomes the lookup key. The inner path may optionally carry a leading $ root marker: - Indirect reference: `{"$ref": "agent.secrets[session.metadata.user_id]"}` looks up the per-user secret named by `session.metadata.user_id` - Equivalent forms: `agent.secrets[$session.metadata.user_id]` and `agent.secrets[$.session.metadata.user_id]` Example: `{"query": {"$ref": ".session.metadata.query"}}` To use a literal `"$ref"` value, write `"$$ref"`. The $$ escapes the first $. - `category` string — Functional category of the tool (e.g., retrieval, artifacts, indexing, utilities, orchestration). - `lineage` string — The base tool name without version suffix. Groups versioned variants of the same tool together. - `version` string — Date-based version identifier in YYYY-MM-DD format. Null for unversioned tools. - `tool_groups` string[] — Groups this tool belongs to. Tools in the same group form a functional set and should be added or removed together by default. - `type` string, required — This should always be `client`. ## Other responses - `400` — The request is malformed or contains an invalid configuration. - `403` — Permissions do not allow creating tools. - `409` — A tool with this name already exists. --- [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)