JavaScript
import Cadenya from '@cadenya/cadenya';
const client = new Cadenya({
apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});
const response = await client.search.searchToolsOrToolSets({
workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
query: 'query',
});
console.log(response.agents);import os
from cadenya import Cadenya
client = Cadenya(
api_key=os.environ.get("CADENYA_API_KEY"), # This is the default and can be omitted
)
response = client.search.search_tools_or_tool_sets(
workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
query="query",
)
print(response.agents)package main
import (
"context"
"fmt"
"go.cadenya.com/cadenya-go"
"go.cadenya.com/cadenya-go/option"
)
func main() {
client := cadenya.NewClient(
option.WithAPIKey("My API Key"),
)
response, err := client.Search.SearchToolsOrToolSets(context.TODO(), cadenya.SearchSearchToolsOrToolSetsParams{
WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
Query: "query",
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.Agents)
}
require "cadenya"
cadenya = Cadenya::Client.new(api_key: "My API Key")
response = cadenya.search.search_tools_or_tool_sets(
workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
query: "query"
)
puts(response)cadenya search search-tools-or-tool-sets \
--api-key 'My API Key' \
--workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
--query querycurl --request GET \
--url https://api.cadenya.com/v1/workspaces/{workspaceId}/search/tools_or_tool_sets \
--header 'Authorization: Bearer <token>'<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/search/tools_or_tool_sets",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}HttpResponse<String> response = Unirest.get("https://api.cadenya.com/v1/workspaces/{workspaceId}/search/tools_or_tool_sets")
.header("Authorization", "Bearer <token>")
.asString();{
"tools": [
{
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"createdAt": "2023-11-07T05:31:56Z",
"externalId": "<string>",
"labels": {},
"updatedAt": "2023-11-07T05:31:56Z"
},
"spec": {
"description": "<string>",
"requiresApproval": true,
"parameters": {},
"config": {
"type": "http",
"http": {
"path": "<string>",
"query": "<string>",
"headers": {},
"requestBodyTemplate": "<string>",
"requestBodyContentType": "<string>"
}
},
"llmToolName": "<string>"
},
"info": {
"toolSet": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"createdAt": "2023-11-07T05:31:56Z",
"externalId": "<string>",
"labels": {},
"updatedAt": "2023-11-07T05:31:56Z"
},
"createdBy": {
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"externalId": "<string>",
"labels": {},
"createdAt": "2023-11-07T05:31:56Z"
},
"spec": {
"email": "<string>",
"name": "<string>"
}
},
"signature": "<string>"
}
}
],
"toolSets": [
{
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"createdAt": "2023-11-07T05:31:56Z",
"externalId": "<string>",
"labels": {},
"updatedAt": "2023-11-07T05:31:56Z"
},
"spec": {
"description": "<string>",
"adapter": {
"type": "mcp",
"mcp": {
"url": "<string>",
"headers": {},
"includeTools": {
"filters": [
{
"matcher": {
"type": "exact",
"exact": "<string>",
"caseSensitive": true
}
}
]
},
"excludeTools": {
"filters": [
{
"matcher": {
"type": "exact",
"exact": "<string>",
"caseSensitive": true
}
}
]
},
"toolApprovals": {
"type": "always",
"always": true
},
"justInTime": {
"enabled": true,
"failObjectiveOnToolListError": true
}
}
}
},
"info": {
"toolCount": 123,
"agentCount": 123,
"lastSync": "2023-11-07T05:31:56Z",
"createdBy": {
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"externalId": "<string>",
"labels": {},
"createdAt": "2023-11-07T05:31:56Z"
},
"spec": {
"email": "<string>",
"name": "<string>"
}
},
"availableTools": 123,
"omittedTools": 123
}
}
],
"agents": [
{
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"createdAt": "2023-11-07T05:31:56Z",
"externalId": "<string>",
"labels": {},
"updatedAt": "2023-11-07T05:31:56Z"
},
"spec": {
"description": "<string>",
"webhookEventsUrl": "<string>",
"systemPromptDataSchema": {},
"outputDefinition": {},
"enableEpisodicMemory": true,
"episodicMemoryTtl": 123
},
"info": {
"variationCount": 123,
"createdBy": {
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"externalId": "<string>",
"labels": {},
"createdAt": "2023-11-07T05:31:56Z"
},
"spec": {
"email": "<string>",
"name": "<string>"
}
}
}
}
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"@type": "<string>"
}
]
}Tool Search
Search tools and tool sets
Find a tool, a tool set, or an agent by name prefix. One query, three buckets of results.
GET
/
v1
/
workspaces
/
{workspaceId}
/
search
/
tools_or_tool_sets
JavaScript
import Cadenya from '@cadenya/cadenya';
const client = new Cadenya({
apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});
const response = await client.search.searchToolsOrToolSets({
workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
query: 'query',
});
console.log(response.agents);import os
from cadenya import Cadenya
client = Cadenya(
api_key=os.environ.get("CADENYA_API_KEY"), # This is the default and can be omitted
)
response = client.search.search_tools_or_tool_sets(
workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
query="query",
)
print(response.agents)package main
import (
"context"
"fmt"
"go.cadenya.com/cadenya-go"
"go.cadenya.com/cadenya-go/option"
)
func main() {
client := cadenya.NewClient(
option.WithAPIKey("My API Key"),
)
response, err := client.Search.SearchToolsOrToolSets(context.TODO(), cadenya.SearchSearchToolsOrToolSetsParams{
WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
Query: "query",
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", response.Agents)
}
require "cadenya"
cadenya = Cadenya::Client.new(api_key: "My API Key")
response = cadenya.search.search_tools_or_tool_sets(
workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
query: "query"
)
puts(response)cadenya search search-tools-or-tool-sets \
--api-key 'My API Key' \
--workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
--query querycurl --request GET \
--url https://api.cadenya.com/v1/workspaces/{workspaceId}/search/tools_or_tool_sets \
--header 'Authorization: Bearer <token>'<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/search/tools_or_tool_sets",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}HttpResponse<String> response = Unirest.get("https://api.cadenya.com/v1/workspaces/{workspaceId}/search/tools_or_tool_sets")
.header("Authorization", "Bearer <token>")
.asString();{
"tools": [
{
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"createdAt": "2023-11-07T05:31:56Z",
"externalId": "<string>",
"labels": {},
"updatedAt": "2023-11-07T05:31:56Z"
},
"spec": {
"description": "<string>",
"requiresApproval": true,
"parameters": {},
"config": {
"type": "http",
"http": {
"path": "<string>",
"query": "<string>",
"headers": {},
"requestBodyTemplate": "<string>",
"requestBodyContentType": "<string>"
}
},
"llmToolName": "<string>"
},
"info": {
"toolSet": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"createdAt": "2023-11-07T05:31:56Z",
"externalId": "<string>",
"labels": {},
"updatedAt": "2023-11-07T05:31:56Z"
},
"createdBy": {
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"externalId": "<string>",
"labels": {},
"createdAt": "2023-11-07T05:31:56Z"
},
"spec": {
"email": "<string>",
"name": "<string>"
}
},
"signature": "<string>"
}
}
],
"toolSets": [
{
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"createdAt": "2023-11-07T05:31:56Z",
"externalId": "<string>",
"labels": {},
"updatedAt": "2023-11-07T05:31:56Z"
},
"spec": {
"description": "<string>",
"adapter": {
"type": "mcp",
"mcp": {
"url": "<string>",
"headers": {},
"includeTools": {
"filters": [
{
"matcher": {
"type": "exact",
"exact": "<string>",
"caseSensitive": true
}
}
]
},
"excludeTools": {
"filters": [
{
"matcher": {
"type": "exact",
"exact": "<string>",
"caseSensitive": true
}
}
]
},
"toolApprovals": {
"type": "always",
"always": true
},
"justInTime": {
"enabled": true,
"failObjectiveOnToolListError": true
}
}
}
},
"info": {
"toolCount": 123,
"agentCount": 123,
"lastSync": "2023-11-07T05:31:56Z",
"createdBy": {
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"externalId": "<string>",
"labels": {},
"createdAt": "2023-11-07T05:31:56Z"
},
"spec": {
"email": "<string>",
"name": "<string>"
}
},
"availableTools": 123,
"omittedTools": 123
}
}
],
"agents": [
{
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"createdAt": "2023-11-07T05:31:56Z",
"externalId": "<string>",
"labels": {},
"updatedAt": "2023-11-07T05:31:56Z"
},
"spec": {
"description": "<string>",
"webhookEventsUrl": "<string>",
"systemPromptDataSchema": {},
"outputDefinition": {},
"enableEpisodicMemory": true,
"episodicMemoryTtl": 123
},
"info": {
"variationCount": 123,
"createdBy": {
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"externalId": "<string>",
"labels": {},
"createdAt": "2023-11-07T05:31:56Z"
},
"spec": {
"email": "<string>",
"name": "<string>"
}
}
}
}
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"@type": "<string>"
}
]
}One query, searched across everything an agent variation can be assigned: individual tools, whole tool sets, and other agents.
Despite the name, the response has three buckets.
The
Prefix-only is the thing to design around. Half-remembering a tool as
An empty
const results = await client.search.searchToolsOrToolSets({ workspaceId, query: 'Generate' });
console.log(results.tools?.length); // 8
console.log(results.toolSets?.length); // 0
console.log(results.agents?.length); // 0
results, err := client.Search.SearchToolsOrToolSets(ctx,
cadenya.SearchSearchToolsOrToolSetsParams{
WorkspaceID: cadenya.String(workspaceID),
Query: cadenya.String("Generate"),
})
fmt.Println(len(results.Tools)) // 8
fmt.Println(len(results.ToolSets)) // 0
fmt.Println(len(results.Agents)) // 0
results = cadenya.search.search_tools_or_tool_sets(workspace_id: workspace_id, query: "Generate")
puts results.tools&.length # 8
puts results.tool_sets&.length # 0
puts results.agents&.length # 0
curl "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/search/tools_or_tool_sets?query=Generate" \
-H "Authorization: Bearer ${CADENYA_API_KEY}"
agents bucket is there because an agent can be assigned to a variation as a sub-agent, which makes it a tool from the calling agent’s point of view.
Matching is a case-insensitive name prefix
All three buckets match a prefix of the resource name, folding case.?query=Generate → tools: 4 (GenerateFake, GenerateCurseWord, ...)
?query=generate → tools: 4 ← same result, folded
?query=enerate → tools: 0 ← prefix only, never a substring
?query=Faker → toolSets: 1, agents: 1
FakeGenerator finds nothing, because the name starts Generate.
A query containing a space matches nothing.
Faker MCP is the exact, full name of a tool set and returns zero results, and even Faker M returns zero, while Faker returns it. Search on a single word.query returns everything in the workspace, which is a reasonable way to populate a picker on first render.
Results are scoped to live tool sets. A tool whose tool set was deleted or archived no longer appears, so what you get back is assignable.
A tool result does not carry its parent tool set, though: info holds only a signature. Group results by tool set and you have to cross-reference.
What it is for
The intended flow is assignment. You are building a variation, you want to hand it a capability, and you do not remember whether that capability is one tool, a whole tool set, or a sub-agent.const results = await client.search.searchToolsOrToolSets({ workspaceId, query: 'Generate' });
// Assign exactly one of the three; type names which.
await client.agents.variations.addAssignment(agentId, variationId, {
workspaceId,
type: 'toolId',
toolId: results.tools![0].metadata.id,
// or type: 'toolSetId', toolSetId: results.toolSets[0].metadata.id
// or type: 'subAgentId', subAgentId: results.agents[0].metadata.id
});
addAssignment takes one target, a union whose type discriminator is the same three-way choice this endpoint returns. That symmetry is the whole design.
This endpoint has nothing to do with
tool_search, the tool an agent gets under progressive discovery. That one loads tools into a running objective by exact name. This one is for you, at configuration time.Related
Create a tool set
Where the tools this endpoint finds come from.
Agents and variations
Assigning a tool, a tool set, or a sub-agent to a variation.
Delegate to sub-agents
Why agents appear in a tool search.
Preventing tool bloat
The other
tool_search, the one the agent calls.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
NOTE: query is runtime-required (buf.validate min_len), but gnostic
does not propagate message-level schema required to GET query
parameters — overlay.yaml marks the parameter required instead.
Example:
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Query Parameters
⌘I