API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Tool Sets

ToolService manages tool sets and tools at the WORKSPACE level. Tool sets group related tools, and tools define specific capabilities for agents. All operations are implicitly scoped to the workspace determined by the JWT token.

Note: When a ToolSet has managed=true, only API Key actors can modify its tools. Profile actors (humans) are restricted from modifying managed tool sets.

Authentication: Bearer token (JWT) Scope: Workspace-level operations

List tool sets

client.toolSets.list(ToolSetListParams { cursor, includeInfo, limit, 2 more } query?, RequestOptionsoptions?): CursorPagination<ToolSet { metadata, spec, info } >

GET/v1/tool_sets

Create a new tool set

client.toolSets.create(ToolSetCreateParams { metadata, spec } body, RequestOptionsoptions?): ToolSet { metadata, spec, info }

POST/v1/tool_sets

Get a tool set by ID

client.toolSets.retrieve(stringid, RequestOptionsoptions?): ToolSet { metadata, spec, info }

GET/v1/tool_sets/{id}

Update a tool set

client.toolSets.update(stringid, ToolSetUpdateParams { metadata, spec, updateMask } body, RequestOptionsoptions?): ToolSet { metadata, spec, info }

PUT/v1/tool_sets/{id}

Delete a tool set

client.toolSets.delete(stringid, RequestOptionsoptions?): void

DELETE/v1/tool_sets/{id}

List tool set events

client.toolSets.listEvents(stringtoolSetID, ToolSetListEventsParams { cursor, includeInfo, limit, sortOrder } query?, RequestOptionsoptions?): CursorPagination<ToolSetEvent { metadata, event, info, toolSetId } >

GET/v1/tool_sets/{toolSetId}/events

ModelsExpand Collapse

McpToolFilter { 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<Filter>

attribute: "ATTRIBUTE_UNSPECIFIED" | "ATTRIBUTE_NAME" | "ATTRIBUTE_TITLE" | "ATTRIBUTE_DESCRIPTION"

formatenum

One of the following:

"ATTRIBUTE_UNSPECIFIED"

"ATTRIBUTE_NAME"

"ATTRIBUTE_TITLE"

"ATTRIBUTE_DESCRIPTION"

matcher?: Matcher { caseSensitive, contains, endsWith, 3 more }

String matching operations

caseSensitive?: boolean

contains?: string

endsWith?: string

exact?: string

regex?: string

startsWith?: string

SyncCompleted { message, toolsSynced }

SyncCompleted is emitted when a tool set sync operation completes successfully

message?: string

Optional message with additional details

toolsSynced?: number

Number of tools synced

formatint32

SyncFailed { error, errorType, message }

SyncFailed is emitted when a tool set sync operation fails

error?: boolean

Indicates this is an error event

errorType?: string

Optional error type/code for programmatic handling

message?: string

Error message describing what went wrong

SyncStarted { message }

SyncStarted is emitted when a tool set sync operation begins

message?: string

Timestamp when the sync was initiated

ToolSet { metadata, spec, info }

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

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: ToolSetSpec { adapter, description }

adapter?: ToolSetAdapter { http, mcp }

http?: ToolSetAdapterHTTP { baseUrl, headers }

baseUrl?: string

headers?: Record<string, string>

mcp?: ToolSetAdapterMcp { excludeTools, headers, includeTools, 2 more }

excludeTools?: McpToolFilter { 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<Filter>

attribute: "ATTRIBUTE_UNSPECIFIED" | "ATTRIBUTE_NAME" | "ATTRIBUTE_TITLE" | "ATTRIBUTE_DESCRIPTION"

formatenum

One of the following:

"ATTRIBUTE_UNSPECIFIED"

"ATTRIBUTE_NAME"

"ATTRIBUTE_TITLE"

"ATTRIBUTE_DESCRIPTION"

matcher?: Matcher { caseSensitive, contains, endsWith, 3 more }

String matching operations

caseSensitive?: boolean

contains?: string

endsWith?: string

exact?: string

regex?: string

startsWith?: string

headers?: Record<string, string>

includeTools?: McpToolFilter { 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<Filter>

attribute: "ATTRIBUTE_UNSPECIFIED" | "ATTRIBUTE_NAME" | "ATTRIBUTE_TITLE" | "ATTRIBUTE_DESCRIPTION"

formatenum

One of the following:

"ATTRIBUTE_UNSPECIFIED"

"ATTRIBUTE_NAME"

"ATTRIBUTE_TITLE"

"ATTRIBUTE_DESCRIPTION"

matcher?: Matcher { caseSensitive, contains, endsWith, 3 more }

String matching operations

caseSensitive?: boolean

contains?: string

endsWith?: string

exact?: string

regex?: string

startsWith?: string

toolApprovals?: ToolApprovals { always, only }

Approval filters that will automatically set the approval requirement on the tools synced from the MCP server

always?: boolean

only?: McpToolFilter { 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<Filter>

attribute: "ATTRIBUTE_UNSPECIFIED" | "ATTRIBUTE_NAME" | "ATTRIBUTE_TITLE" | "ATTRIBUTE_DESCRIPTION"

formatenum

One of the following:

"ATTRIBUTE_UNSPECIFIED"

"ATTRIBUTE_NAME"

"ATTRIBUTE_TITLE"

"ATTRIBUTE_DESCRIPTION"

matcher?: Matcher { caseSensitive, contains, endsWith, 3 more }

String matching operations

caseSensitive?: boolean

contains?: string

endsWith?: string

exact?: string

regex?: string

startsWith?: string

url?: string

description?: string

info?: ToolSetInfo { agentCount, createdBy, lastSync, toolCount }

Tool set information

agentCount?: number

createdBy?: Profile { metadata, spec }

Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).

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 }

ProfileSpec contains the profile-specific fields

type: "PROFILE_TYPE_USER" | "PROFILE_TYPE_API_KEY" | "PROFILE_TYPE_SYSTEM"

Type is the type of profile. User's are humans, API keys are computers. You know the deal.

formatenum

One of the following:

"PROFILE_TYPE_USER"

"PROFILE_TYPE_API_KEY"

"PROFILE_TYPE_SYSTEM"

email?: string

Email address of the user (required, unique per account)

name?: string

Display name for the user (e.g., "Bobby Tables")

lastSync?: string

toolCount?: number

ToolSetAdapter { http, mcp }

http?: ToolSetAdapterHTTP { baseUrl, headers }

baseUrl?: string

headers?: Record<string, string>

mcp?: ToolSetAdapterMcp { excludeTools, headers, includeTools, 2 more }

excludeTools?: McpToolFilter { 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<Filter>

attribute: "ATTRIBUTE_UNSPECIFIED" | "ATTRIBUTE_NAME" | "ATTRIBUTE_TITLE" | "ATTRIBUTE_DESCRIPTION"

formatenum

One of the following:

"ATTRIBUTE_UNSPECIFIED"

"ATTRIBUTE_NAME"

"ATTRIBUTE_TITLE"

"ATTRIBUTE_DESCRIPTION"

matcher?: Matcher { caseSensitive, contains, endsWith, 3 more }

String matching operations

caseSensitive?: boolean

contains?: string

endsWith?: string

exact?: string

regex?: string

startsWith?: string

headers?: Record<string, string>

includeTools?: McpToolFilter { 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<Filter>

attribute: "ATTRIBUTE_UNSPECIFIED" | "ATTRIBUTE_NAME" | "ATTRIBUTE_TITLE" | "ATTRIBUTE_DESCRIPTION"

formatenum

One of the following:

"ATTRIBUTE_UNSPECIFIED"

"ATTRIBUTE_NAME"

"ATTRIBUTE_TITLE"

"ATTRIBUTE_DESCRIPTION"

matcher?: Matcher { caseSensitive, contains, endsWith, 3 more }

String matching operations

caseSensitive?: boolean

contains?: string

endsWith?: string

exact?: string

regex?: string

startsWith?: string

toolApprovals?: ToolApprovals { always, only }

Approval filters that will automatically set the approval requirement on the tools synced from the MCP server

always?: boolean

only?: McpToolFilter { 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<Filter>

attribute: "ATTRIBUTE_UNSPECIFIED" | "ATTRIBUTE_NAME" | "ATTRIBUTE_TITLE" | "ATTRIBUTE_DESCRIPTION"

formatenum

One of the following:

"ATTRIBUTE_UNSPECIFIED"

"ATTRIBUTE_NAME"

"ATTRIBUTE_TITLE"

"ATTRIBUTE_DESCRIPTION"

matcher?: Matcher { caseSensitive, contains, endsWith, 3 more }

String matching operations

caseSensitive?: boolean

contains?: string

endsWith?: string

exact?: string

regex?: string

startsWith?: string

url?: string

ToolSetAdapterHTTP { baseUrl, headers }

baseUrl?: string

headers?: Record<string, string>

ToolSetAdapterMcp { excludeTools, headers, includeTools, 2 more }

excludeTools?: McpToolFilter { 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<Filter>

attribute: "ATTRIBUTE_UNSPECIFIED" | "ATTRIBUTE_NAME" | "ATTRIBUTE_TITLE" | "ATTRIBUTE_DESCRIPTION"

formatenum

One of the following:

"ATTRIBUTE_UNSPECIFIED"

"ATTRIBUTE_NAME"

"ATTRIBUTE_TITLE"

"ATTRIBUTE_DESCRIPTION"

matcher?: Matcher { caseSensitive, contains, endsWith, 3 more }

String matching operations

caseSensitive?: boolean

contains?: string

endsWith?: string

exact?: string

regex?: string

startsWith?: string

headers?: Record<string, string>

includeTools?: McpToolFilter { 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<Filter>

attribute: "ATTRIBUTE_UNSPECIFIED" | "ATTRIBUTE_NAME" | "ATTRIBUTE_TITLE" | "ATTRIBUTE_DESCRIPTION"

formatenum

One of the following:

"ATTRIBUTE_UNSPECIFIED"

"ATTRIBUTE_NAME"

"ATTRIBUTE_TITLE"

"ATTRIBUTE_DESCRIPTION"

matcher?: Matcher { caseSensitive, contains, endsWith, 3 more }

String matching operations

caseSensitive?: boolean

contains?: string

endsWith?: string

exact?: string

regex?: string

startsWith?: string

toolApprovals?: ToolApprovals { always, only }

Approval filters that will automatically set the approval requirement on the tools synced from the MCP server

always?: boolean

only?: McpToolFilter { 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<Filter>

attribute: "ATTRIBUTE_UNSPECIFIED" | "ATTRIBUTE_NAME" | "ATTRIBUTE_TITLE" | "ATTRIBUTE_DESCRIPTION"

formatenum

One of the following:

"ATTRIBUTE_UNSPECIFIED"

"ATTRIBUTE_NAME"

"ATTRIBUTE_TITLE"

"ATTRIBUTE_DESCRIPTION"

matcher?: Matcher { caseSensitive, contains, endsWith, 3 more }

String matching operations

caseSensitive?: boolean

contains?: string

endsWith?: string

exact?: string

regex?: string

startsWith?: string

url?: string

ToolSetEvent { metadata, event, info, toolSetId }

ToolSetEvent represents a single event in the tool set's operation timeline

metadata: OperationMetadata { id, accountId, createdAt, 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...")

accountId: string

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

createdAt: string

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

formatdate-time

profileId: string

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

workspaceId: string

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

externalId?: string

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

labels?: Record<string, string>

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

event?: ToolSetEventData { syncCompleted, syncFailed, syncStarted, type }

ToolSetEventData represents the actual event payload for tool set operations

syncCompleted?: SyncCompleted { message, toolsSynced }

SyncCompleted is emitted when a tool set sync operation completes successfully

message?: string

Optional message with additional details

toolsSynced?: number

Number of tools synced

formatint32

syncFailed?: SyncFailed { error, errorType, message }

SyncFailed is emitted when a tool set sync operation fails

error?: boolean

Indicates this is an error event

errorType?: string

Optional error type/code for programmatic handling

message?: string

Error message describing what went wrong

syncStarted?: SyncStarted { message }

SyncStarted is emitted when a tool set sync operation begins

message?: string

Timestamp when the sync was initiated

type?: string

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

info?: Info { createdBy, toolSet }

createdBy?: Profile { metadata, spec }

Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).

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 }

ProfileSpec contains the profile-specific fields

type: "PROFILE_TYPE_USER" | "PROFILE_TYPE_API_KEY" | "PROFILE_TYPE_SYSTEM"

Type is the type of profile. User's are humans, API keys are computers. You know the deal.

formatenum

One of the following:

"PROFILE_TYPE_USER"

"PROFILE_TYPE_API_KEY"

"PROFILE_TYPE_SYSTEM"

email?: string

Email address of the user (required, unique per account)

name?: string

Display name for the user (e.g., "Bobby Tables")

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

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"}

toolSetId?: string

The tool set this event is associated with

ToolSetEventData { syncCompleted, syncFailed, syncStarted, type }

ToolSetEventData represents the actual event payload for tool set operations

syncCompleted?: SyncCompleted { message, toolsSynced }

SyncCompleted is emitted when a tool set sync operation completes successfully

message?: string

Optional message with additional details

toolsSynced?: number

Number of tools synced

formatint32

syncFailed?: SyncFailed { error, errorType, message }

SyncFailed is emitted when a tool set sync operation fails

error?: boolean

Indicates this is an error event

errorType?: string

Optional error type/code for programmatic handling

message?: string

Error message describing what went wrong

syncStarted?: SyncStarted { message }

SyncStarted is emitted when a tool set sync operation begins

message?: string

Timestamp when the sync was initiated

type?: string

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

ToolSetInfo { agentCount, createdBy, lastSync, toolCount }

agentCount?: number

createdBy?: Profile { metadata, spec }

Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).

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 }

ProfileSpec contains the profile-specific fields

type: "PROFILE_TYPE_USER" | "PROFILE_TYPE_API_KEY" | "PROFILE_TYPE_SYSTEM"

Type is the type of profile. User's are humans, API keys are computers. You know the deal.

formatenum

One of the following:

"PROFILE_TYPE_USER"

"PROFILE_TYPE_API_KEY"

"PROFILE_TYPE_SYSTEM"

email?: string

Email address of the user (required, unique per account)

name?: string

Display name for the user (e.g., "Bobby Tables")

lastSync?: string

toolCount?: number

ToolSetSpec { adapter, description }

adapter?: ToolSetAdapter { http, mcp }

http?: ToolSetAdapterHTTP { baseUrl, headers }

baseUrl?: string

headers?: Record<string, string>

mcp?: ToolSetAdapterMcp { excludeTools, headers, includeTools, 2 more }

excludeTools?: McpToolFilter { 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<Filter>

attribute: "ATTRIBUTE_UNSPECIFIED" | "ATTRIBUTE_NAME" | "ATTRIBUTE_TITLE" | "ATTRIBUTE_DESCRIPTION"

formatenum

One of the following:

"ATTRIBUTE_UNSPECIFIED"

"ATTRIBUTE_NAME"

"ATTRIBUTE_TITLE"

"ATTRIBUTE_DESCRIPTION"

matcher?: Matcher { caseSensitive, contains, endsWith, 3 more }

String matching operations

caseSensitive?: boolean

contains?: string

endsWith?: string

exact?: string

regex?: string

startsWith?: string

headers?: Record<string, string>

includeTools?: McpToolFilter { 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<Filter>

attribute: "ATTRIBUTE_UNSPECIFIED" | "ATTRIBUTE_NAME" | "ATTRIBUTE_TITLE" | "ATTRIBUTE_DESCRIPTION"

formatenum

One of the following:

"ATTRIBUTE_UNSPECIFIED"

"ATTRIBUTE_NAME"

"ATTRIBUTE_TITLE"

"ATTRIBUTE_DESCRIPTION"

matcher?: Matcher { caseSensitive, contains, endsWith, 3 more }

String matching operations

caseSensitive?: boolean

contains?: string

endsWith?: string

exact?: string

regex?: string

startsWith?: string

toolApprovals?: ToolApprovals { always, only }

Approval filters that will automatically set the approval requirement on the tools synced from the MCP server

always?: boolean

only?: McpToolFilter { 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<Filter>

attribute: "ATTRIBUTE_UNSPECIFIED" | "ATTRIBUTE_NAME" | "ATTRIBUTE_TITLE" | "ATTRIBUTE_DESCRIPTION"

formatenum

One of the following:

"ATTRIBUTE_UNSPECIFIED"

"ATTRIBUTE_NAME"

"ATTRIBUTE_TITLE"

"ATTRIBUTE_DESCRIPTION"

matcher?: Matcher { caseSensitive, contains, endsWith, 3 more }

String matching operations

caseSensitive?: boolean

contains?: string

endsWith?: string

exact?: string

regex?: string

startsWith?: string

url?: string

description?: string

Tool SetsTools

ToolService manages tool sets and tools at the WORKSPACE level. Tool sets group related tools, and tools define specific capabilities for agents. All operations are implicitly scoped to the workspace determined by the JWT token.

Note: When a ToolSet has managed=true, only API Key actors can modify its tools. Profile actors (humans) are restricted from modifying managed tool sets.

Authentication: Bearer token (JWT) Scope: Workspace-level operations

List tools

client.toolSets.tools.list(stringtoolSetID, ToolListParams { cursor, includeInfo, limit, 2 more } query?, RequestOptionsoptions?): CursorPagination<Tool { metadata, spec, info } >

GET/v1/tool_sets/{toolSetId}/tools

Create a new tool

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

POST/v1/tool_sets/{toolSetId}/tools

Get a tool by ID

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

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

Update a tool

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

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

Delete a tool

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

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

ModelsExpand Collapse

ConfigHTTP { requestMethod, headers, path, 4 more }

requestMethod: "GET" | "POST" | "PUT" | 2 more

formatenum

One of the following:

"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

Tool { metadata, spec, info }

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

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 }

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: "GET" | "POST" | "PUT" | 2 more

formatenum

One of the following:

"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

description: string

parameters: Record<string, unknown>

status: "TOOL_STATUS_UNSPECIFIED" | "TOOL_STATUS_AVAILABLE" | "TOOL_STATUS_FILTERED" | "TOOL_STATUS_ARCHIVED"

formatenum

One of the following:

"TOOL_STATUS_UNSPECIFIED"

"TOOL_STATUS_AVAILABLE"

"TOOL_STATUS_FILTERED"

"TOOL_STATUS_ARCHIVED"

requiresApproval?: boolean

info?: ToolInfo { createdBy, toolSet }

createdBy?: Profile { metadata, spec }

Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).

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 }

ProfileSpec contains the profile-specific fields

type: "PROFILE_TYPE_USER" | "PROFILE_TYPE_API_KEY" | "PROFILE_TYPE_SYSTEM"

Type is the type of profile. User's are humans, API keys are computers. You know the deal.

formatenum

One of the following:

"PROFILE_TYPE_USER"

"PROFILE_TYPE_API_KEY"

"PROFILE_TYPE_SYSTEM"

email?: string

Email address of the user (required, unique per account)

name?: string

Display name for the user (e.g., "Bobby Tables")

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

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 }

Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).

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 }

ProfileSpec contains the profile-specific fields

type: "PROFILE_TYPE_USER" | "PROFILE_TYPE_API_KEY" | "PROFILE_TYPE_SYSTEM"

Type is the type of profile. User's are humans, API keys are computers. You know the deal.

formatenum

One of the following:

"PROFILE_TYPE_USER"

"PROFILE_TYPE_API_KEY"

"PROFILE_TYPE_SYSTEM"

email?: string

Email address of the user (required, unique per account)

name?: string

Display name for the user (e.g., "Bobby Tables")

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

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 }

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: "GET" | "POST" | "PUT" | 2 more

formatenum

One of the following:

"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

description: string

parameters: Record<string, unknown>

status: "TOOL_STATUS_UNSPECIFIED" | "TOOL_STATUS_AVAILABLE" | "TOOL_STATUS_FILTERED" | "TOOL_STATUS_ARCHIVED"

formatenum

One of the following:

"TOOL_STATUS_UNSPECIFIED"

"TOOL_STATUS_AVAILABLE"

"TOOL_STATUS_FILTERED"

"TOOL_STATUS_ARCHIVED"

requiresApproval?: boolean

ToolSpecConfig { http, mcp }

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: "GET" | "POST" | "PUT" | 2 more

formatenum

One of the following:

"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