Skip to main content
Glama

Verify a retailer's authorization

verify_retailer_authorization
Read-onlyIdempotent

Check whether a shop is an authorized retailer of a brand, from the shop's domain or URL plus the brand or one of its products' GTIN (EAN). Read-only. Use this when you know the seller's domain, e.g. from a shopping or UCP catalog result. Pass exactly one of 'brand' or 'gtin'; a GTIN resolves the product's brand and the check stays brand-level. status: AUTHORIZED = authorization active: the brand has confirmed this shop on authorized.by; official_shop, partnership_date and certificate_url / certificate_url_de prove it, share the certificate link when a user needs proof; 'brand' in the answer is the brand that was checked. NO_RECORD_FOR_BRAND = the shop and the brand are on authorized.by, but this brand has not confirmed this shop there (also when a GTIN belongs to several brands and not exactly one confirmed it; brand is then null). RETAILER_NOT_REGISTERED = no public shop on authorized.by at this domain. BRAND_NOT_REGISTERED = 'brand' does not identify exactly one public brand (the brand is not on authorized.by, or the value is a name shared by several brands or only part of a brand's name), or no product matches 'gtin'; before telling a user that a brand is not on authorized.by, search get_brands with the name and call again with the slug of the brand that was meant. None of these statuses means that the shop is unauthorized. Domains match exactly, never a parent domain or another subdomain (www. and m. count as the same shop); marketplace hosts such as amazon.de or ebay.de only match the exact store URL. The answer is computed live, never cached. Data scope: results only cover relationships registered and confirmed on authorized.by. An empty result or a not-found error does NOT prove that no authorization exists outside authorized.by. Distinguish outcomes: an empty list means no matching record on authorized.by; an error result whose text starts with 'Brand not found' or 'Retailer not found' means the given id/alias is unknown; an error result whose text starts with 'Tool execution failed' is a technical error and says nothing about the data.

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": {
      "retailer_domain": "<retailer_domain>"
    },
    "name": "verify_retailer_authorization"
  }
}

Input Schema

NameRequiredDescriptionDefault
gtinNoGTIN / EAN of a product of the brand, 8 to 14 or 18 digits. Omit when passing 'brand'.
brandNoBrand numeric ID, slug, alias, website domain or name, e.g. 'deuter', 'deuter.com' or 'Napoleon'. A number is always read as an ID. A name is only accepted when it identifies exactly one brand; otherwise use get_brands to find the slug. Omit when passing 'gtin'.
retailer_domainYesShop domain or URL, e.g. 'best-shop.de' or 'https://www.best-shop.de/de/grills'.

Output Schema

NameRequiredDescriptionDefault
gtinYesThe checked GTIN, normalized to 14 digits (18 for GTIN-18); null when checked by brand.
brandYesThe checked brand, also when it was given by its name; null when the shop or the brand is not registered, or when a GTIN matches several brands and not exactly one of them confirmed the shop.
statusYesOutcome of the check: AUTHORIZED (authorization active), NO_RECORD_FOR_BRAND, RETAILER_NOT_REGISTERED or BRAND_NOT_REGISTERED. None of them means that the shop is unauthorized.
retailerYesThe authorized.by shop registered at this domain; null when there is none.
checked_atYesTimestamp (ISO 8601) the check was made; answers are never cached.
official_shopYestrue when this shop is the brand's own official online shop, false when it is an independent authorized retailer. In verify_retailer_authorization it is null unless the status is AUTHORIZED.
certificate_urlYesPublic authorized.by certificate page (English) that proves the authorization: of this brand and retailer where the entry is about both, otherwise the retailer's page listing all brands that authorize it. Null when there is no active authorization.
retailer_domainYesThe checked shop domain and path, as parsed from the request.
partnership_dateYesDate (YYYY-MM-DD) this brand's authorization of this retailer STARTED on authorized.by. Not the date either company joined authorized.by and not a last-verified date: every listed partnership is active as of the response.
certificate_url_deYesSame certificate page in German; null when there is no active authorization.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / brand / description
      Previous value: -"Brand numeric ID, slug, alias or website domain, e.g. 'deuter' or 'deuter.com'. Use get_brands to find the slug from a name. Omit when passing 'gtin'."New value: +"Brand numeric ID, slug, alias, website domain or name, e.g. 'deuter', 'deuter.com' or 'Napoleon'. A number is always read as an ID. A name is only accepted when it identifies exactly one brand; otherwise use get_brands to find the slug. Omit when passing 'gtin'."
    • changedOutput schema / properties / brand / description
      Previous value: -"The checked brand; null when the shop or the brand is not registered, or when a GTIN matches several brands and not exactly one of them confirmed the shop."New value: +"The checked brand, also when it was given by its name; null when the shop or the brand is not registered, or when a GTIN matches several brands and not exactly one of them confirmed the shop."
  2. Changed3 schema fields changed
    • changedOutput schema / properties / certificate_url / description
      Previous value: -"Public authorized.by certificate page (English) that proves the authorization; null when there is no active authorization."New value: +"Public authorized.by certificate page (English) that proves the authorization: of this brand and retailer where the entry is about both, otherwise the retailer's page listing all brands that authorize it. Null when there is no active authorization."
    • changedOutput schema / properties / official_shop / description
      Previous value: -"Whether this shop is the brand's own official shop."New value: +"true when this shop is the brand's own official online shop, false when it is an independent authorized retailer. In verify_retailer_authorization it is null unless the status is AUTHORIZED."
    • changedOutput schema / properties / partnership_date / description
      Previous value: -"Date (YYYY-MM-DD) the authorization STARTED. Not a last-verified date: every listed partnership is active as of the response."New value: +"Date (YYYY-MM-DD) this brand's authorization of this retailer STARTED on authorized.by. Not the date either company joined authorized.by and not a last-verified date: every listed partnership is active as of the response."
  3. Changed3 schema fields changed
    • changedOutput schema / description
      Previous value: -"Outcome of the authorization check, with certificate links when VERIFIED."New value: +"Outcome of the authorization check, with certificate links when AUTHORIZED."
    • changedOutput schema / properties / status / description
      Previous value: -"Outcome of the check: VERIFIED, NO_RECORD_FOR_BRAND, RETAILER_NOT_REGISTERED or BRAND_NOT_REGISTERED. None of them means that the shop is unauthorized."New value: +"Outcome of the check: AUTHORIZED (authorization active), NO_RECORD_FOR_BRAND, RETAILER_NOT_REGISTERED or BRAND_NOT_REGISTERED. None of them means that the shop is unauthorized."
    • changedOutput schema / properties / status / enum
      Previous value: -[
      -  "VERIFIED",
      -  "NO_RECORD_FOR_BRAND",
      -  "RETAILER_NOT_REGISTERED",
      -  "BRAND_NOT_REGISTERED",
      -  null
      -]New value: +[
      +  "AUTHORIZED",
      +  "NO_RECORD_FOR_BRAND",
      +  "RETAILER_NOT_REGISTERED",
      +  "BRAND_NOT_REGISTERED",
      +  null
      +]
  4. Added

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already cover read-only and idempotency, but the description adds substantial context beyond them: live computation with no caching, exact-domain matching rules (www./m. equivalence, no parent or subdomain matches, marketplace host behavior), the data scope limit, and how to distinguish an empty list from 'Brand not found'/'Retailer not found' versus 'Tool execution failed' errors. That error-taxonomy guidance is exactly the kind of disclosure annotations cannot carry.

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

Conciseness4/5

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

The core purpose and input rule are front-loaded, and nearly every sentence carries operational information. The status-code enumeration is dense prose that slightly repeats itself (the NO_RECORD_FOR_BRAND parenthetical restates the ambiguity rule already covered by BRAND_NOT_REGISTERED), so it reads longer than strictly necessary.

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?

For a three-parameter verification tool with an output schema, the definition covers everything an agent needs: input exclusivity, matching semantics, every status code's meaning, the certificate-proof path for end users, and the limits of what a negative result proves.

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 coverage is already 100%, yet the description still adds meaning: the mutual exclusivity of brand and gtin, the fact that a GTIN only resolves the brand so the verdict stays brand-level, that 'brand' in the answer is the brand actually checked, and that ambiguous brand values should be resolved via get_brands first.

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 opening sentence gives a specific verb and resource (check whether a shop is an authorized retailer of a brand) plus the exact inputs that drive the check (domain or URL plus brand or GTIN). It is clearly distinguishable from siblings such as get_retailer and get_brands, which are named as lookup tools rather than verification tools.

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

Usage Guidelines5/5

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

It states when to use it ('when you know the seller's domain, e.g. from a shopping or UCP catalog result'), the input constraint ('pass exactly one of brand or gtin'), and the fallback path ('search get_brands ... and call again with the slug'). It also explicitly warns that a negative result must not be reported as 'unauthorized', which is a usage rule, not just a behavior note.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources