> ## 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. # Search tools and tool sets > Find a tool, a tool set, or an agent by name prefix. One query, three buckets of results. One query, searched across everything an [agent variation](/docs/api-reference/agentvariationservice/create-a-new-variation) can be assigned: individual tools, whole tool sets, and other agents. Despite the name, the response has **three** buckets. ```typescript TypeScript theme={null} const results = await client.search.searchToolsOrToolSets({ workspaceId, query: 'Generate' }); console.log(results.tools?.length); // 8 console.log(results.toolSets?.length); // 0 console.log(results.agents?.length); // 0 ``` ```go Go theme={null} results, err := client.Search.SearchToolsOrToolSets(ctx, cadenya.SearchSearchToolsOrToolSetsParams{ WorkspaceID: cadenya.String(workspaceID), Query: cadenya.String("Generate"), }) fmt.Println(len(results.Tools)) // 8 fmt.Println(len(results.ToolSets)) // 0 fmt.Println(len(results.Agents)) // 0 ``` ```ruby Ruby theme={null} results = cadenya.search.search_tools_or_tool_sets(workspace_id: workspace_id, query: "Generate") puts results.tools&.length # 8 puts results.tool_sets&.length # 0 puts results.agents&.length # 0 ``` ```bash cURL theme={null} curl "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/search/tools_or_tool_sets?query=Generate" \ -H "Authorization: Bearer ${CADENYA_API_KEY}" ``` The `agents` bucket is there because an agent can be assigned to a variation as a [sub-agent](/docs/guides/delegate-to-sub-agents), which makes it a tool from the calling agent's point of view. ## Matching is a case-insensitive name prefix All three buckets match a prefix of the resource name, folding case. ``` ?query=Generate → tools: 4 (GenerateFake, GenerateCurseWord, ...) ?query=generate → tools: 4 ← same result, folded ?query=enerate → tools: 0 ← prefix only, never a substring ?query=Faker → toolSets: 1, agents: 1 ``` Prefix-only is the thing to design around. Half-remembering a tool as `FakeGenerator` finds nothing, because the name starts `Generate`. A query containing a space matches nothing. `Faker MCP` is the exact, full name of a tool set and returns zero results, and even `Faker M` returns zero, while `Faker` returns it. Search on a single word. An empty `query` returns everything in the workspace, which is a reasonable way to populate a picker on first render. Results are scoped to live tool sets. A tool whose tool set was deleted or archived no longer appears, so what you get back is assignable. A tool result does not carry its parent tool set, though: `info` holds only a `signature`. Group results by tool set and you have to cross-reference. ## What it is for The intended flow is assignment. You are building a variation, you want to hand it a capability, and you do not remember whether that capability is one tool, a whole tool set, or a sub-agent. ```typescript theme={null} const results = await client.search.searchToolsOrToolSets({ workspaceId, query: 'Generate' }); // Assign exactly one of the three; type names which. await client.agents.variations.addAssignment(agentId, variationId, { workspaceId, type: 'toolId', toolId: results.tools![0].metadata.id, // or type: 'toolSetId', toolSetId: results.toolSets[0].metadata.id // or type: 'subAgentId', subAgentId: results.agents[0].metadata.id }); ``` [`addAssignment`](/docs/guides/sdk/agents#assignments-tools-sub-agents-memory) takes one target, a union whose `type` discriminator is the same three-way choice this endpoint returns. That symmetry is the whole design. This endpoint has nothing to do with `tool_search`, the tool an agent gets under [progressive discovery](/docs/guides/preventing-tool-bloat). That one loads tools into a running objective by exact name. This one is for you, at configuration time. ## Related Where the tools this endpoint finds come from. Assigning a tool, a tool set, or a sub-agent to a variation. Why agents appear in a tool search. The other `tool_search`, the one the agent calls. ## OpenAPI ````yaml get /v1/workspaces/{workspaceId}/search/tools_or_tool_sets 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}/search/tools_or_tool_sets: get: tags: - SearchService - Tool Search summary: Search for tools or tool sets description: Searches for tools or tool sets in the workspace operationId: SearchService_SearchToolsOrToolSets parameters: - name: workspaceId in: path description: >- NOTE: `query` is runtime-required (buf.validate min_len), but gnostic does not propagate message-level schema `required` to GET query parameters — overlay.yaml marks the parameter required instead. required: true schema: type: string example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q - name: query in: query schema: type: string required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SearchToolsOrToolSetsResponse' default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' x-codeSamples: - lang: JavaScript source: |- import Cadenya from '@cadenya/cadenya'; const client = new Cadenya({ apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted }); const response = await client.search.searchToolsOrToolSets({ workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q', query: 'query', }); console.log(response.agents); - lang: Python source: |- import os from cadenya import Cadenya client = Cadenya( api_key=os.environ.get("CADENYA_API_KEY"), # This is the default and can be omitted ) response = client.search.search_tools_or_tool_sets( workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q", query="query", ) print(response.agents) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"go.cadenya.com/cadenya-go\"\n\t\"go.cadenya.com/cadenya-go/option\"\n)\n\nfunc main() {\n\tclient := cadenya.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Search.SearchToolsOrToolSets(context.TODO(), cadenya.SearchSearchToolsOrToolSetsParams{\n\t\tWorkspaceID: cadenya.String(\"workspace_01HXKD2E5NQM3T9AYWCF133E3Q\"),\n\t\tQuery: \"query\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Agents)\n}\n" - lang: Ruby source: |- require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") response = cadenya.search.search_tools_or_tool_sets( workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q", query: "query" ) puts(response) - lang: CLI source: |- cadenya search search-tools-or-tool-sets \ --api-key 'My API Key' \ --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \ --query query components: schemas: SearchToolsOrToolSetsResponse: type: object properties: tools: type: array items: $ref: '#/components/schemas/Tool' toolSets: type: array items: $ref: '#/components/schemas/ToolSet' agents: type: array items: $ref: '#/components/schemas/Agent' 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). Tool: required: - metadata - spec - state type: object properties: metadata: $ref: '#/components/schemas/ResourceMetadata' spec: $ref: '#/components/schemas/ToolSpec' info: $ref: '#/components/schemas/ToolInfo' state: readOnly: true enum: - STATE_UNSPECIFIED - STATE_AVAILABLE - STATE_OMITTED - STATE_ARCHIVED type: string description: >- The current lifecycle state of the tool. Output only. Use the :omit and :restore actions to transition; tool set syncs may also update it. format: enum 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 Agent: required: - metadata - spec - state type: object properties: metadata: allOf: - $ref: '#/components/schemas/ResourceMetadata' description: Resource metadata spec: allOf: - $ref: '#/components/schemas/AgentSpec' description: Agent specification info: readOnly: true allOf: - $ref: '#/components/schemas/AgentInfo' description: Agent information state: readOnly: true enum: - STATE_UNSPECIFIED - STATE_DRAFT - STATE_PUBLISHED - STATE_ARCHIVED type: string description: >- The current lifecycle state of the agent. Output only. Agents are created in STATE_DRAFT; use the :publish, :unpublish, :archive, and :unarchive actions to transition between states. format: enum description: Agent resource 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. ResourceMetadata: required: - id - accountId - workspaceId - name - profileId - createdAt 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) ToolSpec: required: - description - parameters - config - requiresApproval type: object properties: description: type: string requiresApproval: type: boolean parameters: type: object additionalProperties: true description: >- The tool's JSON Schema, as handed to the LLM. Required, but may be the empty object `{}` for a tool that takes no arguments. Requiring it rather than defaulting it means a misspelled field name (`inputSchema`, say) is a 400 instead of a silently parameterless tool. config: allOf: - $ref: '#/components/schemas/ToolSpec_Config' description: >- Configuration for this specific tool. Transport/Protocol are derived from the tool set adapter, while specifics such as endpoint, method, etc, are stored on the tool itself. Required, and exactly one adapter must be set. llmToolName: type: string description: >- The name provided to the LLM, which may differ from the metadata.name on the tool. LLMs have specific length and format requirements, and tool set sources may not comply with them, so Cadenya does its best to format names into a usable format. ToolInfo: type: object properties: toolSet: $ref: '#/components/schemas/ResourceMetadata' createdBy: $ref: '#/components/schemas/Profile' signature: readOnly: true type: string description: >- Content signature identifying the tool within its tool set: a hash of the sanitized llm_tool_name, description, and canonical parameters. Two tools with the same llm_tool_name but different parameters or description (as MCP servers may return per user) have distinct signatures. ToolSetSpec: type: object properties: description: type: string adapter: $ref: '#/components/schemas/ToolSetAdapter' ToolSetInfo: 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 AgentSpec: required: - variationSelectionMode type: object properties: description: type: string description: Description of the agent's purpose webhookEventsUrl: type: string description: >- The URL that Cadenya will send events for any objective assigned to the agent. variationSelectionMode: enum: - VARIATION_SELECTION_MODE_UNSPECIFIED - VARIATION_SELECTION_MODE_RANDOM - VARIATION_SELECTION_MODE_WEIGHTED type: string description: >- Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified format: enum systemPromptDataSchema: type: object additionalProperties: true description: >- SystemPromptDataSchema enforces the shape of system_prompt_data when objectives are created. This is valuable when using liquid formatting in agent variation system prompt templates. The schema is also used when the agent is attached as a sub-agent, as it becomes the tool's input parameter schema. If omitted, the sub-agent schema will be loaded with a simple "prompt" free text string as its schema. outputDefinition: type: object additionalProperties: true description: |- Optional output definition for objectives created for this agent. When provided, Cadenya will append a tool to that will be called by the LLM in use by the variant to extract information in the format provided here. Use this option when you want structured data to be created by your objectives. enableEpisodicMemory: type: boolean description: |- Enable episodic memory for objectives created for this agent. When true, objective creation requires an episodic_memory key and the system finds or creates a memory layer for that (agent, key) pair, letting the agent store and retrieve memories across objectives that share the key. Memory is agent-level so all variations of the agent share the same layers. episodicMemoryTtl: pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ type: integer description: |- How long episodic memories should be retained. Each new objective slides the layer's expiry forward by this duration, and stored entries expire this long after they are written. If not set, episodic memories are retained indefinitely. description: Agent specification (user-provided configuration) AgentInfo: type: object properties: variationCount: readOnly: true type: integer format: int32 createdBy: $ref: '#/components/schemas/Profile' description: >- AgentInfo contains simple information about an agent for display or quick reference ToolSpec_Config: oneOf: - $ref: '#/components/schemas/ToolSpec_Config_Http' - $ref: '#/components/schemas/ToolSpec_Config_Mcp' - $ref: '#/components/schemas/ToolSpec_Config_Openapi' - $ref: '#/components/schemas/ToolSpec_Config_Bare' discriminator: propertyName: type mapping: http: $ref: '#/components/schemas/ToolSpec_Config_Http' mcp: $ref: '#/components/schemas/ToolSpec_Config_Mcp' openapi: $ref: '#/components/schemas/ToolSpec_Config_Openapi' bare: $ref: '#/components/schemas/ToolSpec_Config_Bare' description: |- Config defines the adapter to use for the tool. This is used to determine how the tool is called. For example, if the tool is an HTTP tool, the adapter will be Http. If the tool is an inline tool, the adapter will be Inline. 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: 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' ToolSpec_Config_Http: type: object required: - type - http properties: type: type: string enum: - http http: $ref: '#/components/schemas/Config_HTTP' ToolSpec_Config_Mcp: type: object required: - type - mcp properties: type: type: string enum: - mcp mcp: $ref: '#/components/schemas/Config_MCP' ToolSpec_Config_Openapi: type: object required: - type - openapi properties: type: type: string enum: - openapi openapi: $ref: '#/components/schemas/Config_OpenAPI' ToolSpec_Config_Bare: type: object required: - type - bare properties: type: type: string enum: - bare bare: $ref: '#/components/schemas/Config_Bare' AccountResourceMetadata: required: - id - accountId - name - profileId 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 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_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' Config_HTTP: required: - requestMethod type: object properties: requestMethod: enum: - HTTP_METHOD_UNSPECIFIED - GET - POST - PUT - PATCH - DELETE type: string format: enum path: type: string query: type: string headers: type: object additionalProperties: type: string requestBodyTemplate: type: string description: These are only used when the request method is a POST, PUT, or PATCH requestBodyContentType: type: string Config_MCP: type: object properties: annotations: allOf: - $ref: '#/components/schemas/MCP_Annotations' description: Tool behavior annotations from the MCP server, captured during sync. Config_OpenAPI: type: object properties: path: type: string method: type: string Config_Bare: type: object properties: {} description: |- Marks the tool as bare: it has no execution adapter of its own and relies on the parent tool set being a Bare tool set. Present so a webhook consumer can tell a tool is bare from the tool data alone, without cross-referencing the tool set. x-stainless-empty-object: true 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 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). MCP_Annotations: type: object properties: title: type: string description: A human-readable title for the tool. readOnlyHint: type: boolean description: If true, the tool does not modify its environment. destructiveHint: type: boolean description: >- If true, the tool may perform destructive updates to its environment. Only meaningful when read_only_hint is false. idempotentHint: type: boolean description: |- If true, calling the tool repeatedly with the same arguments has no additional effect. Only meaningful when read_only_hint is false. openWorldHint: type: boolean description: |- If true, the tool may interact with an "open world" of external entities (e.g. web search); if false, its domain is closed. description: |- Behavior hints synced from the MCP server's tool definition (ToolAnnotations in the MCP specification). All hints are advisory: servers are not required to send them, and clients should not rely on them for security decisions. Absent hints keep the MCP spec defaults (destructiveHint and openWorldHint default to true; readOnlyHint and idempotentHint default to false). 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. 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. 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_AttributeFilter: required: - attribute type: object properties: attribute: enum: - ATTRIBUTE_UNSPECIFIED - ATTRIBUTE_NAME - ATTRIBUTE_TITLE - ATTRIBUTE_DESCRIPTION - ATTRIBUTE_NAME - ATTRIBUTE_TITLE - ATTRIBUTE_DESCRIPTION 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' 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 ````