# 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](#1-what-it-does).
2. [Name it in `tools`](#2-name-it-in-tools).
3. [Choose what is deferred](#3-choose-what-is-deferred).
4. [Read what it bills on](#4-read-what-it-bills-on).

This page is one helper. The list of helpers, and how the charge adds up, sit in [Helpers](/docs/helpers). Your own functions are shown in [Tools and function calling](/docs/tools).

## 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.

| | |
|---|---|
| Type | `opendunes:tool_search` |
| Routes | `/v1/responses` and `/v1/messages` |
| A step | one search |
| Steps | at most 30 a request |
| Bills on | tokens 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](/docs/tools) shows.

```python
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"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/responses";
const MODEL = "anthropic/claude-sonnet-4.5";
const PROMPT = "Is the olive oil in stock?";

const response = await fetch(ADDRESS, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    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,
      },
    ],
  }),
});
const answer = await response.json();

for (const item of answer.output) {
  if (item.type === "function_call") console.log(item.name, item.arguments);
}
console.log(answer.usage.cost);
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

const (
	address = "https://opendunes.com/v1/responses"
	model   = "anthropic/claude-sonnet-4.5"
	prompt  = "Is the olive oil in stock?"
	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
  }
]`
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")
	body, err := json.Marshal(map[string]any{
		"model": model,
		"input": prompt,
		"tools": json.RawMessage(tools),
	})
	if err != nil {
		panic(err)
	}
	req, err := http.NewRequest("POST", address, bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	var answer struct {
		Output []struct {
			Type      string `json:"type"`
			Name      string `json:"name"`
			Arguments string `json:"arguments"`
		} `json:"output"`
		Usage struct {
			Cost json.Number `json:"cost"`
		} `json:"usage"`
	}
	if err := json.NewDecoder(res.Body).Decode(&answer); err != nil {
		panic(err)
	}
	for _, item := range answer.Output {
		if item.Type == "function_call" {
			fmt.Println(item.Name, item.Arguments)
		}
	}
	fmt.Println(answer.Usage.Cost)
}
```

```bash cURL
ADDRESS="https://opendunes.com/v1/responses"
MODEL="anthropic/claude-sonnet-4.5"
PROMPT="Is the olive oil in stock?"

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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
      }
    ]
  }'
```

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 do | Because |
|---|---|
| add `"defer_loading": true` to each function you want withheld | a deferred function is hidden until a search returns it |
| keep your three to five most used functions loaded | the model reaches them without a search |
| leave the helper itself loaded | the helper cannot be deferred; deferring it is a `400` |
| leave `tool_choice` out, or set `auto` or `allowed_tools` | any 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.

| Parameter | Does |
|---|---|
| `max_results` | the 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.

<div class="dont">
<p>Don't defer the functions every request uses. The model searches for them each time and you pay a round trip for nothing.</p>
</div>

<div class="do">
<p>Defer the long tail of functions, and keep the few the model reaches first loaded.</p>
</div>
