PDG Lookup Workflow

This skill teaches the correct tool-calling sequence for PDG lookups via the pdg_* MCP tools. All PDG tools are local-only (no network) and require PDG_DB_PATH to be set.

Tool Chain Overview

pdg_info                    # Check DB status, see available editions
    |
pdg_find_particle           # Search by name / MCID / PDG identifier
    |
    +-- pdg_get_property     # Quick: mass, width, lifetime (with uncertainties)
    +-- pdg_get_measurements # Detailed: all measurements for a PDG identifier
    +-- pdg_get_decays       # All decay modes for a particle
    +-- pdg_get              # Full PDG identifier object (JSON artifact)
    |
pdg_find_reference          # Find PDG references by DOI / INSPIRE recid / title
pdg_get_reference           # Get a specific PDG reference record

Step 1: Check availability

pdg_info {}

Returns DB path, edition year, and data directories. If this fails, the user needs to set PDG_DB_PATH.

Step 2: Find the particle

pdg_find_particle { query: "top quark" }
pdg_find_particle { query: "t", mcid: 6 }
pdg_find_particle { pdgid: "S008" }

The result includes pdgid values (e.g., "S008" for the top quark) needed for subsequent calls.

Step 3: Get properties or measurements

Quick property lookup

pdg_get_property { pdgid: "S008M", particle: "t" }
pdg_get_property { particle: "W", property: "mass" }
pdg_get_property { particle: "Z", property: "width" }

• Use allow_derived: true to get width derived from lifetime (and vice versa).
• Returns value, uncertainties, unit, and PDG locator.

Detailed measurements (CRITICAL: stop-and-select pattern)

pdg_get_measurements { particle: "t", property: "mass" }

CRITICAL: If the result has kind: "series_options" or stop_here: true, you MUST STOP and present the options to the user. Then call again with the specific property_pdgid or data_type from example_next_calls:

pdg_get_measurements { property_pdgid: "S008M" }
pdg_get_measurements { pdgid: "S008M", data_type: "DIRECT MEASUREMENT" }

Never skip the series selection step. The result is a JSONL artifact with full measurement details.

Decay modes

pdg_get_decays { particle: "Z" }
pdg_get_decays { pdgid: "S044" }

Returns all known decay modes with branching ratios as a JSONL artifact.

Step 4: References

Find references

pdg_find_reference { query: "CKM" }
pdg_find_reference { doi: "10.1103/PhysRevD.110.030001" }
pdg_find_reference { inspire_id: "2830185" }

Get a specific reference

pdg_get_reference { document_id: 12345 }

Common Workflow Examples

Top quark mass

1. pdg_find_particle { query: "top quark" } -> get pdgid S008
2. pdg_get_property { particle: "t", property: "mass" } -> quick value
3. pdg_get_measurements { particle: "t", property: "mass" } -> may return series_options
4. Select the appropriate series -> pdg_get_measurements { property_pdgid: "S008M" }

Z boson decays

1. pdg_find_particle { query: "Z boson" } -> get pdgid S044
2. pdg_get_decays { pdgid: "S044" } -> all decay modes with BRs

Higgs measurements

1. pdg_find_particle { query: "Higgs" } -> pdgid S126
2. pdg_get_measurements { particle: "H", property: "mass" } -> handle series_options
3. pdg_get_measurements { property_pdgid: "S126M" } -> all mass measurements

CKM review reference

1. pdg_find_reference { query: "CKM" } -> find document_id
2. pdg_get_reference { document_id: <id> } -> full reference with INSPIRE link

Tips

• pdg_get_property is fast and returns a single best-fit value. Use it for quick lookups.
• pdg_get_measurements returns the full measurement history. Use it when the user needs individual experiment results.
• Particle names are case-insensitive: "W", "w", "W boson" all work.
• Use pdg_batch (full exposure only) to run multiple PDG lookups in one call.
• Width and lifetime are related: if only one is in the DB, use allow_derived: true to get the other.