Skip to main content
Glama

List a brand's authorized retailers

get_brand_retailers
Read-onlyIdempotent

List all retailers (shops) currently authorized by a brand on authorized.by. Read-only. Use this to list a brand's authorized shops; to check one shop by its domain or URL, use verify_retailer_authorization. Sorted by brand_count (the number of brands that authorize the retailer) descending, then by name. Each retailer includes shop_url, official_shop (the brand's own online shop, as opposed to an independent authorized retailer), partnership_date, tuv_certified (shop identity verified in the TÜV Saarland ShopIdent procedure), and certificate_url / certificate_url_de: links to the public authorized.by certificate page (English / German) proving this specific brand-retailer authorization. Share the certificate link when a user needs verifiable proof. Only active partnerships are returned: confirmed by both the brand and the retailer, with both profiles public and both companies approved by authorized.by. Revoked or pending partnerships are never listed. Responses are cached and refreshed when the underlying profile or partnership changes, so a revocation may take a short time to disappear. partnership_date is the date the authorization STARTED, not the date it was last verified; a partnership listed here is currently active as of the response time. 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": {
      "id_or_alias": "<id_or_alias>"
    },
    "name": "get_brand_retailers"
  }
}

Input Schema

NameRequiredDescriptionDefault
id_or_aliasYesBrand numeric ID, slug or alias.

Output Schema

NameRequiredDescriptionDefault
totalYesNumber of entries in the list.
brand_idYesNumeric ID of the brand the list belongs to.
retailersYes
tuv_certified_countYesNumber of listed retailers whose identity has been verified in the TÜV Saarland ShopIdent procedure.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed17 schema fields changed
    • removedOutput schema / properties / premium_count
      Removed value: -{
      -  "description": "Number of listed retailers on the PREMIUM plan.",
      -  "type": "integer"
      -}
    • changedOutput schema / properties / retailers / items / properties / brand_count / description
      Previous value: -"Number of brands that currently authorize this retailer on authorized.by."New value: +"Number of brands with a public, approved profile that currently authorize this retailer on authorized.by. Only authorizations confirmed by both the brand and the retailer count; pending requests and ended authorizations do not."
    • changedOutput schema / properties / retailers / items / 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 / retailers / items / properties / details / properties / registration_date / description
      Previous value: -"Date (YYYY-MM-DD) the company registered on authorized.by."New value: +"Date (YYYY-MM-DD) the retailer registered on authorized.by."
    • removedOutput schema / properties / retailers / items / properties / details / properties / trustami
      Removed value: -{
      -  "additionalProperties": false,
      -  "description": "Customer rating from Trustami; fields are null when no rating exists.",
      -  "properties": {
      -    "profile_url": {
      -      "description": "URL of the rating profile, or null.",
      -      "type": [
      -        "string",
      -        "null"
      -      ]
      -    },
      -    "rating": {
      -      "description": "Average customer rating, or null.",
      -      "type": [
      -        "number",
      -        "null"
      -      ]
      -    },
      -    "review_count": {
      -      "description": "Number of customer reviews, or null.",
      -      "type": [
      -        "integer",
      -        "null"
      -      ]
      -    }
      -  },
      -  "required": [
      -    "rating",
      -    "review_count",
      -    "profile_url"
      -  ],
      -  "type": [
      -    "object",
      -    "null"
      -  ]
      -}
    • changedOutput schema / properties / retailers / items / properties / details / properties / tuv_certification_date / description
      Previous value: -"Date (YYYY-MM-DD) the TÜV certification was granted; null when not certified."New value: +"Date (YYYY-MM-DD) the TÜV Saarland ShopIdent verification of the shop's identity was approved; null when there is none. It does not say how long the verification remains valid."
    • changedOutput schema / properties / retailers / items / properties / details / required
      Previous value: -[
      -  "address",
      -  "phone",
      -  "email",
      -  "opening_hours",
      -  "payment_methods",
      -  "description",
      -  "categories",
      -  "tuv_certification_date",
      -  "registration_date",
      -  "trustami",
      -  "social"
      -]New value: +[
      +  "address",
      +  "phone",
      +  "email",
      +  "opening_hours",
      +  "payment_methods",
      +  "description",
      +  "categories",
      +  "tuv_certification_date",
      +  "registration_date",
      +  "social"
      +]
    • changedOutput schema / properties / retailers / items / 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 / retailers / items / 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."
    • removedOutput schema / properties / retailers / items / properties / plan
      Removed value: -{
      -  "description": "authorized.by subscription plan of the retailer: PREMIUM, START or FREE.",
      -  "type": [
      -    "string",
      -    "null"
      -  ]
      -}
    • removedOutput schema / properties / retailers / items / properties / product_count
      Removed value: -{
      -  "description": "Number of products registered on authorized.by; null when unknown.",
      -  "type": [
      -    "integer",
      -    "null"
      -  ]
      -}
    • removedOutput schema / properties / retailers / items / properties / seal_implemented
      Removed value: -{
      -  "description": "Whether the authorized.by seal is live on the retailer's shop.",
      -  "type": "boolean"
      -}
    • removedOutput schema / properties / retailers / items / properties / sponsored
      Removed value: -{
      -  "description": "Whether the brand sponsors (highlights) this retailer.",
      -  "type": "boolean"
      -}
    • changedOutput schema / properties / retailers / items / properties / tuv_certified / description
      Previous value: -"Whether the retailer holds a TÜV certification via authorized.by."New value: +"Whether the identity of the shop has been verified in the TÜV Saarland ShopIdent procedure, arranged through authorized.by. It is an identity check of the shop operator, not a certification of the retailer's business, service or products."
    • changedOutput schema / properties / retailers / items / required
      Previous value: -[
      -  "id",
      -  "name",
      -  "slug",
      -  "shop_url",
      -  "logo",
      -  "plan",
      -  "tuv_certified",
      -  "seal_implemented",
      -  "official_shop",
      -  "sponsored",
      -  "certificate_url",
      -  "certificate_url_de",
      -  "brand_count",
      -  "product_count",
      -  "partnership_date",
      -  "details"
      -]New value: +[
      +  "id",
      +  "name",
      +  "slug",
      +  "shop_url",
      +  "logo",
      +  "tuv_certified",
      +  "official_shop",
      +  "certificate_url",
      +  "certificate_url_de",
      +  "brand_count",
      +  "partnership_date",
      +  "details"
      +]
    • changedOutput schema / properties / tuv_certified_count / description
      Previous value: -"Number of listed retailers with a TÜV certification."New value: +"Number of listed retailers whose identity has been verified in the TÜV Saarland ShopIdent procedure."
    • changedOutput schema / required
      Previous value: -[
      -  "brand_id",
      -  "total",
      -  "premium_count",
      -  "tuv_certified_count",
      -  "retailers"
      -]New value: +[
      +  "brand_id",
      +  "total",
      +  "tuv_certified_count",
      +  "retailers"
      +]
  2. Changed3 schema fields changed
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / id_or_alias / description
      Previous value: -"Brand numeric ID or alias."New value: +"Brand numeric ID, slug or alias."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": false,
      +  "description": "All retailers currently authorized by the brand, with per-retailer certificate links.",
      +  "properties": {
      +    "brand_id": {
      +      "description": "Numeric ID of the brand the list belongs to.",
      +      "type": "integer"
      +    },
      +    "premium_count": {
      +      "description": "Number of listed retailers on the PREMIUM plan.",
      +      "type": "integer"
      +    },
      +    "retailers": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "brand_count": {
      +            "description": "Number of brands that currently authorize this retailer on authorized.by.",
      +            "type": "integer"
      +          },
      +          "certificate_url": {
      +            "description": "Public authorized.by certificate page (English) that proves the authorization; null when there is no active authorization.",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "certificate_url_de": {
      +            "description": "Same certificate page in German; null when there is no active authorization.",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "details": {
      +            "additionalProperties": false,
      +            "description": "Extended profile details.",
      +            "properties": {
      +              "address": {
      +                "type": [
      +                  "string",
      +                  "null"
      +                ]
      +              },
      +              "categories": {
      +                "description": "Product categories.",
      +                "items": {
      +                  "additionalProperties": false,
      +                  "properties": {
      +                    "de": {
      +                      "description": "German text, or null.",
      +                      "type": [
      +                        "string",
      +                        "null"
      +                      ]
      +                    },
      +                    "en": {
      +                      "description": "English text, or null.",
      +                      "type": [
      +                        "string",
      +                        "null"
      +                      ]
      +                    }
      +                  },
      +                  "required": [
      +                    "de",
      +                    "en"
      +                  ],
      +                  "type": "object"
      +                },
      +                "type": [
      +                  "array",
      +                  "null"
      +                ]
      +              },
      +              "description": {
      +                "additionalProperties": false,
      +                "description": "Description text in German (de) and English (en); each may be null.",
      +                "properties": {
      +                  "de": {
      +                    "description": "German text, or null.",
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "en": {
      +                    "description": "English text, or null.",
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  }
      +                },
      +                "required": [
      +                  "de",
      +                  "en"
      +                ],
      +                "type": [
      +                  "object",
      +                  "null"
      +                ]
      +              },
      +              "email": {
      +                "type": [
      +                  "string",
      +                  "null"
      +                ]
      +              },
      +              "opening_hours": {
      +                "description": "Weekly opening hours of the physical store; empty or null when unknown.",
      +                "items": {
      +                  "additionalProperties": false,
      +                  "properties": {
      +                    "closing_hour": {
      +                      "description": "Closing time.",
      +                      "type": [
      +                        "string",
      +                        "null"
      +                      ]
      +                    },
      +                    "day_of_week": {
      +                      "description": "Day of the week.",
      +                      "type": [
      +                        "string",
      +                        "null"
      +                      ]
      +                    },
      +                    "opening_hour": {
      +                      "description": "Opening time.",
      +                      "type": [
      +                        "string",
      +                        "null"
      +                      ]
      +                    }
      +                  },
      +                  "required": [
      +                    "day_of_week",
      +                    "opening_hour",
      +                    "closing_hour"
      +                  ],
      +                  "type": "object"
      +                },
      +                "type": [
      +                  "array",
      +                  "null"
      +                ]
      +              },
      +              "payment_methods": {
      +                "description": "Accepted payment methods; null when unknown.",
      +                "items": {
      +                  "type": "string"
      +                },
      +                "type": [
      +                  "array",
      +                  "null"
      +                ]
      +              },
      +              "phone": {
      +                "type": [
      +                  "string",
      +                  "null"
      +                ]
      +              },
      +              "registration_date": {
      +                "description": "Date (YYYY-MM-DD) the company registered on authorized.by.",
      +                "type": [
      +                  "string",
      +                  "null"
      +                ]
      +              },
      +              "social": {
      +                "additionalProperties": false,
      +                "description": "Social media profile URLs; each may be null.",
      +                "properties": {
      +                  "facebook": {
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "instagram": {
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "linkedin": {
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "youtube": {
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  }
      +                },
      +                "required": [
      +                  "instagram",
      +                  "facebook",
      +                  "linkedin",
      +                  "youtube"
      +                ],
      +                "type": [
      +                  "object",
      +                  "null"
      +                ]
      +              },
      +              "trustami": {
      +                "additionalProperties": false,
      +                "description": "Customer rating from Trustami; fields are null when no rating exists.",
      +                "properties": {
      +                  "profile_url": {
      +                    "description": "URL of the rating profile, or null.",
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "rating": {
      +                    "description": "Average customer rating, or null.",
      +                    "type": [
      +                      "number",
      +                      "null"
      +                    ]
      +                  },
      +                  "review_count": {
      +                    "description": "Number of customer reviews, or null.",
      +                    "type": [
      +                      "integer",
      +                      "null"
      +                    ]
      +                  }
      +                },
      +                "required": [
      +                  "rating",
      +                  "review_count",
      +                  "profile_url"
      +                ],
      +                "type": [
      +                  "object",
      +                  "null"
      +                ]
      +              },
      +              "tuv_certification_date": {
      +                "description": "Date (YYYY-MM-DD) the TÜV certification was granted; null when not certified.",
      +                "type": [
      +                  "string",
      +                  "null"
      +                ]
      +              }
      +            },
      +            "required": [
      +              "address",
      +              "phone",
      +              "email",
      +              "opening_hours",
      +              "payment_methods",
      +              "description",
      +              "categories",
      +              "tuv_certification_date",
      +              "registration_date",
      +              "trustami",
      +              "social"
      +            ],
      +            "type": [
      +              "object",
      +              "null"
      +            ]
      +          },
      +          "id": {
      +            "description": "Numeric authorized.by ID. Accepted by the id_or_alias argument of the detail tools.",
      +            "type": "integer"
      +          },
      +          "logo": {
      +            "description": "Logo image URL, or null.",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "name": {
      +            "description": "Display name.",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "official_shop": {
      +            "description": "Whether this shop is the brand's own official shop.",
      +            "type": "boolean"
      +          },
      +          "partnership_date": {
      +            "description": "Date (YYYY-MM-DD) the authorization STARTED. Not a last-verified date: every listed partnership is active as of the response.",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "plan": {
      +            "description": "authorized.by subscription plan of the retailer: PREMIUM, START or FREE.",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "product_count": {
      +            "description": "Number of products registered on authorized.by; null when unknown.",
      +            "type": [
      +              "integer",
      +              "null"
      +            ]
      +          },
      +          "seal_implemented": {
      +            "description": "Whether the authorized.by seal is live on the retailer's shop.",
      +            "type": "boolean"
      +          },
      +          "shop_url": {
      +            "description": "Retailer online-shop URL, or null.",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "slug": {
      +            "description": "URL-safe identifier. Accepted by the id_or_alias argument of the detail tools.",
      +            "type": [
      +              "string",
      +              "null"
      +            ]
      +          },
      +          "sponsored": {
      +            "description": "Whether the brand sponsors (highlights) this retailer.",
      +            "type": "boolean"
      +          },
      +          "tuv_certified": {
      +            "description": "Whether the retailer holds a TÜV certification via authorized.by.",
      +            "type": "boolean"
      +          }
      +        },
      +        "required": [
      +          "id",
      +          "name",
      +          "slug",
      +          "shop_url",
      +          "logo",
      +          "plan",
      +          "tuv_certified",
      +          "seal_implemented",
      +          "official_shop",
      +          "sponsored",
      +          "certificate_url",
      +          "certificate_url_de",
      +          "brand_count",
      +          "product_count",
      +          "partnership_date",
      +          "details"
      +        ],
      +        "type": "object"
      +      },
      +      "type": [
      +        "array",
      +        "null"
      +      ]
      +    },
      +    "total": {
      +      "description": "Number of entries in the list.",
      +      "type": "integer"
      +    },
      +    "tuv_certified_count": {
      +      "description": "Number of listed retailers with a TÜV certification.",
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "brand_id",
      +    "total",
      +    "premium_count",
      +    "tuv_certified_count",
      +    "retailers"
      +  ],
      +  "type": "object"
      +}
  3. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Goes well past the annotations, which only establish read-only/idempotent safety. The description discloses the sort order (brand_count descending, then name), the active-only guarantee (both sides confirmed, both profiles public, both companies approved), that revoked or pending partnerships are never listed, and that caching can delay a revocation from disappearing. It also documents that partnership_date is the start date, not a verification timestamp, and distinguishes empty results from 'Brand not found' and technical errors.

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

Conciseness3/5

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

The purpose and sibling routing are front-loaded, but the body is a single dense paragraph. It enumerates return fields (shop_url, official_shop, tuv_certified, certificate_url/certificate_url_de) that are already covered by the output schema, and 'Read-only' repeats the readOnlyHint annotation, so some sentences do not fully earn their place.

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 filtered list tool with an output schema and full annotation coverage, nothing material is missing: scope limits (only relationships registered on authorized.by, empty result does not prove absence elsewhere), freshness/caching caveats, active-only guarantees, and error classification are all present.

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

Parameters3/5

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

Schema coverage is 100%, so the single id_or_alias parameter is already documented as a brand numeric ID, slug, or alias. The description only adds that an unknown id/alias produces a 'Brand not found' error, which clarifies failure behavior but not the parameter's format or accepted values. Baseline 3 is appropriate when the schema carries the semantics.

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?

States a specific verb and resource ('List all retailers (shops) currently authorized by a brand on authorized.by') and immediately distinguishes itself from verify_retailer_authorization, which handles single-shop lookups by domain or URL. An agent can pick between the two without opening either schema.

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?

Gives an explicit routing rule: use this to list a brand's authorized shops, use verify_retailer_authorization to check one shop by domain or URL. It also tells the agent when to surface certificate links ('when a user needs verifiable proof'), so both tool selection and post-call behavior are covered.

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