> 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-entities.md).

# search\_entities — Search entities by name

Search entities by name

Search entities by name

## What it does

Resolve a user-typed name or symbol (a gene, disease, drug, pathway, …) to ranked candidate graph nodes — returns candidates the agent disambiguates, NOT a single guess.

**When to use:** the user names an entity and you need its uuid before any entity-anchored tool (get\_entity, where\_entity\_ranks, get\_entity\_connections); resolving an ambiguous name (e.g. a symbol that hits a Gene node and several Events) — the tool returns candidates, not a guess.

**When NOT to use:** you already have the entity's uuid (use get\_entity); listing entity TYPES / classes rather than instances (use list\_entity\_types); finding a reasoning model rather than an entity (use list\_reasoning\_models / search\_models).

**Parameters:**

* `query` — the name or symbol the user typed (e.g. "ERBB4") — matched against node display names
* `limit` — max candidates to return (optional; default 10) — `total` still reports all hits
* `dbLabel` — optional graph label to scope the search to (e.g. "Gene") — a dbLabel from list\_entity\_types / get\_graph\_schema. Use when you already know the entity's TYPE to filter out other matches (e.g. drop Reactome Events / Transcripts). Note: the label-scoped backing op does not report whether more results exist, so `hasMore` is always false when scoped.

**Returns:** An object { candidates, total, hasMore, truncated }. Each candidate has: uuid (pass to entity-anchored tools — this is the key downstream tools consume), displayName, dbLabels (graph labels), and nodeID. Disambiguate via dbLabels: e.g. the Gene node carries \["Gene","ProteinCoding"] while a Reactome event carries \["Event"]. `total` is the number of candidates returned (= candidates.length, not the gateway's full hit count); `hasMore` is true if the gateway has more beyond this page (always false when scoped by dbLabel); `truncated` is true if the page was capped client-side. Pick the candidate whose dbLabels match the intended entity, then anchor on its uuid.

## Parameters

| Parameter | Type   | Required | Description                                                                                                                                                                                                                                                                                                                                                     |
| --------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`   | string | yes      | the name or symbol the user typed (e.g. "ERBB4") — matched against node display names                                                                                                                                                                                                                                                                           |
| `limit`   | number | no       | max candidates to return (optional; default 10) — `total` still reports all hits                                                                                                                                                                                                                                                                                |
| `dbLabel` | string | no       | optional graph label to scope the search to (e.g. "Gene") — a dbLabel from list\_entity\_types / get\_graph\_schema. Use when you already know the entity's TYPE to filter out other matches (e.g. drop Reactome Events / Transcripts). Note: the label-scoped backing op does not report whether more results exist, so `hasMore` is always false when scoped. |

## Response

```ts
{
  candidates: Array<{
    uuid: string;
    displayName: string | null;
    dbLabels: string[];
    nodeID: string | null;
  }>;
  total: number;
  hasMore: boolean;
  truncated: boolean;
}
```

## Example

```json
// search_entities({"query":"ERBB4"})
{
  "query": "ERBB4"
}
```

Response (arrays truncated):

```json
{
  "candidates": [
    {
      "uuid": "ENSG00000178568",
      "displayName": "ERBB4",
      "dbLabels": [
        "Gene",
        "ProteinCoding"
      ],
      "nodeID": "68419"
    },
    {
      "uuid": "R-HSA-9612593",
      "displayName": "ERBB4 binds DLG4",
      "dbLabels": [
        "Event"
      ],
      "nodeID": "4152893"
    },
    {
      "uuid": "R-HSA-1236398",
      "displayName": "ERBB4 binds NRGs or EGF-like ligands",
      "dbLabels": [
        "Event"
      ],
      "nodeID": "4092233"
    },
    "… 7 more"
  ],
  "total": 10,
  "hasMore": true,
  "truncated": false
}
```