DOCS · THE DOOR OF RECORD

Docs

The door at version 1.0.0: twenty tools in seven groups over one ontology — product × ingredient × market × actor — answering from records whose every field carries its source page. This page is the reference; the Agent Card is the discovery document; the setup page is the connection page.

§01 · ONTOLOGY

Ontology

product × ingredient × market × actor.

  • Markets (18) — US · MX · CA · BR · UK · FR · DE · NL · IT · ES · PL · CH · AE · IN · SG · JP · KR · AU (UK is stored as ISO GB in machine fields and written UK everywhere a person reads).
  • Rule sets (13) — US · MX · CA · BR · UK · EU (FR DE NL IT ES PL share it; label language and local contact differ) · CH · AE · IN · SG · JP · KR · AU.
  • Actors — brand · manufacturer · retailer · distributor · auditor; agent inherits the class of its credential.
  • Market status — cosmetic · drug · special_class · not_permitted, product type by market.
§02 · THE TWENTY TOOLS

The twenty tools

  • Gate — called first; allow or deny with the reason and the rule
  • resolve_jurisdiction — Where is this going? Returns the market and rule set.
  • resolve_actor — Who is asking? Brand, manufacturer, retailer or distributor.
  • gate_transaction — Allow or deny, with the reason and the rule.
  • Regulatory truth — what the regulators' pages say, with the source on every field
  • get_ingredient_record — One ingredient, and its status in every market.
  • get_market_status — Is this product type a cosmetic here?
  • get_notification_requirements — What must be filed before sale.
  • get_label_and_claims — What the label must say, and which claims are allowed.
  • get_enforcement_watch — Recalls, bans and safety alerts, dated.
  • Catalogue — only validated rows are served
  • search_cleared_items — Find products cleared for this market.
  • get_item — One product by GTIN, fully resolved.
  • compare_items — Compare products, variants and shades.
  • Supply — after the gate
  • find_verified_supplier — Verified makers and brands for this product.
  • get_availability — In stock, and where.
  • get_price — The price for this buyer.
  • Documents — the papers behind a product
  • get_product_documents — Safety report, certificate of analysis, data sheet.
  • verify_gtin — Is this GTIN real, and whose is it?
  • Commerce — an order between two agents; the handoff
  • create_order_intent — Open an order between two agents.
  • a2a_handoff — Hand the buyer to the right agent.
  • Operations — warnings and the audit line
  • get_safety_label — Warnings and age limits.
  • log_audit — Write a line to the audit record.
§03 · GATE ORDER

Gate order

resolve_jurisdiction → resolve_actor → gate_transaction. No availability, price, documents, order or handoff tool answers before an allow decision exists for the request.

  • Reason codes (twelve) — ALLOW · REQUIRE_NOTIFICATION · REQUIRE_RESPONSIBLE_PERSON · DENY_NOT_A_COSMETIC_HERE · DENY_INGREDIENT_BANNED · DENY_INGREDIENT_LIMIT · DENY_CLAIM · DENY_MARKET · DENY_ACTOR_CLASS · DENY_UNLICENSED_AGENT · DENY_NO_GTIN · DENY_NOT_VERIFIED.
  • Rule set — {jurisdiction, version, effective_date, supersedes, markets[], notification, responsible_person, market_status[], ingredient_lists[], claims_rules[], label[], rules[], source_urls[]}; a change on a regulator's page produces a new version with supersedes set; the old version stays readable.
  • Conditions — REQUIRE_NOTIFICATION and REQUIRE_RESPONSIBLE_PERSON are allow-with-condition: the trade proceeds once the filing or the person is on the record.
§04 · RECORD PRIMITIVE

Record primitive

Every field on every record is {value, source_url, read_by, read_at, state}; a value with no source page does not exist on this graph. Counts are produced from records at request time, never typed.

  • Product — gtin · product_name · brand · taxonomy {level1..level4} · variant_form · lanes[] · ingredients_inci[] · claims[] · attributes · shades[] (parent and child) · availability {banners, product_urls, pos_count} · documents[] · claim_status · source_url · read_at.
  • Ingredient — inci_name · aliases[] · cas · status per rule set {status, list, annex, limit, condition, source_url}.
  • Supplier — brand or manufacturer · market · website (a candidate URL, read live by the sweep) · claim_status. Retailer — banner · parent banner · country · channel · store count where known.
  • Enforcement event — recalls, bans, safety alerts, dated, with the regulator's page.
§05 · ON THE WIRE

On the wire

  • Transport — streamable-HTTP, stateless; server name a2a-cosmetics; endpoint https://mcp.a2a-cosmetics.ai/mcp.
  • Schemas — open (no additionalProperties:false), no oneOf, so the stock clients of the three major clouds attach without an adapter.
  • Headers — the GSC wire envelope on every response (x-gsc-node, x-gsc-card, x-gsc-trust-anchor, x-gsc-mcp, x-gsc-graph and the rest).
  • Signing — the Agent Card and records are signed ES256 under kid a2ac-2026-09; keyring https://a2a-cosmetics.ai/.well-known/jwks.json.
  • Settlement — create_order_intent settles by x402 on a2a-x402.ai after the gate; receipts signed EdDSA; a refused intent is not settled and not charged.