---
name: 5etools-query
description: Query self-hosted 5e.tools data for D&D 5e stat blocks, spells, items, vehicles, and rules, plus campaign web-tool and stat-block presentation recipes.
version: 2.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos]
metadata:
  hermes:
    tags: [dnd, 5e, 5etools, ttrpg, self-hosted, stat-blocks, spells, items, vehicles, web-tools, campaign-aids]
    related_skills: [obsidian, obsidian]
    category: dnd
---

# 5e.tools Query Skill

> **Load this skill when the user mentions:** any of the following topics:
> - D&D 5e monsters, spells, items, vehicles, stat blocks, rules
> - "look up X in 5e.tools" or "query 5e.tools"
> - Building a TTRPG web tool, campaign aid, tracker, or digital handout
> - Pirate / naval / ship campaign tools or crew morale systems
> - Self-hosted RPG reference tools

Use this skill to look up D&D 5e data from a self-hosted 5e.tools instance. The data lives at `~/5etools/data/` and is served via HTTP at `http://localhost:8080/` (local) or `http://100.85.54.6:8080/` (Tailscale).

The user may also access this instance remotely via Tailscale. If so, use the Tailscale address `100.85.54.6:8080` unless the user specifies otherwise. Do not default to `localhost` when working on the Hermes container itself; `localhost:8080` works there, but Tailscale access is also valid and may be preferred depending on context.

## Data Structure

- **Bestiary**: Split across 107 files in `data/bestiary/bestiary-*.json`. Each file has a `"monster"` array. Total: ~4,539 monsters.
- **Spells**: Split across 17 files in `data/spells/spells-*.json`. Each file has a `"spell"` array. Total: ~936 spells.
- **Items**: Single file `data/items.json` with an `"item"` array. Total: ~2,428 items.
- **Vehicles**: Single file `data/vehicles.json` with a `"vehicle"` array. Includes ships (Galley, Warship, Sailing Ship, Longship, Keelboat) from *Ghosts of Saltmarsh* and spelljamming vessels. Ships have `hull`, `control`, `movement`, `weapon`, and `actionThresholds` fields instead of standard monster stats.
- **Other**: `data/classes.json`, `data/races.json`, `data/feats.json`, `data/backgrounds.json`, etc.

## Querying

### By Name (recommended — searches all files)

Use the `5etools-query` script to search by name across all data types:

```bash
python3 ~/.hermes/skills/dnd/5etools-query/scripts/query.py "Mind Flayer"
python3 ~/.hermes/skills/dnd/5etools-query/scripts/query.py "Fireball" --type spell
python3 ~/.hermes/skills/dnd/5etools-query/scripts/query.py "Bag of Holding" --type item
```

For exact vehicle/ship lookups, use direct JSON access instead — see `references/vehicles.md` for the data structure and a quick lookup script.

### Direct file access

For bulk operations or custom queries, read the JSON files directly:

```python
import json, glob

# Find a monster by name across all bestiary files
for f in glob.glob('/home/thesage/5etools/data/bestiary/bestiary-*.json'):
    data = json.load(open(f))
    for monster in data.get('monster', []):
        if monster['name'].lower() == target.lower():
            return monster
```

## Key Fields

See `references/json-schema.md` for a complete field-by-field reference with type annotations, size/school code maps, and batch query patterns.

### Monster
- `name`, `cr` (challenge rating), `type`, `size`, `alignment`
- `ac` (armor class, can be list of objects), `hp` (dict with `average` and `formula`)
- `str`, `dex`, `con`, `int`, `wis`, `cha` (scores)
- `speed` (dict), `senses`, `passive`
- `immune`, `resist`, `vulnerable` (damage types)
- `conditionImmune`
- `trait` (list of special traits), `action` (list of actions), `legendary` (legendary actions)
- `spellcasting` (spellcasting ability)
- `environment`, `source`

### Spell
- `name`, `level`, `school`, `classes`
- `time` (casting time), `range`, `duration`
- `components` (V, S, M)
- `entries` (description text, can be nested)
- `source`

### Item
- `name`, `type`, `rarity`, `value`, `weight`
- `entries` (description)
- `source`

## Formatting Output

When displaying a stat block, format it cleanly:

```
**Mind Flayer** — Medium aberration, lawful evil
─────────────────────────────────
AC 15 (breastplate) | HP 71 (13d8+13) | Speed 30 ft.
STR 11 | DEX 12 | CON 12 | INT 19 | WIS 17 | CHA 17
Saving Throws: INT +7, WIS +6, CHA +6
Skills: Arcana +7, Deception +6, Insight +6, Perception +6, Persuasion +6, Stealth +4
Senses: Darkvision 120 ft., Passive Perception 16
Languages: Deep Speech, Undercommon, Telepathy 120 ft.
CR 7 (2,900 XP)
```

## Pitfalls

- Monster names may have accents or special characters (e.g., "Goblin" vs "Goblin Boss")
- Some monsters appear in multiple source files (e.g., variants) — return the most complete version
- AC can be a list of objects with `from` arrays — show the first AC value and its source
- HP is always a dict with `average` and `formula`
- Spell entries can be nested lists — flatten them for display
- The `source` field indicates which book the data comes from
- **The query script is fuzzy and may return wrong matches** (e.g., "Sailing Ship" returns a "Jiangshi"). For vehicles, monsters with generic names, or any exact lookup, bypass the script and query the JSON directly
- **Vehicle stat blocks differ from monsters**: ships use `hull` (dict with `ac`, `hp`, `dt`), `control` (array), `movement` (array), `weapon` (array), and `actionThresholds` (dict mapping crew count to actions). They do NOT have `ac`, `hp`, `speed`, `trait`, or `action` at the top level
- `vehicles.json` is the canonical source for all ships and waterborne vehicles; `items.json` also contains ship entries but they are purchase/equipment records, not full stat blocks

---

## Campaign Aids and Web Tools

The same verified JSON data can drive self-contained HTML tools for sessions: initiative trackers, ship stat viewers, random encounter rollers, and digital handouts.

### Tool starter

Copy `templates/tool-starter.html` for a responsive, single-file web tool. It is a no-build dependency canvas useful for any campaign aid that does not need a database.

### Ship / crew tools

When building pirate/naval campaign aids:

1. Pull ship stats from `data/vehicles.json` (hull AC/HP, control, movement, weapons, action thresholds).
2. Use `references/loose-crew-morale-pattern.md` for the crew/morale model.
3. Combine both into a single HTML file with sections for ship stat block, grid viewer, and crew status.

### Vault-local web tools

When placing tools inside an Obsidian vault, store them in a subfolder (e.g., `Ships/` or `Tools/`) so they are markdown-ignored but reachable via `file://` or a local HTTP server. See `obsidian:references/ttrpg-campaign-vault.md` for the complementary markdown tracker pattern.

---

## References

- `references/loose-crew-morale-pattern.md` — Story-first crew/morale system for naval/pirate campaigns.
- `references/vehicles.md` — Vehicle/ship data structure and direct lookup recipe.
- `references/json-schema.md` — Complete field-by-field reference for monsters, spells, and items.

## Templates

- `templates/tool-starter.html` — Single-file responsive HTML/CSS/JS starter for TTRPG web tools.

## Scripts

- `scripts/query.py` — Name-based fuzzy search across bestiary, spells, and items.