Create detect

Asks Kai (POST /v1/decisions) which skills and tools in the caller's org and project are relevant to a prompt, and optionally activates them automatically.

POST /v1/tool/detect

Tool → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/tool/detect`
Method	`POST`
Operation	`post_tool_detect`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Asks Kai (POST /v1/decisions) which skills and tools in the caller's org and project are relevant to a prompt, and optionally activates them automatically.

Each candidate skill and tool is posed as a typed boolean question over the prompt state in a single Kai decision pass, returning calibrated probabilities in [0, 1]. When autoActivate is true, recommended entries that are not yet enabled — and that the caller has authority to toggle — are activated in the caller's (org, project) scope and recorded on the audit trail.

Request

5 fields, body application/json (required).

Field	In	Type	Required	Description
`autoActivate`	body	boolean	—	AutoActivate switches on the recommended skills and tools that the caller is permitted to activate for the current org and project scope.
`maxSkills`	body	integer (int64)	—	MaxSkills bounds how many skills are returned (default 6, max 16).
`maxTools`	body	integer (int64)	—	MaxTools bounds how many callable tools are returned (default 8, max 32).
`prompt`	body	string	—	Prompt is the user message, task description, or conversation turn to evaluate against the organization's available skills and tools.
`threshold`	body	number (double)	—	Threshold is the minimum calibrated probability (0 to 1, default 0.55) a skill or tool must score to be recommended.

Response

Status	Body	Meaning
`200`	tool.detectResult	ok
`default`	problem-details	refused

200 body — 15 fields.

Field	In	Type	Always	Description
`activated`	body	string[]	—	Activated lists the tool and skill names that were newly switched on by this call when autoActivate was set.
`decisionId`	body	string	—	DecisionID is the decision identifier returned by POST /v1/decisions when the Kai service answered the batch.
`model`	body	string	—	Model is the decision model that evaluated the candidates (for example "kai" or a versioned "kai-<hash>").
`skills`	body	tool.detectRecommendation[]	—	Skills lists the recommended skills (skill_<name>), ordered from highest to lowest probability.
`skills[].activated`	body	boolean	—	Activated reports whether the candidate is switched on for the caller's org and project after processing autoActivate.
`skills[].description`	body	string	—	Description summarizes what the skill or tool does.
`skills[].name`	body	string	—	Name is the tool or skill identifier as reported by GET /v1/tool (for example "skill_dev", "skill_ui", or "github_create_issue").
`skills[].probability`	body	number (double)	—	Probability is the calibrated relevance probability in [0, 1] assigned to this candidate for the prompt.
`skills[].source`	body	string	—	Source names the provider that owns the entry: skill, mcp, connector, function, agent or zap-service.
`tools`	body	tool.detectRecommendation[]	—	Tools lists the recommended callable tools, ordered from highest to lowest probability.
`tools[].activated`	body	boolean	—	Activated reports whether the candidate is switched on for the caller's org and project after processing autoActivate.
`tools[].description`	body	string	—	Description summarizes what the skill or tool does.
`tools[].name`	body	string	—	Name is the tool or skill identifier as reported by GET /v1/tool (for example "skill_dev", "skill_ui", or "github_create_issue").
`tools[].probability`	body	number (double)	—	Probability is the calibrated relevance probability in [0, 1] assigned to this candidate for the prompt.
`tools[].source`	body	string	—	Source names the provider that owns the entry: skill, mcp, connector, function, agent or zap-service.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo tool detect

.ts

.py

.go

.rs

.java

import { Configuration, ToolApi } from 'hanzoai';

const api = new ToolApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postToolDetect({ autoActivate: false, maxSkills: 0 });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import ToolApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = ToolApi(client).post_tool_detect(auto_activate=False, max_skills=0)

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.ToolAPI.PostToolDetect(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, tool_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = tool_api::post_tool_detect(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.ToolApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new ToolApi(client).postToolDetect();

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

curl -X POST https://api.hanzo.ai/v1/tool/detect \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "autoActivate": false,
       "maxSkills": 0
     }'

MCP reaches tool through the tool tool, which names its 20 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_tools"
         }
       }
     }'

Tool API · All Hanzo APIs · Interactive reference

Was this page useful?

Broken link or missing step? Drop it in #docs on Discord or open a PR.

PreviousCreate call NextCreate servers