Getting started: give your agent only the tools each turn needs

user message ─▶ your backend ──▶ POST /v1/context ──▶ ["refund_invoice", "get_customer_invoices", "find_customer", ...]
                     │                                         │
                     └──── your LLM call with only those tools ◀┘

pip install toolcue           # Python 3.10+, no dependencies
npm install toolcue           # Node 18+, no dependencies

export TOOLCUE_URL=...              # the base URL you were given
export TOOLCUE_TOKEN=...            # read token: per-turn calls
export TOOLCUE_ADMIN_TOKEN=...      # admin token: publishing

curl -X PUT "$TOOLCUE_URL/v1/agents/acme-billing/catalog" \
  -H "Authorization: Bearer $TOOLCUE_ADMIN_TOKEN" -H "Content-Type: application/json" \
  --data @examples/tool-selection/catalog.json

{"agentId": "acme-billing", "tools": 9, "edges": 5, "traces": 0,
 "edgesBySource": {"DECLARED": 4, "STATIC": 1, "TRACE": 0}}

{
  "name": "refund_invoice",
  "displayName": "Refund an invoice",
  "description": "Refund a paid invoice fully or partially.",
  "parameters": [
    {"name": "invoice_id", "description": "The invoice id, e.g. INV-1042", "dataType": "string", "required": true},
    {"name": "amount", "description": "Amount to refund; omit for a full refund", "dataType": "number", "required": false}
  ],
  "examples": ["give them their money back", "refund INV-1042"]
}

from toolcue import ToolcueClient, tools_from_definitions

toolcue = ToolcueClient()
toolcue.publish_catalog("acme-billing", tools_from_definitions(MY_TOOLS, extras={
    "find_customer": {"produces": ["customer_id"]},
    "ask_user": {"core": True},
}))

curl -X POST "$TOOLCUE_URL/v1/context" \
  -H "Authorization: Bearer $TOOLCUE_TOKEN" -H "Content-Type: application/json" \
  -d '{"agentId": "acme-billing",
       "message": "Refund the last invoice for Globex",
       "context": {"user": {"roles": ["agent"]}},
       "options": {"includePrompt": false}}'

{
  "agentId": "acme-billing",
  "turnType": "ACTION",
  "tools": [
    {"name": "refund_invoice",        "reason": "RETRIEVED",  "detail": "matched the turn"},
    {"name": "get_customer_invoices", "reason": "DEPENDENCY", "detail": "provides invoice_id for refund_invoice"},
    {"name": "find_customer",         "reason": "DEPENDENCY", "detail": "provides customer_id for get_customer_invoices"},
    {"name": "create_invoice",        "reason": "RETRIEVED",  "detail": "one of the best matches for a request"},
    {"name": "cancel_subscription",   "reason": "RERANKED",   "detail": "reranker"},
    {"name": "ask_user",              "reason": "CORE",       "detail": "always attached"}
  ],
  "resolvedParams": {},
  "timings": {"totalMs": 46.7}
}

{"agentId": "acme-billing",
 "message": "ok, move them to the scale plan",
 "history": [
   {"role": "user", "content": "what plan is Globex on?"},
   {"role": "assistant", "content": "Globex (cus_8812) is on growth.",
    "toolCalls": [{"name": "find_customer", "arguments": {"query": "Globex"},
                   "result": "{\"customer_id\": \"cus_8812\", \"plan\": \"growth\"}"}]}],
 "options": {"includePrompt": false}}

from toolcue import ToolcueClient

toolcue = ToolcueClient()
keys = toolcue.select_names("acme-billing", "Refund the last invoice for Globex", history=[], user={"roles": ["agent"]})
tools_for_this_turn = [t for t in MY_TOOLS if t["function"]["name"] in keys]

import { ToolcueClient } from "toolcue";

const toolcue = new ToolcueClient();
const keys = await toolcue.selectNames("acme-billing", "Refund the last invoice for Globex", [], { roles: ["agent"] });
const toolsForThisTurn = MY_TOOLS.filter((t) => keys.includes(t.function.name));

import os
from openai import OpenAI
from toolcue import ToolcueClient, tools_from_definitions

client, toolcue = OpenAI(), ToolcueClient()
TOOLS = [...]                                             # your {"type": "function", "function": {...}} list
BY_NAME = {t["function"]["name"]: t for t in TOOLS}
toolcue.publish_catalog("acme-billing", tools_from_definitions(TOOLS))    # at deploy time, not per turn

def answer(messages, user):
    keys = toolcue.select_names("acme-billing", messages[-1]["content"], history=to_toolcue_history(messages[:-1]), user=user)
    return client.chat.completions.create(
        model=os.environ["OPENAI_MODEL"],
        messages=messages,
        tools=[BY_NAME[k] for k in keys if k in BY_NAME],
    )

import anthropic
from toolcue import ToolcueClient, tools_from_definitions

client, toolcue = anthropic.Anthropic(), ToolcueClient()
TOOLS = [...]                                             # your {"name", "description", "input_schema"} list
BY_NAME = {t["name"]: t for t in TOOLS}
toolcue.publish_catalog("acme-billing", tools_from_definitions(TOOLS))

def answer(user_text, history, user):
    keys = toolcue.select_names("acme-billing", user_text, history=history, user=user)
    tools = [BY_NAME[k] for k in keys if k in BY_NAME]   # fixed for the whole turn
    messages = [{"role": "user", "content": user_text}]
    while True:
        response = client.messages.create(model="claude-opus-5-5", max_tokens=16000, tools=tools, messages=messages)
        if response.stop_reason != "tool_use":
            return response
        messages.append({"role": "assistant", "content": response.content})
        messages.append({"role": "user", "content": [
            {"type": "tool_result", "tool_use_id": b.id, "content": run_tool(b.name, b.input)}
            for b in response.content if b.type == "tool_use"]})

from langchain.agents import create_agent
from toolcue.langchain import ToolcueMiddleware, publish_tools

publish_tools("acme-billing", TOOLS, extras={"find_customer": {"produces": ["customer_id"]}})   # at deploy time

agent = create_agent("anthropic:claude-opus-5-5", tools=TOOLS,
                     middleware=[ToolcueMiddleware("acme-billing", user=lambda ctx: {"roles": ctx.roles})],
                     context_schema=Session)

import { generateText, stepCountIs } from "ai";
import { findToolsTool, selectTurn, toolcuePrepareStep } from "toolcue/ai-sdk";

const turn = await selectTurn("acme-billing", messages, { user: { roles: session.roles } });
const tools = { ...TOOLS, find_tools: findToolsTool(turn) };
const result = await generateText({ model, tools, messages, stopWhen: stepCountIs(10),
                                    prepareStep: toolcuePrepareStep(turn, tools) });

listed = await session.list_tools()
toolcue.publish_catalog("my-assistant", tools_from_definitions([t.model_dump() for t in listed.tools]))

keys = toolcue.select_names("my-assistant", user_text, history)
tools_for_model = [t for t in listed.tools if t.name in keys]

FIND_TOOLS = {"name": "find_tools",
              "description": "If none of your tools can do what the user asked, describe the task here to get more tools.",
              "input_schema": {"type": "object", "properties": {"task": {"type": "string"}}, "required": ["task"]}}

# in your tool loop, when the model calls find_tools:
found = toolcue.find_tools("acme-billing", block.input["task"], exclude=[t["name"] for t in tools], limit=3, user=user)
tools += [BY_NAME[t["name"]] for t in found["tools"] if t["name"] in BY_NAME]
result = "New tools available: " + ", ".join(t["name"] for t in found["tools"]) if found["tools"] else "No matching tool."