Manage the TracePass product catalogue. A product is the catalogue layer — one product can have many passports (one per serialised unit). Products are not billable on their own.

Actions (pass via action, with args):

• list — args: { page?, limit? (≤100), category?, status?, search? }. Read-only.

• get — args: { id }. Read-only.

• create — args: { name, model, category, description? }. category is one of: battery, textile, electronics, construction, steel, detergents, paints-coatings, packaging, furniture, tyres, jewelry, toys, fmcg.

• update — args: { id, name?, model?, description? }; pass at least one field to change.

• create_batch — args: { products: [ { name, model, category, description? }, … ] }, up to 100. Partial-success: the response carries a per-item status, so some items can be created while others error. The whole batch consumes N writes upfront; if that would exceed the daily cap NOTHING is created (429).

• archive — args: { id }. Soft-archive a product. Blocked with 409 while any non-archived passport still references it — archive those passports first. This is reversible and is NOT deletion.

Manage Digital Product Passports — create, read, and run lifecycle actions.

IMPORTANT: create makes a DRAFT passport. A draft takes no plan DPP slot and is never billed; the slot, and any per-DPP overage past the plan cap, is taken when the passport is published, which happens in the TracePass dashboard, not through this tool. Each create counts against the daily write budget. archive is IRREVERSIBLE (the public QR permanently 404s); prefer suspend when a change might be undone.

IDENTIFIER SCHEMES (EN 18219): passports are identified by one of five schemes. Battery passports (Battery Regulation Art. 77(3)) accept ONLY gs1 and iso15459. • gs1 — { scheme:"gs1", gtin, serialNumber } — GS1 GTIN + serial; gtin is 8/12/13/14 digits, stored as GTIN-14. • iso15459 — { scheme:"iso15459", issuingAgencyCode, primaryId, serial? } — ISO/IEC 15459; the server derives raw (IAC + primaryId + serial). • iec61406 — { scheme:"iec61406", uri } — IEC 61406 Identification Link (https URI). Not valid for batteries. • did — { scheme:"did", did, method } — W3C DID Core. Not valid for batteries. • doi — { scheme:"doi", doi, granularity:"model"|"batch"|"item" } — ISO 26324 DOI, stored as bare 10./ (any https://doi.org/ or doi: prefix stripped on input; resolves as https://doi.org/); granularity REQUIRED per EN 18219 §5.6.2(b). Not valid for batteries. The legacy top-level gtin + serialNumber pair is still accepted as a deprecated alias for scheme:"gs1".

Actions (pass via action, with args):

• list — args: { page?, limit? (≤100), productId?, status?, search? }. status ∈ draft|in_review|approved|published|suspended|expired|archived. Read-only.

• get — args: { id, format? (summary|full), lang? }. Read-only. Response includes identifier, identifierKey, and (for GS1 passports) gs1.

• get_by_serial — args: { serial, format?, lang?, gtin? }. Read-only. Addresses the passport by your own serial. A serial is unique only WITHIN a GTIN — if the same serial exists under two GTINs in your account the call returns 409 ambiguous_serial; pass gtin (or use the by-id action) to resolve exactly.

• compliance — args: { id }. Read-only. Returns a three-tier compliance verdict (compliant | compliant_with_warnings | incomplete) with regulation-cited findings — use to gap-check a passport against the rules for its category, fix the cited fields/parties, then re-check. Also returns byRegulation[]: the same findings grouped per regulation, worst first, so you can tell WHICH regime is failing instead of reading one incomplete as everything being wrong. A regulation absent from that array raised no finding — that is not the same as it having passed.

• registry_readiness — args: { id }. Read-only. Returns { ready, findings[] } — whether the passport would pass the EU DPP Registry's FORMAL submission gate (mandatory fields present, correct formatting, a resolvable public link, item-level granularity via a serial number, and a well-formed commodity code where the category carries one, and, for EV, LMT and industrial (over 2 kWh) batteries, conformance to the Commission's battery data model that the Registry validates against (REG-READY-SEMANTIC)). This is the registry's mechanical pre-submission check, NOT the substantive compliance verdict; a passport can be registry-ready yet not substantively compliant. Battery passports only.

• place_on_market — args: { id }. WRITE, battery passports only, published only. Places the passport on the market: registers it in the EU DPP registry under the account's own registry access (the upload Battery Regulation Art. 77(10) requires of the operator placing the battery on the market). A legal act for the economic operator — confirm with the user first. ASYNCHRONOUS: answers 202 { passport, passportId, status: "placing", dppId } and the registry call follows in the background; read the passport (get) to follow placeOnMarketStatus: placing → placed (placedOnMarketAt, registrationId) or rejected (registrationRejectionReason). To retry a rejected passport, fix the cause and call place_on_market again. Refusals are 409 with a code: not_a_battery | not_published | already_placed (placing or placed) | operator_id_missing (no economic-operator identifier on the account) | registry_not_configured (an admin sets registry access in the dashboard) | registry_not_ready (findings[] lists what stands in the way — run registry_readiness for the structured findings; an empty list means the configured registry is not open to submissions from TracePass yet). After placement the passport's party operatorIdentifier / facilityIdentifier are locked (409 operator_locked on a change). Counts 1 write.

• create — args: { productId, identifier?, gtin?, serialNumber?, lineage? }. Creates a draft (not billed). Provide identifier (preferred) or legacy gtin + serialNumber. Battery passports accept only gs1 and iso15459 schemes — other schemes return 400. A duplicate identifier returns 409. lineage (battery only) — a repurposed, remanufactured or reused battery needs a NEW passport linked to the original(s) (Battery Regulation Art. 77(7)): { predecessors: [ { internalPassportId? | identifier?, trigger: preparation_for_reuse|preparation_for_repurposing|repurposing|remanufacturing } ] (≤10), noPredecessorReason? (only with an empty list, e.g. placed on the market before 18 Feb 2027) }. The server derives batteryStatus from the triggers and links your own predecessor passports back. Immutable after create. Rule violations return 422 with the rule code (duplicate_predecessor, predecessor_not_found, status_trigger_mismatch, …).

• suspend — args: { id }. Reversible — public QR shows 'suspended'.

• suspend_by_serial — args: { serial, gtin? }. Same as suspend, addressed by your serial. 409 ambiguous_serial if the serial isn't unique in your account — pass gtin.

• archive — args: { id, reason? (recycled|never_placed|duplicate_or_error) }. IRREVERSIBLE and destructive — confirm with the user first. reason is REQUIRED for battery passports (400 reason_required / invalid_reason without a valid one): recycled, never_placed (never placed on the market or put into service), or duplicate_or_error (a duplicate or erroneous record); for other categories it is optional. A passport marked for deletion cannot be archived (409).

• archive_by_serial — args: { serial, gtin?, reason? }. IRREVERSIBLE and destructive, addressed by your serial — confirm first. Same reason rule as archive. 409 ambiguous_serial if the serial isn't unique — pass gtin.

• get_qr — args: { id, format? (svg|png), symbology? (qr|datamatrix) }. Read-only. symbology=datamatrix renders an ISO/IEC 16022 Data Matrix instead of a QR (EN 18220 permits both; same passport URL).

• get_qr_by_serial — args: { serial, format? (svg|png), symbology? (qr|datamatrix), gtin? }. Read-only. Same as get_qr, addressed by your own serial. A serial is unique only WITHIN a GTIN — if the same serial exists under two GTINs in your account the call returns 409 ambiguous_serial; pass gtin (or use get_qr by id) to resolve exactly.

• list_snapshots — args: { id, page?, limit? (≤100), at? (ISO 8601) }. Read-only. Returns a paginated list of snapshots for the passport (newest first). A snapshot is written on publish and after every change to a non-draft passport (EN 18221 change archive); each carries id, version, reason (e.g. published|field_edit|status_change|baseline), actor (who caused it, when known), snapshotAt, contentHash, hashValid (re-verified on every read), restorable, fieldCount. With at, returns instead the single snapshot valid at that instant (full record plus validFrom/validUntil) — answers "what did this passport say on date D"; 404 before the first snapshot. Counts 1 against the daily read budget.

• get_snapshot — args: { id, snapshotId }. Read-only. Returns the full archival record of one snapshot: the complete JSON-LD the passport asserted at that time, plus hash and hashValid. Counts 1 against the daily read budget.

• get_condition_flags — args: { id }. Read-only. Returns the resolved condition profile Record<flagKey,{value,status,source}>. Condition flags are reviewer-approved yes/no facts gating conditional legal duties. Battery flags: hasBMS, rechargeable, externalStorageOnly, isStationaryBess. An approved flag makes specific fields required — a missing gated field is a hard publish block (conditional_missing). Counts 1 against the daily read budget.

• get_condition_flags_by_serial — args: { serial, gtin? }. Read-only. Same as get_condition_flags, addressed by your own serial. 409 ambiguous_serial if serial not unique — pass gtin.

• set_condition_flags — args: { id, flags: Record<flagKey, boolean|null> }. WRITE. Set or clear condition flags (null clears). Keys must be registered for the passport category (battery: hasBMS, rechargeable, externalStorageOnly, isStationaryBess). WARNING: approving a flag can make fields required and block publishing if those fields are empty — fix any gated fields before or immediately after setting the flag. Writes are approved + audited. Idempotency-Key supported. Counts 1 write.

• set_condition_flags_by_serial — args: { serial, gtin?, flags }. WRITE. Same as set_condition_flags, addressed by your own serial. 409 ambiguous_serial if serial not unique — pass gtin.

• capture_measurements — args: { id, measurements: [ { fieldKey, value, measuredAt (ISO 8601), externalId?, unit? } ] (≤500) }. WRITE, battery passports only, published only. Pushes over-life measurements from the customer's own equipment (e.g. a BMS reporting stateOfHealth, numberOfFullEquivalentChargingCycles; the Annex XIII point 4 use-data keys). Every measurement is stored; the newest per field becomes the passport's current value and sets dynamicDataAsOf. externalId makes a measurement idempotent. A value may be at most 16 KB serialised. batteryStatus is NOT a measurement (400 invalid_field_key). A key the Regulation keeps off this battery category returns 422 field_not_applicable (e.g. stateOfCertifiedEnergy on an LMT battery). Metered against the plan's monthly measurement allowance, not the daily write budget: paid plans keep counting past it at no charge; Free stops at its allowance. Reading a passport is never metered.

• capture_measurements_by_serial — args: { serial, gtin?, measurements }. Same, addressed by your own serial.

• list_measurements — args: { id, fieldKey?, from?, to? (ISO 8601), limit? (≤200), cursor? }. Read-only. Measurement history, newest first; page with the returned nextCursor.

• list_measurements_by_serial — args: { serial, gtin?, fieldKey?, from?, to?, limit?, cursor? }. Read-only.

• latest_measurements — args: { id }. Read-only. The newest measurement per accepted key (null where none yet).

• latest_measurements_by_serial — args: { serial, gtin? }. Read-only.

Update field values on a Digital Product Passport. Every change is recorded in the passport's audit trail with the credential that made it (API key or connected app) and this MCP channel.

source (optional) says where the value came from. Omit it, or pass "manual", when the user gave you the value or it comes from their own records: it is written with the user's rights (approved for an API key or an admin; sent to review for a connected app acting for an editor). Pass "ai_suggested" when you found or inferred the value yourself (web research, reading a document): it lands in the dashboard review queue for a human to approve, and it is refused on fields only the economic operator may state or that must be measured (e.g. battery stateOfHealth).

Actions (pass via action, with args):

• update — args: { id, fieldKey, value, source? }. value type matches the field's dataType (string, number, boolean, array, object).

• update_by_serial — args: { serial, fieldKey, value, gtin?, source? }. Same as update, addressed by your own serial. A serial is unique only WITHIN a GTIN — if it isn't unique in your account the call returns 409 ambiguous_serial; pass gtin (or use update by id) to resolve exactly.

Manage the economic-operator parties on a passport — manufacturer, importer, authorisedRepresentative, distributor, recycler, producerResponsibilityOrg. Each party carries a legal name and at least one identifier.

Identifier rules (EN 18219 §6.2–6.5): a party needs at least one of gln, legacyOperatorId, or operatorIdentifier. If both gln and operatorIdentifier (scheme gln) are provided they must agree — a mismatch returns 400. An operatorIdentifier of scheme gln also fills the top-level gln field; facilityIdentifier never does. Typed identifiers (operatorIdentifier / facilityIdentifier) are not set by AI extraction or CSV import.

operatorIdentifier schemes: • iso6523 — { scheme:"iso6523", icd:"<4 digits>", value } — ICD 0199 = LEI (ISO 17442), 0088 = GLN, 0060 = DUNS. • gln — { scheme:"gln", gln:"<13 digits>" } — also fills top-level gln. • did — { scheme:"did", did:"did::" } — syntax-checked only (EN 18219 §6.4.2(b)). • doi — { scheme:"doi", doi:"10./" } — doi:/https://doi.org/ prefix accepted and stripped.

facilityIdentifier schemes: same four; the gln variant also accepts optional extension (GS1 SGLN sub-location).

Actions (pass via action, with args):

• set — args: { id, role, legalName, gln?, country?, url?, tradeName?, postalAddress?, email?, legacyOperatorId?, operatorIdentifier?, facilityIdentifier? }. Sets or updates one role. tradeName, postalAddress and email are shown on the public passport; for a battery importer they are its Battery Regulation Art. 41(3) details.

• remove — args: { id, role }. Clears one role. Once a battery passport is placed on the market, a change to a stored operatorIdentifier or facilityIdentifier returns 409 operator_locked; other party edits stay allowed. To correct a locked identifier, the passport is marked for deletion and a new one created.

GS1 EPCIS 2.0 supply-chain events. export, capture, capture_job and query are on every plan, Free included. Captured events count against the plan's event allowance (10 a month on Free); over it, capture returns an overage or hard-block message.

Actions (pass via action, with args):

• export — args: { id }. Export a passport's events as an EPCIS 2.0 JSON-LD document. Read-only.

• export_by_serial — args: { serial, gtin? }. Same as export, addressed by your own serial. A serial is unique only WITHIN a GTIN — if it isn't unique in your account the call returns 409 ambiguous_serial; pass gtin (or use export by id). Read-only.

• capture — args: { events }. events is an EPCISDocument, a single event, or an array of events (JSON-LD). Returns a 202 with a captureJobId.

• capture_job — args: { jobId }. Poll an async capture job. Read-only.

• query — args: { params? }. params is a key/value map of standard EPCIS query parameters (EQ_bizStep, GE_eventTime, MATCH_epc, …). Read-only.

Discover the regulatory field schema for each DPP category — what a COMPLIANT passport must contain, per the governing EU regulation. Read-only reference data. Use this to advise on requirements before creating products/passports, and to gap-check a draft against the rules.

Actions (pass via action, with args):

• list — args: {}. Lists all 13 categories with their field count, required-field count, and governing regulation (name + number + effective/mandatory dates).

• get — args: { category }. Full field schema for one category: every field's key, label, dataType, whether it is REQUIRED, its access level (public/restricted/authority), enum options, validation bounds, and — where known — the regulation article/annex that mandates it. category is one of: battery, textile, electronics, construction, steel, detergents, paints-coatings, packaging, furniture, tyres, jewelry, toys, fmcg.

BATTERY — required-ness is per-category, so required alone is the wrong answer. Resolve it in this order:

1. SCOPE FIRST. Only EV, LMT and industrial_gt_2kwh batteries owe a passport at all (Art. 77(1), Reg (EU) 2023/1542). For portable, SLI or industrial_lte_2kwh, NO field is required — do not list mandatory fields for them; say the battery is out of scope.

2. Then requiredBy[batteryCategory] where the field carries that map (required | conditional | notApplicable). conditional means owed only when a fact holds (a commercial warranty offered, a BMS present, the battery in service); an approved condition flag can make it required. Annex XIII 4(d) use data (charging cycles, negative events, temperature history, state of charge) is expected once the battery is in service and never blocks publishing.

3. Then fall back to required. The map is keyed ONLY by the three in-scope categories, so skipping step 1 falls through to required and invents an obligation the Regulation does not impose. Note also that EV and LMT report state-of-health through MUTUALLY EXCLUSIVE field sets — an EV battery must leave the remaining-capacity cluster empty and an LMT battery must leave stateOfCertifiedEnergy empty, so no single battery ever fills every field.

Check what EU law says for a product type matching the facts given: whether it needs a Digital Product Passport, from when, at which level, under which act and article, and the duties of each role. Also read the company's catalogue-wide scope report and trigger a catalogue refresh run.

HARD RULES — always apply these to scope answers:

• Answers state what the law says for product types matching the given facts. This is not legal advice; never write 'you must' — use product-type phrasing ('LMT batteries need a passport from 18 February 2027, Battery Regulation Art. 77(1)').

• Cite the article the answer gives for every verdict and duty. A regulation without an article is not a citation. A not_covered answer rests on no article: say our rules do not cover the product and name the nearest act it gives, never cite that act as the basis.

• A date with precision 'quarter', 'month' or 'year' is a plan, NEVER a deadline or a start date. Write 'planned for Q2 2027 (planned, not law yet)', never 'from', 'by' or 'deadline'.

• Relay not_covered and needs_input as the results they are, never as errors. not_covered = the product falls outside these scope rules. needs_input = blocking questions remain unanswered — relay the questions in ask[] to the user before giving a verdict.

• Items in an act's planned list are not law yet: always label them 'Planned, not law yet' (labelText), with their wording.

• ruleStatus: 'needs_recheck' means the law behind an act changed and our rules for it are being re-checked (since recheckSince): say so with the answer.

Actions (pass via action, with args):

• check — args: { category?, facts?, role?, placedOnMarket?, lifecycleEvent?, contains?, productId?, passportId?, locale? }. Ask whether a product type needs a DPP. Available on every plan, Free included. Counts against the per-company scope-answer cap (~100/day, 30/min burst), NOT the v1 read/write budget. 429 scope_answer_cap when the daily cap is spent. not_covered and needs_input are 200 results, not errors. category: one of battery | detergents | toys | construction | textile | steel | tyres | furniture | electronics | packaging | paints-coatings | jewelry | fmcg | vehicles | other. facts: namespace-prefixed keys from the loaded rules (e.g. battery.use, battery.capacityKWh). Unknown keys or wrong values return 400 invalid_input. role: your role in the act's terms: manufacturer | importer | distributor | authorised_representative | fulfilment_service_provider. Selling under your own name = manufacturer with facts.ownBrand: true. Omit to list every role's duties. placedOnMarket: { date: 'YYYY-MM-DD' | 'YYYY-MM' | 'YYYY', precision?: 'day'|'month'|'year' } or null. contains: array (≤5) of component queries — use to ask about a battery inside a toy: [ { label?, facts? } ]. locale: en | bg | de | it (default: from Accept-Language header, else en).

• catalogue_report — args: { classification?, category?, act?, changed?, q?, cursor?, limit? (≤500) }. Read the catalogue-wide scope report (one row per product). Requires the Growth plan or above; 403 plan_upgrade_required below Growth — tell the user this needs a plan upgrade, do not retry. Counts 1 against the daily read budget per page. classification filter: missing | draft_only | published_incomplete | published | not_required | open_questions | not_covered. Response: { run, running, totals, items: [{ productId, passportIds, gtin, category, summary, classification, changedAt }], nextCursor, disclaimer }. Full answer for one product: call check with that productId.

• catalogue_run — args: {}. Start a catalogue scope refresh run (also runs nightly). Returns 202 { runId, status }; poll with catalogue_run_status. Requires Growth plan. 409 run_in_progress if already active; 429 run_cooldown with retryAfter within 10 minutes of a finished run.

• catalogue_run_status — args: { runId }. Get the status (queued | running | done | failed) and result counts for one catalogue run. Requires Growth plan.