# Model search

Let a model look up which models fit a job, by what they read, what they write and how much they remember.

1. [What it does](#1-what-it-does).
2. [Name it in `tools`](#2-name-it-in-tools).
3. [Limit the results](#3-limit-the-results).
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).

## 1. What it does

The model asks the helper a question about the catalogue and reads the matches before it answers. An empty search browses the whole list. This is the helper to give an assistant that recommends a model, or that picks one for the next call it makes.

| | |
|---|---|
| Type | `opendunes:experimental__search_models` |
| Routes | `/v1/chat/completions`, `/v1/responses` and `/v1/messages` |
| A step | one search |
| Steps | at most 30 a request |
| Bills on | tokens only |

The helper is experimental. Its name may lose the `experimental__` prefix when it graduates, and a request that names the old spelling would then be refused.

## 2. Name it in `tools`

Souk Bot suggests a model to a builder. The sample lets the model search the catalogue up to three times and prints the answer and the charge.

```python
import json
import os
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/chat/completions"
MODEL = "anthropic/claude-sonnet-4.5"
PROMPT = "Which models read a picture and answer in text?"

body = {
    "model": MODEL,
    "messages": [{"role": "user", "content": PROMPT}],
    "tools": [
        {
            "type": "opendunes:experimental__search_models",
            "parameters": {"max_results": 5},
        }
    ],
    "max_tool_calls": 3,
}
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)

print(answer["choices"][0]["message"]["content"])
print(answer["usage"]["cost"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/chat/completions";
const MODEL = "anthropic/claude-sonnet-4.5";
const PROMPT = "Which models read a picture and answer in text?";

const response = await fetch(ADDRESS, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: MODEL,
    messages: [{ role: "user", content: PROMPT }],
    tools: [
      {
        type: "opendunes:experimental__search_models",
        parameters: { max_results: 5 },
      },
    ],
    max_tool_calls: 3,
  }),
});
const answer = await response.json();

console.log(answer.choices[0].message.content);
console.log(answer.usage.cost);
```

```go
package main

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

const (
	address = "https://opendunes.com/v1/chat/completions"
	model   = "anthropic/claude-sonnet-4.5"
	prompt  = "Which models read a picture and answer in text?"
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")
	body, err := json.Marshal(map[string]any{
		"model": model,
		"messages": []map[string]string{
			{"role": "user", "content": prompt},
		},
		"tools": []map[string]any{
			{
				"type":       "opendunes:experimental__search_models",
				"parameters": map[string]int{"max_results": 5},
			},
		},
		"max_tool_calls": 3,
	})
	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 {
		Choices []struct {
			Message struct {
				Content string `json:"content"`
			} `json:"message"`
		} `json:"choices"`
		Usage struct {
			Cost json.Number `json:"cost"`
		} `json:"usage"`
	}
	if err := json.NewDecoder(res.Body).Decode(&answer); err != nil {
		panic(err)
	}
	fmt.Println(answer.Choices[0].Message.Content)
	fmt.Println(answer.Usage.Cost)
}
```

```bash cURL
ADDRESS="https://opendunes.com/v1/chat/completions"
MODEL="anthropic/claude-sonnet-4.5"
PROMPT="Which models read a picture and answer in text?"

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "'"$PROMPT"'"
      }
    ],
    "tools": [
      {
        "type": "opendunes:experimental__search_models",
        "parameters": {
          "max_results": 5
        }
      }
    ],
    "max_tool_calls": 3
  }'
```

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

## 3. Limit the results

Put this in the helper's `parameters`.

| Parameter | Does |
|---|---|
| `max_results` | the most models one search returns: 5 by default, from 1 to 20 |

The model writes each search itself, and every field of it is optional.

| The model sends | Matches |
|---|---|
| `query` | free text against names, slugs and descriptions |
| `input_modalities` | models that read all of these: `text`, `image`, `file`, `audio`, `video` |
| `output_modalities` | models that write all of these, such as `text`, `image`, `embeddings`, `audio` |
| `min_context_length` | models that remember at least this many tokens |
| `series` | a family, such as `Claude`, `GPT` or `Gemini` |

Each match comes back to the model with its `id`, `name`, `description`, `context_length`, `input_modalities`, `output_modalities` and `series`, beside `total_results`, how many models fit, and `showing`, how many came back.

Check an `id` the model suggests in [Models](/models) before you send it as `model`. A request that names a model that is not on sale answers `404`.

## 4. Read what it bills on

No charge beyond the model's tokens. The matches the model reads are input tokens, so a higher `max_results` costs more input. `usage.cost` carries the whole of it.

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 leave <code>max_results</code> at its widest for a question one match answers. Every match is input on every later turn.</p>
</div>

<div class="do">
<p>Set <code>max_tool_calls</code> to the few searches the question needs, and check the model it names before you call it.</p>
</div>
