opendunes
Helpers · 3 min
Copy page ▾

Tool search

Keep a long list of your own tools out of the prompt, and let the model load a tool only when it needs it.

  1. What it does.
  2. Name it in tools.
  3. Choose what is deferred.
  4. Read what it bills on.

This page is one helperHelperA tool run for you when a model reaches for it mid-answer: a web search, a page read, a sandbox. Named opendunes:‹name›.More on Helpers →. The list of helpers, and how the charge adds up, sit in Helpers. Your own functions are shown in Tools and function calling.

1. What it does

Every function you send is read by the model as input, on every request. With many functions, that is many tokens before the model has done anything. Mark the functions you use rarely defer_loading: the model does not see them. When it needs one, it searches for it by a pattern that matches the name, the description and the arguments, the tools it finds are loaded, and it calls one on its next turn.

Typeopendunes:tool_search
Routes/v1/responses and /v1/messages
A stepone search
Stepsat most 30 a request
Bills ontokens only

On /v1/chat/completions, a request that names the helper is refused with a 400 and nothing runs.

2. Name it in tools

Souk Bot has two rarely used functions: a stock count and a delivery status. The sample defers both, names the helper beside them, and prints the call the model makes. Your code runs that call, as Tools and function calling shows.

import json
import os
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/responses"
MODEL = "anthropic/claude-sonnet-4.5"
PROMPT = "Is the olive oil in stock?"

body = {
    "model": MODEL,
    "input": PROMPT,
    "tools": [
        {"type": "opendunes:tool_search"},
        {
            "type": "function",
            "name": "stock_level",
            "description": "How many units of a product the shop holds.",
            "parameters": {
                "type": "object",
                "properties": {"product": {"type": "string"}},
                "required": ["product"],
            },
            "defer_loading": True,
        },
        {
            "type": "function",
            "name": "delivery_status",
            "description": "Where an order is on its way to the customer.",
            "parameters": {
                "type": "object",
                "properties": {"order": {"type": "string"}},
                "required": ["order"],
            },
            "defer_loading": True,
        },
    ],
}
request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(body).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    answer = json.load(response)

for item in answer["output"]:
    if item["type"] == "function_call":
        print(item["name"], item["arguments"])
print(answer["usage"]["cost"])

The answer is a 200. Name the helper by its type, opendunes:tool_search; any other spelling of the type is a 400.

3. Choose what is deferred

You doBecause
add "defer_loading": true to each function you want withhelda deferred function is hidden until a search returns it
keep your three to five most used functions loadedthe model reaches them without a search
leave the helper itself loadedthe helper cannot be deferred; deferring it is a 400
leave tool_choice out, or set auto or allowed_toolsany other value is a 400

The model writes the search as a pattern. It is matched without regard to case against each deferred function's name, its description, its argument names and their descriptions. A pattern longer than 200 characters, or one that cannot be matched, comes back to the model as an error and the request goes on.

Put this in the helper's parameters to change how many tools one search returns.

ParameterDoes
max_resultsthe most tools one search returns: 5 by default, up to 50

4. Read what it bills on

No charge beyond the model's tokens. The definitions of the functions you send are input tokens on every request, and a deferred one is left out of them. usage.cost carries the whole of it.

Each search is a round trip, and the tools it finds are read as input. A function the model uses on almost every request costs more to search for than to keep loaded.

Before the model starts, OpenDunes holds money from your wallet for the words and the answer. A search costs no money of its own, so the hold sets no step limit lower than yours: a request runs at most 30 steps, or the max_tool_calls you name. The helper runs no other model and no sandbox, so it has no spend cap.

Don't

Don't defer the functions every request uses. The model searches for them each time and you pay a round trip for nothing.

Do

Defer the long tail of functions, and keep the few the model reaches first loaded.