Reusable tool configurations

A reusable tool configuration is a tool setup — a corpora search bound to specific corpora, a web search with domain filters, a lambda with preset arguments — that you define once and attach to any number of agents by a key you choose. Instead of restating the same configuration inline on every agent, each agent holds a reference to the shared definition.

You manage reusable configurations with the /v2/tool_configurations endpoints, and attach one to an agent with a reference entry in the agent's tool_configurations map.

Why it matters

Without reusable configurations, ten agents that share the same search setup carry ten inline copies. Changing the setup means editing all ten, and the copies drift apart over time.

A reusable configuration gives you:

• One definition, many agents. Maintain the configuration in one place and reference it everywhere it applies.
• Controlled rollout. Agents stay pinned to the configuration as it was when they attached it; each agent picks up your changes when you re-save that agent.
• A kill switch. Disabling a configuration removes the tool from every agent that references it, without detaching anything.

Create a reusable configuration

Create a configuration with POST /v2/tool_configurations. The key is the handle agents use to reference it. If you omit the key, one is generated from the name. Keys may contain letters, digits, underscores, and hyphens, up to 50 characters.

POST /v2/tool_configurations
{
  "key": "support_search",
  "name": "Support KB Search",
  "description": "Searches the support knowledge base with tuned parameters.",
  "type": "corpora_search",
  "query_configuration": {
    "search": {
      "corpora": [{ "corpus_key": "support-kb" }]
    }
  }
}

This works for every tool type an agent can use inline: built-in tools such as corpora_search, web_search, and sub_agent are identified by type alone, while dynamic tools (mcp, lambda, dynamic_vectara) also bind to a registered tool through tool_id. Client tools are the one exception — they execute on your application's side and can only be configured inline on an agent.

The configuration is validated at creation time the same way an inline configuration would be: transform expressions must be valid jq, and a lambda's argument_override must match the function's input schema.

Reference it from an agent

In the agent's tool_configurations map, use a reference entry instead of an inline configuration. The map key is the tool's name on that agent and does not have to match the configuration's name or key, so two agents can expose the same shared configuration under different tool names.

{
  "tool_configurations": {
    "kb_search": {
      "type": "reference",
      "tool_configuration_key": "support_search"
    }
  }
}

The agent behaves exactly as if the configuration were written inline: tool permissions are granted the same way, and the tool runs with the shared configuration's parameters.

note

Other fields sent alongside type and tool_configuration_key on a reference entry are ignored. A reference always uses the shared configuration as-is — there are no per-agent overrides.

Update a configuration

Update with PUT /v2/tool_configurations/{tool_configuration_key}, sending the full definition in the same shape as a create request. The stored configuration is replaced wholesale: omitted optional fields are reset to their defaults (description cleared, enabled true, metadata empty) rather than left unchanged. The key in the body is ignored — the path identifies the configuration.

The type of a configuration (and the bound tool_id for dynamic tools) can never change, because it determines which tool the configuration is bound to.

Agents that already reference the configuration are pinned to the version that was current when they attached it. They are not affected by your update until you re-save each agent (for example, by replacing it with the same definition), at which point the reference re-resolves to the latest version. This means updating a shared configuration never silently changes a running agent.

Disable or delete

Setting "enabled": false on a reusable configuration removes the tool from every agent that references it — the agents keep their references, but the tool is not offered to the model and does not execute. Re-enabling restores it everywhere. Use this as a fast, reversible kill switch for a shared tool.

Deleting is permanent and only allowed when nothing references the configuration. While any agent still references it, DELETE returns 409 Conflict with the list of referencing agents; detach the configuration from those agents first.

List and inspect

• GET /v2/tool_configurations/{tool_configuration_key} returns one configuration.
• GET /v2/tool_configurations lists configurations, with paging plus optional filters: filter (a regular expression matched against names and descriptions), type (a built-in tool name such as corpora_search, or mcp or lambda), and enabled.