JavaScript
Tool Sets
Create a tool set
Point a tool set at an MCP server, an OpenAPI spec, an HTTP API, or nothing at all. Cadenya syncs the tools it finds.
POST
JavaScript
A tool set is a collection of tools that share one provider. You supply an adapter, Cadenya discovers the tools behind it, and any agent variation you assign the set to can call them.
The request has two required fields,
The call returns immediately with
Three event types:
Read the secret back and
Match on
Four fields are required on a tool spec:
That unlocks two patterns. Human in the loop: park the call, show it to a person, submit their answer. Reverse harness: run the tool on your own infrastructure, inside your VPC, and report the result back. Cadenya never needs a route into your network.
Set
Archiving stops the sync, hides the set from lists, and pulls its tools from objectives, while leaving variation assignments and history intact. Delete refuses to run while the set is assigned to a variation. Individual tools follow the same idea with
metadata and spec, and the whole story lives in spec.adapter.
Pick an adapter
Four kinds. Set exactly one.The adapter is a discriminated union:
type names the variant, and the key matching type carries the payload. Both are required, and the SDKs type it as a tagged union, so TypeScript narrows on type and Go offers one constructor per variant.state: STATE_ACTIVE. Discovery happens in the background, so info.toolCount reads 0 for a moment even when the provider has tools waiting.
Watch the sync
There is no public sync endpoint. Cadenya syncs when you create or update the adapter. Synced MCP sources and OpenAPI specifications fetched by URL also refresh hourly. The only way to know a sync landed is the event stream.syncStarted, syncCompleted (carries toolsSynced), and syncFailed (carries message and errorType). Poll listEvents after a create when your setup script needs to block until the tools exist. info.lastSync gives you the timestamp of the most recent successful sync (it is omitted until one lands). info returns on every read; includeInfo is a no-op on tool sets.
Keep secrets out of the request
Adapter headers take${SECRET_NAME} placeholders. Cadenya resolves them at call time and the plaintext never comes back on a read.
spec.value is an empty string. Names resolve in order: objective secrets, then tool set secrets, then workspace secrets. The narrowest scope wins, which is how a per-user token overrides a service credential for one run.
Filter what syncs
MCP and OpenAPI adapters takeincludeTools and excludeTools. A filter is a list of attribute matchers joined by OPERATOR_AND or OPERATOR_OR.
ATTRIBUTE_NAME, ATTRIBUTE_TITLE, or ATTRIBUTE_DESCRIPTION. The matcher is its own union: type picks exact, contains, startsWith, endsWith, or regex, the matching key carries the string, and caseSensitive rides alongside. toolApprovals puts every synced tool behind human approval, either always or for the subset an only filter selects.
Filters apply on every sync, not once. Restore a tool the filter excludes and the next sync omits it again.
Define tools by hand
Anhttp or bare tool set starts empty. Create tools on it with spec.config naming the same adapter kind as the parent set.
description, parameters (a JSON Schema), requiresApproval, and config. All four are enforced, so a misspelled inputSchema or a missing config is a 400 rather than a tool the agent can never call correctly.
The response adds llmToolName, a cleaned-up name Cadenya derives for the model: issue_refund becomes IssueRefund.
Bare tools: your code is the runtime
A bare tool call fires nothing. The objective parks, the tool call sits atTOOL_CALL_EXECUTION_STATUS_WAITING_FOR_CONTENT, and your code answers it.
contentTimeout on the bare adapter to bound the wait. Leave it unset and the call waits 24 hours, then resolves on its own with a synthesized system result saying no content arrived. The objective keeps going either way.
Lifecycle
Tool sets are createdSTATE_ACTIVE and archive rather than delete when they are still in use.
omit and restore: an omitted tool stays in the set but no agent sees it.
Next steps
Connect an MCP server
The hands-on lesson, from server URL to an agent calling the tools.
Import an OpenAPI spec
Turn an existing REST API into a tool set, one operation at a time.
Approve a tool call
Park a dangerous call, ask a person, then let the objective continue.
Store and use secrets
Where
${SECRET_NAME} resolves from, and which scope wins.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Workspace ID.
Example:
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Body
application/json
Response
OK
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
The current lifecycle state of the tool set. Output only. Tool sets are created STATE_ACTIVE; use the :archive and :unarchive actions to transition between states.
Available options:
STATE_UNSPECIFIED, STATE_ACTIVE, STATE_ARCHIVED Tool set information