opencode-bioresearcher 1.6.0

package/skills/bioresearcher-deep-research/references/genes.md

@@ -0,0 +1,93 @@
+# Gene Research
+
+Gene discovery, annotation, cross-links, and pathway enrichment via
+`gene_search` / `gene_get` and the `gene_*` family.
+
+## Overview
+
+`gene_search` finds genes by symbol/name/keyword (MyGene-backed);
+`gene_get` returns rich per-gene annotation with selectable sections;
+cross-link tools connect a gene to diseases, drugs, trials, and articles;
+`gene_enrich` runs Reactome pathway enrichment on a gene list.
+
+## Tools
+
+### gene_search
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| query | string (required) | Gene symbol, name, or keyword |
+| chromosome | string, optional | e.g. "7", "X" |
+| limit | int 1-50, default 10 | Maximum results |
+| offset | int >= 0, default 0 | Result offset |
+
+### gene_get
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| symbol | string (required) | OFFICIAL HGNC symbol only (e.g. "BRAF", "TP53", "ERBB2"); aliases like "HER2"/"NEU" rejected unless `smart: true` |
+| sections | enum array, optional | `core`, `pathways`, `ontology`, `diseases`, `protein`, `go`, `interactions`, `clinical_evidence`, `expression`, `protein_atlas`, `druggability`, `dosage_sensitivity`, `constraint`, `disease_associations`, `funding`, `all` |
+| limit | int 1-100, default 20 | Caps array lengths per section |
+| smart | boolean, default false | When true, resolves aliases/common names to the official HGNC symbol first (e.g. "HER2" -> "ERBB2"); zero overhead for valid symbols |
+
+Section highlights: `protein` (UniProt), `pathways` (Reactome),
+`clinical_evidence` (CIViC variants), `expression` + `protein_atlas` (Human
+Protein Atlas - see pacing note below), `druggability` (DGIdb),
+`disease_associations` (DisGeNET - needs key), `dosage_sensitivity` (ClinGen),
+`constraint` (gnomAD pLI), `funding` (NIH Reporter grants).
+
+### Cross-link and enrichment tools
+
+| Tool | Parameters | Notes |
+|------|-----------|-------|
+| gene_diseases | symbol, limit (1-50, default 10) | DisGeNET associations NEED `DISGENET_API_KEY`; without it the tool falls back to OpenTargets gene-disease associations |
+| gene_drugs | symbol | Drugs targeting the gene |
+| gene_trials | symbol | Clinical trials referencing the gene |
+| gene_articles | symbol | Articles about the gene (relevance search, no recency sort) |
+| gene_enrich | genes (list of HGNC symbols) | Reactome pathway enrichment; returns `_error` row on failure |
+
+## Worked examples
+
+Resolve an alias and pull focused annotation:
+
+```json
+{"symbol": "HER2", "smart": true, "sections": ["core", "druggability", "clinical_evidence"]}
+```
+
+Search by chromosome:
+
+```json
+{"query": "kinase", "chromosome": "7", "limit": 15}
+```
+
+Disease associations via the fallback path (no DisGeNET key):
+
+```json
+{"symbol": "BRCA1", "limit": 10}
+```
+
+Enrichment on a hit list:
+
+```json
+{"genes": ["BRAF", "NRAS", "MAP2K1", "MAPK1"]}
+```
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| gene_get error: not a valid HGNC symbol | alias or outdated name used | pass the official symbol, or set `smart: true` |
+| gene_diseases returns `_error` re DisGeNET | `DISGENET_API_KEY` missing | the tool already fell back to OpenTargets data; add the key for DisGeNET-grade associations |
+| HPA sections slow/erroring when iterating many genes | `protein_atlas`/`expression` use an unthrottled raw fetch | pace these calls manually; other sections are server-limited |
+| gene_enrich single `_error` row | Reactome AnalysisService rejected the input | check symbols are valid HGNC; retry with a smaller list |
+
+## Integration notes
+
+- Typical chain: `gene_search` (discovery) -> `gene_get` (annotation) ->
+  `gene_diseases`/`gene_drugs`/`gene_trials` (cross-links) -> `trial_get` /
+  `article_get` for depth.
+- `gtex_expression`/`gtex_eqtl` (references/functional-genomics.md) extend
+  gene expression questions with tissue profiles.
+- `ensembl_lookup` (references/ensembl-pdb.md) is the identifier/structure
+  authority (stable IDs, coordinates, transcripts) for ANY Ensembl species.
+- MyGene is server-limited at 100 ms - no manual throttling.

package/skills/bioresearcher-deep-research/references/optional-analysis.md

@@ -0,0 +1,108 @@
+# Optional Analysis Tools
+
+Environment-gated analysis: SQL database access (3 tools), R/Bioconductor
+differential expression (4 tools), and biowasm BAM/VCF/BED pipelines
+(8 tools). All register ONLY when their env gate is set at server start.
+
+## Overview
+
+These 15 tools extend biomcp beyond retrieval into local-data analysis. They
+are optional: without `DB_TYPE`, `ANALYSIS_R=1`, or `ANALYSIS_BIOWASM=1` set
+in the client env block, they do not exist (calls return `no_such_tool`).
+
+## Database tools (gate: DB_TYPE=mysql or sqlite)
+
+| Tool | Parameters | Notes |
+|------|-----------|-------|
+| db_list_tables | none | Lists databases/aliases, tables, row counts; call FIRST |
+| db_describe_table | table_name | Column schema; qualify attached SQLite dbs as `alias.table` |
+| db_query | sql, params? | READ-ONLY: only SELECT/SHOW/DESCRIBE/EXPLAIN/WITH allowed; named params `:name` passed via `params` |
+
+```json
+{"sql": "SELECT gene_symbol, COUNT(*) AS n FROM variants
+ WHERE significance = :sig GROUP BY gene_symbol LIMIT 20",
+ "params": {"sig": "pathogenic"}}
+```
+
+MySQL additionally needs DB_HOST/DB_USER/DB_PASSWORD/DB_DATABASE and the
+`mysql2` peer dependency (`-p mysql2@3` in the client command); SQLite needs
+DB_SQLITE_PATH (comma-separated; first = main, rest attached read-only,
+enabling `alias.table` cross-database JOINs).
+
+## R analysis tools (gate: ANALYSIS_R=1, needs webr peer `-p webr@0.6`)
+
+| Tool | Purpose |
+|------|---------|
+| analysis_r_deseq2 | DESeq2 negative-binomial DE (params: alpha, fit_type, shrink) |
+| analysis_r_edger | edgeR TMM + quasi-likelihood/exact (param: test=qlm/exact) |
+| analysis_r_limma | limma-voom precision-weighted linear models |
+| analysis_r_session_info | Runtime diagnostics (R/Wasm versions, package versions, memory) |
+
+Shared input schema: `counts` (genes x samples integer matrix), `coldata`
+(per-sample metadata), `design` (R formula, e.g. "batch + condition"),
+`contrast` {variable, numerator, denominator} or `coef`, `top_n`
+(default 50), `include_full`, `format` ("json" for structured output).
+
+COLD START: the first call starts a ~1 GB WebAssembly R worker and downloads
+a ~62 MB package bundle - MINUTES, not seconds. Set the client MCP timeout to
+120000 (ms) once R analysis is enabled, or pre-warm from bash before asking
+the client. Later calls reuse the warm worker (seconds).
+
+## Biowasm tools (gate: ANALYSIS_BIOWASM=1; npx-only, nothing to install)
+
+| Tool | Purpose |
+|------|---------|
+| analysis_bam_summary | Alignment triage: contigs, flagstat, idxstats |
+| analysis_bam_view_region | Reads/depth/pileup in a region (mode=count/depth/pileup/reads) |
+| analysis_bcf_summary | VCF/BCF triage: counts, samples, INFO/FORMAT inventory |
+| analysis_bcf_view_region | Region variant projection (column pick, sample subset, filter) |
+| analysis_bed_op | bedtools intersect/merge/subtract/coverage/jaccard/sort |
+| analysis_biowasm_convert | Format plumbing: SAM/BAM/CRAM/VCF/BCF/TSV conversion |
+| analysis_biowasm_session_info | Runtime report (tool versions, cache, artifacts) |
+| analysis_biowasm_cli | Escape hatch: allowlisted samtools/bedtools/bcftools subcommand (max 32 args, no shell) |
+
+Source inputs accept inline `content`, a prior `artifact_id`, or a
+`host_path` under `ANALYSIS_BIOWASM_DATA_DIR` (unset = host files denied).
+Output `format`: "table" (markdown, `top_n` rows, 2 MB cap), "json", or
+"artifact" (handle + preview; reusable as the next call's `artifact_id`).
+`top_n` max is 200 (default 50).
+
+ARTIFACT THREADING: multi-step pipelines pass `artifact_id` between calls,
+e.g. bam_view_region(format="artifact") -> biowasm_convert(to="SAM") ->
+bam_summary. This keeps bulky data server-side and out of context.
+
+## Worked examples
+
+```json
+{"sql": "SELECT * FROM gene_effect WHERE gene_symbol = :g LIMIT 50",
+ "params": {"g": "KRAS"}}
+```
+
+```json
+{"source": {"artifact_id": "art_abc123"}, "mode": "count", "region": "chr7:140453000-140453500"}
+```
+
+```json
+{"source": {"content": "chr1\t10\t20\nchr1\t100\t200\n"}, "op": "merge"}
+```
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `no_such_tool` | env gate unset, or set after server start | set DB_TYPE/ANALYSIS_R/ANALYSIS_BIOWASM, restart client |
+| First R call fails client-side despite healthy machine | cold bootstrap runs minutes; client timeout too low | raise client timeout to 120000 or pre-warm from bash |
+| R bundle download times out | slow link vs download budget | raise `features.analysis_r.asset_timeout_ms` via biomcp_configure or self-fetch the bundle (see ENV-VARS docs) |
+| db_query rejected | non-SELECT statement | only SELECT/SHOW/DESCRIBE/EXPLAIN/WITH are allowed |
+| host_path denied | ANALYSIS_BIOWASM_DATA_DIR unset | set it to the allowlisted root directory |
+| webr/mysql2 missing while install_mode is npx-cache | peers invisible to npx cache | use a client command carrying `-p webr@0.6` and/or `-p mysql2@3` |
+
+## Integration notes
+
+- GEO workflow: `geo_get(download=true)` -> load counts -> `analysis_r_*`.
+- Large-input guards: estimate-gated tools return guidance; re-run with
+  `proceed_on_large_input: true` to stream (progress reported).
+- Worker pool: `ANALYSIS_BIOWASM_WORKERS` (default 1 = serial); memory limits
+  default 2048 MB RSS watermark.
+- Full guides: R-ANALYSIS.md / BIOWASM-ANALYSIS.md / DATABASE.md in the
+  biomcp-ts docs.

package/skills/bioresearcher-deep-research/references/patents.md

@@ -0,0 +1,92 @@
+# Patent Research
+
+Worldwide patent search and detail via `patent_search` / `patent_get`
+(USPTO Public Search, USPTO ODP, EPO OPS, Google Patents backends).
+
+## Overview
+
+`patent_search` runs multi-backend patent search with automatic seminal
+prior-art mining; `patent_get` retrieves one patent by publication number with
+claims, citations, family, and classifications. These tools are slower than
+the biomedical ones: search is bounded at 60 s, detail at 120 s.
+
+## Tools
+
+### patent_search
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| query | string (required) | Free text; QUOTE exact multi-word concepts, e.g. "\"mRNA display\"" - unquoted phrases drift off-topic |
+| assignee | string, optional | Assignee/applicant org, e.g. "Moderna" |
+| inventor | string, optional | Inventor name |
+| cpc | string, optional | Full CPC symbol, e.g. "C12N15/11" |
+| status | enum, optional | `granted` / `application` |
+| date_range | string, optional | `YYYY-MM-DD/YYYY-MM-DD`, either side may be empty |
+| limit | int 1-50, default 10 | Maximum results |
+| offset | int >= 0, default 0 | Pagination |
+| source | enum, optional | Force backend: `ppubs` (USPTO Public Search, US full-text, keyless, default US), `ops` (EPO OPS worldwide bibliographic; needs EPO keys), `uspto_odp` (US application metadata; needs USPTO_API_KEY), `google_patents` (best-effort, often unavailable) |
+| sort_by | enum, optional | `relevance` (default) / `recency` - currently affects the ppubs backend only |
+| seminal | boolean, optional, default true | Co-citation mining of top results to surface foundational prior art in `seminal_prior_art`; adds ~5-30 s - set `false` for the fastest bibliographic lookups |
+
+Default (no `source`) "auto" mode: queries worldwide + ppubs concurrently; if
+ppubs fails hard it falls back to uspto_odp once (tagged `_note`).
+
+### patent_get
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| patent_id | string (required) | Publication number, e.g. "US11027025B2", "EP3904939B1", "US20260240819A1" |
+| sections | enum array, optional | `core`, `abstract`, `claims`, `citations`, `family`, `classifications`, `all`; default core only |
+| limit | int 1-100, default 20 | Max entries per section array |
+
+Claims detail: US full text via USPTO Public Search; EP/WO claims via EPO OPS
+which REQUIRES `EPO_OPS_CONSUMER_KEY` + `EPO_OPS_CONSUMER_SECRET` (both, set
+together).
+
+## Worked examples
+
+Fast bibliographic landscape (skip seminal mining):
+
+```json
+{"query": "\"mRNA display\" peptide library", "assignee": "Moderna",
+ "seminal": false, "limit": 20}
+```
+
+Foundational prior-art discovery (default behavior):
+
+```json
+{"query": "CRISPR base editing", "date_range": "2015-01-01/", "limit": 15}
+```
+
+Force worldwide search via EPO OPS (keys set):
+
+```json
+{"query": "chimeric antigen receptor", "source": "ops", "limit": 20}
+```
+
+Pull claims and citations for a specific patent:
+
+```json
+{"patent_id": "US11027025B2", "sections": ["abstract", "claims", "citations"]}
+```
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Search exceeds 60 s budget / times out | seminal mining + multi-backend fan-out on a broad query | set `seminal: false`, quote multi-word concepts, narrow with `assignee`/`cpc`/`date_range` |
+| patent_get exceeds 120 s / times out | claims fetch across slow backends | request fewer sections (drop `family`/`citations` if unneeded), retry once |
+| EP/WO claims missing or error mentioning EPO | EPO OPS keys absent | set `EPO_OPS_CONSUMER_KEY` + `EPO_OPS_CONSUMER_SECRET` together, or accept abstract-only detail |
+| google_patents source fails | backend often unavailable | rely on ppubs (US) or ops (worldwide with keys) |
+| Off-topic results | unquoted multi-word concepts | quote the exact phrase in `query` |
+
+## Integration notes
+
+- Auto-mode `_note` fields flag backend fallbacks - mention data lineage in
+  the report when present.
+- EPO OPS and USPTO are server-limited at ~1 s token buckets - no manual
+  throttling; expect patent tools to be the slowest calls in an aspect.
+- Cite patents by publication number with a Google Patents or Espacenet URL
+  (references/citations.md).
+- Link patents to literature: `seminal_prior_art` entries often carry patent
+  and paper citations that map to `article_get` inputs.

package/skills/bioresearcher-deep-research/references/rate-limiting-auth.md

@@ -0,0 +1,95 @@
+# Rate Limiting & Auth
+
+biomcp enforces server-side per-source rate limiters, so workers do NOT need
+manual sleep timers between calls. This file lists the limiters, the
+exceptions that DO need pacing, and every auth variable.
+
+## Overview
+
+Every ConnectionManager-backed source has a token-bucket limiter applied
+inside the server (src/connections/registry.ts). Sequential calls from a
+worker are automatically paced. Manual `sleep`/timer logic between biomcp
+calls is unnecessary and slows research down - drop the old 0.3 s/0.5 s
+worker rules from earlier agent generations.
+
+## Server-side limiter table (per source)
+
+| Source (tools affected) | Interval | Notes |
+|------------------------|----------|-------|
+| eutils - SHARED by PubMed/GEO/SRA/GenBank (article_search, geo_*, sra_*, genbank_*) | 334 ms keyless; 100 ms with NCBI_API_KEY | One budget across ALL NCBI E-utilities databases (conditional limiter); server also retries 4x |
+| pubtator (article_search source=pubtator) | 334 ms keyless; 100 ms keyed | |
+| MyGene (gene_search/gene_get) | 100 ms | |
+| MyVariant (variant_*) | 100 ms | |
+| MyChem (drug_*) | 100 ms | |
+| MyDisease (disease_*) | 100 ms | |
+| OpenTargets (disease_drugs, gene_diseases fallback) | 500 ms | |
+| ClinicalTrials.gov (trial_search/trial_get, *_trials) | 100 ms | |
+| Ensembl REST (ensembl_*) | 100 ms | Server retries transient 500/503s 3x |
+| RCSB PDB (pdb) | 100-200 ms | |
+| Semantic Scholar (article_search source=semantic_scholar) | 2000 ms keyless; 1000 ms keyed (S2_API_KEY) | |
+| LitSense / OpenCitations / NIH Reporter | 1000 ms | |
+| Crossref (citation data) | 100 ms | Polite pool with CROSSREF_EMAIL |
+| Google Patents (patent fallback backend) | 2000 ms | |
+| EPO OPS (patent_search/patent_get ops backend) | ~1 s token bucket | |
+| USPTO PPUBS + ODP (patent US backends) | ~1 s token bucket | |
+| GTEx (gtex_*) | 100 ms | |
+
+## Exceptions - pace these manually
+
+1. **HPA raw fetch**: the `protein_atlas` and `expression` sections of
+   `gene_get` call proteinatlas.org via a raw (unthrottled) fetch. When
+   iterating these sections over many genes, space the calls yourself.
+2. **GEO supplementary downloads**: `geo_get(download=true)` fetches files
+   via raw fetch (not the limiter). Pace repeated downloads; each is also
+   capped by `max_bytes` (default 50 MB).
+
+Everything else: call sequentially, no timers.
+
+## Timeout reference
+
+| Tool | Budget |
+|------|--------|
+| article_search / article_get | 30 s |
+| patent_search | 60 s |
+| patent_get | 120 s |
+| Per-source HTTP timeout (most sources) | 15 s |
+| R analysis first call | minutes (cold start) - set client MCP timeout 120000 |
+
+## Auth table
+
+### Required (tool fails without them)
+
+| Variable | Unlocks | Without it |
+|----------|---------|-----------|
+| `ONCOKB_TOKEN` | `variant_oncokb` precision-oncology annotations | Tool errors; use variant_get clinical section instead (register: oncokb.org/account/register) |
+| `DISGENET_API_KEY` | DisGeNET disease-gene associations | `gene_diseases` falls back to OpenTargets associations (soft degradation, note lineage in reports) |
+
+### Optional (higher limits / extra backends)
+
+| Variable | Effect |
+|----------|--------|
+| `NCBI_API_KEY` | NCBI E-utilities rate: 3 -> 10 req/s (eutils limiter 334 -> 100 ms). Recommended for literature-heavy research |
+| `NCBI_EMAIL` | Polite tool/email parameters on E-utilities requests |
+| `S2_API_KEY` | Semantic Scholar higher limits (2 s -> 1 s interval) |
+| `OPENFDA_API_KEY` | openFDA higher upstream limits (drug_get regulatory/FAERS sections; unlike NCBI_API_KEY this does not change the in-process limiter interval) |
+| `CROSSREF_EMAIL` | Crossref polite pool - faster citation metadata |
+| `EPO_OPS_CONSUMER_KEY` + `EPO_OPS_CONSUMER_SECRET` | EPO OPS patent backend: worldwide search + EP/WO claims (BOTH must be set together) |
+| `USPTO_API_KEY` | USPTO Open Data Portal application search backend |
+
+Set keys in the MCP client's env block (opencode: `environment`; Claude/
+Codex: `env`), then restart the client - config changes never apply live.
+
+## Keyless fallback behavior
+
+- Patents: US search works keyless via USPTO Public Search (ppubs default US
+  backend); Google Patents is a best-effort fallback.
+- Drug regulatory/FAERS data works keyless (lower limits).
+- Literature works keyless across all five federated sources.
+
+## Integration notes
+
+- The worker rule is simply: sequential calls, no sleep timers; pace only the
+  HPA and GEO-download exceptions.
+- If a client ever reports HTTP 429 despite the limiters, back off for a few
+  seconds and retry once (see worker-protocol.md retry ladder).
+- Keys live in the client env block, never in reports or committed files.

package/skills/bioresearcher-deep-research/references/report-template.md

@@ -0,0 +1,117 @@
+# Report Template
+
+Mandatory structure for `final_report.md` (and the per-aspect files, in
+lighter form). Ported from the bioresearcher agent's report standard.
+
+## Overview
+
+Every report has exactly SIX mandatory sections, in this order. Every claim
+carries provenance: a citation [N], a documented data source, or a described
+analysis method.
+
+## Mandatory sections
+
+```markdown
+  # [Research Topic Title]
+
+Generated: [YYYY-MM-DD] | TOPIC: <TOPIC> | Scope: [1-2 sentence research question]
+
+  ## Executive Summary
+[2-3 sentence overview of key findings with the most critical citations [1, 2]]
+
+Key findings:
+- [Finding 1 [1]]
+- [Finding 2 [2, 3]]
+- [Finding 3 [4]]
+
+  ## Data Sources
+[Table: source | type | query/accession | date accessed]
+[Scope: records retrieved, date range, filters applied]
+[Quality notes: gaps, known biases]
+
+  ## Analysis Methodology
+[Aspects researched and how (worker/sequential mode)]
+[Tools used per aspect with key query parameters]
+[Validation steps and error handling (retries, fallbacks)]
+
+  ## Findings
+[Organized by research question; each subsection = one theme]
+[Key data points with confidence and citation: metric | value | confidence | source]
+[Evidence tables where numeric comparisons exist]
+
+  ## Limitations
+[Data gaps: what could not be found and why]
+[Methodological constraints: source coverage, date windows, auth-gated tools skipped]
+[Generalizability: where findings apply and where they may not]
+
+  ## References
+[Numbered bibliography in references/citations.md format, ordered by first appearance]
+```
+
+## Per-aspect file structure (lighter)
+
+```markdown
+  # [Aspect Name] (TOPIC: <TOPIC>)
+
+Scope: [1 paragraph from the worker ABSTRACT]
+
+  ## Findings
+[Findings with in-text citations [1], [2, 3]]
+
+  ## Tool / Query Log
+[tool + key arguments, e.g. article_search(query="...", dateRange="2021-01-01/", limit=15)]
+
+  ## Evidence Gaps
+[queries that failed after retries, with reasons]
+
+  ## References
+[numbered bibliography]
+```
+
+## Citation placement rules
+
+- In-text: [1] single; [2, 3] list; [1-5] range - numbered by ORDER OF
+  APPEARANCE across the document.
+- The Executive Summary cites only the most critical sources.
+- Every table row with a number has a Source column.
+- Bibliography is ordered by number, not alphabetized.
+
+## Provenance standard
+
+BAD (no provenance):
+
+```markdown
+BRAF V600E is found in 50% of melanomas.
+```
+
+GOOD:
+
+```markdown
+BRAF V600E mutations occur in approximately 50% of cutaneous melanomas [1],
+consistent with earlier estimates of 40-60% prevalence [2, 3].
+```
+
+Where the claim derives from an analysis rather than a document, name the
+method and input: "based on trial_search(query='melanoma', phase='Phase 3')
+conducted 2026-09-04, 42 recruiting trials of which 28 list a BRAF/MEK
+combination [4]."
+
+## Quality checklist (before finalizing)
+
+- [ ] All six sections present, in order
+- [ ] Every claim has provenance (citation / source / method)
+- [ ] All in-text [N] present in References; no orphan references
+- [ ] Identifiers included in references (PMIDs, DOIs, NCT IDs, patent IDs, accessions)
+- [ ] Access dates for web/official-site sources
+- [ ] Limitations honest about gaps and auth-gated tools not used
+- [ ] Findings re-numbered into one bibliography in final_report.md
+- [ ] Conflicting findings surfaced, not silently dropped
+
+## Common mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Missing Data Sources section | Document every tool query and accession |
+| "We analyzed the data" methodology | Name tools + parameters + steps |
+| Absolute-truth tone in Findings | Mark confidence; hedge appropriately |
+| No Limitations | Always include coverage gaps and constraints |

package/skills/bioresearcher-deep-research/references/tool-selection.md

@@ -0,0 +1,142 @@
+# Tool Selection
+
+Route a research question to the correct biomcp tool, then shape the call with
+`sections` / `limit` / pagination so payloads stay small.
+
+## Overview
+
+biomcp (npm `biomcp`, pinned `biomcp@1.1`) exposes 56 tools: 41 core plus 15
+environment-gated optional tools (3 database, 4 R analysis, 8 biowasm). This
+file routes question types to tools; per-domain parameter detail lives in the
+domain reference files.
+
+> In MCP clients that prefix server tools (e.g. opencode with server name
+> 'biomcp'), tools appear as biomcp_article_search etc.
+
+## Domain routing decision tree
+
+```
+QUESTION TYPE
+├─ Literature / papers / PubMed
+│   → article_search (query, source?, dateRange?, limit, offset)
+│   → article_get (id: PMID/PMCID/DOI, sections?, citation_mode?)
+│   → details: references/article-literature.md
+│
+├─ Clinical trials / NCT IDs
+│   → trial_search (query, status?, phase?, intervention_type?, page_token?)
+│   → trial_get (nct_id, sections?)   # no "protocol" section exists
+│   → details: references/clinical-trials.md
+│
+├─ Genes
+│   → gene_search (query, chromosome?, limit, offset)   # discovery
+│   → gene_get (symbol, sections?, smart?)               # annotation
+│   → gene_diseases / gene_drugs / gene_trials / gene_articles  # cross-links
+│   → gene_enrich (genes[])                              # Reactome pathways
+│   → details: references/genes.md
+│
+├─ Variants / mutations
+│   → variant_search (gene + hgvsp as SEPARATE params - never free text)
+│   → variant_get (id, sections?)
+│   → variant_oncokb (gene, protein_change)   # needs ONCOKB_TOKEN
+│   → variant_trials (variant)
+│   → details: references/variants.md
+│
+├─ Drugs / compounds
+│   → drug_search (query, limit, offset)
+│   → drug_get (name, sections?)   # safety = labels; adverse_events = FAERS
+│   → drug_trials (drug)
+│   → details: references/drugs.md
+│
+├─ Diseases
+│   → disease_search (query, limit, offset)
+│   → disease_get (disease_id, sections?)   # DOID/MONDO/OMIM/EFO/Orphanet/CUI
+│   → disease_drugs / disease_trials
+│   → details: references/diseases.md
+│
+├─ Patents / prior art
+│   → patent_search (query, assignee?, source?, seminal?, sort_by?)
+│   → patent_get (patent_id, sections?)
+│   → details: references/patents.md
+│
+├─ Functional genomics datasets / sequences
+│   → geo_search / geo_get        # expression & sequencing studies
+│   → sra_search / sra_get        # sequencing runs (NCBI accessions only)
+│   → genbank_search / genbank_get / genbank_genes
+│   → gtex_expression / gtex_eqtl
+│   → details: references/functional-genomics.md
+│
+├─ Orthologues / consequences / regions / structures
+│   → ensembl_lookup / ensembl_homology / ensembl_consequence / ensembl_region
+│   → pdb (query | pdb_id | pdb_id+download)
+│   → details: references/ensembl-pdb.md
+│
+├─ Ambiguous / multi-entity free text ("BRAF V600E melanoma")
+│   → discover (query)            # resolves concepts to typed entities
+│
+├─ Many entities at once
+│   → batch_get (inputs: [{entity, id, sections?}])
+│
+├─ Local SQL database (DB_TYPE set)
+│   → db_list_tables → db_describe_table → db_query
+│   → details: references/optional-analysis.md
+│
+└─ Differential expression / BAM/VCF/BED analysis (opt-in features)
+    → analysis_r_* / analysis_bam_* / analysis_bcf_* / analysis_bed_op / ...
+    → details: references/optional-analysis.md
+```
+
+## The `sections` pattern (payload trimming, part 1)
+
+The `_get` tools for article, trial, gene, variant, drug, disease, and patent
+accept `sections` (array of enum strings) plus `limit` (1-100, default 20):
+
+- Omit `sections` -> core metadata only (smallest payload).
+- Request only the sections you need, e.g. `drug_get` with
+  `sections: ["safety"]` instead of `["all"]`.
+- `"all"` expands to every non-core section - use it only when most sections
+  are genuinely needed.
+- `limit` caps array lengths within requested sections (e.g. top 20 citations,
+  top 20 adverse-event reaction rows).
+
+Valid section enums per tool are tabulated in the domain reference files.
+
+## Pagination (payload trimming, part 2)
+
+- Most search tools (`article_search`, `gene_search`, `variant_search`,
+  `drug_search`, `disease_search`, `patent_search`, `geo_search`,
+  `sra_search`, `genbank_search`): offset-based - `limit` (1-50, default 10)
+  plus `offset` (>= 0).
+- `trial_search` is the exception: CURSOR-based only - pass the `page_token`
+  string from the previous response; there is no `offset` parameter.
+- Stop paging when a page returns fewer than `limit` results, or when you have
+  enough sources for the claim at hand (typically 5-15 per aspect).
+
+## Worked example: routing a compound question
+
+Question: "What evidence links BRAF V600E to melanoma drug resistance?"
+
+1. `discover(query="BRAF V600E")` - confirm entity types (gene + variant).
+2. `article_search(query="BRAF V600E melanoma treatment resistance",
+   dateRange="2018-01-01/", limit=15)` - recent literature.
+3. `variant_search(gene="BRAF", hgvsp="V600E")` - variant IDs/coordinates.
+4. `drug_get(name="vemurafenib", sections=["core","safety"])` - approved BRAF
+   inhibitor label data.
+5. `trial_search(query="BRAF melanoma", phase="Phase 3")` - trial landscape.
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `no_such_tool` for a db/analysis tool | feature not enabled, or enabled after server start (tools register at startup only) | set `DB_TYPE`/`ANALYSIS_R`/`ANALYSIS_BIOWASM` in the client env block, restart the client |
+| Tool error mentioning OncoKB token | `variant_oncokb` without `ONCOKB_TOKEN` | get a token (oncokb.org registration) and set it, or skip OncoKB |
+| gene_diseases returns an `_error` about DisGeNET | no `DISGENET_API_KEY` | the tool falls back to OpenTargets associations; add the key for DisGeNET data |
+| variant_search returns nothing for "BRAF V600E" as `query` | compound free text is not a variant ID | use `gene="BRAF"`, `hgvsp="V600E"` as separate params (the tool also auto-splits a bare "GENE V600E" query, but explicit params are reliable) |
+| Trial pages repeat or skip | offset paging used on trial_search | use `page_token` cursor paging |
+
+## Integration notes
+
+- Confirm the server is connected before fan-out: any cheap call (e.g.
+  `gene_search(query="BRAF", limit=1)`) suffices as a smoke test.
+- `biomcp_configure` with `{}` reports feature availability and config health
+  in one call (see `references/utility-config.md`).
+- Rate limits, timeouts, and auth requirements: `references/rate-limiting-auth.md`.