tracepass-mcp-server

TracePass passport fields

tracepass_passport_fields

Idempotent

Update field values on a Digital Product Passport by ID or serial; every change is recorded in the audit trail.

Instructions

Update field values on a Digital Product Passport. Every change is recorded in the passport's audit trail, tagged as an API-key update.

Actions (pass via action, with args):

update — args: { id, fieldKey, value }. value type matches the field's dataType (string, number, boolean, array, object).
update_by_serial — args: { serial, fieldKey, value, gtin? }. 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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`args`	No	Arguments for the chosen action; required fields depend on `action`.
`action`	Yes	Update one passport field, addressed by passport id (update) or by your serial (update_by_serial).

Output Schema

TableJSON Schema

Name	Required	Description
`id`	No	The resource's TracePass id, when the response is a single entity.
`page`	No	Current page number (list actions).
`error`	No	Machine-readable error code, when the API rejected the request.
`items`	No	The page of results, when the action is a list.
`limit`	No	Page size (list actions).
`total`	No	Total matching records across all pages (list actions).
`result`	No	Wraps a non-object response body (e.g. a QR code string).
`message`	No	Human-readable error or status detail, when present.
`totalPages`	No	Total number of pages (list actions).

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv1.7.3Aug 7, 2026

addedInput schema / properties / action / description

Added value: +"Update one passport field, addressed by passport id (update) or by your serial (update_by_serial)."

changedInput schema / properties / action / enum

Previous value: -[
-  "update"
-]New value: +[
+  "update",
+  "update_by_serial"
+]

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: +{
+  "fieldKey": {
+    "description": "The field key to set (required).",
+    "type": "string"
+  },
+  "gtin": {
+    "description": "GTIN disambiguator for update_by_serial when the serial isn't unique (else 409).",
+    "type": "string"
+  },
+  "id": {
+    "description": "Passport id. Required for update.",
+    "type": "string"
+  },
+  "serial": {
+    "description": "Your serial. Required for update_by_serial.",
+    "type": "string"
+  },
+  "value": {
+    "description": "The new value for the field (required). Type depends on the field's dataType."
+  }
+}

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"
+}

First observedv1.1.4Jun 9, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Beyond the idempotentHint annotation, the description discloses that every change is recorded in the passport's audit trail and tagged as an API-key update. It also explains the 409 error condition for ambiguous serials and that the value type must match the field's dataType. This adds meaningful behavioral context without contradicting the annotation.

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?

The description is compact and well-structured: a purpose sentence followed by a clear list of actions with their args and usage notes. Every sentence adds value; there is no redundant repetition of schema information. The format makes it easy to scan and understand the tool's behavior.

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?

Given the tool's complexity (two actions, nested args, optional disambiguator) and the presence of an output schema, the description covers all necessary aspects: purpose, action mechanics, error handling, audit trail, and value typing. No critical behavior is left unexplained, and the output schema handles return-value details.

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?

Although the input schema describes each parameter, the description adds crucial semantic meaning by tying parameters to actions: it details the args structure for update vs update_by_serial, clarifies the optional `gtin` disambiguator, and specifies that `value` must match the field's dataType. This goes well beyond the schema's one-line descriptions.

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

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Update field values on a Digital Product Passport.' This clearly states the tool's function and distinguishes it from sibling tools that manage passports, products, parties, EPCIS, or templates. The two actions (update, update_by_serial) are concrete and further clarify the scope.

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?

The description gives clear guidance on choosing between the two actions: 'update' by passport id and 'update_by_serial' by your own serial. It explains the serial-uniqueness caveat within a GTIN and the 409 ambiguous_serial error, advising to pass `gtin` or use update by id. However, it does not explicitly compare this tool to sibling tools or state when to prefer this over them.

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

Deploy Server