API Reference

Tool Sets

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Tools

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

client.toolSets.tools.list(stringtoolSetID, ToolListParams { workspaceId, bundleKey, cursor, 8 more } params, RequestOptionsoptions?): CursorPagination<Tool { metadata, spec, info } >

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

Create a new tool

client.toolSets.tools.create(stringtoolSetID, ToolCreateParams { workspaceId, metadata, spec } params, RequestOptionsoptions?): Tool { metadata, spec, info }

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

Get a tool by ID

client.toolSets.tools.retrieve(stringid, ToolRetrieveParams { workspaceId, toolSetId } params, RequestOptionsoptions?): Tool { metadata, spec, info }

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

Update a tool

client.toolSets.tools.update(stringid, ToolUpdateParams { workspaceId, toolSetId, metadata, 2 more } params, RequestOptionsoptions?): Tool { metadata, spec, info }

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

Delete a tool

client.toolSets.tools.delete(stringid, ToolDeleteParams { workspaceId, toolSetId } params, RequestOptionsoptions?): void

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

ModelsExpand Collapse

ConfigHTTP { requestMethod, headers, path, 4 more }

requestMethod: "HTTP_METHOD_UNSPECIFIED" | "GET" | "POST" | 3 more

formatenum

One of the following:

"HTTP_METHOD_UNSPECIFIED"

"GET"

"POST"

"PUT"

"PATCH"

"DELETE"

headers?: Record<string, string>

path?: string

query?: string

requestBodyContentType?: string

requestBodyTemplate?: string

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

toolName?: 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.

ConfigMcp { toolDescription, toolName, toolTitle }

toolDescription?: string

toolName?: string

toolTitle?: string

ConfigOpenAPI { method, operationId, path }

method?: string

operationId?: string

path?: string

Tool { metadata, spec, info }

metadata: ResourceMetadata { id, accountId, createdAt, 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…”)

accountId: string

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

createdAt: string

Timestamp when this resource was created

formatdate-time

name: string

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

profileId: string

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

workspaceId: string

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

bundleKey?: 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.

externalId?: string

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

labels?: Record<string, 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 { requestMethod, headers, path, 4 more }

requestMethod: "HTTP_METHOD_UNSPECIFIED" | "GET" | "POST" | 3 more

formatenum

One of the following:

"HTTP_METHOD_UNSPECIFIED"

"GET"

"POST"

"PUT"

"PATCH"

"DELETE"

headers?: Record<string, string>

path?: string

query?: string

requestBodyContentType?: string

requestBodyTemplate?: string

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

toolName?: 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.

mcp?: ConfigMcp { toolDescription, toolName, toolTitle }

toolDescription?: string

toolName?: string

toolTitle?: string

openapi?: ConfigOpenAPI { method, operationId, path }

method?: string

operationId?: string

path?: string

description: string

parameters: Record<string, unknown>

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"

requiresApproval?: boolean

info?: ToolInfo { createdBy, toolSet }

createdBy?: 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, accountId, 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…”)

accountId: string

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

name: string

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

profileId: string

externalId?: string

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

labels?: Record<string, 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.

name?: string

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

toolSet?: ResourceMetadata { id, accountId, createdAt, 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…”)

accountId: string

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

createdAt: string

Timestamp when this resource was created

formatdate-time

name: string

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

profileId: string

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

workspaceId: string

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

bundleKey?: 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.

externalId?: string

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

labels?: Record<string, string>

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

ToolInfo { createdBy, toolSet }

createdBy?: 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, accountId, 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…”)

accountId: string

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

name: string

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

profileId: string

externalId?: string

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

labels?: Record<string, 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.

name?: string

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

toolSet?: ResourceMetadata { id, accountId, createdAt, 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…”)

accountId: string

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

createdAt: string

Timestamp when this resource was created

formatdate-time

name: string

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

profileId: string

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

workspaceId: string

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

bundleKey?: 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.

externalId?: string

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

labels?: Record<string, string>

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

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 { requestMethod, headers, path, 4 more }

requestMethod: "HTTP_METHOD_UNSPECIFIED" | "GET" | "POST" | 3 more

formatenum

One of the following:

"HTTP_METHOD_UNSPECIFIED"

"GET"

"POST"

"PUT"

"PATCH"

"DELETE"

headers?: Record<string, string>

path?: string

query?: string

requestBodyContentType?: string

requestBodyTemplate?: string

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

toolName?: 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.

mcp?: ConfigMcp { toolDescription, toolName, toolTitle }

toolDescription?: string

toolName?: string

toolTitle?: string

openapi?: ConfigOpenAPI { method, operationId, path }

method?: string

operationId?: string

path?: string

description: string

parameters: Record<string, unknown>

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"

requiresApproval?: boolean

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 { requestMethod, headers, path, 4 more }

requestMethod: "HTTP_METHOD_UNSPECIFIED" | "GET" | "POST" | 3 more

formatenum

One of the following:

"HTTP_METHOD_UNSPECIFIED"

"GET"

"POST"

"PUT"

"PATCH"

"DELETE"

headers?: Record<string, string>

path?: string

query?: string

requestBodyContentType?: string

requestBodyTemplate?: string

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

toolName?: 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.

mcp?: ConfigMcp { toolDescription, toolName, toolTitle }

toolDescription?: string

toolName?: string

toolTitle?: string

openapi?: ConfigOpenAPI { method, operationId, path }

method?: string

operationId?: string

path?: string