> For the complete documentation index, see [llms.txt](https://docs.biobox.io/guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.biobox.io/guide/how-to/ask-biobox-with-claude/tools/search-models.md).

# search\_models — Search reasoning models

Search reasoning models

## What it does

Find the right reasoning model(s) from a disease / entity / intent phrase — users describe a model by what it does or by an entity it ranks, not by its uuid. The entry point that turns free text into model uuids before reading reports or scores.

**When to use:** intent: a phrase like "which model ranks targets for ALS / RCC?" or "prioritize oncology targets" → ranks the org's models by how their name/description/concepts match the phrase; entity: a symbol/name like "which models is ERBB4 anchored/ranked in?" (a gene, or any graph node) → resolves it and returns the models that rank it, best-rank-first (one row per model); auto (default): mixed/unknown input — tries to resolve it as an entity first, else treats it as intent.

**When NOT to use:** enumerate ALL of the org's models (use list\_reasoning\_models); inspect one model's scoring criteria / weights (use get\_reasoning\_model); list a model's reports or read its ranked scores (use list\_reports / get\_report\_scores); cross-model rank of an entity you ALREADY have the uuid for (call where\_entity\_ranks directly).

**Parameters:**

* `query` — The free-text phrase: a disease/intent (intent mode) or an entity symbol/name, e.g. a gene (entity mode).
* `mode` — Optional: 'auto' (default — resolve as an entity first, else intent), 'intent' (text-match the org's models), or 'entity' (resolve the query to a graph node and rank the models it appears in).
* `includeArchived` — include archived (historical) reports when computing each model's bestRank + reportCount (entity mode; optional; default false — only current reports count toward 'best').

**Returns:** An object { query, mode, resolvedMode, resolvedEntity?, models, count, truncated, note? }. `resolvedMode` is which mode ran ('entity' or 'intent'); `count` is the number of matching models BEFORE the cap and `truncated` is true if the models list was capped (at 15). In INTENT mode each model has: modelId (pass to list\_reports / report tools), modelName, description, anchorConcept, returnsEntityType (each a { dbLabel, displayName } concept ref), textMatchScore (query↔metadata relevance, NOT a model score), whyMatched (which fields matched). In ENTITY mode `resolvedEntity` ({ uuid, displayName, dbLabels }) is the node that was anchored on, and each model has: modelId, modelName, anchorConcept ({ dbLabel, displayName }), bestRank, total, bestScore (raw weighted sum) + bestNormScore (0–1 within that report — keep both), bestReportId + bestReportName (the entity's best-rank report — drill into get\_evidence / get\_report\_scores with reportId), reportCount, whyMatched (' ranks #/ here'). `note` is set when entity mode could not resolve the query, or resolved it to >1 candidate (names the node anchored on).

## Parameters

| Parameter         | Type    | Required | Description                                                                                                                                                                                      |
| ----------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `query`           | string  | yes      | The free-text phrase: a disease/intent (intent mode) or an entity symbol/name, e.g. a gene (entity mode).                                                                                        |
| `mode`            | enum    | no       | Optional: 'auto' (default — resolve as an entity first, else intent), 'intent' (text-match the org's models), or 'entity' (resolve the query to a graph node and rank the models it appears in). |
| `includeArchived` | boolean | no       | include archived (historical) reports when computing each model's bestRank + reportCount (entity mode; optional; default false — only current reports count toward 'best').                      |

## Response

```ts
{
  query: string;
  mode: "auto" | "intent" | "entity";
  resolvedMode: "intent" | "entity";
  resolvedEntity?: {
    uuid: string;
    displayName: string | null;
    dbLabels: string[];
  } | undefined | null;
  models: Array<{
    modelId: string;
    modelName: string;
    description: string | null;
    anchorConcept: {
      dbLabel: string | null;
      displayName: string | null;
    } | null;
    returnsEntityType: {
      dbLabel: string | null;
      displayName: string | null;
    } | null;
    textMatchScore: number;
    whyMatched: string;
  } | {
    modelId: string | null;
    modelName: string | null;
    anchorConcept: {
      dbLabel: string | null;
      displayName: string | null;
    } | null;
    bestRank: number;
    total: number;
    bestScore: number | null;
    bestNormScore: number | null;
    bestReportId: string | null;
    bestReportName: string | null;
    reportCount: number;
    whyMatched: string;
  }>;
  count: number;
  truncated: boolean;
  note?: string | undefined;
}
```

## Example

```json
// search_models({"query":"ERBB4","mode":"entity"})
{
  "query": "ERBB4",
  "mode": "entity"
}
```

Response (arrays truncated):

```json
{
  "query": "ERBB4",
  "mode": "entity",
  "resolvedMode": "entity",
  "resolvedEntity": {
    "uuid": "ENSG00000178568",
    "displayName": "ERBB4",
    "dbLabels": [
      "Gene",
      "ProteinCoding"
    ]
  },
  "models": [
    {
      "modelId": "7oNxw84sOcCi0v8h2fn15",
      "modelName": "Neurodegenerative Target Prioritization 2",
      "anchorConcept": {
        "dbLabel": "Disease",
        "displayName": "Disease"
      },
      "bestRank": 1,
      "total": 44750,
      "bestScore": 1.1987416527906658,
      "bestNormScore": 0.3878177499422183,
      "bestReportId": "mbYRHvcGOSp4Wsl",
      "bestReportName": "ALS",
      "reportCount": 1,
      "whyMatched": "ERBB4 ranks #1/44750 here"
    },
    {
      "modelId": "Ok8nsoMnRLWiC_YByOslb",
      "modelName": "Neurodegenerative Target Prioritization + Pathways",
      "anchorConcept": {
        "dbLabel": "Disease",
        "displayName": "Disease"
      },
      "bestRank": 1,
      "total": 44750,
      "bestScore": 1.3274501206893674,
      "bestNormScore": 0.36858877328971584,
      "bestReportId": "CR-Ksa7pFW1SOnDyPQ0kd",
      "bestReportName": "ALS",
      "reportCount": 1,
      "whyMatched": "ERBB4 ranks #1/44750 here"
    },
    {
      "modelId": "d3wyAtDLSewvY90zVcrAP",
      "modelName": "Neurodegenerative Target Prioritization 3",
      "anchorConcept": {
        "dbLabel": "Disease",
        "displayName": "Disease"
      },
      "bestRank": 1,
      "total": 39542,
      "bestScore": 1.5162798625413438,
      "bestNormScore": 0.2552555043353279,
      "bestReportId": "3EIVH6mRrz3lQLu",
      "bestReportName": "ALS",
      "reportCount": 1,
      "whyMatched": "ERBB4 ranks #1/39542 here"
    },
    "… 8 more"
  ],
  "count": 11,
  "truncated": false,
  "note": "'ERBB4' matched 5+ candidates; anchored on ERBB4 [Gene, ProteinCoding]"
}
```