API Reference

Tool Sets

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Tools

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

GET/v1/tool_sets/{toolSetId}/tools

Create a new tool

POST/v1/tool_sets/{toolSetId}/tools

Get a tool by ID

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

Update a tool

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

Delete a tool

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

ModelsExpand Collapse

ConfigHTTP = object { requestMethod, headers, path, 4 more }

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

formatenum

One of the following:

"GET"

"POST"

"PUT"

"PATCH"

"DELETE"

headers: optional map[string]

path: optional string

query: optional string

requestBodyContentType: optional string

requestBodyTemplate: optional string

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

toolName: optional 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 = object { toolDescription, toolName, toolTitle }

toolDescription: optional string

toolName: optional string

toolTitle: optional string

Tool = object { 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: optional string

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

labels: optional map[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: optional ConfigHTTP { requestMethod, headers, path, 4 more }

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

formatenum

One of the following:

"GET"

"POST"

"PUT"

"PATCH"

"DELETE"

headers: optional map[string]

path: optional string

query: optional string

requestBodyContentType: optional string

requestBodyTemplate: optional string

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

toolName: optional 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: optional ConfigMcp { toolDescription, toolName, toolTitle }

toolDescription: optional string

toolName: optional string

toolTitle: optional string

description: string

parameters: map[unknown]

status: "TOOL_STATUS_UNSPECIFIED" or "TOOL_STATUS_AVAILABLE" or "TOOL_STATUS_FILTERED" or "TOOL_STATUS_ARCHIVED"

formatenum

One of the following:

"TOOL_STATUS_UNSPECIFIED"

"TOOL_STATUS_AVAILABLE"

"TOOL_STATUS_FILTERED"

"TOOL_STATUS_ARCHIVED"

requiresApproval: optional boolean

info: optional ToolInfo { createdBy, toolSet }

createdBy: optional 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: optional string

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

labels: optional map[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" or "PROFILE_TYPE_API_KEY" or "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: optional string

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

name: optional string

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

toolSet: optional 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: optional string

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

labels: optional map[string]

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

ToolInfo = object { createdBy, toolSet }

createdBy: optional 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: optional string

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

labels: optional map[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" or "PROFILE_TYPE_API_KEY" or "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: optional string

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

name: optional string

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

toolSet: optional 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: optional string

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

labels: optional map[string]

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

ToolSpec = object { 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: optional ConfigHTTP { requestMethod, headers, path, 4 more }

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

formatenum

One of the following:

"GET"

"POST"

"PUT"

"PATCH"

"DELETE"

headers: optional map[string]

path: optional string

query: optional string

requestBodyContentType: optional string

requestBodyTemplate: optional string

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

toolName: optional 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: optional ConfigMcp { toolDescription, toolName, toolTitle }

toolDescription: optional string

toolName: optional string

toolTitle: optional string

description: string

parameters: map[unknown]

status: "TOOL_STATUS_UNSPECIFIED" or "TOOL_STATUS_AVAILABLE" or "TOOL_STATUS_FILTERED" or "TOOL_STATUS_ARCHIVED"

formatenum

One of the following:

"TOOL_STATUS_UNSPECIFIED"

"TOOL_STATUS_AVAILABLE"

"TOOL_STATUS_FILTERED"

"TOOL_STATUS_ARCHIVED"

requiresApproval: optional boolean

ToolSpecConfig = object { 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: optional ConfigHTTP { requestMethod, headers, path, 4 more }

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

formatenum

One of the following:

"GET"

"POST"

"PUT"

"PATCH"

"DELETE"

headers: optional map[string]

path: optional string

query: optional string

requestBodyContentType: optional string

requestBodyTemplate: optional string

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

toolName: optional 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: optional ConfigMcp { toolDescription, toolName, toolTitle }

toolDescription: optional string

toolName: optional string

toolTitle: optional string