Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@pf2e-mcp help me build a Goblin Swashbuckler"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for building Pathfinder 2nd Edition Remastered characters together with an AI assistant. Rather than relying on the assistant's own memory of the rules — which is often incomplete or out of date — it looks everything up in a local, structured database built from the official rules data.
That local database also means your AI assistant doesn't need to search the web or query sites like Archives of Nethys just to answer a rules question. That keeps character-building conversations fast and token-efficient, and keeps traffic off those free community resources.
It exposes two tool namespaces over a single local SQLite database:
rules_* — general rules reference (search, get an entry, cross-reference
prerequisites, explain a rules topic).
build_* — character-building tools (browse ancestries/backgrounds/
classes/equipment/spells, find feats a character actually qualifies for,
validate a build, compute derived stats, see what unlocks on level-up,
export to Pathbuilder JSON).
A companion Claude Skill (.claude/skills/pf2e-character-builder/) teaches
an agent the conversational workflow for using these tools together.
Published on PyPI as pf2e-mcp. With
uv, nothing needs to be cloned or installed
up front:
# Build the rules database once (~1 minute, a few hundred MB downloaded)
uvx --from pf2e-mcp python -m pf2e_mcp.ingestion.buildThen point your MCP client at it:
{
"mcpServers": {
"pf2e-mcp": {
"command": "uvx",
"args": ["pf2e-mcp"]
}
}
}Or install it as a normal package (pip install pf2e-mcp, uv tool install pf2e-mcp) and use pf2e-mcp as the command instead.
The database build is not optional — no game data ships with this project (see NOTICE.md), so the server starts but every tool call fails until you run it. It's a one-time step; re-run it whenever you want newer rules data. See Where the files go for where it puts things.
If you'd like the companion character-building Skill as well, or want to work on the project itself, clone the repository instead — see Manual setup.
Related MCP server: dnd-oracle
Never used a command line before? You don't need to learn one — the easiest way to set this up is to let an AI assistant do it for you. This works the same way on Windows, Mac, or Linux.
1. Install an AI assistant that's allowed to run commands on your computer. Any of these have simple installers and can act as your "installer" for everything else:
Claude Code — Anthropic's assistant for working with project folders on your own computer. This is what was used to build pf2e-mcp itself, so it's a safe bet for setting it up too.
Visual Studio Code with the GitHub Copilot extension, using its "agent mode" chat — a free, widely-used code editor with a simple Windows installer.
Cursor — another free code editor built around AI agent chat, similar idea to VS Code + Copilot.
You only need one of these, and only to do the one-time setup below — you don't need to learn it in any depth.
(Why not just use Claude Desktop for this step? It's a great chat app — see below — but it doesn't have a built-in way to run commands on your computer, so it can't install things or edit its own config file for you the way these three can. You'll still want it, or another chat app, for step 5.)
2. Download this project. Click the green Code button near the
top of this page on GitHub, then Download ZIP, and unzip it somewhere
easy to find, like your Documents folder. (If you already use git,
git clone works too, but the ZIP download is simpler if you don't.)
3. Open the unzipped folder in whichever assistant you installed in step 1.
4. Ask it, in plain English, to set this up for you. For example, paste something like this into the chat:
Please set up the pf2e-mcp server in this folder so I can use it with Claude Desktop. Install anything it needs (like Python and
uv), build its rules database, and register the server in my Claude Desktop config.
Swap "Claude Desktop" for whichever chat app you actually want to use day-to-day — see "Chat apps you can connect this to" below for a few options. Your assistant should be able to figure out and run the actual commands (they're all documented further down this page, in "Manual setup", if you're curious what it's doing).
5. Start building a character. Once it's set up, open a conversation in your chosen chat app and just ask for help building a Pathfinder 2e character — e.g. "help me build a Goblin Swashbuckler" or "what does the Toughness feat do?" It'll use this project's tools automatically instead of guessing from memory.
pf2e-mcp is an MCP server — on its own it doesn't have a chat window, it needs a chat app that speaks MCP to actually talk to. A few well-known options:
Claude Desktop — Anthropic's free chat app for Windows and Mac. The simplest day-to-day experience once it's connected.
Claude Code — if you used it to do the setup in step 1 above, you can just keep chatting with it directly; no separate app needed.
ChatGPT and other AI chat apps are adding support for tools like this too. If you'd rather use one of those, ask your setup assistant (step 1) to connect pf2e-mcp to it instead of Claude Desktop — just check that whichever app you pick currently supports MCP servers first, since this is a fast-moving area and support varies.
Everything below is what the AI-assisted setup above does on your behalf. Follow it directly if you're comfortable with a terminal, want more control, or are extending the project yourself.
Python 3.12+
If you only want to use the server, you don't need a checkout at all — see Quick install above. Clone the repository if you want the companion Skill, or intend to work on the project:
git clone https://github.com/rjenks/pf2e-mcp
cd pf2e-mcp
uv syncThe server reads from a local SQLite database that isn't checked into the repo — no game data ships with this project (see NOTICE.md) — so you need to build it once before first use:
uv run python -m pf2e_mcp.ingestion.build(From a PyPI install rather than a checkout, the equivalent is
uvx --from pf2e-mcp python -m pf2e_mcp.ingestion.build. Either way the
database lands in the same per-user location, so it doesn't matter which
one you used to build it.)
This downloads the latest foundryvtt/pf2e GitHub release's json-assets.zip
(the official, community-maintained Pathfinder 2e Remastered rules data),
extracts it, and builds the database. Takes under a minute; only re-downloads
if a newer release than what's cached is available.
The two artifacts land in the standard per-user locations for your platform,
so the server works the same whether it's run from a checkout, installed with
pip, or launched via uvx:
Linux | macOS | |
Database (~100 MB) |
|
|
Extracted release cache |
|
|
They're split deliberately. The database is expensive to recreate, so it sits in the data directory where nothing reclaims it. The extracted release is pure cache — a few hundred MB, re-downloadable at any time — so it sits in the cache directory, and deleting it costs you one re-download and nothing else. A successful build prunes superseded release tags automatically, keeping only the one it just ingested.
Override either with PF2E_MCP_DB (full path to the .sqlite file) and
PF2E_MCP_CACHE (directory) — useful for a throwaway build, a shared
read-only database, or to keep everything inside a checkout while developing:
PF2E_MCP_DB=.data/pf2e.sqlite PF2E_MCP_CACHE=.data/raw \
uv run python -m pf2e_mcp.ingestion.buildFrom PyPI (no checkout needed). For Claude Code:
claude mcp add pf2e-mcp -- uvx pf2e-mcpOr in your MCP client's config:
{
"mcpServers": {
"pf2e-mcp": {
"command": "uvx",
"args": ["pf2e-mcp"]
}
}
}From a checkout, when you're working on the project and want your local edits to be what runs:
claude mcp add pf2e-mcp -- uv run --directory "$(pwd)" pf2e-mcp{
"mcpServers": {
"pf2e-mcp": {
"command": "uv",
"args": ["run", "--directory", "/path/to/pf2e-mcp", "pf2e-mcp"]
}
}
}For a project-scoped registration in this repo, copy .mcp.json.example to
.mcp.json and replace /path/to/pf2e-mcp with your checkout path. The
real .mcp.json is gitignored, since that path is per-machine.
To run it directly (e.g. for debugging over stdio):
uvx pf2e-mcp # from PyPI
uv run pf2e-mcp # from a checkout.claude/skills/pf2e-character-builder/SKILL.md is project-scoped, so
Claude Code picks it up automatically when working in this repo. If you're
using the server from a different project, copy that directory into the
other project's .claude/skills/, or your user-level ~/.claude/skills/.
Tool | Purpose |
| Full-text search across all ingested rules content |
| Fetch one entry's full detail by id/name/slug, including any |
| A feat's prerequisites/what requires it, plus structured (not prose-parsed) |
| Explain a rules topic (conditions, actions, glossary terms) |
| Which |
| Browse optional/variant rules (Free Archetype, Ancestry Paragon, Proficiency without Level, etc.) and GM-facing subsystems (Chases, Influence, etc.) |
| List every subclass-style choice-group tag (Druid Order, Animist Apparition, Sorcerer Bloodline, Witch Patron, etc.), with option counts |
| List every option in one subclass choice-group by exact tag, with full text and structured |
| Browse character-building options |
| Browse classes, including level-1 baseline (HP, Perception, saves, trained skills — including any "X or Y" choice — weapon/armor proficiencies) |
| Browse weapons/armor/gear, with price filtering |
| Feats a character currently qualifies for (the main token-saving discovery tool) |
| Legal ability boosts for a given source (ancestry/background/class/free) |
| Skills legally eligible for a rank increase right now |
| Spells of a tradition at or below the character's current max rank |
| Check one specific feat's eligibility |
| Structured errors/warnings for the current build |
| AC, saves, Perception, skills, HP, class DC, spell DC/attack |
| What unlocks at a target level |
| Export the working character as Pathbuilder-compatible JSON |
| Write a print-ready, single-file HTML character sheet with full rules text (see below) |
Every build_* tool but one is a pure function — the server holds no
character state between calls. The calling agent passes the in-progress
character JSON (shaped like a Pathbuilder 2e export) on every call and keeps
it in conversation. The exception is build_render_character_sheet, which
writes a file to the output_path it is given; it returns a summary rather
than the HTML, because a real sheet runs to 120–170 KB.
build_render_character_sheet(character, output_path, paper="letter")
renders a print-ready HTML sheet with no external dependencies of any kind —
fonts are inlined as base64 WOFF2, every ornament is generated inline SVG,
and nothing is fetched at view time — so the file can be emailed to a player
as a single attachment and printed unchanged.
Page 1 is a one-sheet statistics summary (attributes, skills with proficiency
pips, AC and shield, saves, HP with dying/wounded trackers, Perception,
strikes, spell DC, a condition tracker and space for session notes). It is
held to a single physical page for every character, verified against every
build in characters/, from level 2 through a level-9 dual-class. Subsequent
sections run to whatever length the content needs, in page-width cards that
reflow across page boundaries rather than being cropped: one page per
spellcasting entry with each spell's complete rules text and traits, then
features (a deity block where there is one, then ancestry, heritage,
background, level-appropriate auto-granted class features, detected subclass,
and every feat), equipment with item rules text, a page showing how each
number was derived, and a licence attribution page listing only the
sourcebooks actually quoted.
The attribution section comes last and reproduces the full text of both the Open Game License 1.0a (when OGL-licensed rules are quoted) and the SIL Open Font License 1.1 (always, since the sheet embeds the Noto fonts). Both are required to travel with what the sheet carries, so they can't be dropped from the file — but they are the final pages, so you can simply set a page range in the Print dialog and leave them off the paper copy.
Deities are in the ingested data — 480 entries, thoroughly structured — even
though no rules_* tool exposes their mechanical fields. The sheet reads them
straight from the database, and handles three cases, reported back as
deity.status:
| When | What renders |
| No deity, including the export's own placeholders ( | Nothing — block omitted |
| The recorded name matched the rules data | Divine font, sanctification, divine skill, favored weapon, primary and alternate domains, divine attribute, and the deity's cleric spells resolved to names by rank — then the full descriptive text: title, areas of concern, edicts, anathema, iconography. Pantheons, covenants and philosophies resolve here too, labelled as such |
| A name is recorded but isn't in the database — a home-game or non-standard pantheon | A labelled block with ruled lines for the standard fields, to fill in by hand |
An unrecognized deity is deliberately not reported in unresolved: a
homebrew god is a legitimate thing for a character to have, not a defect in
the data.
Note that a deity block reproduces more than mechanics. Titles, edicts,
anathema and iconography are Reserved Material under the ORC License (Product
Identity under the OGL), not the generic game content either licence grants
freely — so when one is rendered, the attribution page says explicitly that
this material appears as a descriptive reference under Paizo's Community Use
Policy rather than as an exercise of the ORC License. This matches
licensing.py's product_identity_likely flag on the deities pack.
logo_path embeds an image top-left on page 1 in place of the sheet's own
spiral mark — intended for the Pathfinder logo from Paizo's Community Use
Package, which the
Community Use FAQ permits on
free fan material (it gives putting "a Pathfinder logo on the cover" of a
non-commercial fan adventure as an example). Section headings keep the spiral,
so the sheet still has a mark of its own.
Accepts PNG, SVG, JPEG, GIF or WebP. EPS and AI are rejected with an
explanation — they ship in the package but no browser can display them. The
bytes are embedded verbatim and scaled by height with width: auto: the policy
forbids altering a logo's colour, typography, design or proportions, and allows
proportional resizing, so the renderer applies no filter, recolour, crop or
blend mode. Downloads from the package require a Paizo sign-in, so the file has
to be fetched by hand once.
Equipment values vs. transient effects. Printed statistics reflect the gear
as it permanently is, never as it might temporarily be. A shield's Hardness, HP
and Broken Threshold are the item's own values plus any etched rune — a
reinforcing rune's increments and caps are parsed from the rune's own text,
since they exist nowhere in structured form — while bonuses from spells, feats
and other effects are left out. A status bonus like Emblazon Armament's +1
Hardness may not be active when the shield is needed, so printing it would
overstate what the shield reliably blocks. Note that a shield recorded as a
bare [name, quantity] pair has nowhere to carry runes; only a dict-shaped
record does.
Everything is derived from the character data plus the ingested rules — there is no authored commentary, so a sheet is exactly as complete as the export it came from. Two consequences worth knowing:
A character with no spellCasters block gets no spell pages, even for a
caster class. Pathbuilder populates it; hand-written character JSON often
doesn't.
Class features are read from class_progression.granted_items filtered to
the character's level, since exports record only choices. A subclass
(cleric doctrine, druid order) is recovered by matching the class's tagged
option names against the character's free-text specials, which is
best-effort — check the returned subclass.
The return value reports unresolved names and aliased ones. An item an
export calls "Repair Kit" where the rules data has "Repair Toolkit" is
reported rather than guessed at or dropped silently; a systematic mismatch
that is resolved ("Thieves' Tools" → "Thieves' Toolkit", "Clothing
(Explorer's)" → "Explorer's Clothing") is listed as an alias on both the tool
result and the sheet's own notes page. Treat a non-empty unresolved as
something to fix in the character data.
Every entry (feats, ancestries, etc.) carries a rarity and a best-effort
pfs legality status now, and build_get_level_up_choices /
build_validate_build take an optional variant_rules: list[str] argument.
See the companion Skill's step 0 for the intended flow: ask the user which
optional rules and PFS mode they want before starting a build, since
that changes real math (extra feat slots, ability-boost timing) that isn't
safe to assume either way.
Variant rules come from GM Core's "Subsystems and Variant Rules"
section, ingested into the same entries table as everything else
(pack = 'variant-rules') — browse with rules_list_variant_rules, read
full official text with rules_get_entry. Of these, only
'free-archetype' and 'ancestry-paragon' currently change computed
output (extra feat-level unlocks, feat-count budget checks); the rest are
recognized slugs with reference text only, no mechanical enforcement yet.
PFS legality has no structured feed in the foundryvtt/pf2e data this
project ingests — Organized Play legality is Paizo's own policy document,
updated on its own cadence, and doesn't map cleanly onto rarity. The pfs
field on every entry (and build_validate_build's pfs_legal_only
parameter) is a best-effort heuristic: common rarity = legal,
uncommon/rare/unique = flagged restricted, with a hand-curated override
file (src/pf2e_mcp/server/pfs_overrides.json) for known exceptions. Not
authoritative — see that file's _comment/_format keys and
src/pf2e_mcp/server/pfs.py's module docstring for the reasoning, and
"Maintaining PFS overrides" below for how to add exceptions.
This project's own code is Apache 2.0 (LICENSE); the Pathfinder 2e data
it ingests is Paizo Inc.'s content, used under separate terms — see
NOTICE.md for the full picture. Two things relevant to using
the tools:
Bestiary, Monster Core, NPC Core, and full-adventure packs are excluded
from ingestion entirely (ingestion/build.py) — they're almost entirely
proper nouns/narrative content ("Product Identity"/"Reserved Material"
under OGL/ORC), and none of it is needed for character building.
Every rules_* tool result carries a license field
(src/pf2e_mcp/server/licensing.py) noting which regime applies (OGL
1.0a vs. the ORC License, from the ingested is_remaster flag) and
whether the entry is likely Product Identity/Reserved Material rather
than open game mechanics. Like pfs, this is a best-effort, pack-level
heuristic, not a per-entry legal determination.
Paizo releases new content and errata on a near-weekly cadence, and
foundryvtt/pf2e tracks it closely. Re-run ingestion any time to refresh:
uv run python -m pf2e_mcp.ingestion.buildThis is idempotent and safe to run repeatedly: it does a full rebuild into a temp file and atomically swaps it in, so there's no incremental-patch state to get out of sync. It also prints a changelog of entry-count deltas per pack since the last build, e.g.:
Changes since last ingestion:
feats: 6044 -> 6051 (+7)
spells: 1802 -> 1805 (+3)Check rules_data_version (or SELECT * FROM meta in the SQLite file) to
see which release is currently loaded.
About 87% of feat prerequisites are automatically parsed into structured
data: skill rank (single, or a comma/or-separated list satisfied by any
one), ability score, character level, or a named feat/feature reference
(including one with a stripped trailing category word, e.g. "muse" or
"heritage"). The rest are free-form text the parser can't confidently
structure. Those show up as "unresolved" in the prerequisites table,
surfaced to callers as an "unconfirmed" bucket rather than silently
guessed at.
To hand-fix a specific one, add it to
src/pf2e_mcp/ingestion/prerequisite_overrides.json, keyed by the exact
raw prerequisite text, then re-run ingestion. If upstream errata later
changes that feat's prerequisite wording, the override simply stops
matching and the entry reverts to unconfirmed rather than silently
applying a stale rule — check for newly-unresolved entries after a refresh
if you maintain overrides.
An override's value must include its own "kind" field, dispatched by
pf2e_math.check_single_prerequisite's override branch. Reuse an
existing kind directly if it fits — e.g. the 'Counterspell' entry
(genuinely ambiguous between 6 real Counterspell-named feats) is expressed
as {"kind": "compound_named", "any_of": [...]} to reuse that evaluator
rather than inventing a new one. spellcasting_trained is available
built-in for "you have a spellcasting class feature" style text, with an
optional "tradition" (string or list) to restrict it to specific
traditions.
src/pf2e_mcp/server/pfs_overrides.json starts empty on purpose — see
"Optional/variant rules and Pathfinder Society legality" above for why this
project doesn't ship a pre-populated ban/restriction list (no reliable
structured feed, and Organized Play rules change on their own quarterly
cadence independent of errata). Add an entry when a real exception comes up:
{
"Some Feat Name": {
"status": "banned",
"note": "Banned per Additional Resources, <season/date it changed>"
}
}status is "legal" (clears a rarity-based "restricted" flag — e.g. an
uncommon option that's actually fine in PFS), "restricted", or "banned"
(stronger than the rarity default — no boon unlocks it). Keys are matched
case-insensitively against the entry name. Unlike
prerequisite_overrides.json, this file is not baked in at ingestion
time — it's read fresh by server/pfs.py on every relevant tool call, so
edits take effect immediately.
src/pf2e_mcp/
paths.py # where the DB and download cache live
ingestion/ # pulls foundryvtt/pf2e data, builds the SQLite DB
source.py # GitHub release fetching
prerequisites.py # feat prerequisite parsing
prerequisite_overrides.json
schema.sql
build.py # orchestrates a full ingestion run
server/ # the MCP server
app.py # tool registration and entrypoint
rules_tools.py # rules_* tools
build_tools.py # build_* tools
pf2e_math.py # PF2e arithmetic and prerequisite evaluation
pfs.py # PFS-legality heuristic (rarity + override file)
pfs_overrides.json # hand-curated PFS legality exceptions (starts empty)
licensing.py # OGL/ORC + Product Identity classification heuristic
db.py # read-only SQLite connection helper
scripts/
spike_prerequisites.py # standalone prerequisite-parseability report
.claude/skills/pf2e-character-builder/SKILL.md
.github/workflows/publish.yml # tag-triggered PyPI release.github/workflows/publish.yml publishes to PyPI when a semver tag is
pushed. It uses Trusted
Publishing, so no PyPI API token
exists anywhere — PyPI verifies a short-lived OIDC token minted by GitHub for
this specific repository, workflow and environment.
One-time setup on PyPI, before the first release. Since the project isn't on PyPI yet, add a pending publisher at https://pypi.org/manage/account/publishing/:
Field | Value |
PyPI project name |
|
Owner |
|
Repository name |
|
Workflow name |
|
Environment name |
|
Then create a matching pypi environment under the repository's Settings →
Environments. Adding yourself as a required reviewer there makes every
release pause for a manual approval, which is worth doing given that a
version number, once uploaded, can never be reused.
To cut a release, bump the version, commit, then tag:
# edit pyproject.toml: version = "0.2.0"
git commit -am "Release 0.2.0"
git tag v0.2.0
git push && git push --tagsThe workflow refuses to publish if the tag and pyproject.toml disagree, so
a forgotten version bump fails loudly rather than burning the wrong version
number. It also verifies LICENSE, NOTICE.md and LICENSES/OFL-1.1.txt
are present in the built wheel — the fonts it bundles are OFL-licensed, and
that licence has to travel with them.
Level 1–20 character creation and leveling across all ancestries, backgrounds, and classes, including spellcasting and equipped-armor AC. See KNOWN_ISSUES.md for tracked gaps.
Deterministic PF2e math: AC, saves, Perception, skill totals, HP, class DC, and spell DC/attack per casting tradition the character has trained. Never left to model arithmetic -- proficiency stacking (untrained = ability mod only, no level) is easy to get wrong.
AC uses the character's worn armor (Pathbuilder's `armor` list) if
present, else the unarmored baseline, and includes the armor's potency
rune if any. Does not yet include a raised shield's bonus -- see
pf2e_math.armor_ac docstring.
HP's `attributes.ancestryhp`/`attributes.classhp` and AC's
`proficiencies.unarmored` fall back to a lookup against this project's
own ingested `ancestry_boosts`/`class_progression` data (via the
character's `ancestry`/`class` fields) when the caller doesn't supply
them explicitly -- previously a caller-side omission here silently
produced a plausible-looking-but-wrong result (confirmed live: HP
understated by ~90 points, AC by 12, for a real level-10 character
built without these three fields) rather than an error, since Python's
dict.get default masked the difference between "explicitly 0" and
"never set." The explicit-value case is preserved -- these fallbacks
only apply when the key is genuinely absent, not when it's present and
zero (e.g. a real Wizard's `classhp` isn't 0, but nothing in this
system produces a *correct* 0 for these three fields either, so
treating "key absent" as the signal to fall back is safe in practice).
| Name | Required | Description | Default |
|---|---|---|---|
| character | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and delivers extensively. It discloses the deterministic nature, the AC calculation basis (armor vs unarmored, potency rune), and a deep explanation of fallback behavior for missing HP/AC fields, including a real-world example of silent wrong results. This goes far beyond typical transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear statement, then logically organized into AC specifics and a detailed fallback explanation. It is longer than average, and the fallback paragraph is verbose, but every sentence carries important technical nuance. Not maximally concise, but not bloated either.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema is present, so return values needn't be explained. The description covers major inputs, edge cases, and limitations. It does not list all required character fields (e.g., ability scores, level), but given the tool is clearly PF2e-specific and the schema is open, the provided field references give strong context. A small gap remains for a fully self-contained spec.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is nearly empty (one generic object with additionalProperties). The description compensates by referencing concrete fields like 'armor', 'attributes.ancestryhp', 'attributes.classhp', 'proficiencies.unarmored', 'ancestry', and 'class', explaining their role and even the nuanced absent-vs-zero behavior. This gives an agent essential guidance for constructing a correct 'character' object.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly states the tool's scope: 'Deterministic PF2e math: AC, saves, Perception, skill totals, HP, class DC, and spell DC/attack per casting tradition...' This is a specific verb+resource+output list, and it distinguishes the tool from sibling build_* list/validate/render tools. No ambiguity about what it does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context (compute derived stats for a PF2e character) and explicitly notes a limitation: 'Does not yet include a raised shield's bonus'. This tells the agent when not to rely on it. However, it does not name alternative tools or explicitly say 'use this instead of manual arithmetic' in a way that contrasts with siblings. The context is clear but exclusions are minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Narrow single-feat eligibility check -- use when sanity-checking one user-proposed choice rather than re-running full discovery.
| Name | Required | Description | Default |
|---|---|---|---|
| feat_id | Yes | ||
| character | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states it's a 'check', which implies read-only, but does not explicitly confirm it has no side effects, doesn't modify the character, or what kind of result it returns. It lacks any detail on error behavior, auth, or rate limits, leaving much unsaid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the core action and usage context. Every word earns its place, and it avoids redundancy or filler, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a narrow, simple tool: it states the purpose and when to use it. However, it lacks details on input expectations (e.g., what the character object needs) and does not disclose any behavioral nuances. The presence of an output schema reduces the need to describe return values, but the overall information is still minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only mentions 'single-feat' and 'one user-proposed choice', which vaguely maps to feat_id, but gives no guidance on the 'character' object structure or the format of feat_id. The schema shows character is an open object with additionalProperties, but the description does not clarify required fields or expected shape.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a 'narrow single-feat eligibility check', identifying the action (eligibility check) and resource (a single feat). It distinguishes from siblings by contrasting with 'full discovery', so its purpose is specific and not easily confused with broader build tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'use when sanity-checking one user-proposed choice rather than re-running full discovery', providing clear context of when to use it. It implies a lightweight, targeted scenario and distinguishes from heavier alternatives, though it doesn't enumerate specific sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What unlocks at target_level for the character's class: which feat categories/skill increases become available (from the class's structured level-gate arrays) plus any automatically-granted class features (no choice required). Ability boosts are always at 5/10/15/20 per core PF2e rules, not class-specific data.
`variant_rules` is a list of slugs for optional/variant rules this
build is using -- see rules_list_variant_rules for the full catalog and
rules_get_entry for each one's official text. Only two currently change
what this function reports (the rest are recognized as valid slugs but
don't affect the computed unlocks yet):
- `'ancestry-paragon'` (GM Core p.194): 2 ancestry feats at level 1
instead of 1, then one more at every odd level (3, 5, 7, 9, ...)
instead of the class's normal 1/5/9/13/17 schedule. Reflected in
`unlocks.ancestry_feat_count`.
- `'free-archetype'` (GM Core p.84): one bonus archetype-only feat at
every even level. Reflected in `unlocks.archetype_feat` -- when true,
call build_list_available_feats(feat_category='archetype') for that
slot specifically, in addition to whatever the normal class-feat slot
allows this level.
| Name | Required | Description | Default |
|---|---|---|---|
| character | Yes | ||
| target_level | Yes | ||
| variant_rules | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavior disclosure. It transparently explains that only two variant rules affect the output, that other valid slugs are recognized but ignored, and describes the exact effect of each relevant rule. It does not mention mutation or side effects, but the tool name implies a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, opening with the main purpose before detailing variant rules. The dash-separated list for variant-rule edge cases is scannable, and every sentence adds meaningful information without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has high complexity due to level-gate arrays and variant rules, and the description covers the core behaviors, variant effects, and related tool calls. The existence of an output schema reduces the need to document return values, though the character parameter structure and potential error conditions are not addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It thoroughly explains `variant_rules` and clarifies that `target_level` is the level at which unlocks are computed. However, `character` is only referenced as containing the character's class, leaving its structure underdefined even though it is a required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool reports what unlocks at a target level for the character's class, including specific content like feat categories, skill increases, and automatically-granted class features. This verb+resource+scope formulation distinguishes it from sibling tools by describing a consolidated level-up view.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives practical guidance by noting ability boosts follow core PF2e rules rather than class-specific data, and it explicitly tells the caller to use build_list_available_feats for archetype-feat slots when the free-archetype variant rule is active. However, it does not broadly contrast with all sibling tools or provide a general 'when not to use' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Eligible ability score boosts for the given source, respecting ancestry flaws and boosts already recorded in character.abilities.breakdown (Pathbuilder's own per-level boost history field -- see the plan's Pathbuilder-schema findings). Does not yet cross-check the "can't take two free boosts in the same ability at the same tier" rule beyond what's already recorded in breakdown for this source; full multi-source interaction (e.g. voluntary ancestry flaws freeing up a boost) is left to validate_build.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ||
| character | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and it does so excellently. It discloses exactly which data sources are respected (ancestry flaws, Pathbuilder's breakdown field), what is not yet checked (the two-free-boosts rule), and what is delegated elsewhere. This is transparent about the tool's internal logic and limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat long but every clause carries important information. It front-loads the core purpose, then adds caveats and redirects. No filler words or redundant statements, but it could be slightly tightened without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of ability boost rules and the presence of an output schema, the description is sufficiently complete. It explains the source parameter, the integration with Pathbuilder's breakdown, the known exception not handled, and points to validate_build for full cross-source validation. This gives an agent all necessary context to decide whether and how to invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the parameter meanings. It explains that 'source' is one of the enum values and clarifies how 'character' is used (specifically its abilities.breakdown field). This adds significant meaning beyond the bare schema, though it doesn't describe the full structure of the character object.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: lists eligible ability score boosts for a given source. It names the specific resource (ability boost options), the input (source), and the constraints (ancestry flaws, recorded boosts). This clearly distinguishes it from sibling tools like build_list_skill_increase_options or build_list_available_feats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool (for a single source's boosts) and when not to use it (for full multi-source interaction), pointing to validate_build as the alternative. It also notes the known limitation about the 'two free boosts' rule, giving clear usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List playable ancestries, optionally filtered by name substring.
`include_legacy` (default False): excludes pre-Remaster/OGL-flagged
ancestries unless set -- but 38% of ancestries are legacy-flagged and
still fully playable (not reprinted under ORC yet isn't the same as
retired), so set this True whenever the user wants the full catalog,
not just what's been individually remastered. See `_legacy_filter_sql`.| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | ||
| include_legacy | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses a key behavioral trait: legacy-flagged ancestries are excluded by default, and explains that 38% are still playable. This goes beyond a simple 'list' and arms the agent with important context, though it omits minor details like sorting or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately sized and front-loaded with the main purpose. The detailed explanation of include_legacy is valuable, but the internal reference 'See `_legacy_filter_sql`' is an implementation detail that adds little for an agent. Overall, it is concise and well-structured, earning a high score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no nested objects) and the presence of an output schema (so return values need not be explained), the description is complete. It covers the primary purpose and the non-obvious legacy behavior, which is sufficient context for an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates: 'filter' is clarified as a name substring, and 'include_legacy' is explained in depth, including its default behavior and the 38% legacy-flagged ancestries. This adds meaning beyond the bare schema types, though it doesn't provide explicit syntax or examples for the filter parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List playable ancestries, optionally filtered by name substring.' This specifies the verb (list), resource (playable ancestries), and optional filtering. It distinguishes itself from sibling tools like build_list_backgrounds and build_list_classes by focusing specifically on ancestries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to set the include_legacy parameter, advising to set it True when the user wants the full catalog. It does not explicitly mention alternative tools or exclusions, but the tool's purpose and siblings make selection obvious, and the parameter guidance is a useful decision point for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The main token-saving discovery tool: returns only feats of the requested category at or below the target level (character's current level if unspecified) whose prerequisites the character already meets, instead of the caller reasoning over the full feat list or raw rules text. Split into two buckets:
- "available": prerequisites confirmed satisfied (or none required).
- "unconfirmed": at least one prerequisite couldn't be automatically
verified (freeform text the parser can't structure -- roughly 16% of
all feats per the Phase 0 parsing spike). Never silently included in
"available" -- surface these to the user for manual confirmation.
Feats that definitely fail a prerequisite, or that the character
already has, are omitted entirely.
"class" and "ancestry" feats are further restricted to the character's
own class/ancestry (matched via the feat's trait list, e.g. a Fighter
class feat carries the "fighter" trait) -- category alone only narrows
to "any class feat from any class".
"archetype" is a special case: the source data has no "archetype"
category value at all (confirmed against the real data -- every
archetype/dedication feat is stored as category "class" or "skill",
with "archetype" appearing only as a trait). This matches actual PF2e
rules: archetype feats are taken using ordinary class or skill feat
slots, not a separate slot type. This function queries for the
"archetype" trait within those two categories instead. It does not
filter further to one specific chosen archetype (e.g. "only Alchemist
archetype feats") -- that gating already happens naturally through each
feat's own prerequisite (e.g. "Alchemist Dedication"), checked the same
way as any other prerequisite.
Every returned entry also carries `rarity` and a best-effort `pfs`
legality status (not authoritative -- see pfs.py module docstring),
so a PFS-bound build can be steered away from restricted picks without
a separate lookup per feat.
`include_legacy` (default False): excludes pre-Remaster/OGL-flagged
feats unless set. See `_legacy_filter_sql`.
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | ||
| character | Yes | ||
| feat_category | Yes | ||
| include_legacy | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels. It discloses the two output buckets ('available' vs 'unconfirmed'), the rule that unconfirmed feats are never silently included, and the omission of failing/owned feats. It also honestly notes that pfs legality is 'best-effort' and 'not authoritative,' and explains the archetype data anomaly in detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured and front-loaded with the core purpose. Each paragraph addresses a distinct aspect: output buckets, filtering logic, archetype special case, and return metadata. Some redundancy exists (e.g., restating PF2e rules context), but for the tool's complexity, the length is justified and every major section adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description is remarkably complete. It covers output semantics, filtering edge cases, category-specific behavior, legacy filtering, and added metadata. The presence of an output schema reduces the need to explain return values, but the description already covers what appears in each entry (rarity, pfs status). It fully equips an agent to decide when and how to invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains level defaults to character's current level, feat_category includes the special 'archetype' handling, and include_legacy default behavior is described. The character parameter is implied through repeated references to 'character's own class/ancestry' and 'current level,' providing enough context for an agent to understand its role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: a 'token-saving discovery tool' that 'returns only feats of the requested category at or below the target level whose prerequisites the character already meets.' This clearly distinguishes it from sibling tools like rules_search and build_check_prerequisite by emphasizing its filtering and token-saving role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool: instead of reasoning over the full feat list or raw rules text. It also provides when-not guidance by explaining that feats failing prerequisites or already owned are omitted, and that archetype feats are queried via trait within class/skill categories. Special cases like class/ancestry restrictions and include_legacy behavior are thoroughly covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Spells of the given tradition at or below the highest rank the character can currently access, plus (new) the character's actual spell slot counts by rank for their level, when their class has one.
Rank cap resolution, in order: an explicitly-passed `max_rank` always
wins (needed for a caster archetype/dedication, where `character.class`
itself isn't the caster and so has no row in `class_spell_slots` at
all); otherwise the character class's own real slot table (see
`_class_spell_slots`) if it has one -- this replaces the standard
full-caster `ceil(level/2)` heuristic with the class's actual
progression, which matters for Magus/Summoner specifically (both delayed
relative to full casters, and non-monotonic -- they only ever hold 2
active ranks at once); if neither applies (the character's class isn't
a recognized caster at all), falls back to the `ceil(level/2)`
heuristic same as before, since a caller may still be probing a
non-standard tradition/dedication combination this project can't
resolve on its own.
`spell_slots` in the result is the real per-rank slot table when the
class has one, else `None` (honestly "not known," not a guess) --
resolves the previous "spell slots aren't modeled at all" gap for every
class with real ingested data.
Cantrips are stored in the source data with `level: 1` (they
auto-heighten to half the caster's level) rather than rank 0, so they'd
otherwise be indistinguishable from true 1st-rank slotted spells --
each result is tagged `is_cantrip` to keep that mechanical distinction
visible (cantrips are at-will, leveled spells consume slots).
`include_legacy` (default False): excludes pre-Remaster/OGL-flagged
spells unless set. See `_legacy_filter_sql`.| Name | Required | Description | Default |
|---|---|---|---|
| max_rank | No | ||
| character | Yes | ||
| tradition | Yes | ||
| include_legacy | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the tool's behavior: rank cap resolution order, fallback logic, spell_slots null semantics, cantrip tagging, and the include_legacy flag effect. It even explains the discrepancy in source data leveling for cantrips.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is quite long and dense, but it is organized into logical paragraphs with clear topics. While every sentence adds value, it could be more concise without losing important edge case details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all key behaviors, including edge cases like Magus/Summoner non-monotonic progression and legacy filtering. With an output schema present, the description sufficiently explains the tool's overall functionality and return semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description compensates by explaining max_rank precedence, include_legacy default, and character class usage. It also clarifies how tradition and character interact, giving meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists available spells for a given tradition based on rank, and also provides spell slot counts. It distinguishes itself from sibling tools by focusing on spells and slot data, with explicit references to class progression and cantrip handling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides significant usage context, explaining when max_rank is needed, when the class's own slot table applies, and when the fallback heuristic is used. It does not explicitly name alternative tools, but clearly defines the scenarios this tool is designed for.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List backgrounds, optionally filtered by name substring.
`trained_skills` (`{"fixed": [skill slugs], "lore": [Lore skill names]}`)
and `granted_items` (`[{level, name, uuid}]`, `level` always null for a
background -- granted at character creation) come straight from the
background item's own structured `system.trainedSkills`/`system.items`
fields, the same mechanism `build_list_classes` already exposes for
classes -- e.g. Field Medic: trained_skills `{"fixed": ["medicine"],
"lore": ["Warfare Lore"]}`, granted_items `[{"name": "Battle
Medicine", ...}]`.
`include_legacy` (default False): excludes pre-Remaster/OGL-flagged
backgrounds unless set -- 54% of all backgrounds are legacy-flagged and
still fully playable, the single largest exclusion of any pack this
filter touches. See `_legacy_filter_sql`.| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | ||
| include_legacy | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses that trained_skills and granted_items come from specific system fields, that level is always null, and details the significant impact of include_legacy (54% legacy-flagged, still playable). This provides meaningful behavioral context beyond just 'list'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately detailed but well-structured, with separate sections for output fields and include_legacy. The mention of `_legacy_filter_sql` is cryptic but not overly distracting, and each substantial part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description adds important context by explaining the nested structure of trained_skills and granted_items and the legacy filter's practical implications. It covers the key aspects needed for an AI agent to use the tool correctly, though it omits potential details like ordering or pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description thoroughly explains both parameters: filter as a name substring and include_legacy's default and meaning. It also gives concrete examples of output structures, adding context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it 'List backgrounds' with an optional name substring filter. This specific verb+resource combination unambiguously distinguishes it from sibling tools like build_list_classes and build_list_ancestries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving background lists and references build_list_classes for comparison, but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. It explains parameter behavior but not usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List classes, optionally filtered by name substring. Includes each
class's level-1 initial proficiency baseline (HP, Perception, saves,
trained skills formula, weapon/armor proficiencies) -- sourced directly
from the class item's own data rather than requiring the caller to
recall or look this up externally. Proficiency ranks in the returned
perception/fortitude/reflex/will/class_dc/attacks/defenses
fields use this project's 0/2/4/6/8 convention (untrained/trained/
expert/master/legendary), the same as a character's proficiencies
dict elsewhere -- ready to drop into a draft character directly.
Note this is the class's own *baseline* only -- doctrine/subclass
choices (e.g. Cleric's Warpriest doctrine granting expert Fortitude and
martial weapons) and later automatic class features (e.g. Champion's
Weapon Expertise at level 5) can raise these further; this call doesn't
know about either, only what every member of the class starts with at
level 1.
**`trained_skills.additional` is the class's own flat baseline ONLY --
it does NOT include the Intelligence-modifier bonus to additional
trained skills that every class gets at character creation** ("...
becomes trained in a number of skills equal to [class value] plus your
Intelligence modifier" -- Player Core, Skills step of character
creation). This is a genuinely easy value to miscount: confirmed live
building a level-10 Magus with Int 14 (+2) where only 2 additional
skills were picked instead of the correct 4. The caller is responsible
for adding `max(0, ability_mod(character's Int score))` to this value
themselves before presenting a skill count to the user; `validate_build`
now includes a floor check for this specifically (see
`_validate_trained_skill_count`) but it's a warning after the fact, not
a substitute for getting the count right when first proposing it.
`trained_skills.choice`, when present, is a class's "trained in X **or**
Y" pattern (e.g. Fighter's Acrobatics-or-Athletics) that `fixed` alone
can't represent -- sourced from the class item's own ChoiceSet rule
element (see `item_choice_sets`), not from `fixed` being silently
incomplete.
`include_legacy` (default False): excludes pre-Remaster/OGL-flagged
classes unless set -- currently a no-op (every class chassis has been
reprinted under ORC, so all 29 are is_remaster:1), kept for API
consistency with the other `list_*` tools and in case a future release
adds a class before its own remaster reprint. See `_legacy_filter_sql`.| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | ||
| include_legacy | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It extensively discloses behaviors: the 0/2/4/6/8 proficiency rank convention, the fact that this is 'baseline only' excluding subclass/later features, the no-op status of include_legacy, and detailed caveats about the trained skills count. This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but structured with clear paragraphs and bold text, front-loading the core purpose before diving into caveats. While some internal details like `_legacy_filter_sql` and the Magus anecdote could be trimmed, the length is justified by the complexity of the output semantics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool and the presence of an output schema, the description covers the necessary behavioral context: the meaning of the returned proficiency ranks, the baseline vs. subclass distinction, the trained skills calculation gotcha, and the parameter semantics. It leaves little ambiguity for an agent to misuse the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain the parameters. It adequately describes `filter` as a name substring, and it thoroughly explains `include_legacy` including its default, its current no-op status, and the reason for its existence. Although `filter` lacks details like case sensitivity, the description adds meaning far beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List classes, optionally filtered by name substring', which clearly states the verb and resource. It further specifies that it returns level-1 proficiency baselines and distinguishes itself from generic list tools by noting the data source. The purpose is specific and distinguishes from sibling list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: for obtaining class baseline stats for a draft character, with a caution that it does not account for doctrine/subclass choices or later automatic features. It also explains that the caller must add the Intelligence modifier to `trained_skills.additional`, which is a usage directive. However, it does not explicitly name alternative tools for those other needs, so it falls short of fully explicit alternative selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browse the equipment pack (weapons, armor, shields, gear) by name substring, item type, and/or maximum price. A fresh level-1 character has STARTING_WEALTH_GP (15) gold pieces to spend using the standard "starting money" method -- returned alongside results as a reminder, not a per-call lookup, since it's a fixed constant.
`include_legacy` (default False): excludes pre-Remaster/OGL-flagged
equipment unless set. See `_legacy_filter_sql`.| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | ||
| item_type | No | ||
| max_price_gp | No | ||
| include_legacy | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden. It reveals that STARTING_WEALTH_GP is returned alongside results as a reminder, explains the default behavior of include_legacy, and references the legacy filter SQL, adding transparency about filtering behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The main purpose is stated in one sentence, followed by context about starting wealth and a parameter detail. The reference to `_legacy_filter_sql` could be trimmed, but the description remains focused and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple list operation with an output schema. The description covers filtering, default behavior, and the starting wealth caveat, making it sufficient for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by naming the filter criteria ('name substring, item type, and/or maximum price') and explicitly explaining include_legacy's default and meaning. All four parameters are effectively documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Browse the equipment pack (weapons, armor, shields, gear) by name substring, item type, and/or maximum price.' This clearly identifies the resource (equipment) and the verb (browse), and distinguishes it from sibling tools that list other character options like ancestries or classes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly mention alternatives, but the context of sibling tools (e.g., build_list_ancestries, build_list_classes) makes it clear this is for equipment. It also sets expectations for use during character building by referencing starting wealth and legacy filtering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Which of the 16 core skills are legal to raise one rank right now, given the character's current level and current rank in each (the trained/expert/master/legendary level-3/7/15 caps are a fixed core rule, independent of class). Does not consult skillIncreaseLevels itself -- call build_get_level_up_choices to confirm a skill-increase choice is actually available at the target level before offering these.
| Name | Required | Description | Default |
|---|---|---|---|
| character | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses a key behavioral limitation: it does not consult skillIncreaseLevels itself, and it clarifies the fixed caps rule. However, it does not explicitly state that it is a read-only operation, though this is implied by 'list'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main purpose, and each sentence adds valuable context. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has an output schema, the description does not need to explain return values. It covers the core rule, the limitation, and the relationship to a sibling tool, making it complete for a list-like tool with good annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With one parameter 'character' that has no schema description, the description compensates by indicating that the character's current level and current ranks are required. It does not detail the full object structure, but the key inputs are identified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: lists which of the 16 core skills can be legally raised by one rank given current level and ranks. It distinguishes itself from build_get_level_up_choices by explicitly naming that as the confirmation tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use this tool (to list legal skill increases) and when not to (to confirm availability, use build_get_level_up_choices). Also explains the fixed caps rule, clarifying that it applies regardless of class.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a print-ready, fully self-contained HTML character sheet and return a summary of what went onto it.
The rendered file has no external dependencies of any kind -- fonts are
inlined as base64 WOFF2, all ornament is generated inline SVG, and there
is no stylesheet, script, or image fetched at view time -- so it can be
sent to a player as a single attachment and printed unchanged. Open it and
use the browser's own Print dialog (enable background graphics).
The HTML is written to `output_path` and deliberately not returned: a
real sheet runs to 150 KB or more, which would swamp a tool response.
Sections rendered, each only when the character data supports it:
core statistics (attributes, skills, AC and shield, saves, HP,
Perception, strikes, spell DC, conditions tracker); one spellcasting
page per entry in `spellCasters`, with every spell's complete rules text
and traits; features, led by a deity block where there is one (see below)
and then ancestry, heritage, background, level-appropriate auto-granted
class features, any detected subclass, and every feat; equipment with item
rules text; a notes page showing how each number was derived; and a licence
attribution page listing only the sourcebooks actually quoted.
The deity block distinguishes three cases, reported as `deity.status`:
* `none` -- the character follows no deity, including when the export
writes its own placeholder ("Not set", an empty string, a dash). No
block is rendered.
* `resolved` -- the recorded name matched the rules data. Renders every
mechanical field the game defines (divine font, sanctification, skill,
favored weapon, primary and alternate domains, divine attribute, and the
deity's cleric spells resolved to names by rank) followed by its full
descriptive text: title, areas of concern, edicts, anathema, iconography.
Pantheons, covenants and philosophies resolve here too, labelled as such.
* `unrecognized` -- a name is recorded but isn't in the database, i.e. a
home-game or non-standard pantheon. Renders a labelled block with ruled
lines for the standard fields to be filled in by hand. This is *not*
treated as a defect in the character data and is deliberately kept out
of `unresolved`.
Everything is derived from `character` plus this project's ingested rules
data -- there is no authored commentary, so a sheet is exactly as complete
as the character export it came from. Two things follow from that worth
knowing before you call it:
* A character with no `spellCasters` block gets no spell pages, even if
the class is a caster. Pathbuilder exports populate it; hand-written
character JSON often doesn't.
* Class features come from the ingested `class_progression.granted_items`
filtered to the character's level, because exports record only choices.
A subclass (cleric doctrine, druid order) is recovered by matching the
class's tagged option names against the character's free-text
`specials`, which is best-effort -- check `subclass` in the result.
`paper` accepts 'letter' (default) or 'a4'; it sets the @page size, and
content reflows rather than being scaled.
`logo_path` embeds an image top-left on page 1 in place of the sheet's own
spiral mark -- intended for the Pathfinder logo from Paizo's Community Use
Package, which the Community Use FAQ permits on free fan material. Accepts
PNG, SVG, JPEG, GIF or WebP (not EPS or AI, which browsers can't display).
The bytes are embedded verbatim and scaled by height with automatic width,
so the logo is never recoloured, cropped or distorted -- the policy forbids
altering a logo's colour, typography, design or proportions, and permits
proportional resizing. Section headings keep the spiral, so the sheet still
has a mark of its own. Omit to use the spiral everywhere.
`symbol_dir` points at a directory of deity symbol images named after the
deity ("Pharasma.png"), such as Paizo's Community Use "Pathfinder Religious
Symbols" pack -- underscores in place of spaces are matched too, so
"Sun_Wukong.png" resolves. When the character's deity resolves and a
matching file exists, the symbol is embedded beside the deity block's stat
table, again scaled by height only. A missing symbol is not an error: the
block simply renders without one.
Returns a dict with the output `path` and `bytes`, the `sections` written,
counts of what was rendered, the detected `subclass`, the sourcebooks
quoted under each licence, and -- importantly -- `unresolved` names and
`warnings`. An item the export calls "Repair Kit" where the rules data has
"Repair Toolkit" is reported there rather than guessed at or dropped
silently, so treat a non-empty `unresolved` as something to fix in the
character data.
| Name | Required | Description | Default |
|---|---|---|---|
| paper | No | letter | |
| character | Yes | ||
| logo_path | No | ||
| symbol_dir | No | ||
| output_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description thoroughly discloses behavior: output is written to disk and not returned, fonts are inlined, deity statuses have three distinct cases, unresolved items are reported, and logo embedding follows licensing constraints. This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Although long, every paragraph earns its place by covering a distinct aspect: output format, section list, deity handling, parameter details, and return value. The structure is front-loaded with the core purpose and flows logically, making it easy to navigate despite the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the absence of annotations, the description is exceptionally complete. It covers behavior, edge cases, parameter semantics, and the return dict, leaving little room for misinterpretation. It even explains why certain data might be missing and how to interpret warnings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameter descriptions, yet the description explains every parameter in depth: character, output_path, paper (letter/a4 defaults), logo_path (accepted formats, scaling behavior), and symbol_dir (matching rules). It fully compensates for the schema's lack of guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly states the tool's purpose: to write a print-ready, self-contained HTML character sheet and return a summary. This specific verb+resource formulation distinguishes it from sibling tools like build_to_pathbuilder_export or build_validate_build.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides rich context on when to use the tool (e.g., sending a printable sheet to a player) and highlights important caveats before calling (e.g., lack of spellCasters means no spell pages). It does not explicitly name alternative tools, but the use-case is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wrap the working character representation as a Pathbuilder-compatible
export. The working schema already follows Pathbuilder's build shape
(per the user's decision -- see the plan's Pathbuilder-schema
findings), so this is a normalize/strip pass rather than a full
transform: drop any internal-only keys (none introduced in Phase 1) and
wrap in the {success, build} envelope real exports use.
| Name | Required | Description | Default |
|---|---|---|---|
| character | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently explains that this is a normalize/strip pass (not a full transform), mentions dropping internal-only keys, and specifies the output envelope {success, build}. This provides useful context about what happens during the operation, though it does not cover side effects or permissions (which are likely irrelevant for a local transform).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary purpose in the first sentence. The second sentence adds useful implementation details but includes internal references like 'plan's Pathbuilder-schema findings' and 'Phase 1', which could be confusing without context. Overall it is reasonably concise and well-structured, with minor extra jargon.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (one nested param, output schema present), the description is fairly complete. It covers the transformation approach, the output envelope, and the parameter's expected shape. It does not describe failure modes or edge cases, but the combination of description and output schema provides sufficient context. The internal references slightly reduce universal completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has only one parameter 'character' with no description and 0% schema_description_coverage, so the description must compensate. It does by clarifying that the character is the working representation and already follows Pathbuilder's build shape, which adds semantic meaning beyond the bare 'object' type. However, it does not detail specific required subfields, but given the permissive schema (additionalProperties true), this is reasonable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: wrapping the working character representation into a Pathbuilder-compatible export. It distinguishes from siblings by specifying the output format (Pathbuilder) and describing the operation as a normalize/strip pass rather than a full transform, which differentiates it from tools like build_render_character_sheet or build_validate_build.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a Pathbuilder-compatible export is needed, but it does not explicitly state when to use this tool versus alternatives or mention exclusions. The context about the schema already following Pathbuilder's shape gives some situational background, but there is no direct guidance on selecting this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Structured validation, not prose -- returns errors (definite rule
violations) and warnings (things that couldn't be auto-verified and
need human confirmation). Covers: duplicate feats, prerequisites of
every taken feat still being satisfied (important after e.g. a
hypothetical ancestry swap mid-build), skill ranks not exceeding the
fixed level-3/7/15 expert/master/legendary caps, whether the number of
ancestry-category feats taken fits the character's actual budget for
their level, and (new) the archetype "one dedication feat at a time"
rule -- a level-ordered check that no dedication feat was taken while
an earlier, different dedication still needed two other archetype
feats first (see _validate_dedication_exclusivity; this is validation
this project does that Foundry's own reference implementation doesn't
attempt either -- confirmed nothing in its source enforces it), and
(new) a warning for any fixed (non-player-choice) trained skill or
Lore the character's background/class grants but that isn't actually
trained on the character (see _validate_fixed_trained_skills --
deliberately scoped to just the fixed/unconditional grants, not the
player's free "additional" choices, since those can't be cleanly told
apart from later Skill Increases without risking a false positive at
higher levels), (new) a warning if the character's total count of
trained-or-better skills/lores is below the level-1 minimum implied by
class fixed+additional skills, background fixed/lore/choice skills, and
the character's Intelligence modifier if positive -- a floor check, not
an identity check, so it stays valid at any level (see
_validate_trained_skill_count; this exists specifically because the
Intelligence-modifier bonus to a class's additional trained-skill count
is a universal core rule not baked into list_classes' additional
field, and is easy to silently drop), and (new) a warning for any
save/Perception/weapon/
armor/class-DC proficiency rank that's lower than what the
character's class baseline plus its granted class features/taken feats
up to their level should produce (see _validate_proficiency_ranks).
Does NOT yet check ability-boost-tier double-ups across sources, or
spellcasting proficiency specifically (tradition-dependent -- see
_validate_proficiency_ranks's docstring for why that one key is
skipped).
`variant_rules` (see rules_list_variant_rules / get_level_up_choices)
changes the ancestry-feat budget when `'ancestry-paragon'` is included
(2 feats at level 1, one more at every odd level, instead of the
class's normal 1/5/9/13/17 schedule), and adds a soft, non-blocking
note about archetype-trait feat count when `'free-archetype'` is
included -- that one is a warning rather than an error because this
server doesn't track class/skill-feat-slot usage at all, so it can't
tell a normal-slot archetype feat apart from a free-archetype bonus
slot with certainty; only ancestry feats get a hard budget check, since
'ancestry' is otherwise never used as a normal class/skill/general feat
slot. The **Ancestral Paragon** general feat (a real, always-available
pick independent of any variant rule) adds +1 to the ancestry budget on
its own if taken.
`pfs_legal_only=True` adds a warning for any taken feat whose
best-effort PFS status (see pfs.py) isn't 'legal' -- not authoritative,
see that module's docstring.| Name | Required | Description | Default |
|---|---|---|---|
| character | Yes | ||
| variant_rules | No | ||
| pfs_legal_only | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers thoroughly. It explains the error/warning distinction, details each validation check, describes how variant_rules changes behavior, notes the soft/non-blocking nature of some warnings, and discloses limitations (e.g., no ability-boost double-up check, no spellcasting proficiency). It even provides rationale for scoping decisions (e.g., fixed trained skills warning).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very long and includes parenthetical references to internal function names and docstrings, which adds noise. However, it is front-loaded with the main purpose and logically organized: validation categories first, then variant rules and parameter effects. Most sentences add meaningful information, but it could be tightened by removing some internal implementation details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters, one nested object, and an output schema, yet the description covers all key aspects: return types (errors/warnings), validation scope, parameter effects, limitations, and even the distinction from Foundry's implementation. It is complete enough for an agent to use correctly without additional lookups, despite the moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does so excellently: it explains variant_rules values ('ancestry-paragon', 'free-archetype') and their effects, and describes pfs_legal_only semantics with caveats. The 'character' parameter's meaning is inherently clear from the tool's purpose. Nearly all parameter intent is covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool validates builds and returns structured errors and warnings. It enumerates specific validation categories (duplicate feats, prerequisites, skill caps, ancestry budget, archetype dedication, etc.), which distinguishes it from sibling tools like build_check_prerequisite. The verb-resource pair is explicit: 'build_validate_build' validates a character build.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives strong context on when the tool is appropriate (full build validation) and lists limitations ('Does NOT yet check...'), but it does not explicitly name alternatives or say 'use this when validating an entire build'. The scope is clear, though exclusions for alternative tools are implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report which foundryvtt/pf2e release the current rules database was built from.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It fully states the output (which release the database was built from) and implies no side effects. As a read-only reporting tool, this is transparent and sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that conveys the exact action and result with no wasted words. It is optimally structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a trivial tool with no parameters and an output schema available. The description is complete for understanding what the tool does and what it returns, requiring no additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so per the rubric baseline is 4. The description adds no parameter information because there are none to explain, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Report' and clearly identifies the resource (foundryvtt/pf2e release) and scope (current rules database). It distinctly separates this tool from sibling search/build tools, which all focus on querying or manipulating rules data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use when needing to know the database version, but there is no explicit guidance on when to use it vs alternatives or any exclusions. It is self-evident enough for a simple version query, but lacks explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explain a rules topic (e.g. a condition or general rule) by full-text searching content most likely to hold rules text (conditions, actions, glossary entries) and returning descriptions inline, since the point is a direct answer rather than a lookup requiring a follow-up call.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| topic | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose the full-text search approach, the targeted content types (conditions, actions, glossary entries), and the inline return behavior. However, it does not state read-only status, permissions, or potential side effects, leaving some behavioral transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence that front-loads the verb and object, then efficiently adds search scope and the rationale for its inline behavior. Every word earns its place, with no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search/explain tool, the description covers the tool's goal, method, and key differentiator from sibling lookups, which is sufficient for an agent to select and invoke it. The output schema presumably documents return values, so the lack of return-format detail is not a gap. However, it could be more complete by explicitly naming sibling alternatives or mapping to the limit parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description implies the 'topic' parameter by saying 'Explain a rules topic', but it does not mention the optional 'limit' parameter or its default/value range. With 0% schema description coverage, the description only partially compensates for parameter documentation, though the two-parameter surface makes the missing 'limit' detail a moderate gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Explain' and identifies the resource as 'a rules topic', clearly stating what the tool does. It also distinguishes itself from sibling lookup tools by emphasizing 'a direct answer rather than a lookup requiring a follow-up call', which positions it uniquely against rules_search and rules_get_entry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly frames the tool as the one to use when a direct answer is needed ('returning descriptions inline') versus a lookup that requires follow-up, giving clear context for when to use it. It does not explicitly name alternative sibling tools or state when not to use it, but the inline-vs-lookup contrast provides usable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single PF2e entry's full detail (description, traits, raw data) by id, exact name, or slug. Provide exactly one of the three.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| name | No | ||
| slug | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the entry includes 'description, traits, raw data' and that matching is by 'exact name' or slug. However, it does not state behavior for missing entries, multiple identifiers provided, or error conditions. The 'Provide exactly one' hint partially covers misuse but not edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and resource. Every clause adds value: what is fetched, via which identifiers, and the exclusivity constraint. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values don't need description. The description covers the essential input constraint and the nature of the output. Minor gaps include not-found behavior and error handling, but the overall context is sufficient for a low-complexity fetch tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It explains that id, name, and slug are alternative selectors and that exactly one must be provided. This adds meaning beyond the raw schema (which only lists nullable properties with defaults), though it does not detail the format for each identifier.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Fetch a single PF2e entry's full detail (description, traits, raw data) by id, exact name, or slug.' It uses a specific verb ('Fetch') and resource ('single PF2e entry'), and distinguishes from siblings like rules_search by emphasizing 'single' and 'full detail'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it fetches a single entry by exactly one of three identifiers, with the explicit constraint 'Provide exactly one of the three.' However, it does not explicitly mention when to prefer this over alternatives like rules_search or rules_related, so it misses the 'when-not' guidance for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every subclass-style choice-group tag found in the ingested
data -- e.g. 'animist-apparition', 'sorcerer-bloodline', 'druid-order',
'witch-patron', 'cleric-doctrine', 'barbarian-instinct' -- one tag
family per class that has this kind of choice (order/practice/
doctrine/patron/instinct/mystery/muse/racket/style/...). Each of these
is a real level-1-or-later pick with mechanical consequences (e.g. a
Druid Order or Animist Practice can outright grant a bonus feat), but
nothing else in this server can enumerate them -- build_list_classes
only returns a class's flat level-1 baseline, with no concept of
sub-choices. Call rules_list_subclass_options with one of the tags
returned here to get its actual member options, their full mechanical
description text, and a structured grants field for anything each
option automatically grants (e.g. Shaman practice granting Spirit
Familiar) -- sourced from exact GrantItem data, not parsed from
prose.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses the scope ('every...found in the ingested data'), the grouping ('one tag family per class'), and the data source ('exact GrantItem data, not parsed from prose'). While it implies a read-only list operation, it does not explicitly state that it has no side effects or other behavioral constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but every sentence earns its place: it gives the purpose with examples, clarifies the grouping and importance, differentiates from a sibling, and provides forward guidance. It is front-loaded with the main action and uses concrete examples throughout without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with an output schema, the description is complete. It describes what is returned, why the tool is needed, how it relates to other tools, and what to do next. It even notes the data source and the 'grants' field behavior without over-explaining since the output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100% (trivially), so the baseline is 4. The description adds useful context by explaining that the output tags are intended as inputs to `rules_list_subclass_options`, but since there are no parameters, there is nothing more to clarify.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'List every subclass-style choice-group tag found in the ingested data', followed by concrete examples. It clearly distinguishes itself from siblings by explicitly contrasting with `build_list_classes` and pointing to `rules_list_subclass_options` as the next step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'nothing else in this server can enumerate them', and provides an alternative exclusion: `build_list_classes` only returns a flat baseline. It also gives direct usage instructions by telling the caller to invoke `rules_list_subclass_options` with a returned tag.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every option in a subclass-style choice group by its exact tag
(see rules_list_subclass_option_groups for valid values -- tag
matching is exact, not fuzzy, since e.g. Inventor's two groups
('weapon-innovation-modification'/'armor-innovation-modification')
don't share a class-name prefix the way most others do, so guessing a
class-name-based filter would silently miss real groups). Returns full
entries (with description, plus grants -- anything the option
automatically grants, e.g. Shaman practice granting Spirit Familiar --
and stat_modifiers -- numeric/proficiency changes, e.g. an order's
skill training -- both sourced from structured GrantItem/
ActiveEffectLike data, not parsed from prose) rather than summaries,
since the point of this tool is seeing what each option actually does
in one call.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully covers behavioral details. It explains exact tag matching with a concrete example, the return format (full entries including grants and stat_modifiers), and that these fields come from structured GrantItem/ActiveEffectLike data, not prose. This is highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action, then provides necessary rationale and return details. It is longer than the ideal two-sentence summary, but each clause adds value, and the structure is logical and free of filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter, no schema descriptions, and no annotations, the description is remarkably complete. It covers what the tool does, how to use it correctly, what the output contains, and why the design choices were made. The existence of an output schema means the return structure is already documented elsewhere.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines 'tag' as a string with no description. The description compensates by explaining what a valid tag is, pointing to the sibling group tool, and illustrating why exact matching matters with real tag examples. This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists every option in a subclass-style choice group by exact tag, distinguishing it from the sibling rules_list_subclass_option_groups. It also specifies that it returns full entries rather than summaries, further clarifying its unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly references rules_list_subclass_option_groups for valid tag values and explains why exact matching is necessary to avoid missing groups. It warns against guessing class-name-based filters, providing clear context. It does not explicitly state when not to use the tool, but the guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browse the optional/variant character-building and subsystem rules ingested from GM Core's "Subsystems and Variant Rules" section (what Pathbuilder and most tables call "optional rules") -- Free Archetype, Ancestry Paragon, Proficiency without Level, Gradual Attribute Boosts, Automatic Bonus Progression, Stamina, Mythic Characters, and several GM-facing downtime/encounter subsystems (Chases, Influence, etc.). Returns compact summaries; call rules_get_entry with an id/name for the full official rule text and book/page citation.
`category` filters to 'character-building' (affects what a character
gets at creation/level-up -- ask about these when starting a new
character) or 'subsystem' (GM-facing, doesn't change character
creation) -- omit to see both. Only Free Archetype and Ancestry Paragon
currently have mechanical support elsewhere in this server (extra feat
slots in build_get_level_up_choices, feat-count checks in
build_validate_build, both via their `variant_rules` parameter) -- the
rest are reference text only for now.| Name | Required | Description | Default |
|---|---|---|---|
| category | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It reveals that the tool returns compact summaries, supports a category filter, and currently provides mechanical support only for Free Archetype and Ancestry Paragon while the rest are reference text only. This sets accurate expectations about scope and limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed yet every sentence earns its place: content scope, examples, return type, pointer to the alternative tool, parameter semantics, and current mechanical support status. It is well-structured and front-loaded with the primary purpose, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple one-parameter surface and the existence of an output schema, the description covers all essential user-facing aspects: what is returned, how to filter, when to use alternatives, and current limitations. No critical usage information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the only parameter `category`, but the description fully compensates by defining the two filter values ('character-building' and 'subsystem') and explaining that omitting the parameter shows both. This makes the parameter's meaning and default behavior completely clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Browse' and a resource 'optional/variant character-building and subsystem rules', enumerating concrete examples like Free Archetype and Ancestry Paragon. It explicitly distinguishes itself from sibling tools by directing users to rules_get_entry for full text and noting where mechanical support lives in build tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states when to use this tool (browsing summaries) and when to call rules_get_entry for full official text. It also explains the category filter context ('ask about these when starting a new character') and names alternative tools for mechanical support, giving explicit when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search over PF2e rules content. Returns compact summaries (id/name/pack/type/level/category) -- call rules_get_entry with an id for the full description and raw data of a specific result.
`include_legacy` (default False): excludes pre-Remaster/OGL-flagged
content unless set -- but `is_remaster: false` does NOT mean "retired,"
just "not (yet) reprinted under ORC" (54% of backgrounds, 38% of
ancestries are legacy-flagged and still fully playable), so set this
True whenever the user wants the full catalog. See
`licensing.legacy_filter_sql`.| Name | Required | Description | Default |
|---|---|---|---|
| pack | No | ||
| type | No | ||
| limit | No | ||
| query | Yes | ||
| include_legacy | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does this well by explaining the default legacy filter behavior, the nuance that 'is_remaster: false' does not mean 'retired,' and even provides statistical context (54% of backgrounds, 38% of ancestries). It stops short of explicitly stating read-only behavior or pagination, but the search nature makes that largely implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured into a concise summary paragraph and a detailed note on the critical include_legacy parameter. The second paragraph is lengthy but earns its place because the legacy filter nuance is genuinely non-obvious and decision-relevant. No filler sentences are present, though the reference to 'licensing.legacy_filter_sql' is slightly technical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's primary behavior, return format, sibling-tool differentiation, and the most important filter nuance. It also points to an output schema for raw data. It does not explicitly describe limit behavior or pack/type filtering, but those are straightforward from the schema. Given the tool's search nature and the presence of an output schema, this is a quite complete description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It thoroughly explains include_legacy: its default, its effect, and when to change it. However, the description does not add meaning for query, pack, type, or limit; those rely on their names and schema titles. While include_legacy is the most complex parameter, the others are left entirely to the schema, leaving partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Full-text search over PF2e rules content') and clearly states what it returns ('compact summaries (id/name/pack/type/level/category)'). It also distinguishes itself from the sibling tool by explicitly directing users to rules_get_entry for full data, eliminating ambiguity about its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus an alternative ('call rules_get_entry with an id for the full description and raw data'), and it gives a clear rule for when to set include_legacy=True ('whenever the user wants the full catalog'). This is exactly the kind of when-to-use/when-not-to-use context the rubric asks for.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct resource or action: rules_search returns summaries for later lookup, rules_explain gives inline answers, rules_get_entry fetches details by id/name/slug, and rules_related traverses prerequisites. Build tools are similarly separated: list_* tools cover different entity types, and validation/calculation/export/sheet-rendering are clearly distinct. Even similarly named tools like build_list_available_feats and build_check_prerequisite are well-differentiated by scope (discovery vs single-check).
The server uses two clear prefixes, rules_ and build_, followed by mostly verb_noun patterns (e.g., rules_search, build_list_classes, build_validate_build). Minor deviations like rules_related (adjective) and rules_data_version (noun phrase) break the strict pattern but are still readable and predictable. The naming is consistent and does not mix camelCase or different verb styles.
At 22 tools, this is slightly heavy but each tool justifies its presence—rules lookups, variant/subclass browsing, character-building lists, validation, math, and export/render are all needed for the server's stated purpose. It is close to the upper bound but not excessive, and the count reflects a comprehensive feature set rather than redundancy.
The tool surface covers the full lifecycle of building a character: referencing rules, selecting ancestries/backgrounds/classes/equipment/feats/boosts, validating the build, calculating derived stats, determining level-up choices, and exporting to Pathbuilder or rendering a character sheet. There are no obvious dead ends—every major step has a corresponding tool, and rules_get_entry can retrieve any referenced entity.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Official remote MCP server for Archivist AI TTRPG campaign memory: characters, sessions, and more.
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
Official MCP server for subfeed.app — the cloud for agents. 15+ tools for AI agents to register, build, and deploy other agents. Zero human required. Start here: subfeed.app/skill.md
Official MCP server for Lovable, the AI-powered full-stack app builder.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/rjenks/pf2e-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
