--- title: "Update tool" method: PATCH path: "/v2/tools/{tool_id}" tags: ["Tools"] --- # Update tool `PATCH /v2/tools/{tool_id}` Updates an existing tool’s configuration, including its metadata, enabled status, or other properties. Updating a tool changes how agents invoke it during a session. ## Path parameters - `tool_id` string, required ## Headers - `Request-Timeout` integer - `Request-Timeout-Millis` integer ## Request body - union — Request to update a tool. Supports updating MCP, Python lambda, and client tools. - UpdateMcpToolRequest — Request object for updating an existing MCP tool. - `type` string, required — This should always be `mcp`. - `enabled` boolean — Whether the tool is enabled. - UpdateLambdaToolRequest — Request to update a lambda tool's code, configuration, and metadata. When you update the code, the platform re-discovers input and output schemas from function parameter type annotations. - `type` string, required — This should always be `lambda`. - `enabled` boolean — Whether the tool should be enabled or disabled. - `title` string — Updated user-friendly display name for the tool. - `description` string — Updated description of what the tool does. - `code` string — Updated code for the lambda function. Use function parameter type annotations for automatic schema discovery. 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. - `tool_configurations` object, nullable — Replaces the tool's `tool_configurations` map. Omit to leave the existing configurations unchanged; set to `null` to clear them. See the `tool_configurations` field on `CreateLambdaToolRequest` for semantics and constraints. - UpdateClientToolRequest — Request to update an existing client tool. - `type` string, required — This should always be `client`. - `enabled` boolean — Whether the tool should be enabled or disabled. - `title` string — Updated human-readable title of the tool. - `description` string — Updated description of what the tool does. - `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 `200` The tool is updated. - 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 invalid references. - `403` — Permissions do not allow updating this tool. - `404` — Tool not found. --- [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)