> 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/find-guidance.md).

# find\_guidance — Find DB-authored query guidance

Find DB-authored query guidance

Find DB-authored query guidance

## What it does

Retrieve the organization's DB-authored guidance playbooks relevant to a question — matched by intent keywords and/or the concepts in play — so query building follows org-specific rules (e.g. how to handle single-cell differential expression).

**When to use:** at the start of building a query, to pick up any org guidance for this kind of question; when you have candidate concepts and want guidance tied to them.

**When NOT to use:** you want the org's GENERAL query-building rules — use get\_ql\_instructions; you want guidance for one specific concept only — use get\_concept\_guidance; you want reusable query templates — use list\_query\_templates.

**Parameters:**

* `intent` — the user's question or intent phrase — matched against each playbook's trigger keywords.
* `conceptDbLabels` — optional concept dbLabels in play (e.g. \["Disease", "CellType"]) to pull concept-scoped guidance.
* `kind` — optional filter: concept | subgraph | evidence | intent.

**Returns:** An object { playbooks, count }. Each playbook is { uuid, kind, title, instructions, triggers, conceptDbLabels, relationshipTypes, propertyUsages, subgraphUuids, groundingBxql, bxql, cypher, enabled }. Treat `conceptDbLabels`/`relationshipTypes` as REFERENCES to hydrate from the ontology (pull each concept's real properties and each relationship's valid endpoints/forQL from the schema tools), NOT snapshots. `propertyUsages` is an optional grounding-key hint (which Concept.property to filter on; defaults to displayName). `groundingBxql` is a narrower discovery path to run FIRST to enumerate the distinct grounding values, then inject them into `bxql`. `bxql` is a SCAFFOLD to adapt (inject grounded filters, add question-specific constraints), not a literal. `instructions` is the org's guidance to follow; `cypher` is an optional snippet. Newest playbooks first.

## Parameters

| Parameter         | Type   | Required | Description                                                                                        |
| ----------------- | ------ | -------- | -------------------------------------------------------------------------------------------------- |
| `intent`          | string | no       | the user's question or intent phrase — matched against each playbook's trigger keywords.           |
| `conceptDbLabels` | array  | no       | optional concept dbLabels in play (e.g. \["Disease", "CellType"]) to pull concept-scoped guidance. |
| `kind`            | enum   | no       | optional filter: concept \| subgraph \| evidence \| intent.                                        |

## Response

```ts
_(identity shaper — response = the handler result; see the tool source.)_
```

## Example

```json
// find_guidance({"intent":"single-cell differential expression","conceptDbLabels":["CellType"]})
{
  "intent": "single-cell differential expression",
  "conceptDbLabels": [
    "CellType"
  ]
}
```

Response (arrays truncated):

```json
{
  "playbooks": [
    {
      "uuid": "3hyIxPUQHozHNEVz7MEkg",
      "kind": "intent",
      "title": "Differentially expressed genes by disease (bulk, no cell type)",
      "instructions": "Use when the question asks for genes differentially expressed in a disease but does NOT mention a cell type. The bxql is a scaffold to adapt. Grounding flow: (1) run groundingBxql to enumerate the Dis…",
      "triggers": [
        "differentially expressed",
        "differential expression",
        "upregulated genes",
        "… 1 more"
      ],
      "conceptDbLabels": [
        "DifferentialExpressionDataset",
        "Disease",
        "Gene"
      ],
      "relationshipTypes": [
        "differentially expresses",
        "studies condition"
      ],
      "propertyUsages": [
        "Disease.displayName"
      ],
      "subgraphUuids": [],
      "groundingBxql": "(d:DifferentialExpressionDataset)-> studies condition ->(di:Disease)",
      "bxql": "(g:Gene)<- differentially expresses <-(d:DifferentialExpressionDataset)-> studies condition ->(di:Disease)",
      "cypher": null,
      "enabled": true
    },
    {
      "uuid": "wAKnkxZI9sA15pq6zI7Hc",
      "kind": "intent",
      "title": "Differentially expressed genes by disease × cell type (single-cell)",
      "instructions": "Use when the question asks for genes differentially expressed in a disease AND names a cell type / population (single-cell). The bxql is a scaffold to adapt. Grounding flow: (1) run groundingBxql to e…",
      "triggers": [
        "differentially expressed",
        "differential expression",
        "cell population",
        "… 3 more"
      ],
      "conceptDbLabels": [
        "CellType",
        "ScDiffExpDataset",
        "Disease",
        "… 1 more"
      ],
      "relationshipTypes": [
        "analyzes celltype",
        "studies condition",
        "differentially expresses"
      ],
      "propertyUsages": [
        "CellType.displayName",
        "Disease.displayName"
      ],
      "subgraphUuids": [],
      "groundingBxql": "(input:CellType)<- analyzes celltype <-(d:ScDiffExpDataset)-> studies condition ->(di:Disease)",
      "bxql": "(input:CellType)<- analyzes celltype <-(d:ScDiffExpDataset)-> studies condition ->(di:Disease) + (d:ScDiffExpDataset)-> differentially expresses ->(g:Gene)",
      "cypher": null,
      "enabled": true
    }
  ],
  "count": 2
}
```