Tool Picker

POST https://cloud.ratel.sh/v1/tools/pick answers which of your project's tools an agent should call for a query.

You send only the query. Tool Picker reads the catalog your SDK already syncs to Cloud, so there is nothing to upload.

Pick a tool

curl -s https://cloud.ratel.sh/v1/tools/pick \
  -H "Authorization: Bearer $RATEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "leave a progress note on the task", "mode": "precise", "top_k": 3}'

const res = await fetch("https://cloud.ratel.sh/v1/tools/pick", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RATEL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "leave a progress note on the task", top_k: 3 }),
});
const { tools, confident } = await res.json();

import os, requests

res = requests.post(
    "https://cloud.ratel.sh/v1/tools/pick",
    headers={"Authorization": f"Bearer {os.environ['RATEL_API_KEY']}"},
    json={"query": "leave a progress note on the task", "top_k": 3},
)
best = res.json()["tools"][0]

{
  "mode": "precise",
  "tools": [
    {
      "id": "add_task_comment",
      "name": "add_task_comment",
      "description": "Comment on a task.",
      "score": 0.94
    },
    {
      "id": "update_task",
      "name": "update_task",
      "description": "Update a task.",
      "score": 0.04
    }
  ],
  "confident": true,
  "usage": { "candidates": 99, "questions": 1, "input_tokens": 9580 }
}

Modes

• Precise reads the whole catalog up to about 150 tools. Above that it reads the 25 most relevant.
• Exhaustive reads every tool, up to 2,000. On a catalog that fits one read, it is the same as Precise.
• Instant has no model in the loop. Use it for high-volume routing or a first pass.

On a real 99-tool production catalog, Precise matched the reference answer for 93.5% of queries, and had it in the top 5 for 98.4%.

Request

• query (required): what the agent wants to do, up to 2,000 characters.
• mode: instant, precise (default), or exhaustive.
• top_k: how many tools to return, 1 to 20 (default 5).

Response

• tools: best first. Each has the agent-facing description and a score.
• score: for Precise and Exhaustive, the model's probability that this is the tool to call next. For Instant, keyword relevance where the best match is 1.
• confident: true when the top pick clears the confidence bar calibrated against expert judges. Below it, treat tools as a shortlist. null for Instant.
• usage: tools considered, model questions asked, and input tokens read.

An empty tools list means nothing in the catalog matched.

Pricing

Precise and Exhaustive are billed by the tokens the model reads: €0.0441 per 1M tokens. A pick on a 100-tool catalog reads about 9,600 tokens; smaller catalogs cost less. Instant is free.

They spend your Tool Picker balance, separate from Embeddings.

Rate limits

Limits are per project, per minute.

A 429 carries Retry-After in seconds.

Errors

Errors use the same envelope as Embeddings.

Earlier endpoint

POST /v1/pick still works with its original request and response shape. It answers with a Deprecation header. Move to /v1/tools/pick.