> ## Documentation Index > Fetch the complete documentation index at: https://cadenya.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Archive a tool set > Transitions a tool set to STATE_ARCHIVED. Syncing stops, the tool set is hidden from list results, its tools are no longer offered to objectives, and new variation assignments are rejected. Existing assignments are retained, and history is preserved — unlike delete, archiving works while the tool set is still assigned to agent variations. ## OpenAPI ````yaml /api-spec.yml post /v1/workspaces/{workspaceId}/tool_sets/{id}:archive openapi: 3.1.0 info: title: Cadenya API description: API for the Cadenya Agent Runtime platform. version: '1.0' servers: - url: https://api.cadenya.com description: Production server security: - bearerAuth: [] tags: - name: AIProviderKeyService - name: APIKeyService description: |- Issue, rotate, disable, and revoke a workspace's API keys. Every key belongs to exactly one workspace; the system-managed global account key is managed via GlobalAPIKeyService instead. - name: AccountService description: >- Manage the authenticated account. Accounts are the top-level organizational unit and contain one or more workspaces. - name: AgentScheduleService description: >- Manage recurring schedules attached to agents. Schedules trigger objectives on a cadence defined by AgentScheduleSpec.Schedule. - name: AgentService description: >- Manage AI agents within a workspace. Agents define AI behavior and tool access. - name: AgentVariationService description: >- Manage variations of an agent and their tool, sub-agent, and memory layer assignments. - name: GlobalAPIKeyService description: |- Manage the account's system-provisioned global API key. The global key is the only key that spans every workspace; it is created by the system and cannot be deleted, so the surface is retrieve, rotate, and the disable/enable kill switch. - name: MemoryService description: >- Manage memory layers and their entries. Layers are named containers that can be composed into an objective's memory cascade; entries are the keyed values within a layer. System-managed layers (e.g., episodic layers created by the runtime) cannot be mutated through this API. - name: ModelService description: |- Manage LLM models available to a workspace. Models represent provider and family pairs (e.g., "anthropic/claude-sonnet-4.6"). Workspaces are seeded with the supported models and you can enable or disable each one. - name: ObjectiveEventStreamsService - name: ObjectiveService - name: ProfilesService description: |- Operations on profiles, the account-level principals (users, API keys, system) that authenticate against the API. - name: SearchService - name: TenantService description: >- Read and erase tenants and the subjects under them. Tenants and subjects are created by assertion — on objective creation or widget session mint — never directly, so this service has no create or update: it exists to enumerate what assertions have produced, and to destroy it on request. - name: ToolService description: >- Manage tool sets and the tools they contain. Tool sets group related tools, and tools define specific capabilities available to agents. When a tool set is managed, only API key actors can modify its tools; human (profile) actors cannot. - name: UploadService description: |- Issue short-lived presigned URLs for direct client-to-object-storage uploads. Created uploads can be referenced by id when creating or updating resources that accept binary content (e.g., MemoryEntry). - name: WidgetService description: |- Manage embeddable chat widgets. A widget binds an agent to a globally unique hostname with a per-widget origin allowlist; browsers reach it with session tokens minted via WidgetSessionService. - name: WidgetSessionService description: >- Mint and manage widget sessions. Session creation is server-to-server only: the customer's backend authenticates its visitor, asserts tenant/subject context, attaches any per-visitor secrets, and receives a short-lived bearer token the browser uses against the widget host. - name: WorkspaceAdminService description: >- Administer workspaces across the account: create and archive workspaces and manage their membership. These operations are account-scoped and require the admin role (a token whose profile holds the WorkOS admin role); they live under /v1/account/workspaces rather than the workspace-scoped /v1/workspaces tree so an admin can manage any workspace in the account, including ones they are not themselves a member of. - name: WorkspaceSecretService - name: WorkspaceService description: |- Manage workspaces within an account. Workspaces provide organizational grouping and isolation for resources such as agents, tools, and API keys. This is the workspace-scoped, end-user surface. Administrative operations (create / archive workspaces, manage members) live in WorkspaceAdminService under /v1/account/workspaces and require the admin role. paths: /v1/workspaces/{workspaceId}/tool_sets/{id}:archive: post: tags: - ToolService - Tool Sets summary: Archive a tool set description: >- Transitions a tool set to STATE_ARCHIVED. Syncing stops, the tool set is hidden from list results, its tools are no longer offered to objectives, and new variation assignments are rejected. Existing assignments are retained, and history is preserved — unlike delete, archiving works while the tool set is still assigned to agent variations. operationId: ToolService_ArchiveToolSet parameters: - name: workspaceId in: path description: Workspace ID. required: true schema: type: string example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q - name: id in: path description: |- Tool set ID. Accepts the canonical ts_… form or the external_id: form. required: true schema: example: toolset_01HXKD2E5NQM3T9AYWCFNRMN74 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ArchiveToolSetRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ToolSet' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' x-codeSamples: - lang: typescript label: TypeScript source: |- import Cadenya from '@cadenya/cadenya'; const client = new Cadenya(); const result = await client.toolSets.archive('_123'); - lang: go label: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\n\tcadenya \"go.cadenya.com/cadenya-go\"\n)\n\nfunc main() {\n\tclient, err := cadenya.NewClient()\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tctx := context.Background()\n\tparams := &cadenya.ToolSetArchiveParams{}\n\tresult, err := client.ToolSets().Archive(ctx, \"_123\", params)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tfmt.Printf(\"%+v\\n\", result)\n}" - lang: python label: Python source: |- from cadenya import Cadenya with Cadenya() as client: result = client.tool_sets.archive("_123") print(result) - lang: ruby label: Ruby source: |- require "cadenya" client = Cadenya::Client.new result = client.tool_sets.archive("_123") puts result.inspect - lang: shell label: CLI source: cadenya tool-sets archive _123 components: schemas: ArchiveToolSetRequest: type: object properties: workspaceId: readOnly: true example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q type: string description: Workspace ID. id: readOnly: true example: toolset_01HXKD2E5NQM3T9AYWCFNRMN74 type: string description: |- Tool set ID. Accepts the canonical ts_… form or the external_id: form. description: Archive tool set request ToolSet: required: - metadata - spec - state type: object properties: metadata: $ref: '#/components/schemas/ResourceMetadata' spec: $ref: '#/components/schemas/ToolSetSpec' info: readOnly: true allOf: - $ref: '#/components/schemas/ToolSetInfo' description: Tool set information state: readOnly: true enum: - STATE_UNSPECIFIED - STATE_ACTIVE - STATE_ARCHIVED type: string description: >- The current lifecycle state of the tool set. Output only. Tool sets are created STATE_ACTIVE; use the :archive and :unarchive actions to transition between states. format: enum Status: type: object properties: code: type: integer description: >- The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. format: int32 message: type: string description: >- A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. details: type: array items: $ref: '#/components/schemas/GoogleProtobufAny' description: >- A list of messages that carry the error details. There is a common set of message types for APIs to use. description: >- The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors). ResourceMetadata: required: - id - accountId - workspaceId - name - profileId - createdAt - externalId - labels type: object properties: id: readOnly: true type: string description: >- Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") accountId: readOnly: true example: account_01HXKD2E5NQM3T9AYWCFTJHJVF type: string description: >- Account this resource belongs to for multi-tenant isolation (prefixed ULID) workspaceId: readOnly: true example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q type: string description: >- Workspace this resource belongs to for organizational grouping (prefixed ULID) name: type: string description: >- Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly externalId: type: string description: >- External ID for the resource (e.g., a workflow ID from an external system) labels: type: object additionalProperties: type: string description: |- Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"} profileId: readOnly: true example: profile_01HXKD2E5NQM3T9AYWCFS0AP08 type: string description: ID of the actor (user or service account) that created this resource createdAt: readOnly: true type: string description: Timestamp when this resource was created format: date-time updatedAt: readOnly: true type: string description: Timestamp when this resource was last updated format: date-time description: >- Standard metadata for persistent, named resources (e.g., agents, tools, prompts) ToolSetSpec: required: - adapter type: object properties: description: type: string adapter: $ref: '#/components/schemas/ToolSetAdapter' overlays: type: array items: $ref: '#/components/schemas/ToolOverlay' description: |- Overlays applied to this tool set's tools, evaluated in order. See ToolOverlay. Overlay keys must be unique within the list. As a repeated field this is replaced wholesale on update: an update_mask of `spec.overlays` swaps the entire list for the one in the request. Read-modify-write to add or remove a single overlay. ToolSetInfo: required: - toolCount - agentCount - availableTools - omittedTools type: object properties: toolCount: readOnly: true type: integer format: int32 agentCount: readOnly: true type: integer format: int32 lastSync: readOnly: true type: string format: date-time createdBy: $ref: '#/components/schemas/Profile' availableTools: type: integer format: int32 omittedTools: type: integer format: int32 GoogleProtobufAny: type: object properties: '@type': type: string description: The type of the serialized message. additionalProperties: true description: >- Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. ToolSetAdapter: oneOf: - $ref: '#/components/schemas/ToolSetAdapter_McpVariant' - $ref: '#/components/schemas/ToolSetAdapter_HttpVariant' - $ref: '#/components/schemas/ToolSetAdapter_OpenapiVariant' - $ref: '#/components/schemas/ToolSetAdapter_BareVariant' discriminator: propertyName: type mapping: mcp: $ref: '#/components/schemas/ToolSetAdapter_McpVariant' http: $ref: '#/components/schemas/ToolSetAdapter_HttpVariant' openapi: $ref: '#/components/schemas/ToolSetAdapter_OpenapiVariant' bare: $ref: '#/components/schemas/ToolSetAdapter_BareVariant' ToolOverlay: required: - key - selector - disabled type: object properties: key: type: string description: |- Identifies the overlay within its tool set. Unique across the tool set's overlays (enforced by the server), stable across reorders, and surfaced in tool call diagnostics ("parameter removed by overlay strip-list-knobs") so an operator can trace a rewritten call back to the policy that rewrote it. Referenced by ToolInfo.overlays and the ListToolsRequest.overlays filter. selector: allOf: - $ref: '#/components/schemas/ToolOverlay_Selector' description: |- Which tools this overlay applies to. Required; an empty selector (no conditions) matches every tool in the set. parameterActions: type: array items: $ref: '#/components/schemas/ToolOverlay_ParameterAction' description: Pre-call actions, applied in order. See ParameterAction. resultActions: type: array items: $ref: '#/components/schemas/ToolOverlay_ResultAction' description: Post-call actions, applied in order. See ResultAction. disabled: type: boolean description: >- When true the overlay is retained in the spec but not evaluated. Lets an operator switch a policy off to diagnose a misbehaving tool without deleting it and losing the configuration. widgetArgumentExposure: allOf: - $ref: '#/components/schemas/ToolOverlay_WidgetArgumentExposure' description: >- Arguments may carry sensitive customer data, including values injected by parameter actions, so they stay private unless an overlay enables them. Unset means this overlay has no opinion. When several enabled overlays match a tool, they are evaluated in list order and the last overlay that supplies this policy wins. If none supplies it, arguments stay private. Disabled overlays never participate. description: >- A tool overlay is a policy attached to a tool set that reshapes the tools the model sees and calls. It pairs a selector (which tools it applies to) with actions that run before a call — rewriting the tool's parameter schema and the arguments the model supplied — and after a call — rewriting the result before it enters the model's context. It can also explicitly allow the final call arguments to cross the otherwise-private widget API boundary. Overlays exist for three reasons: - Authority. Adapter-derived tool sets (OpenAPI especially) expose many parameters the model must never guess — a workspace id, a tenant id, an account scope. Overlays bind those parameters to the objective's `pinned_parameters` (see CreateObjectiveRequest.pinned_parameters): the parameter disappears from the schema and the value is forced server-side, so the model has no opportunity to supply a different one. - Context. Large specs carry pagination cursors, expansion flags and verbose responses that cost tokens without helping the model. Overlays strip parameters, fix them to literals, and compact results. - Widget presentation. Tool arguments are private by default. An overlay can opt matching tools into exposing their final call arguments in visitor-facing widget events so an embedding UI can select a custom renderer or presentation. Pinned parameters and overlays are complementary: pinned parameters are *data* supplied per objective (or per widget session) by the caller; overlays are *policy* authored once on the tool set. Pinning by name still works without an overlay — a pinned key that matches a top-level parameter name is applied to every tool in the objective — overlays are for the cases that needs more: nested paths, renamed keys, a subset of tools, or values that are literals rather than caller-supplied. Evaluation model: - Overlays are evaluated in list order; within an overlay, actions are evaluated in list order. Later actions win on the same path (a `set` followed by a `remove` leaves the parameter removed). - The parameter schema the model sees is computed when tools are assembled for an objective, so pre-call actions can consult that objective's pinned parameters (this is what makes `pin` with ON_MISSING_SKIP meaningful). Argument rewriting runs on every call. - An action whose `path` does not exist in the tool's parameter schema changes nothing in the schema the model sees. This is deliberate: a broad selector (every `list_*` tool) may match tools with different shapes, and one overlay should be able to cover all of them without erroring on the ones that lack a given parameter. At call time the model's arguments can still not widen what it controls: `remove` strips the path whether or not it is declared, and `set`/`pin` overwrite a value the model sent at an undeclared path (a schema this evaluator cannot see through, e.g. behind $ref/allOf) while injecting nothing into tools that lack the parameter. - Overlays apply to just-in-time tool sets as well; the tools are evaluated against overlays at the moment they are loaded. - Result actions run once, when the tool call's result is recorded; the stored result is the transformed one, so every reader (the model, compaction, the API) sees the same content. They are not supported on bare tool sets. Profile: required: - metadata - spec type: object properties: metadata: $ref: '#/components/schemas/AccountResourceMetadata' spec: $ref: '#/components/schemas/ProfileSpec' description: |- A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. ToolSetAdapter_McpVariant: type: object required: - type - mcp properties: type: type: string enum: - mcp mcp: $ref: '#/components/schemas/ToolSetAdapter_MCP' ToolSetAdapter_HttpVariant: type: object required: - type - http properties: type: type: string enum: - http http: $ref: '#/components/schemas/ToolSetAdapter_HTTP' ToolSetAdapter_OpenapiVariant: type: object required: - type - openapi properties: type: type: string enum: - openapi openapi: $ref: '#/components/schemas/ToolSetAdapter_OpenAPI' ToolSetAdapter_BareVariant: type: object required: - type - bare properties: type: type: string enum: - bare bare: $ref: '#/components/schemas/ToolSetAdapter_Bare' ToolOverlay_Selector: required: - operator type: object properties: conditions: type: array items: $ref: '#/components/schemas/Selector_Condition' operator: enum: - OPERATOR_UNSPECIFIED - OPERATOR_AND - OPERATOR_OR - OPERATOR_AND - OPERATOR_OR type: string description: 'Default: OPERATOR_AND.' format: enum description: |- Which tools in the tool set an overlay applies to. Conditions are combined with `operator`; an overlay with no conditions matches every tool in the set. ToolOverlay_ParameterAction: oneOf: - $ref: '#/components/schemas/ToolOverlay_ParameterAction_Remove' - $ref: '#/components/schemas/ToolOverlay_ParameterAction_Set' - $ref: '#/components/schemas/ToolOverlay_ParameterAction_Pin' discriminator: propertyName: type mapping: remove: $ref: '#/components/schemas/ToolOverlay_ParameterAction_Remove' set: $ref: '#/components/schemas/ToolOverlay_ParameterAction_Set' pin: $ref: '#/components/schemas/ToolOverlay_ParameterAction_Pin' description: |- A pre-call action. Parameter actions rewrite the tool's parameter schema as presented to the model and the arguments the model supplies when it calls the tool. Both sides are always kept in agreement: a parameter that is hidden from the schema is also stripped from (or forced in) the arguments, so the model can neither see nor smuggle it. ToolOverlay_ResultAction: oneOf: - $ref: '#/components/schemas/ToolOverlay_ResultAction_Transform' discriminator: propertyName: type mapping: transform: $ref: '#/components/schemas/ToolOverlay_ResultAction_Transform' description: |- A post-call action. Result actions rewrite a tool call's result after the adapter returns and before it is recorded: the transformed content is what is stored and what the model reads (ObjectiveToolCallResult content). The adapter's raw response is kept in the tool call's debug log for operators; it is not otherwise retained. Result actions apply to MCP, OpenAPI and HTTP tool sets. They are not supported on bare tool sets — a bare tool's content is supplied by an external consumer, so there is nothing for the platform to reshape — and a tool set whose adapter is `bare` rejects overlays that carry result actions. When several matching overlays carry transforms they run in overlay order, each one reading the previous one's output. ToolOverlay_WidgetArgumentExposure: required: - enabled type: object properties: enabled: type: boolean description: |- Controls whether matching tool calls may expose their final arguments to visitor-facing widget events. The containing message's presence means the overlay has an opinion; enabled selects whether that opinion is on or off. AccountResourceMetadata: required: - id - accountId - name - profileId - externalId - labels type: object properties: id: readOnly: true type: string description: >- Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") accountId: readOnly: true example: account_01HXKD2E5NQM3T9AYWCFTJHJVF type: string description: >- Account this resource belongs to for multi-tenant isolation (prefixed ULID) name: type: string description: >- Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly externalId: type: string description: >- External ID for the resource (e.g., a workflow ID from an external system) labels: type: object additionalProperties: type: string description: |- Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"} profileId: readOnly: true example: profile_01HXKD2E5NQM3T9AYWCFS0AP08 type: string createdAt: readOnly: true type: string format: date-time description: >- AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. ProfileSpec: required: - type - email - name type: object properties: email: type: string description: >- Email address of the profile. Required and unique within an account for user profiles. name: type: string description: Display name (e.g., "Bobby Tables"). type: enum: - PROFILE_TYPE_UNSPECIFIED - PROFILE_TYPE_USER - PROFILE_TYPE_API_KEY - PROFILE_TYPE_SYSTEM type: string description: >- Whether this profile represents a human user, an API key, or a system principal. format: enum description: Configuration for a profile. ToolSetAdapter_MCP: type: object properties: url: type: string headers: type: object additionalProperties: type: string includeTools: allOf: - $ref: '#/components/schemas/ToolSetAdapter_ToolFilter' description: Include/exclude with flat filters excludeTools: $ref: '#/components/schemas/ToolSetAdapter_ToolFilter' toolApprovals: allOf: - $ref: '#/components/schemas/ToolSetAdapter_ApprovalRequirementFilter' description: >- Setting for how to assign tool approval requirements when they are synced from an MCP server justInTime: allOf: - $ref: '#/components/schemas/ToolSetAdapter_JustInTime' description: |- When enabled, tools are loaded from the MCP server just-in-time at objective creation using the objective's resolved secrets, instead of being synced ahead of time. Just-in-time tool sets are excluded from the background sync system. ToolSetAdapter_HTTP: type: object properties: baseUrl: type: string description: |- Base URL for dispatching tool calls. May be templated. Two reference forms are supported, and they resolve in a single pass each so neither can inject into the other: ${SECRET_NAME} a workspace or tool set secret {{ pinned_parameters. }} the objective's pinned parameters (see CreateObjectiveRequest.pinned_parameters) Pinned parameters are what make a per-tenant host possible: one tool set can serve every customer of a product that assigns each of them their own subdomain, e.g. https://{{ pinned_parameters.tenant }}.example.com Because the value may be a template rather than a literal URL, this field is not constrained to a URI shape. It is validated as an absolute http(s) URL after references are resolved, both on write (with references stubbed) and again before each tool call. headers: type: object additionalProperties: type: string ToolSetAdapter_OpenAPI: oneOf: - $ref: '#/components/schemas/ToolSetAdapter_OpenAPI_Url' - $ref: '#/components/schemas/ToolSetAdapter_OpenAPI_UploadId' discriminator: propertyName: type mapping: url: $ref: '#/components/schemas/ToolSetAdapter_OpenAPI_Url' uploadId: $ref: '#/components/schemas/ToolSetAdapter_OpenAPI_UploadId' ToolSetAdapter_Bare: type: object properties: contentTimeout: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: integer description: |- How long to wait for content to be set before the tool call errors. If unset, the call waits indefinitely. description: |- Bare tool sets define tools without an execution adapter. A bare tool call doesn't fire anything: the objective's workflow pauses and waits for an external API consumer to set the tool call's content (e.g. human-in-the-loop tools, or a reverse harness that polls for pending tool calls, executes locally, and reports results back via SetToolCallContent). Selector_Condition: oneOf: - $ref: '#/components/schemas/Selector_Condition_Attribute' - $ref: '#/components/schemas/Selector_Condition_HasParameter' - $ref: '#/components/schemas/Selector_Condition_Tools' discriminator: propertyName: type mapping: attribute: $ref: '#/components/schemas/Selector_Condition_Attribute' hasParameter: $ref: '#/components/schemas/Selector_Condition_HasParameter' tools: $ref: '#/components/schemas/Selector_Condition_Tools' description: A single selector condition. ToolOverlay_ParameterAction_Remove: type: object required: - type - remove properties: type: type: string enum: - remove remove: $ref: '#/components/schemas/ParameterAction_Remove' ToolOverlay_ParameterAction_Set: type: object required: - type - set properties: type: type: string enum: - set set: $ref: '#/components/schemas/ParameterAction_Set' ToolOverlay_ParameterAction_Pin: type: object required: - type - pin properties: type: type: string enum: - pin pin: $ref: '#/components/schemas/ParameterAction_Pin' ToolOverlay_ResultAction_Transform: type: object required: - type - transform properties: type: type: string enum: - transform transform: $ref: '#/components/schemas/ResultAction_Transform' ToolSetAdapter_ToolFilter: required: - operator type: object properties: filters: type: array items: $ref: '#/components/schemas/ToolSetAdapter_AttributeFilter' operator: enum: - OPERATOR_UNSPECIFIED - OPERATOR_AND - OPERATOR_OR - OPERATOR_AND - OPERATOR_OR type: string format: enum description: Top-level filter with simple boolean logic (no nesting) ToolSetAdapter_ApprovalRequirementFilter: oneOf: - $ref: '#/components/schemas/ToolSetAdapter_ApprovalRequirementFilter_Always' - $ref: '#/components/schemas/ToolSetAdapter_ApprovalRequirementFilter_Only' discriminator: propertyName: type mapping: always: $ref: >- #/components/schemas/ToolSetAdapter_ApprovalRequirementFilter_Always only: $ref: '#/components/schemas/ToolSetAdapter_ApprovalRequirementFilter_Only' description: >- Approval filters that will automatically set the approval requirement on tools synced from an external source ToolSetAdapter_JustInTime: type: object properties: enabled: type: boolean failObjectiveOnToolListError: type: boolean description: >- If set, an objective will automatically be failed if tools cannot be loaded in the initial stages of an objective being created. Tools are loaded asynchronously, so this setting is useful for ensuring that an objective continued any further if tools are not available. description: 'Defines behavior for just-in-time capable tool set adapters (IE: MCP).' ToolSetAdapter_OpenAPI_Url: type: object required: - type - url properties: type: type: string enum: - url url: type: string description: URL to fetch the OpenAPI spec from. Synced automatically every hour. headers: type: object additionalProperties: type: string description: >- Headers sent when fetching the spec from a URL and when dispatching tool calls. includeTools: $ref: '#/components/schemas/ToolSetAdapter_ToolFilter' excludeTools: $ref: '#/components/schemas/ToolSetAdapter_ToolFilter' toolApprovals: $ref: '#/components/schemas/ToolSetAdapter_ApprovalRequirementFilter' baseUrl: type: string description: |- Base URL for dispatching tool calls. If set, overrides the server resolved from the spec's servers array. May be templated with the same two reference forms the HTTP adapter's base_url accepts: ${SECRET_NAME} a workspace or tool set secret {{ pinned_parameters. }} the objective's pinned parameters A spec written against a single host can therefore be dispatched to a per-tenant one, e.g. https://{{ pinned_parameters.tenant }}.example.com, without cloning the tool set per customer. Validated as an absolute http(s) URL after references are resolved rather than as a literal URI. serverName: type: string description: |- Name of the server entry in the spec's servers array (OpenAPI 3.2 server.name field). Used to select which server URL to dispatch to when base_url is not set. If unset, the first server is used. Ignored when base_url is set. ToolSetAdapter_OpenAPI_UploadId: type: object required: - type - uploadId properties: type: type: string enum: - uploadId uploadId: example: upload_01HXKD2E5NQM3T9AYWCFZ05DNK type: string description: ID of a COMPLETE Upload containing the OpenAPI spec document. headers: type: object additionalProperties: type: string description: >- Headers sent when fetching the spec from a URL and when dispatching tool calls. includeTools: $ref: '#/components/schemas/ToolSetAdapter_ToolFilter' excludeTools: $ref: '#/components/schemas/ToolSetAdapter_ToolFilter' toolApprovals: $ref: '#/components/schemas/ToolSetAdapter_ApprovalRequirementFilter' baseUrl: type: string description: |- Base URL for dispatching tool calls. If set, overrides the server resolved from the spec's servers array. May be templated with the same two reference forms the HTTP adapter's base_url accepts: ${SECRET_NAME} a workspace or tool set secret {{ pinned_parameters. }} the objective's pinned parameters A spec written against a single host can therefore be dispatched to a per-tenant one, e.g. https://{{ pinned_parameters.tenant }}.example.com, without cloning the tool set per customer. Validated as an absolute http(s) URL after references are resolved rather than as a literal URI. serverName: type: string description: |- Name of the server entry in the spec's servers array (OpenAPI 3.2 server.name field). Used to select which server URL to dispatch to when base_url is not set. If unset, the first server is used. Ignored when base_url is set. Selector_Condition_Attribute: type: object required: - type - attribute properties: type: type: string enum: - attribute attribute: allOf: - $ref: '#/components/schemas/ToolSetAdapter_AttributeFilter' description: |- Match on a tool attribute (name, title, description, llm_tool_name) with a string matcher — the same filter used by the adapter's include/exclude lists. Selector_Condition_HasParameter: type: object required: - type - hasParameter properties: type: type: string enum: - hasParameter hasParameter: allOf: - $ref: '#/components/schemas/ToolOverlay_ParameterPath' description: |- Match tools whose parameter schema contains the given path. This is the usual way to target "every tool that takes a workspaceId" without enumerating tools by name. Selector_Condition_Tools: type: object required: - type - tools properties: type: type: string enum: - tools tools: allOf: - $ref: '#/components/schemas/Selector_ToolNames' description: |- Match specific tools by LLM tool name. The direct way to assign an overlay to one tool (or a handful) without writing a matcher. ParameterAction_Remove: required: - path type: object properties: path: type: string description: |- Remove the parameter entirely. It is deleted from the schema (including any `required` entry) and stripped from the arguments if the model supplies it anyway. The tool receives no value for it — the upstream default, if any, applies. Use this to save context on parameters the model has no business setting (pagination cursors, expansion flags, debug toggles). ParameterAction_Set: required: - path - valueTemplate type: object properties: path: type: string valueTemplate: type: string description: |- Force the parameter to a value. It is deleted from the schema (including any `required` entry), and on every call the rendered value is written into the arguments, overwriting anything the model supplied. `value_template` is a Liquid template rendered against the objective: {{ pinned_parameters. }} the objective's pinned parameters {{ objective.id }} the objective's id {{ objective.external_id }} the objective's external id {{ objective.labels. }} the objective's labels Templates render with strict variables: referencing a pinned parameter or label that does not exist fails the call rather than rendering an empty value. Tool set secrets are intentionally not exposed here: overlay-set values are recorded as tool call arguments in events and tool call history, and would leak. Use adapter headers for credentials. The rendered string is coerced to the parameter's declared schema type: for a non-string parameter (integer, number, boolean, object, array) the output is parsed as JSON. A value that fails to parse errors the tool call. Prefer `pin` when the value is simply a pinned parameter — it fails loudly when the key is absent instead of rendering an empty string. ParameterAction_Pin: required: - path - pinnedParameter - onMissing type: object properties: path: type: string pinnedParameter: type: string description: |- Key into the objective's pinned_parameters map. Need not equal the last segment of `path` — this is how a pinned `orgId` reaches a tool whose parameter is named `organizationId`. onMissing: enum: - ON_MISSING_UNSPECIFIED - ON_MISSING_FAIL - ON_MISSING_SKIP - ON_MISSING_FAIL - ON_MISSING_SKIP type: string description: 'Default: ON_MISSING_FAIL.' format: enum description: |- Bind the parameter to one of the objective's pinned parameters. It is deleted from the schema (including any `required` entry), and on every call the pinned value is written into the arguments, overwriting anything the model supplied. This is the authoritative-value action: the model never sees the parameter and cannot influence it. `pin` differs from `set` with `{{ pinned_parameters.key }}` only in how a missing key is handled (see `on_missing`) and in intent — reading the tool set config, `pin` says "this comes from the caller". ResultAction_Transform: required: - contentTemplate - onError - expectJson type: object properties: contentTemplate: type: string onError: enum: - ON_ERROR_UNSPECIFIED - ON_ERROR_RAW_CONTENT - ON_ERROR_FAIL - ON_ERROR_RAW_CONTENT - ON_ERROR_FAIL type: string description: 'Default: ON_ERROR_RAW_CONTENT.' format: enum expectJson: type: boolean description: |- Require the tool result to have text content that parses as JSON before rendering. A non-JSON (or text-less) result is then an error subject to `on_error` even if the template never reads `result.json`. Off by default: `result.json` is simply absent for non-JSON results, and text-less results skip the transform. description: |- Replace the result's text content with a rendered Liquid template. Used to compact verbose responses to the fields the model actually needs, or to rewrite a JSON response into a smaller JSON document. `content_template` is rendered against the call: {{ result.text }} the result's text content (text blocks joined with newlines) {{ result.json }} result.text parsed as JSON — objects and arrays are navigable (`result.json.items`, `| map: "id"`); absent when the text is not valid JSON {{ result.blocks }} every content block: [{type, text?, mime_type?, size_bytes?}] {{ parameters }} the arguments the tool was called with, after parameter actions were applied {{ tool.name }} the tool's metadata.name {{ tool.llm_tool_name }} the name the model called it by {{ pinned_parameters }} the objective's pinned parameters {{ objective.id }} / {{ objective.external_id }} / {{ objective.labels. }} Templates render with strict variables: referencing `result.json` on a non-JSON result, or any other undefined variable, is a render error and `on_error` decides the outcome. The `json` filter pretty-prints a value as JSON; `sanitized_json` emits it compact and escaped for embedding. Transforms are text-only. `result.text` and `result.json` are built from the result's text blocks; media blocks (images, audio) are opaque to the template and pass through unchanged. The rendered text replaces the text blocks as a single text block. A result with no text blocks at all (an image-only or audio-only result) is out of scope: the transform is skipped, the result is recorded as returned, and the skip is noted in the tool call's debug log — this is not an `on_error` case, nothing was attempted. The one exception is `expect_json`, where a result with no text is a violated precondition and `on_error` applies. ToolSetAdapter_AttributeFilter: required: - attribute type: object properties: attribute: enum: - ATTRIBUTE_UNSPECIFIED - ATTRIBUTE_NAME - ATTRIBUTE_TITLE - ATTRIBUTE_DESCRIPTION - ATTRIBUTE_LLM_TOOL_NAME - ATTRIBUTE_NAME - ATTRIBUTE_TITLE - ATTRIBUTE_DESCRIPTION - ATTRIBUTE_LLM_TOOL_NAME type: string format: enum matcher: $ref: '#/components/schemas/ToolSetAdapter_StringMatcher' description: Single attribute filter ToolSetAdapter_ApprovalRequirementFilter_Always: type: object required: - type - always properties: type: type: string enum: - always always: type: boolean ToolSetAdapter_ApprovalRequirementFilter_Only: type: object required: - type - only properties: type: type: string enum: - only only: $ref: '#/components/schemas/ToolSetAdapter_ToolFilter' ToolOverlay_ParameterPath: required: - path type: object properties: path: type: string description: |- A dotted path into a tool's parameter schema. Each segment is a property name; the path `filter.workspaceId` addresses `properties.filter.properties.workspaceId` in the schema and `arguments.filter.workspaceId` in the call. Only object properties are addressable — there is no array indexing, wildcarding or filtering. This is deliberately not JSONPath: every action needs a single, unambiguous location in both the schema and the arguments so that removing a parameter from the schema and stripping it from the call are guaranteed to agree. Selector_ToolNames: type: object properties: names: type: array items: type: string description: |- An explicit list of tools, matched on spec.llm_tool_name — the name the model calls the tool by. It identifies a tool across versions: just-in-time MCP sets keep one tool per signature and every version shares the LLM name, so the condition keeps matching as the source evolves. Any name in the list matches (OR). Names of tools not (or not yet) present in the set are allowed and match nothing. ToolSetAdapter_StringMatcher: oneOf: - $ref: '#/components/schemas/ToolSetAdapter_StringMatcher_Exact' - $ref: '#/components/schemas/ToolSetAdapter_StringMatcher_StartsWith' - $ref: '#/components/schemas/ToolSetAdapter_StringMatcher_EndsWith' - $ref: '#/components/schemas/ToolSetAdapter_StringMatcher_Contains' - $ref: '#/components/schemas/ToolSetAdapter_StringMatcher_Regex' discriminator: propertyName: type mapping: exact: $ref: '#/components/schemas/ToolSetAdapter_StringMatcher_Exact' startsWith: $ref: '#/components/schemas/ToolSetAdapter_StringMatcher_StartsWith' endsWith: $ref: '#/components/schemas/ToolSetAdapter_StringMatcher_EndsWith' contains: $ref: '#/components/schemas/ToolSetAdapter_StringMatcher_Contains' regex: $ref: '#/components/schemas/ToolSetAdapter_StringMatcher_Regex' description: String matching operations ToolSetAdapter_StringMatcher_Exact: type: object required: - type - exact properties: type: type: string enum: - exact exact: type: string caseSensitive: type: boolean ToolSetAdapter_StringMatcher_StartsWith: type: object required: - type - startsWith properties: type: type: string enum: - startsWith startsWith: type: string caseSensitive: type: boolean ToolSetAdapter_StringMatcher_EndsWith: type: object required: - type - endsWith properties: type: type: string enum: - endsWith endsWith: type: string caseSensitive: type: boolean ToolSetAdapter_StringMatcher_Contains: type: object required: - type - contains properties: type: type: string enum: - contains contains: type: string caseSensitive: type: boolean ToolSetAdapter_StringMatcher_Regex: type: object required: - type - regex properties: type: type: string enum: - regex regex: type: string caseSensitive: type: boolean securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````