tooluniverse-microbial-genome-characterization - Claude MCP Skill

# Microbial Genome Assembly Characterization & QC

Discover, quality-control, and structurally map genome ASSEMBLIES for any organism using the keyless NCBI Datasets genome tools. Organism/taxon in → assembly inventory, QC metrics, and chromosome/plasmid map out.

## LOOK UP, DON'T GUESS
When uncertain about an accession, assembly level, replicon count, or N50, CALL the tool. Never report assembly statistics from memory — accessions and metrics change with each RefSeq release. A live NCBI Datasets answer is always more reliable than a guess.

## COMPUTE, DON'T DESCRIBE
When comparing multiple assemblies or ranking by quality, retrieve each via the tools, then write and run Python (pandas) over the returned JSON to sort, score, and tabulate. Don't describe what you would compute — execute it and report actual numbers.

## When to Use This Skill

**Triggers**:
- "What genomes are available for [organism]?" / "Find the reference genome for [taxon]"
- "Assembly stats for GCF_000005845.2" / "What's the N50 / GC content of [accession]?"
- "How many plasmids does [strain] have?" / "List the replicons in [accession]"
- "Compare the assemblies for [species] — which is best quality?"
- "Is [accession] a complete genome or draft?"

**Use Cases**:
1. **Assembly discovery**: enumerate available assemblies for a taxon, optionally only reference-grade
2. **Assembly QC**: pull length, N50, contig count, GC%, level, RefSeq category for an accession
3. **Replicon mapping**: list chromosomes and plasmids with their RefSeq/GenBank accessions and lengths
4. **Assembly comparison**: rank candidate assemblies of one species by completeness and contiguity
5. **Reference selection**: identify the designated reference/representative genome for a taxon

**NOT this skill** (point elsewhere):
- Gene-level orthology, synteny, conservation → `tooluniverse-comparative-genomics`
- Plant gene structure / annotation → `tooluniverse-plant-genomics`
- De novo assembly from sequencing reads → no ToolUniverse tool exists; say so
- Pure taxonomy name → lineage lookups with no genome question → use NCBI taxonomy tools directly

---

## Tools (all keyless, verified live)

| Tool | Key params | Returns |
|------|-----------|---------|
| `NCBIDatasets_suggest_taxonomy` | `query` (organism name string) | candidate matches: `scientific_name`, `tax_id`, `rank`, `group_name` |
| `NCBIDatasets_get_taxonomy` | `tax_id` (string/int) | `organism_name`, `rank`, `lineage`, `children` |
| `NCBIDatasets_list_genomes_by_taxon` | `taxon` (name OR taxid), `limit`, `reference_only` (bool) | assembly list (accession, assembly_level, refseq_category, total_sequence_length, contig_n50, gc_percent, number_of_chromosomes, number_of_contigs); `metadata.total_available` = full count |
| `NCBIDatasets_get_genome_assembly` | `accession` (GCF_/GCA_) | full QC: total_sequence_length, number_of_chromosomes, number_of_contigs, contig_n50, scaffold_n50, gc_percent, assembly_level, assembly_status, refseq_category, release_date, submitter, annotation_provider |
| `NCBIDatasets_get_sequence_reports` | `accession` (GCF_/GCA_) | per-replicon list: chr_name, role, refseq_accession, genbank_accession, length, gc_percent |

> Param note: `get_taxonomy` requires `tax_id` (NOT `taxon`). `list_genomes_by_taxon` accepts either a name or a taxid in its `taxon` field. Always pass an accession to the assembly/sequence-report tools.

---

## Workflow

### Phase 0 — Resolve the organism (skip if you already have an accession)
If the user gives an organism name, resolve it to a tax id first:

```
NCBIDatasets_suggest_taxonomy {"query": "Escherichia coli"}
```

Pick the candidate whose `scientific_name`/`rank` matches the user's intent (species vs. a specific strain). Optionally confirm lineage/children with `NCBIDatasets_get_taxonomy {"tax_id": "562"}`.

If the user already gave a GCF_/GCA_ accession, skip to Phase 2.

### Phase 1 — Inventory the assemblies
List what exists for the taxon. Start `reference_only: true` to surface the curated reference/representative genome(s); set it to `false` to see the full set.

```
NCBIDatasets_list_genomes_by_taxon {"taxon": "562", "limit": 5, "reference_only": true}
```

Read `metadata.total_available` for the true count (large taxa return thousands — the `data` array is only the first `limit` rows). Note each candidate's `assembly_level`, `refseq_category`, `contig_n50`, and `number_of_contigs`.

### Phase 2 — Select the assembly
Prefer, in order:
1. `refseq_category == "reference genome"` (NCBI's single designated reference)
2. `refseq_category == "representative genome"`
3. Highest `assembly_level` (Complete Genome > Chromosome > Scaffold > Contig)
4. Highest `contig_n50` and lowest `number_of_contigs` among same-level candidates
5. A GCF_ (RefSeq) accession over its paired GCA_ (GenBank) when both exist — RefSeq is the curated copy

### Phase 3 — Pull assembly QC metrics
```
NCBIDatasets_get_genome_assembly {"accession": "GCF_000005845.2"}
```
Report: total length, # chromosomes, # contigs, contig N50, scaffold N50, GC%, assembly level, RefSeq category, release date, annotation provider.

### Phase 4 — Map the replicons (chromosomes + plasmids)
```
NCBIDatasets_get_sequence_reports {"accession": "GCF_000005845.2"}
```
Each row is one replicon. Distinguish chromosomes from plasmids by `chr_name` / `role`: a row named like `pO157`, `pOSAK1`, or with a plasmid-style name is a plasmid; `chromosome` rows are chromosomes. To answer "how many plasmids", count the non-chromosome assembled-molecule rows.

### Phase 5 — Compare candidates (optional)
When the user wants the best of several assemblies, fetch each accession, build a pandas table, and sort by (assembly_level rank, then contig_n50 desc, then number_of_contigs asc). Report the winner with the metrics that decided it.

---

## Interpretation Table

**Assembly level** (contiguity, best → worst):

| Level | Meaning |
|-------|---------|
| Complete Genome | Every replicon (each chromosome + each plasmid) fully resolved as one gapless sequence. Gold standard. |
| Chromosome | Chromosome(s) assembled to near-complete, but may contain gaps; plasmids/organelles may be incomplete. |
| Scaffold | Contigs ordered/oriented into scaffolds using gap-spanning evidence; gaps remain. Draft. |
| Contig | Only contiguous stretches; no scaffolding. Most fragmented draft. |

**Contiguity metrics** (a typical bacterial genome is 2–6 Mb):

- **Contig N50**: the contig length at which 50% of the assembly is in contigs ≥ that size. Higher = better. A Complete Genome's contig N50 equals its largest replicon length (e.g., 4.64 Mb for E. coli K-12 — the whole chromosome is one contig). A good draft bacterium often has N50 in the hundreds-of-kb; N50 of a few kb signals a fragmented assembly.
- **Number of contigs**: low is better. A Complete Genome has one contig per replicon (so 1 for a single-chromosome no-plasmid genome). Hundreds–thousands of contigs indicates a fragmented draft.
- **Scaffold N50 ≥ contig N50** always; a large gap between them means scaffolding bridged many contigs across gaps.

**RefSeq category**:

| Value | Meaning |
|-------|---------|
| reference genome | NCBI's single, most-curated assembly for the taxon — the default to cite. |
| representative genome | A high-quality assembly chosen to represent the species when no formal reference is designated. |
| (null / none) | An ordinary submitted assembly, not specially designated. |

**GCF_ vs GCA_**: GCF_ = RefSeq (NCBI-curated, consistent annotation). GCA_ = GenBank (as submitted by the author). They share the numeric core (e.g., GCF_000005845.2 / GCA_000005845.2); prefer GCF_ when both exist.

---

## Worked Example 1 — Reference genome of *E. coli* (single chromosome, no plasmid)

1. `NCBIDatasets_suggest_taxonomy {"query":"Escherichia coli"}` → species tax id **562**.
2. `NCBIDatasets_list_genomes_by_taxon {"taxon":"562","limit":5,"reference_only":true}` → top hit **GCF_000005845.2** (*E. coli* str. K-12 substr. MG1655), assembly_level **Complete Genome**, refseq_category **reference genome**, total 4,641,652 bp, contig_n50 4,641,652, GC 51%. `metadata.total_available` = 2 reference-grade.
3. `NCBIDatasets_get_genome_assembly {"accession":"GCF_000005845.2"}` → **4.64 Mb**, **1 chromosome**, **1 contig**, contig N50 = scaffold N50 = 4,641,652 (the entire genome is one gapless contig), GC **51%**, Complete Genome, released 2013-09-26, annotated by NCBI RefSeq.
4. `NCBIDatasets_get_sequence_reports {"accession":"GCF_000005845.2"}` → **one replicon**: `chromosome`, RefSeq **NC_000913.3** (GenBank U00096.3), 4,641,652 bp, GC 51%. **Zero plasmids.**

Answer: The E. coli K-12 reference genome is GCF_000005845.2 — a 4.64 Mb Complete Genome with a single chromosome (NC_000913.3), no plasmids, GC 51%.

## Worked Example 2 — "How many plasmids does *E. coli* O157:H7 Sakai have?"

1. From the same taxon listing, the Sakai reference assembly is **GCF_000008865.2** (Complete Genome, 5.59 Mb, 3 chromosomes-field).
2. `NCBIDatasets_get_sequence_reports {"accession":"GCF_000008865.2"}` → **three replicons**:
   - `chromosome` — NC_002695.2 — 5,498,578 bp
   - `pOSAK1` (plasmid) — NC_002127.1 — 3,306 bp
   - `pO157` (plasmid) — NC_002128.1 — 92,721 bp

Answer: 1 chromosome + **2 plasmids** (pOSAK1 ~3.3 kb, pO157 ~92.7 kb). Note: the assembly's `number_of_chromosomes` field reports 3 (it counts all assembled molecules); the sequence report is authoritative for telling chromosomes from plasmids by name/role.

## Worked Example 3 — Inventory scale (large taxon)

`NCBIDatasets_list_genomes_by_taxon {"taxon":"Mycobacterium tuberculosis","limit":3,"reference_only":false}` → `metadata.total_available` = **16,311** assemblies; first rows include GCA_000195955.2 and its RefSeq pair GCF_000195955.2 (both Complete Genome, reference genome, contig N50 4,411,532, 1 contig). Use `reference_only:true` to cut 16k assemblies down to the curated reference; never page through all of them.

---

## Limitations

- **No de novo assembly**: this skill characterizes *existing* NCBI assemblies. It cannot assemble a genome from FASTQ/raw reads — no ToolUniverse tool does that. Say so and stop.
- **RefSeq vs GenBank**: only assemblies ingested into NCBI Datasets appear. A brand-new GenBank-only submission may lack a GCF_ pair until RefSeq curation runs.
- **`number_of_chromosomes` counts assembled molecules**, not strictly chromosomes — for some bacteria it includes plasmids. Always use `get_sequence_reports` to separate chromosomes from plasmids by replicon name/role.
- **Large taxa paginate**: `list_genomes_by_taxon` returns only `limit` rows; trust `metadata.total_available` for the count and refine with `reference_only:true` rather than fetching thousands.
- **No completeness/contamination scores**: NCBI Datasets does not return BUSCO/CheckM here. Assembly *level* and N50 are proxies for quality; this skill does not compute genome completeness from marker genes.
- **Annotation depth not assessed**: these tools report whether an assembly is annotated and by whom, not gene-by-gene content. For gene-level analysis route to a gene-centric skill.

---

## Completeness Checklist

Before answering, confirm you have:
- [ ] Resolved the organism to a tax id (or were given an accession) — no guessed taxids
- [ ] Stated `metadata.total_available` when reporting "how many genomes exist"
- [ ] Justified the selected accession (reference > representative > level > N50/contigs)
- [ ] Reported assembly level, length, N50, contig count, and GC% from a live `get_genome_assembly` call
- [ ] Used `get_sequence_reports` (not `number_of_chromosomes`) to count chromosomes vs plasmids
- [ ] Preferred the GCF_ accession over its GCA_ pair when both exist
- [ ] Pointed elsewhere if the request was orthology, plant gene structure, de novo assembly, or taxonomy-only