Agentic Architectures

Catalogue / Tools & Action

Tool Retrieval

The agent searches a tool index and loads only what it needs

Shape
loop
Model calls
1 + searches (often 1 or 2) + tool rounds (typically 2 to 5)
Latency
medium
Complexity
medium

Also known as Tool search, Deferred tool loading, RAG-MCP

1

What if the agent has hundreds of tools to choose from?

Tool definitions stay in an index, outside the prompt. The agent starts with one search tool. When it needs a capability it describes it, the search returns the few tools that match, and only those definitions are loaded. From there it calls them as in Tool Use.

You may need it if

  • Tool definitions fill a large part of the prompt before the user has typed anything.
  • The agent picks the wrong one of two tools with similar names or descriptions.
  • Each integration you connect makes every request heavier, whether the request uses it or not.
2

When is searching for tools not worth the extra step?

Use it when

  • The catalogue holds dozens to thousands of tools and each task touches only a few of them.
  • Tools come from several servers or teams, and the list changes without anyone rewriting the prompt.
  • Every tool has a description that says what it does in the words a user would use.

Avoid it when

  • The agent has a handful of tools and uses most of them in every session. List them in the prompt.
    Use Tool Use instead
  • Each request belongs to one of a few known domains, each with its own fixed tool set. Classify once and send it to the agent that owns that set.
    Use Meta-Controller instead
  • What must be found and reused is a tested recipe for a whole task that the agent wrote on an earlier run, not a single tool.
    Use Skill Library instead
  • The first useful call must start at once. The search adds a round before it.

What it costs

Model calls
1 + searches (often 1 or 2) + tool rounds (typically 2 to 5)
Latency
medium
Complexity
medium
3

How do the right tool definitions reach the agent?

A tool loop with a search in front. The agent queries the tool index, the best matches are loaded as full definitions, and it calls them through the usual check. It can search again when a new need appears. A simpler variant searches once on the task, before the agent starts.

describes whatit needsbest matches loadedtool callloaded tool,rounds leftrejectedwith thereasontool resultfinal answerround limitreachedTask: The request or question. No tool list comes with it: the agent starts with the search tool only.TaskAgent: Describes a capability it lacks, or calls a loaded tool, or gives the final answer.AgentTool search: Matches the agent's query against tool names and descriptions and returns the few best definitions in full.Tool searchTool index: Every tool's name, description and arguments, kept outside the prompt and updated when tools are added or changed.Tool indexCall allowed?: Checks the call names a loaded tool with sensible arguments, and counts the rounds used.Call allowed?Loaded tools: The tools whose definitions were loaded. The harness runs them with your credentials and returns a short result.Loaded toolsAnswer: The final reply, with the searches made, the tools loaded and the calls with their results.Answer
  1. Step 1 of 6

    The agent starts with one tool

    The request is "Record a payment of 240 euros from customer 812". Four hundred tools are connected, but the agent's prompt holds only the search. It cannot call a tool it has not loaded.

  2. Step 2 of 6

    It searches for a capability

    The agent asks the search for "record a customer payment". The query is matched against the descriptions in the index. A tool named ledger_post comes first, because its description says it records payments.

  3. Step 3 of 6

    The matches are loaded

    The three best definitions enter the agent's context in full, with their arguments and an example. The other 397 stay out. From now on the agent can call these three.

  4. Step 4 of 6

    The call goes through the usual check

    The agent calls ledger_post with the customer and the amount. Plain code and a checker confirm that the tool is loaded, the arguments are complete and rounds remain. A bad call goes back with the reason.

  5. Step 5 of 6

    A new need, a new search

    The tool confirms the entry. The agent now wants to send a receipt and none of its three tools does that, so it searches again, for "email a receipt to a customer".

  6. Step 6 of 6

    The agent answers, or time runs out

    The final answer leaves with the searches, the tools loaded and the calls made. If the round limit is hit first, the run ends anyway and the answer says it is incomplete.

What each part does
Task
The request or question. No tool list comes with it: the agent starts with the search tool only.
Agent
Describes a capability it lacks, or calls a loaded tool, or gives the final answer.
Tool search
Matches the agent's query against tool names and descriptions and returns the few best definitions in full.
Tool index
Every tool's name, description and arguments, kept outside the prompt and updated when tools are added or changed.
Call allowed?
Checks the call names a loaded tool with sensible arguments, and counts the rounds used.
Loaded tools
The tools whose definitions were loaded. The harness runs them with your credentials and returns a short result.
Answer
The final reply, with the searches made, the tools loaded and the calls with their results.
  • Agent → Tool search: describes what it needs
  • Tool index → Tool search: names and descriptions
  • Tool search → Agent: best matches loaded
  • Agent → Call allowed?: tool call
  • Call allowed? → Loaded tools: loaded tool, rounds left
  • Call allowed? → Agent: rejected with the reason
  • Loaded tools → Agent: tool result
  • Agent → Answer: final answer
  • Call allowed? → Answer: round limit reached

Where it connects

Entry
task
TaskQuestion

A request or question for one agent. The tool index is already built. No tool list travels with the task, only the limits on searches and calls.

Exit
answer
AnswerOutcome

When: The agent gives a final answer, or the round limit is reached.

The final reply, each search with the tools it loaded, the tool calls with their results, and a flag saying whether the round limit cut the run short.

Memory kept between runs
index
Procedure

One entry per tool, with its name, a description of what it does, its arguments and an example call. Maintained outside the run and searched on names and descriptions.

4

What do I ask my assistant to set up?

The agents to launch

Tool agent

Answer the task. You start with one tool, the tool search. When you need a capability, search for it by describing what it should do, not by guessing a name. Then call one loaded tool per turn with complete arguments, or give your final answer. If a search finds nothing useful, rephrase it once, then say what is missing.

Sees: The task, the search tool, the definitions loaded so far, and every call and result. Not the rest of the catalogue or the credentials.

Call checker

Check one proposed tool call. Reject it if the tool has not been loaded by a search, an argument is missing or malformed, or it repeats an earlier call with the same arguments. Give a one-line reason. Do not judge whether the task is solved.

Sees: The definitions of the loaded tools, the proposed call and the previous calls. Not the agent's conversation.

A prompt you can paste

Works with any assistant that can launch sub-agents. It contains the agents, the procedure and the stop rule above.

Framework-agnostic prompt
You are the orchestrator of a multi-agent workflow that follows the "Tool Retrieval" architecture.
Launch every agent listed below as a separate sub-agent with its own context. Give each agent only the context stated for it. Do not do an agent's work yourself. If you cannot launch sub-agents, play each agent in a clearly separated turn and never let it use what is withheld from it.

# Task
[Describe your task here]

# Tool Retrieval
The agent searches a tool index and loads only what it needs.
Input: the task above. It must provide: A request or question for one agent. The tool index is already built. No tool list travels with the task, only the limits on searches and calls. If something essential is missing, ask for it before starting.

Agents to launch:
- Tool agent: Answer the task. You start with one tool, the tool search. When you need a capability, search for it by describing what it should do, not by guessing a name. Then call one loaded tool per turn with complete arguments, or give your final answer. If a search finds nothing useful, rephrase it once, then say what is missing.
  Context for this agent: The task, the search tool, the definitions loaded so far, and every call and result. Not the rest of the catalogue or the credentials.
- Call checker: Check one proposed tool call. Reject it if the tool has not been loaded by a search, an argument is missing or malformed, or it repeats an earlier call with the same arguments. Give a one-line reason. Do not judge whether the task is solved.
  Context for this agent: The definitions of the loaded tools, the proposed call and the previous calls. Not the agent's conversation.

Procedure:
1. Write for every tool a description that says what it does in a user's words, with its arguments and an example call. Index the names and descriptions.
2. Build the search. Given a query, it returns the 3 best matching definitions in full. Start with keyword matching and add embeddings if the right tool is often missed.
3. Keep the few tools that almost every run uses loaded from the start. Leave all the others in the index.
4. Launch the tool agent on the task with the search tool and the always-loaded tools only.
5. On a search, add the returned definitions to the tools the agent can call. On a tool call, launch the call checker. If it allows, run the tool and return the result. If not, return the reason.
6. Count rounds, searches included. After 8 rounds, stop and ask the agent for its best final answer with what it has.

Stop rule: Stop when the agent gives a final answer, or after 8 rounds, searches and tool calls together, whichever comes first. At the limit, ask once for a final answer and mark it incomplete.

Exit:
- `answer`, when: The agent gives a final answer, or the round limit is reached. Deliver: The final reply, each search with the tools it loaded, the tool calls with their results, and a flag saying whether the round limit cut the run short.

# Final deliverable
The final answer, then each search with the tools it loaded, each tool call with its arguments and a one-line summary of its result, and whether the round limit was reached.

The same thing in code

LangGraph, python, package langgraph
import operator
from typing import Annotated, TypedDict

from langchain.chat_models import init_chat_model
from langchain_core.messages import AIMessage, AnyMessage, HumanMessage, SystemMessage, ToolCall, ToolMessage
from langchain_core.tools import tool
from langgraph.graph import END, START, StateGraph
from langgraph.graph.message import add_messages
from pydantic import BaseModel

MAX_ROUNDS = 8  # searches and tool calls together
TOP_K = 3


@tool
def ledger_post(customer_id: str, amount: str) -> str:
    """Record a payment received from a customer. Example: ledger_post(customer_id="812", amount="240.00")"""
    return "stub: entry recorded"  # plug in your system


@tool
def send_receipt(customer_id: str) -> str:
    """Email the latest payment receipt to a customer. Example: send_receipt(customer_id="812")"""
    return "stub: receipt sent"  # plug in your system


CATALOGUE = {t.name: t for t in (ledger_post, send_receipt)}  # in practice, hundreds


def search_index(query: str) -> list[str]:
    # stub: word overlap on descriptions; plug in your keyword or embedding index
    words = set(query.lower().split())
    score = {n: len(words & set(t.description.lower().split())) for n, t in CATALOGUE.items()}
    return [n for n in sorted(score, key=lambda n: -score[n]) if score[n]][:TOP_K]


@tool
def search_tools(query: str) -> str:
    """Find tools by describing what they should do. Example: search_tools(query="record a customer payment")"""
    return ""  # schema only: the graph runs the search and loads the matches


AGENT = ("Answer the task. You start with one tool, the tool search. When you need a capability, search for "
         "it by describing what it should do. Then call one loaded tool per turn with complete arguments, "
         "or give your final answer. If a search finds nothing useful, rephrase once, then say what is missing.")
CHECKER = ("Check one proposed tool call. Reject it if an argument is missing or malformed, or it repeats "
           "an earlier call with the same arguments. Give a one-line reason.")


class Verdict(BaseModel):
    allowed: bool
    reason: str


class State(TypedDict):
    messages: Annotated[list[AnyMessage], add_messages]
    loaded: Annotated[list[str], operator.add]
    log: Annotated[list[str], operator.add]
    approved: list[ToolCall]
    limit_hit: bool


model = init_chat_model("anthropic:claude-sonnet-5-5")
checker_model = model.with_structured_output(Verdict)


def last_ai(state: State) -> AIMessage:
    msg = state["messages"][-1]
    assert isinstance(msg, AIMessage)
    return msg


async def ask(state: State, *extra: AnyMessage) -> dict:
    # only the search tool and the definitions loaded so far are in the prompt
    bound = model.bind_tools([search_tools, *(CATALOGUE[n] for n in dict.fromkeys(state["loaded"]))])
    return {"messages": [*extra, await bound.ainvoke([SystemMessage(AGENT), *state["messages"], *extra])]}


async def agent(state: State) -> dict:
    return await ask(state)


async def check(state: State) -> dict:
    calls = last_ai(state).tool_calls
    if len(state["log"]) + len(calls) > MAX_ROUNDS:  # the gate: at most 8 rounds
        skipped = [ToolMessage("Not run: round limit reached.", tool_call_id=c["id"] or "") for c in calls]
        return {"limit_hit": True, "approved": [], "messages": skipped}
    approved, rejected = [], []
    for call in calls:
        if call["name"] != "search_tools":  # searches pass; real calls go to the checker
            rules = f"{call['name']} {CATALOGUE[call['name']].args}: {CATALOGUE[call['name']].description}"
            prompt = f"Tool:\n{rules}\n\nProposed: {call['name']} {call['args']}\n\nPrevious:\n" + "\n".join(state["log"])
            verdict = Verdict.model_validate(await checker_model.ainvoke([SystemMessage(CHECKER), HumanMessage(prompt)]))
            if not verdict.allowed:
                rejected.append(ToolMessage(f"Rejected: {verdict.reason}", tool_call_id=call["id"] or ""))
                continue
        approved.append(call)
    return {"approved": approved, "messages": rejected}


async def tools(state: State) -> dict:
    results, log, loaded = [], [], []
    for call in state["approved"]:
        if call["name"] == "search_tools":
            found = search_index(str(call["args"].get("query", "")))
            loaded += found  # their full definitions are bound on the next agent turn
            output = "Loaded: " + ", ".join(found) if found else "No tool matches. Rephrase once."
        else:
            output = str(await CATALOGUE[call["name"]].ainvoke(call["args"]))
        results.append(ToolMessage(output, tool_call_id=call["id"] or ""))
        log.append(f"{call['name']} {call['args']} -> {output[:120]}")
    return {"messages": results, "log": log, "loaded": loaded}


async def final(state: State) -> dict:
    return await ask(state, HumanMessage("Round limit reached. Give your best final answer now."))


def after_check(state: State) -> str:
    return "final" if state["limit_hit"] else "tools" if state["approved"] else "agent"


builder = StateGraph(State)
for name, node in {"agent": agent, "check": check, "tools": tools, "final": final}.items():
    builder.add_node(name, node)
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", lambda s: "check" if last_ai(s).tool_calls else END, ["check", END])
builder.add_conditional_edges("check", after_check, ["tools", "agent", "final"])
builder.add_edge("tools", "agent")
builder.add_edge("final", END)
graph = builder.compile()


async def run(task: str) -> dict:
    state = await graph.ainvoke(
        {"messages": [HumanMessage(task)], "loaded": [], "log": [], "approved": [], "limit_hit": False},
        {"recursion_limit": 40},
    )
    return {"answer": state["messages"][-1].text, "loaded": state["loaded"], "calls": state["log"], "incomplete": state["limit_hit"]}

The model can only name tools that are bound, so an unloaded tool cannot be called. Replace search_index with your real index and give write tools such as these their own gate.

Claude Agent SDK, python, package claude-agent-sdk
import json
from typing import Any

from claude_agent_sdk import (
    AgentDefinition, ClaudeAgentOptions, PermissionResultAllow, PermissionResultDeny,
    ResultMessage, ToolPermissionContext, create_sdk_mcp_server, query, tool,
)
from pydantic import BaseModel

MAX_ROUNDS = 8  # searches and tool calls together
TOP_K = 3
SEARCH, CALL = "mcp__catalogue__search_tools", "mcp__catalogue__call_tool"

# the index: in practice hundreds of entries from many servers, with an embedding or keyword search
CATALOGUE = {
    "ledger_post": 'Record a payment received from a customer. Arguments: {"customer_id": str, "amount": str}',
    "send_receipt": 'Email the latest payment receipt to a customer. Arguments: {"customer_id": str}',
}


async def execute(name: str, arguments: dict[str, Any]) -> str:
    return f"stub: {name} done"  # plug in your systems


AGENTS = {
    "tool-agent": AgentDefinition(
        description="Answers the task with tools it finds through the tool search.",
        prompt="Answer the task. You start with search_tools. When you need a capability, search for it by "
               "describing what it should do. Then run one found tool per turn with call_tool, giving its "
               "name and its arguments as JSON, or give your final answer. If a search finds nothing "
               "useful, rephrase once, then say what is missing.",
        tools=[SEARCH, CALL],
    ),
    "call-checker": AgentDefinition(
        description="Allows or rejects one proposed tool call.",
        prompt="Check one proposed tool call. Reject it if an argument is missing or malformed, or it "
               "repeats an earlier call with the same arguments. Give a one-line reason.",
    ),
}


class Verdict(BaseModel):
    allowed: bool
    reason: str


async def result_of(prompt: str, options: ClaudeAgentOptions) -> ResultMessage:
    async for msg in query(prompt=prompt, options=options):
        if isinstance(msg, ResultMessage):
            return msg
    raise RuntimeError("no result")


async def run(task: str) -> dict:
    loaded: list[str] = []
    log: list[str] = []
    limit_hit = False

    @tool("search_tools", 'Find tools by describing what they should do. Example: {"query": "record a customer payment"}', {"query": str})
    async def search_tools(args: dict[str, Any]) -> dict[str, Any]:
        words = set(args["query"].lower().split())  # stub: word overlap on descriptions
        score = {n: len(words & set(d.lower().split())) for n, d in CATALOGUE.items()}
        found = [n for n in sorted(score, key=lambda n: -score[n]) if score[n]][:TOP_K]
        loaded.extend(n for n in found if n not in loaded)
        log.append(f"search {args['query']!r} -> {found}")
        # only now do these definitions enter the agent's context
        text = "\n".join(f"{n}: {CATALOGUE[n]}" for n in found) or "No tool matches. Rephrase once."
        return {"content": [{"type": "text", "text": text}]}

    @tool("call_tool", "Run a tool found by search_tools.", {"name": str, "arguments_json": str})
    async def call_tool(args: dict[str, Any]) -> dict[str, Any]:
        output = await execute(args["name"], json.loads(args["arguments_json"]))
        log.append(f"{args['name']} {args['arguments_json']} -> {output[:120]}")
        return {"content": [{"type": "text", "text": output}]}

    async def gate(name: str, args: dict[str, Any], ctx: ToolPermissionContext) -> PermissionResultAllow | PermissionResultDeny:
        nonlocal limit_hit
        if name not in (SEARCH, CALL):
            return PermissionResultDeny(message=f"{name} is not available.")
        if len(log) >= MAX_ROUNDS:  # the gate: at most 8 rounds
            limit_hit = True
            return PermissionResultDeny(message="Round limit reached: give your best final answer now.")
        if name == SEARCH:
            return PermissionResultAllow()
        if args.get("name") not in loaded:
            return PermissionResultDeny(message="That tool is not loaded. Search for it first.")
        # the checker runs in its own session: the loaded definition and the calls only
        check = await result_of(
            "Use the call-checker agent on this call and return its verdict.\n\n"
            f"Tool:\n{args['name']}: {CATALOGUE[args['name']]}\n\nProposed arguments: {args.get('arguments_json')}\n\n"
            "Previous calls:\n" + "\n".join(log),
            ClaudeAgentOptions(agents=AGENTS, allowed_tools=["Agent"],
                               output_format={"type": "json_schema", "schema": Verdict.model_json_schema()}),
        )
        verdict = Verdict.model_validate(check.structured_output)
        return PermissionResultAllow() if verdict.allowed else PermissionResultDeny(message=f"Rejected: {verdict.reason}")

    options = ClaudeAgentOptions(
        agents=AGENTS,
        mcp_servers={"catalogue": create_sdk_mcp_server("catalogue", tools=[search_tools, call_tool])},
        allowed_tools=["Agent"],  # the two tools are not pre-approved, so each use reaches the gate
        can_use_tool=gate,
    )
    answer = await result_of(f"Use the tool-agent agent on this task and return its answer:\n\n{task}", options)
    return {"answer": answer.result, "loaded": loaded, "calls": log, "incomplete": limit_hit}

The catalogue sits behind two fixed tools, search and call, so no definition enters the context before a search returns it. Replace the word-overlap stub with your real index.

OpenAI Agents SDK, python, package openai-agents
import json
from dataclasses import dataclass, field

from agents import (
    Agent, RunContextWrapper, Runner, ToolGuardrailFunctionOutput, ToolInputGuardrailData,
    function_tool, tool_input_guardrail,
)
from pydantic import BaseModel

MAX_ROUNDS = 8  # searches and tool calls together
TOP_K = 3

# the index: in practice hundreds of entries from many servers, with an embedding or keyword search
CATALOGUE = {
    "ledger_post": 'Record a payment received from a customer. Arguments: {"customer_id": str, "amount": str}',
    "send_receipt": 'Email the latest payment receipt to a customer. Arguments: {"customer_id": str}',
}


async def execute(name: str, arguments: dict) -> str:
    return f"stub: {name} done"  # plug in your systems


class Verdict(BaseModel):
    allowed: bool
    reason: str


@dataclass
class Session:
    loaded: list[str] = field(default_factory=list)
    log: list[str] = field(default_factory=list)
    limit_hit: bool = False


checker = Agent(
    name="Call checker",
    instructions="Check one proposed tool call. Reject it if the tool is not among the loaded ones, an "
                 "argument is missing or malformed, or it repeats an earlier call with the same "
                 "arguments. Give a one-line reason.",
    output_type=Verdict,
)


@tool_input_guardrail
async def check_call(data: ToolInputGuardrailData) -> ToolGuardrailFunctionOutput:
    session: Session = data.context.context
    if len(session.log) >= MAX_ROUNDS:  # the gate: at most 8 rounds
        session.limit_hit = True
        return ToolGuardrailFunctionOutput.reject_content("Round limit reached: give your best final answer now.")
    if data.context.tool_name == "search_tools":
        return ToolGuardrailFunctionOutput.allow()
    # the checker sees the loaded definitions and the calls, not the agent's conversation
    rules = "\n".join(f"{n}: {CATALOGUE[n]}" for n in session.loaded) or "(none)"
    prompt = f"Loaded tools:\n{rules}\n\nProposed: {data.context.tool_arguments}\n\nPrevious calls:\n" + "\n".join(session.log)
    verdict = (await Runner.run(checker, prompt)).final_output_as(Verdict)
    if not verdict.allowed:
        return ToolGuardrailFunctionOutput.reject_content(f"Rejected: {verdict.reason}")
    return ToolGuardrailFunctionOutput.allow()


@function_tool(tool_input_guardrails=[check_call])
def search_tools(ctx: RunContextWrapper[Session], query: str) -> str:
    """Find tools by describing what they should do. Example: query="record a customer payment"."""
    words = set(query.lower().split())  # stub: word overlap on descriptions
    score = {n: len(words & set(d.lower().split())) for n, d in CATALOGUE.items()}
    found = [n for n in sorted(score, key=lambda n: -score[n]) if score[n]][:TOP_K]
    ctx.context.loaded.extend(n for n in found if n not in ctx.context.loaded)
    ctx.context.log.append(f"search {query!r} -> {found}")
    # only now do these definitions enter the agent's context
    return "\n".join(f"{n}: {CATALOGUE[n]}" for n in found) or "No tool matches. Rephrase once."


@function_tool(tool_input_guardrails=[check_call])
async def call_tool(ctx: RunContextWrapper[Session], name: str, arguments_json: str) -> str:
    """Run a tool found by search_tools. Give its name and its arguments as a JSON object."""
    if name not in ctx.context.loaded:
        return "That tool is not loaded. Search for it first."
    output = await execute(name, json.loads(arguments_json))
    ctx.context.log.append(f"{name} {arguments_json} -> {output[:120]}")
    return output


tool_agent = Agent[Session](
    name="Tool agent",
    instructions="Answer the task. You start with search_tools. When you need a capability, search for it "
                 "by describing what it should do. Then run one found tool per turn with call_tool, or "
                 "give your final answer. If a search finds nothing useful, rephrase once, then say "
                 "what is missing.",
    tools=[search_tools, call_tool],
)


async def run(task: str) -> dict:
    session = Session()
    result = await Runner.run(tool_agent, task, context=session, max_turns=MAX_ROUNDS + 6)
    return {"answer": result.final_output, "loaded": session.loaded, "calls": session.log, "incomplete": session.limit_hit}

The catalogue sits behind two fixed tools, search and call, so no definition enters the context before a search returns it. Replace the word-overlap stub with your real index.

Vercel AI SDK, typescript, package ai
import { anthropic } from '@ai-sdk/anthropic';
import { isStepCount, Output, tool, ToolLoopAgent } from 'ai';
import { z } from 'zod';

const MAX_ROUNDS = 8; // searches and tool calls together
const TOP_K = 3;
const model = anthropic('claude-sonnet-5-5');

// the index: in practice hundreds of entries from many servers, with an embedding or keyword search
const CATALOGUE: Record<string, string> = {
  ledgerPost: 'Record a payment received from a customer. Arguments: { customerId: string, amount: string }',
  sendReceipt: 'Email the latest payment receipt to a customer. Arguments: { customerId: string }',
};
const execute = async (name: string, argumentsJson: string) => `stub: ${name} done with ${argumentsJson}`;

// stub: word overlap on descriptions
function searchIndex(query: string): string[] {
  const words = query.toLowerCase().split(/\s+/);
  const score = (name: string) => words.filter((w) => CATALOGUE[name].toLowerCase().includes(w)).length;
  return Object.keys(CATALOGUE).filter((n) => score(n) > 0).sort((a, b) => score(b) - score(a)).slice(0, TOP_K);
}

const checker = new ToolLoopAgent({
  model,
  instructions:
    'Check one proposed tool call. Reject it if an argument is missing or malformed, or it repeats ' +
    'an earlier call with the same arguments. Give a one-line reason.',
  output: Output.object({ schema: z.object({ allowed: z.boolean(), reason: z.string() }) }),
});

export async function run(task: string) {
  const loaded: string[] = [];
  const calls: string[] = [];
  let limitHit = false;

  // the gate: at most 8 rounds, searches included
  const roundsLeft = () => {
    if (calls.length >= MAX_ROUNDS) limitHit = true;
    return !limitHit;
  };

  const agent = new ToolLoopAgent({
    model,
    instructions:
      'Answer the task. You start with searchTools. When you need a capability, search for it by ' +
      'describing what it should do. Then run one found tool per turn with callTool, or give your ' +
      'final answer. If a search finds nothing useful, rephrase once, then say what is missing.',
    tools: {
      searchTools: tool({
        description: 'Find tools by describing what they should do. Example: { query: "record a customer payment" }',
        inputSchema: z.object({ query: z.string() }),
        execute: async ({ query }) => {
          if (!roundsLeft()) return 'Not run: round limit reached. Give your best final answer now.';
          const found = searchIndex(query);
          for (const name of found) if (!loaded.includes(name)) loaded.push(name);
          calls.push(`search "${query}" -> ${found.join(', ')}`);
          // only now do these definitions enter the agent's context
          return found.map((n) => `${n}: ${CATALOGUE[n]}`).join('\n') || 'No tool matches. Rephrase once.';
        },
      }),
      callTool: tool({
        description: 'Run a tool found by searchTools. Give its name and its arguments as a JSON object.',
        inputSchema: z.object({ name: z.string(), argumentsJson: z.string() }),
        execute: async ({ name, argumentsJson }) => {
          if (!roundsLeft()) return 'Not run: round limit reached. Give your best final answer now.';
          if (!loaded.includes(name)) return 'That tool is not loaded. Search for it first.';
          const { output } = await checker.generate({
            prompt: `Tool:\n${name}: ${CATALOGUE[name]}\n\nProposed arguments: ${argumentsJson}\n\nPrevious calls:\n${calls.join('\n')}`,
          });
          if (!output.allowed) return `Rejected: ${output.reason}`;
          const result = await execute(name, argumentsJson);
          calls.push(`${name} ${argumentsJson} -> ${result.slice(0, 120)}`);
          return result;
        },
      }),
    },
    prepareStep: async () => (limitHit ? { toolChoice: 'none' as const } : {}), // at the limit, answer only
    stopWhen: isStepCount(MAX_ROUNDS + 6),
  });

  const { text } = await agent.generate({ prompt: task });
  return { answer: text, loaded, calls, incomplete: limitHit };
}

The catalogue sits behind two fixed tools, search and call, so no definition enters the context before a search returns it. Replace the word-overlap stub with your real index.

Snippets are generated when the site is built and type-checked against the SDK versions listed in the repository. Treat them as a starting skeleton.

What goes wrong

  • A tool with a vague description is never found. Treat descriptions as part of the system and test that typical requests retrieve the right tool.
  • Near-duplicate tools confuse the search as the catalogue grows. Merge or rename them, and test retrieval again after each large addition.
  • When a search misses, the agent may conclude that the capability does not exist. Let it rephrase once and report what it looked for.
  • Loading ten matches per search rebuilds the bloat you removed. Keep the number of definitions returned small.
  • Retrieval does not make write tools safe. A call found by search needs the same gate as a call from a fixed list.

Chain it

Its result can feed

Source