Tool Sets

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.

List tool sets

tool_sets.list(workspace_id, **kwargs) -> CursorPagination<ToolSet { metadata, spec, info } >

GET/v1/workspaces/{workspaceId}/tool_sets

Create a new tool set

tool_sets.create(workspace_id, **kwargs) -> ToolSet { metadata, spec, info }

POST/v1/workspaces/{workspaceId}/tool_sets

Get a tool set by ID

tool_sets.retrieve(id, **kwargs) -> ToolSet { metadata, spec, info }

GET/v1/workspaces/{workspaceId}/tool_sets/{id}

Update a tool set

tool_sets.update(id, **kwargs) -> ToolSet { metadata, spec, info }

PUT/v1/workspaces/{workspaceId}/tool_sets/{id}

Delete a tool set

tool_sets.delete(id, **kwargs) -> void

DELETE/v1/workspaces/{workspaceId}/tool_sets/{id}

Get consumed OpenAPI spec

tool_sets.get_openapi_spec(tool_set_id, **kwargs) -> ToolSetGetOpenAPISpecResponse { spec }

GET/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/openapi_spec

List tool set events

tool_sets.list_events(tool_set_id, **kwargs) -> CursorPagination<ToolSetEvent { metadata, event, info, tool_set_id } >

GET/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/events

ModelsExpand Collapse

class ApprovalRequirementFilter { always, only }

Approval filters that will automatically set the approval requirement on tools synced from an external source

always: bool

only: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

Single attribute filter

formatenum

One of the following:

String matching operations

class StringMatcher { case_sensitive, contains, ends_with, 3 more }

String matching operations

case_sensitive: bool

contains: String

ends_with: String

exact: String

regex: String

starts_with: String

class SyncCompleted { message, tools_synced }

Emitted when a tool set sync operation completes successfully.

message: String

Optional message with additional details.

tools_synced: Integer

Number of tools synced.

formatint32

class SyncFailed { error, error_type, message }

Emitted when a tool set sync operation fails.

error: bool

Indicates this is an error event.

error_type: String

Optional error type/code for programmatic handling.

message: String

Error message describing what went wrong.

class SyncStarted { message }

Emitted when a tool set sync operation begins.

message: String

Human-readable message describing the start of the sync.

class ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

class ToolSet { metadata, spec, info }

metadata: ResourceMetadata { id, account_id, created_at, 6 more }

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

id: String

Unique identifier for the resource (prefixed ULID, e.g., “agent_01HXK…”)

account_id: String

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

created_at: Time

Timestamp when this resource was created

formatdate-time

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profile_id: String

ID of the actor (user or service account) that created this resource

workspace_id: String

Workspace this resource belongs to for organizational grouping (prefixed ULID)

bundle_key: String

Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply.

external_id: String

External ID for the resource (e.g., a workflow ID from an external system)

labels: Hash[Symbol, String]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: ToolSetSpec { adapter, description }

adapter: ToolSetAdapter { http, mcp, openapi }

http: ToolSetAdapterHTTP { base_url, headers }

base_url: String

headers: Hash[Symbol, String]

mcp: ToolSetAdapterMcp { exclude_tools, headers, include_tools, 2 more }

exclude_tools: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

headers: Hash[Symbol, String]

include_tools: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

tool_approvals: ApprovalRequirementFilter { always, only }

Approval filters that will automatically set the approval requirement on tools synced from an external source

always: bool

only: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

url: String

openapi: ToolSetAdapterOpenAPI { base_url, exclude_tools, headers, 5 more }

base_url: String

Base URL for dispatching tool calls. If set, overrides the server resolved from the spec’s servers array.

exclude_tools: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

headers: Hash[Symbol, String]

Headers sent when fetching the spec from a URL and when dispatching tool calls.

include_tools: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

server_name: String

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.

tool_approvals: ApprovalRequirementFilter { always, only }

Approval filters that will automatically set the approval requirement on tools synced from an external source

always: bool

only: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

upload_id: String

ID of a COMPLETE Upload containing the OpenAPI spec document.

url: String

URL to fetch the OpenAPI spec from. Synced automatically every hour.

description: String

info: ToolSetInfo { agent_count, created_by, last_sync, tool_count }

Tool set information

agent_count: Integer

created_by: Profile { metadata, spec }

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.

metadata: AccountResourceMetadata { id, account_id, name, 3 more }

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

id: String

Unique identifier for the resource (prefixed ULID, e.g., “apikey_01HXK…”)

account_id: String

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profile_id: String

external_id: String

External ID for the resource (e.g., a workflow ID from an external system)

labels: Hash[Symbol, String]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: ProfileSpec { type, email, name }

Configuration for a profile.

type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM

Whether this profile represents a human user, an API key, or a system principal.

formatenum

One of the following:

:PROFILE_TYPE_UNSPECIFIED

:PROFILE_TYPE_USER

:PROFILE_TYPE_API_KEY

:PROFILE_TYPE_SYSTEM

email: String

Email address of the profile. Required and unique within an account for user profiles.

Display name (e.g., “Bobby Tables”).

last_sync: Time

tool_count: Integer

class ToolSetAdapter { http, mcp, openapi }

http: ToolSetAdapterHTTP { base_url, headers }

base_url: String

headers: Hash[Symbol, String]

mcp: ToolSetAdapterMcp { exclude_tools, headers, include_tools, 2 more }

exclude_tools: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

headers: Hash[Symbol, String]

include_tools: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

tool_approvals: ApprovalRequirementFilter { always, only }

Approval filters that will automatically set the approval requirement on tools synced from an external source

always: bool

only: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

url: String

openapi: ToolSetAdapterOpenAPI { base_url, exclude_tools, headers, 5 more }

base_url: String

Base URL for dispatching tool calls. If set, overrides the server resolved from the spec’s servers array.

exclude_tools: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

headers: Hash[Symbol, String]

Headers sent when fetching the spec from a URL and when dispatching tool calls.

include_tools: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

server_name: String

tool_approvals: ApprovalRequirementFilter { always, only }

Approval filters that will automatically set the approval requirement on tools synced from an external source

always: bool

only: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

upload_id: String

ID of a COMPLETE Upload containing the OpenAPI spec document.

url: String

URL to fetch the OpenAPI spec from. Synced automatically every hour.

class ToolSetAdapterHTTP { base_url, headers }

base_url: String

headers: Hash[Symbol, String]

class ToolSetAdapterMcp { exclude_tools, headers, include_tools, 2 more }

exclude_tools: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

headers: Hash[Symbol, String]

include_tools: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

tool_approvals: ApprovalRequirementFilter { always, only }

Approval filters that will automatically set the approval requirement on tools synced from an external source

always: bool

only: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

url: String

class ToolSetAdapterOpenAPI { base_url, exclude_tools, headers, 5 more }

base_url: String

Base URL for dispatching tool calls. If set, overrides the server resolved from the spec’s servers array.

exclude_tools: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

headers: Hash[Symbol, String]

Headers sent when fetching the spec from a URL and when dispatching tool calls.

include_tools: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

server_name: String

tool_approvals: ApprovalRequirementFilter { always, only }

Approval filters that will automatically set the approval requirement on tools synced from an external source

always: bool

only: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

upload_id: String

ID of a COMPLETE Upload containing the OpenAPI spec document.

url: String

URL to fetch the OpenAPI spec from. Synced automatically every hour.

class ToolSetEvent { metadata, event, info, tool_set_id }

A single event in the tool set’s operation timeline.

metadata: OperationMetadata { id, account_id, created_at, 4 more }

Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

id: String

Unique identifier for the operation (prefixed ULID, e.g., “obj_01HXK…”)

account_id: String

Account this operation belongs to for multi-tenant isolation (prefixed ULID)

created_at: Time

Timestamp when this operation was created ULID includes timestamp information, but this explicit field enables easier querying

formatdate-time

profile_id: String

ID of the actor (user or service account) that created this operation

workspace_id: String

Workspace this operation belongs to for organizational grouping (prefixed ULID)

external_id: String

External ID for the operation (e.g., a workflow ID from an external system)

labels: Hash[Symbol, String]

Arbitrary key-value pairs for categorization and filtering Examples: {“priority”: “high”, “source”: “api”, “workflow”: “onboarding”}

event: ToolSetEventData { sync_completed, sync_failed, sync_started, type }

Event payload for a tool set operation.

sync_completed: SyncCompleted { message, tools_synced }

Emitted when a tool set sync operation completes successfully.

message: String

Optional message with additional details.

tools_synced: Integer

Number of tools synced.

formatint32

sync_failed: SyncFailed { error, error_type, message }

Emitted when a tool set sync operation fails.

error: bool

Indicates this is an error event.

error_type: String

Optional error type/code for programmatic handling.

message: String

Error message describing what went wrong.

sync_started: SyncStarted { message }

Emitted when a tool set sync operation begins.

message: String

Human-readable message describing the start of the sync.

type: String

Type of the event (e.g., “sync_started”, “sync_completed”, “sync_failed”).

info: Info{ created_by, tool_set}

created_by: Profile { metadata, spec }

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.

metadata: AccountResourceMetadata { id, account_id, name, 3 more }

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

id: String

Unique identifier for the resource (prefixed ULID, e.g., “apikey_01HXK…”)

account_id: String

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profile_id: String

external_id: String

External ID for the resource (e.g., a workflow ID from an external system)

labels: Hash[Symbol, String]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: ProfileSpec { type, email, name }

Configuration for a profile.

type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM

Whether this profile represents a human user, an API key, or a system principal.

formatenum

One of the following:

:PROFILE_TYPE_UNSPECIFIED

:PROFILE_TYPE_USER

:PROFILE_TYPE_API_KEY

:PROFILE_TYPE_SYSTEM

email: String

Email address of the profile. Required and unique within an account for user profiles.

Display name (e.g., “Bobby Tables”).

tool_set: ResourceMetadata { id, account_id, created_at, 6 more }

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

id: String

Unique identifier for the resource (prefixed ULID, e.g., “agent_01HXK…”)

account_id: String

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

created_at: Time

Timestamp when this resource was created

formatdate-time

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profile_id: String

ID of the actor (user or service account) that created this resource

workspace_id: String

Workspace this resource belongs to for organizational grouping (prefixed ULID)

bundle_key: String

external_id: String

External ID for the resource (e.g., a workflow ID from an external system)

labels: Hash[Symbol, String]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

tool_set_id: String

The tool set this event is associated with.

class ToolSetEventData { sync_completed, sync_failed, sync_started, type }

Event payload for a tool set operation.

sync_completed: SyncCompleted { message, tools_synced }

Emitted when a tool set sync operation completes successfully.

message: String

Optional message with additional details.

tools_synced: Integer

Number of tools synced.

formatint32

sync_failed: SyncFailed { error, error_type, message }

Emitted when a tool set sync operation fails.

error: bool

Indicates this is an error event.

error_type: String

Optional error type/code for programmatic handling.

message: String

Error message describing what went wrong.

sync_started: SyncStarted { message }

Emitted when a tool set sync operation begins.

message: String

Human-readable message describing the start of the sync.

type: String

Type of the event (e.g., “sync_started”, “sync_completed”, “sync_failed”).

class ToolSetInfo { agent_count, created_by, last_sync, tool_count }

agent_count: Integer

created_by: Profile { metadata, spec }

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.

metadata: AccountResourceMetadata { id, account_id, name, 3 more }

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

id: String

Unique identifier for the resource (prefixed ULID, e.g., “apikey_01HXK…”)

account_id: String

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profile_id: String

external_id: String

External ID for the resource (e.g., a workflow ID from an external system)

labels: Hash[Symbol, String]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: ProfileSpec { type, email, name }

Configuration for a profile.

type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM

Whether this profile represents a human user, an API key, or a system principal.

formatenum

One of the following:

:PROFILE_TYPE_UNSPECIFIED

:PROFILE_TYPE_USER

:PROFILE_TYPE_API_KEY

:PROFILE_TYPE_SYSTEM

email: String

Email address of the profile. Required and unique within an account for user profiles.

Display name (e.g., “Bobby Tables”).

last_sync: Time

tool_count: Integer

class ToolSetSpec { adapter, description }

adapter: ToolSetAdapter { http, mcp, openapi }

http: ToolSetAdapterHTTP { base_url, headers }

base_url: String

headers: Hash[Symbol, String]

mcp: ToolSetAdapterMcp { exclude_tools, headers, include_tools, 2 more }

exclude_tools: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

headers: Hash[Symbol, String]

include_tools: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

tool_approvals: ApprovalRequirementFilter { always, only }

Approval filters that will automatically set the approval requirement on tools synced from an external source

always: bool

only: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

url: String

openapi: ToolSetAdapterOpenAPI { base_url, exclude_tools, headers, 5 more }

base_url: String

Base URL for dispatching tool calls. If set, overrides the server resolved from the spec’s servers array.

exclude_tools: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

headers: Hash[Symbol, String]

Headers sent when fetching the spec from a URL and when dispatching tool calls.

include_tools: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

server_name: String

tool_approvals: ApprovalRequirementFilter { always, only }

Approval filters that will automatically set the approval requirement on tools synced from an external source

always: bool

only: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: :OPERATOR_UNSPECIFIED | :OPERATOR_AND | :OPERATOR_OR

formatenum

One of the following:

:OPERATOR_UNSPECIFIED

:OPERATOR_AND

:OPERATOR_OR

filters: Array[AttributeFilter { attribute, matcher } ]

formatenum

One of the following:

String matching operations

upload_id: String

ID of a COMPLETE Upload containing the OpenAPI spec document.

url: String

URL to fetch the OpenAPI spec from. Synced automatically every hour.

description: String

class ToolSetGetOpenAPISpecResponse { spec }

spec: String

The consumed OpenAPI specification as a JSON string.

Tool SetsTools

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.

List tools

tool_sets.tools.list(tool_set_id, **kwargs) -> CursorPagination<Tool { metadata, spec, info } >

GET/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/tools

Create a new tool

tool_sets.tools.create(tool_set_id, **kwargs) -> Tool { metadata, spec, info }

POST/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/tools

Get a tool by ID

tool_sets.tools.retrieve(id, **kwargs) -> Tool { metadata, spec, info }

GET/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/tools/{id}

Update a tool

tool_sets.tools.update(id, **kwargs) -> Tool { metadata, spec, info }

PUT/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/tools/{id}

Delete a tool

tool_sets.tools.delete(id, **kwargs) -> void

DELETE/v1/workspaces/{workspaceId}/tool_sets/{toolSetId}/tools/{id}

ModelsExpand Collapse

class ConfigHTTP { request_method, headers, path, 4 more }

request_method: :HTTP_METHOD_UNSPECIFIED | :GET | :POST | 3 more

formatenum

One of the following:

:HTTP_METHOD_UNSPECIFIED

:GET

:POST

:PUT

:PATCH

:DELETE

headers: Hash[Symbol, String]

path: String

query: String

request_body_content_type: String

request_body_template: String

These are only used when the request method is a POST, PUT, or PATCH

tool_name: String

The tool name (commonly an “operation id” in OpenAPI specs) to call on the HTTP adapter. This is used to match the tool spec to the correct endpoint on the HTTP adapter. it will be derived from the name of the tool if not provided.

class ConfigMcp { tool_description, tool_name, tool_title }

tool_description: String

tool_name: String

tool_title: String

class ConfigOpenAPI { method_, operation_id, path }

method_: String

operation_id: String

path: String

class Tool { metadata, spec, info }

metadata: ResourceMetadata { id, account_id, created_at, 6 more }

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

id: String

Unique identifier for the resource (prefixed ULID, e.g., “agent_01HXK…”)

account_id: String

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

created_at: Time

Timestamp when this resource was created

formatdate-time

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profile_id: String

ID of the actor (user or service account) that created this resource

workspace_id: String

Workspace this resource belongs to for organizational grouping (prefixed ULID)

bundle_key: String

external_id: String

External ID for the resource (e.g., a workflow ID from an external system)

labels: Hash[Symbol, String]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: ToolSpec { config, description, parameters, 2 more }

config: ToolSpecConfig { http, mcp, openapi }

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.

http: ConfigHTTP { request_method, headers, path, 4 more }

request_method: :HTTP_METHOD_UNSPECIFIED | :GET | :POST | 3 more

formatenum

One of the following:

:HTTP_METHOD_UNSPECIFIED

:GET

:POST

:PUT

:PATCH

:DELETE

headers: Hash[Symbol, String]

path: String

query: String

request_body_content_type: String

request_body_template: String

These are only used when the request method is a POST, PUT, or PATCH

tool_name: String

mcp: ConfigMcp { tool_description, tool_name, tool_title }

tool_description: String

tool_name: String

tool_title: String

openapi: ConfigOpenAPI { method_, operation_id, path }

method_: String

operation_id: String

path: String

description: String

parameters: Hash[Symbol, untyped]

status: :TOOL_STATUS_UNSPECIFIED | :TOOL_STATUS_AVAILABLE | :TOOL_STATUS_OMITTED | :TOOL_STATUS_ARCHIVED

formatenum

One of the following:

:TOOL_STATUS_UNSPECIFIED

:TOOL_STATUS_AVAILABLE

:TOOL_STATUS_OMITTED

:TOOL_STATUS_ARCHIVED

requires_approval: bool

info: ToolInfo { created_by, tool_set }

created_by: Profile { metadata, spec }

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.

metadata: AccountResourceMetadata { id, account_id, name, 3 more }

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

id: String

Unique identifier for the resource (prefixed ULID, e.g., “apikey_01HXK…”)

account_id: String

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profile_id: String

external_id: String

External ID for the resource (e.g., a workflow ID from an external system)

labels: Hash[Symbol, String]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: ProfileSpec { type, email, name }

Configuration for a profile.

type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM

Whether this profile represents a human user, an API key, or a system principal.

formatenum

One of the following:

:PROFILE_TYPE_UNSPECIFIED

:PROFILE_TYPE_USER

:PROFILE_TYPE_API_KEY

:PROFILE_TYPE_SYSTEM

email: String

Email address of the profile. Required and unique within an account for user profiles.

Display name (e.g., “Bobby Tables”).

tool_set: ResourceMetadata { id, account_id, created_at, 6 more }

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

id: String

Unique identifier for the resource (prefixed ULID, e.g., “agent_01HXK…”)

account_id: String

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

created_at: Time

Timestamp when this resource was created

formatdate-time

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profile_id: String

ID of the actor (user or service account) that created this resource

workspace_id: String

Workspace this resource belongs to for organizational grouping (prefixed ULID)

bundle_key: String

external_id: String

External ID for the resource (e.g., a workflow ID from an external system)

labels: Hash[Symbol, String]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

class ToolInfo { created_by, tool_set }

created_by: Profile { metadata, spec }

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.

metadata: AccountResourceMetadata { id, account_id, name, 3 more }

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

id: String

Unique identifier for the resource (prefixed ULID, e.g., “apikey_01HXK…”)

account_id: String

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profile_id: String

external_id: String

External ID for the resource (e.g., a workflow ID from an external system)

labels: Hash[Symbol, String]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: ProfileSpec { type, email, name }

Configuration for a profile.

type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM

Whether this profile represents a human user, an API key, or a system principal.

formatenum

One of the following:

:PROFILE_TYPE_UNSPECIFIED

:PROFILE_TYPE_USER

:PROFILE_TYPE_API_KEY

:PROFILE_TYPE_SYSTEM

email: String

Email address of the profile. Required and unique within an account for user profiles.

Display name (e.g., “Bobby Tables”).

tool_set: ResourceMetadata { id, account_id, created_at, 6 more }

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

id: String

Unique identifier for the resource (prefixed ULID, e.g., “agent_01HXK…”)

account_id: String

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

created_at: Time

Timestamp when this resource was created

formatdate-time

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profile_id: String

ID of the actor (user or service account) that created this resource

workspace_id: String

Workspace this resource belongs to for organizational grouping (prefixed ULID)

bundle_key: String

external_id: String

External ID for the resource (e.g., a workflow ID from an external system)

labels: Hash[Symbol, String]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

class ToolSpec { config, description, parameters, 2 more }

config: ToolSpecConfig { http, mcp, openapi }

http: ConfigHTTP { request_method, headers, path, 4 more }

request_method: :HTTP_METHOD_UNSPECIFIED | :GET | :POST | 3 more

formatenum

One of the following:

:HTTP_METHOD_UNSPECIFIED

:GET

:POST

:PUT

:PATCH

:DELETE

headers: Hash[Symbol, String]

path: String

query: String

request_body_content_type: String

request_body_template: String

These are only used when the request method is a POST, PUT, or PATCH

tool_name: String

mcp: ConfigMcp { tool_description, tool_name, tool_title }

tool_description: String

tool_name: String

tool_title: String

openapi: ConfigOpenAPI { method_, operation_id, path }

method_: String

operation_id: String

path: String

description: String

parameters: Hash[Symbol, untyped]

status: :TOOL_STATUS_UNSPECIFIED | :TOOL_STATUS_AVAILABLE | :TOOL_STATUS_OMITTED | :TOOL_STATUS_ARCHIVED

formatenum

One of the following:

:TOOL_STATUS_UNSPECIFIED

:TOOL_STATUS_AVAILABLE

:TOOL_STATUS_OMITTED

:TOOL_STATUS_ARCHIVED

requires_approval: bool

class ToolSpecConfig { http, mcp, openapi }

http: ConfigHTTP { request_method, headers, path, 4 more }

request_method: :HTTP_METHOD_UNSPECIFIED | :GET | :POST | 3 more

formatenum

One of the following:

:HTTP_METHOD_UNSPECIFIED

:GET

:POST

:PUT

:PATCH

:DELETE

headers: Hash[Symbol, String]

path: String

query: String

request_body_content_type: String

request_body_template: String

These are only used when the request method is a POST, PUT, or PATCH

tool_name: String

mcp: ConfigMcp { tool_description, tool_name, tool_title }

tool_description: String

tool_name: String

tool_title: String

openapi: ConfigOpenAPI { method_, operation_id, path }

method_: String

operation_id: String

path: String