Skip to main content
Glama
tracepass-mcp-server

tracepass-mcp-server

by malinoto

TracePass passport parties

tracepass_passport_parties
DestructiveIdempotent

Set or remove economic-operator parties—such as manufacturer, importer, or recycler—on a passport, with legal names and required identifiers.

Instructions

Manage the economic-operator parties on a passport (manufacturer, importer, authorisedRepresentative, distributor, recycler, producerResponsibilityOrg). Each carries a legal name and an identifier.

A party needs at least one of gln, legacyOperatorId or operatorIdentifier (EN 18219 §6.2–6.5; they must agree if both gln forms are given, else 400). Identifier shapes: resource tracepass://reference/parties.

Actions (pass via action; {…} is the args object):

  • set — { id, role, legalName, gln?, country?, url?, tradeName?, postalAddress?, email?, legacyOperatorId?, operatorIdentifier?, facilityIdentifier? }. tradeName, postalAddress and email are public; for a battery importer they are its Battery Regulation Art. 41(3) details.

  • remove — { id, role }.

After a battery passport is placed on the market, changing a stored operatorIdentifier or facilityIdentifier returns 409 operator_locked; other edits stay allowed.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "tracepass_passport_parties"
  }
}

Input Schema

NameRequiredDescriptionDefault
argsNo
actionYes

Output Schema

NameRequiredDescriptionDefault
idNo
pageNo
errorNo
itemsNo
limitNo
totalNo
resultNo
messageNo
totalPagesNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed22 schema fields changedv1.27.0
    • removedInput schema / properties / action / description
      Removed value: -"Set (add/replace) or remove an economic-operator party on a passport by its role."
    • removedInput schema / properties / args / description
      Removed value: -"Arguments for the chosen action; required fields depend on `action`."
    • changedInput schema / properties / args / properties / country / description
      Previous value: -"ISO 3166-1 alpha-2 country code (set, optional)."New value: +"ISO 3166-1 alpha-2."
    • changedInput schema / properties / args / properties / email / description
      Previous value: -"Company contact e-mail, not a person's (set, optional). Public."New value: +"Company contact, not a person's. Public."
    • changedInput schema / properties / args / properties / facilityIdentifier / description
      Previous value: -"Structured facility identifier per EN 18219 §6.2–6.5. Same four schemes as operatorIdentifier; the gln variant also accepts optional `extension` (GS1 SGLN sub-location). Never fills the top-level gln field. Not set by AI extraction."New value: +"Same schemes as operatorIdentifier; gln also takes `extension`."
    • changedInput schema / properties / args / properties / gln / description
      Previous value: -"GS1 Global Location Number (13 digits). Strongly recommended for multi-role disambiguation."New value: +"13 digits."
    • removedInput schema / properties / args / properties / id / description
      Removed value: -"Passport id (required)."
    • changedInput schema / properties / args / properties / legacyOperatorId / description
      Previous value: -"Free-text fallback identifier (VAT, EORI, supplier code). Required when gln and operatorIdentifier are both absent."New value: +"Fallback identifier (VAT, EORI, supplier code)."
    • removedInput schema / properties / args / properties / legalName / description
      Removed value: -"Party legal name. Required for set."
    • changedInput schema / properties / args / properties / operatorIdentifier / description
      Previous value: -"Structured operator identifier per EN 18219 §6.2–6.5. Must have `scheme` plus scheme fields. Schemes: iso6523 {icd:\"<4 digits>\", value} | gln {gln:\"<13 digits>\"} | did {did:\"did:<method>:<id>\"} | doi {doi:\"10.<registrant>/<suffix>\"}. scheme gln also fills the top-level gln field; they must match if both are set (400 otherwise). Not set by AI extraction."New value: +"{ scheme: iso6523|gln|did|doi, … }. Shapes: tracepass://reference/parties."
    • changedInput schema / properties / args / properties / postalAddress / description
      Previous value: -"Postal address with a single contact point, one line, max 500 chars (set, optional). Public."New value: +"One line, max 500 chars. Public."
    • changedInput schema / properties / args / properties / tradeName / description
      Previous value: -"Registered trade name or registered trade mark, max 200 chars (set, optional). Public."New value: +"Max 200 chars. Public."
    • removedInput schema / properties / args / properties / url / description
      Removed value: -"Organisation web address (set, optional)."
    • removedOutput schema / properties / error / description
      Removed value: -"Machine-readable error code, when the API rejected the request."
    • removedOutput schema / properties / id / description
      Removed value: -"The resource's TracePass id, when the response is a single entity."
    • removedOutput schema / properties / items / description
      Removed value: -"The page of results, when the action is a list."
    • removedOutput schema / properties / limit / description
      Removed value: -"Page size (list actions)."
    • removedOutput schema / properties / message / description
      Removed value: -"Human-readable error or status detail, when present."
    • removedOutput schema / properties / page / description
      Removed value: -"Current page number (list actions)."
    • removedOutput schema / properties / result / description
      Removed value: -"Wraps a non-object response body (e.g. a QR code string)."
    • removedOutput schema / properties / total / description
      Removed value: -"Total matching records across all pages (list actions)."
    • removedOutput schema / properties / totalPages / description
      Removed value: -"Total number of pages (list actions)."
  2. Changed4 schema fields changedv1.23.2
    • removedOutput schema / properties / error / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / error / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / message / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / message / type
      Added value: +[
      +  "string",
      +  "null"
      +]
  3. Changed4 schema fields changedv1.22.0
    • addedInput schema / properties / args / properties / email
      Added value: +{
      +  "description": "Company contact e-mail, not a person's (set, optional). Public.",
      +  "type": "string"
      +}
    • addedInput schema / properties / args / properties / postalAddress
      Added value: +{
      +  "description": "Postal address with a single contact point, one line, max 500 chars (set, optional). Public.",
      +  "type": "string"
      +}
    • addedInput schema / properties / args / properties / tradeName
      Added value: +{
      +  "description": "Registered trade name or registered trade mark, max 200 chars (set, optional). Public.",
      +  "type": "string"
      +}
    • addedInput schema / properties / args / properties / url
      Added value: +{
      +  "description": "Organisation web address (set, optional).",
      +  "type": "string"
      +}
  4. Changed4 schema fields changedv1.19.1
    • addedOutput schema / properties / error / anyOf
      Added value: +[
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • removedOutput schema / properties / error / type
      Removed value: -"string"
    • addedOutput schema / properties / message / anyOf
      Added value: +[
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • removedOutput schema / properties / message / type
      Removed value: -"string"
  5. Changed6 schema fields changedv1.14.1
    • changedInput schema / properties / args / properties / country / description
      Previous value: -"Party country code (set, optional)."New value: +"ISO 3166-1 alpha-2 country code (set, optional)."
    • addedInput schema / properties / args / properties / facilityIdentifier
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Structured facility identifier per EN 18219 §6.2–6.5. Same four schemes as operatorIdentifier; the gln variant also accepts optional `extension` (GS1 SGLN sub-location). Never fills the top-level gln field. Not set by AI extraction.",
      +  "propertyNames": {
      +    "type": "string"
      +  },
      +  "type": "object"
      +}
    • changedInput schema / properties / args / properties / gln / description
      Previous value: -"GS1 Global Location Number for the party (set, optional)."New value: +"GS1 Global Location Number (13 digits). Strongly recommended for multi-role disambiguation."
    • changedInput schema / properties / args / properties / legacyOperatorId / description
      Previous value: -"Your internal operator id for the party (set, optional)."New value: +"Free-text fallback identifier (VAT, EORI, supplier code). Required when gln and operatorIdentifier are both absent."
    • addedInput schema / properties / args / properties / operatorIdentifier
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Structured operator identifier per EN 18219 §6.2–6.5. Must have `scheme` plus scheme fields. Schemes: iso6523 {icd:\"<4 digits>\", value} | gln {gln:\"<13 digits>\"} | did {did:\"did:<method>:<id>\"} | doi {doi:\"10.<registrant>/<suffix>\"}. scheme gln also fills the top-level gln field; they must match if both are set (400 otherwise). Not set by AI extraction.",
      +  "propertyNames": {
      +    "type": "string"
      +  },
      +  "type": "object"
      +}
    • changedInput schema / properties / args / properties / role / description
      Previous value: -"Economic-operator role, e.g. manufacturer | importer | distributor | authorised_representative (required)."New value: +"Economic-operator role: manufacturer | importer | authorisedRepresentative | distributor | recycler | producerResponsibilityOrg (required)."
  6. Changed6 schema fields changedv1.7.3
    • addedInput schema / properties / action / description
      Added value: +"Set (add/replace) or remove an economic-operator party on a passport by its role."
    • removedInput schema / properties / args / additionalProperties
      Removed value: -{}
    • changedInput schema / properties / args / description
      Previous value: -"Action-specific arguments — see the description."New value: +"Arguments for the chosen action; required fields depend on `action`."
    • addedInput schema / properties / args / properties
      Added value: +{
      +  "country": {
      +    "description": "Party country code (set, optional).",
      +    "type": "string"
      +  },
      +  "gln": {
      +    "description": "GS1 Global Location Number for the party (set, optional).",
      +    "type": "string"
      +  },
      +  "id": {
      +    "description": "Passport id (required).",
      +    "type": "string"
      +  },
      +  "legacyOperatorId": {
      +    "description": "Your internal operator id for the party (set, optional).",
      +    "type": "string"
      +  },
      +  "legalName": {
      +    "description": "Party legal name. Required for set.",
      +    "type": "string"
      +  },
      +  "role": {
      +    "description": "Economic-operator role, e.g. manufacturer | importer | distributor | authorised_representative (required).",
      +    "type": "string"
      +  }
      +}
    • removedInput schema / properties / args / propertyNames
      Removed value: -{
      -  "type": "string"
      -}
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": false,
      +  "properties": {
      +    "error": {
      +      "description": "Machine-readable error code, when the API rejected the request.",
      +      "type": "string"
      +    },
      +    "id": {
      +      "description": "The resource's TracePass id, when the response is a single entity.",
      +      "type": "string"
      +    },
      +    "items": {
      +      "description": "The page of results, when the action is a list.",
      +      "items": {},
      +      "type": "array"
      +    },
      +    "limit": {
      +      "description": "Page size (list actions).",
      +      "type": "number"
      +    },
      +    "message": {
      +      "description": "Human-readable error or status detail, when present.",
      +      "type": "string"
      +    },
      +    "page": {
      +      "description": "Current page number (list actions).",
      +      "type": "number"
      +    },
      +    "result": {
      +      "description": "Wraps a non-object response body (e.g. a QR code string)."
      +    },
      +    "total": {
      +      "description": "Total matching records across all pages (list actions).",
      +      "type": "number"
      +    },
      +    "totalPages": {
      +      "description": "Total number of pages (list actions).",
      +      "type": "number"
      +    }
      +  },
      +  "type": "object"
      +}
  7. First observedv1.1.4

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known; the description then adds substantial context beyond that: the 400 on disagreeing gln forms, the 409 operator_locked lock after the passport is placed on the market, which fields are public, and the Battery Regulation Art. 41(3) framing. This is the kind of failure-mode and state-transition detail annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Structure is front-loaded: purpose, then the identifier rule, then a bulleted action list with inline arg shapes, then the locking caveat. No sentence is filler; the terse parenthetical citations (EN 18219 §6.2–6.5) and reference URI replace paragraphs of explanation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists and annotations cover the safety/mutability profile, so the description is free to focus on the identifier rules, action argument shapes, and error semantics, all of which it covers. For a nested two-parameter tool with a discriminated action, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is reported as 0%, so the description must carry the load, and it does: it states that a party needs at least one of gln/legacyOperatorId/operatorIdentifier, that both gln forms must agree, lists every optional arg for 'set', flags which fields are public, and points to tracepass://reference/parties for the identifier shapes. This adds meaning well beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

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 ('Manage the economic-operator parties on a passport') and enumerates the exact role set (manufacturer, importer, authorisedRepresentative, distributor, recycler, producerResponsibilityOrg). That scope is clearly different from a generic passport tool, but it never names or contrasts a sibling, so it stops short of explicit differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It splits behavior by action and shows exactly when each applies: 'set' with the full args shape versus 'remove' with only { id, role }. It also states the post-market restriction (changing operatorIdentifier or facilityIdentifier returns 409 operator_locked, other edits stay allowed), which is genuine when-to-use guidance. It gives no guidance on choosing this tool over sibling passport tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.