Skip to main content
Glama

Search retailers

get_retailers
Read-onlyIdempotent

Search retailers (shops) registered on authorized.by, or list them all. Read-only. 'search' matches the company name, alias or shop domain (partial match): a URL is reduced to its domain, except on marketplace hosts such as amazon.de or ebay.de, where the store path is kept and the bare host lists every seller. A partial match can find other shops (shop.de also finds myshop.de), so compare shop_url with the domain you are checking; to verify one shop against a brand, use verify_retailer_authorization. Returns for each retailer: id, name, slug, shop URL, logo, the number of brands that authorized it, and certificate_url / certificate_url_de: links to the retailer's public authorized.by certificate page (English / German) listing all brands that authorized it; null when the retailer has no active authorization. Omit 'search' to retrieve the full index; use 'page' and 'size' to paginate. 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

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_retailers"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoZero-based page number (default 0).
sizeNoPage size (default and maximum 500).
searchNoFilter by retailer company name, alias or shop domain/URL, e.g. 'best-shop' or 'best-shop.de'. Optional.

Output Schema

NameRequiredDescriptionDefault
metaYesNetwork-wide totals.
retailersYes
paginationYesPagination of this response.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changed
    • changedInput schema / properties / size / description
      Previous value: -"Page size (default 500)."New value: +"Page size (default and maximum 500)."
    • 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."
    • addedOutput schema / properties / retailers / items / properties / certificate_url
      Added value: +{
      +  "description": "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.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / retailers / items / properties / certificate_url_de
      Added value: +{
      +  "description": "Same certificate page in German; null when there is no active authorization.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • 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"
      +]
    • 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"
      -}
    • changedOutput schema / properties / retailers / items / required
      Previous value: -[
      -  "id",
      -  "name",
      -  "slug",
      -  "shop_url",
      -  "logo",
      -  "seal_implemented",
      -  "brand_count",
      -  "details"
      -]New value: +[
      +  "id",
      +  "name",
      +  "slug",
      +  "shop_url",
      +  "logo",
      +  "certificate_url",
      +  "certificate_url_de",
      +  "brand_count",
      +  "details"
      +]
  2. Changed1 schema field changed
    • changedInput schema / properties / search / description
      Previous value: -"Filter by retailer company name or alias. Optional."New value: +"Filter by retailer company name, alias or shop domain/URL, e.g. 'best-shop' or 'best-shop.de'. Optional."
  3. Changed2 schema fields changed
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": false,
      +  "description": "A page of retailers plus network-wide totals and pagination.",
      +  "properties": {
      +    "meta": {
      +      "additionalProperties": false,
      +      "description": "Network-wide totals.",
      +      "properties": {
      +        "generated_at": {
      +          "description": "Timestamp (ISO 8601) the index was generated.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "total_brands": {
      +          "description": "Total number of public brands on authorized.by.",
      +          "type": "integer"
      +        },
      +        "total_connections": {
      +          "description": "Total number of active brand-retailer authorizations on authorized.by.",
      +          "type": "integer"
      +        },
      +        "total_retailers": {
      +          "description": "Total number of public retailers on authorized.by.",
      +          "type": "integer"
      +        }
      +      },
      +      "required": [
      +        "total_brands",
      +        "total_retailers",
      +        "total_connections",
      +        "generated_at"
      +      ],
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "pagination": {
      +      "additionalProperties": false,
      +      "description": "Pagination of this response.",
      +      "properties": {
      +        "page": {
      +          "description": "Zero-based page number of this response.",
      +          "type": "integer"
      +        },
      +        "size": {
      +          "description": "Page size used for this response.",
      +          "type": "integer"
      +        },
      +        "total_items": {
      +          "description": "Total number of matching entries across all pages.",
      +          "type": "integer"
      +        },
      +        "total_pages": {
      +          "description": "Total number of pages.",
      +          "type": "integer"
      +        }
      +      },
      +      "required": [
      +        "page",
      +        "size",
      +        "total_items",
      +        "total_pages"
      +      ],
      +      "type": [
      +        "object",
      +        "null"
      +      ]
      +    },
      +    "retailers": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "brand_count": {
      +            "description": "Number of brands that currently authorize this retailer on authorized.by.",
      +            "type": "integer"
      +          },
      +          "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"
      +            ]
      +          },
      +          "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"
      +            ]
      +          }
      +        },
      +        "required": [
      +          "id",
      +          "name",
      +          "slug",
      +          "shop_url",
      +          "logo",
      +          "seal_implemented",
      +          "brand_count",
      +          "details"
      +        ],
      +        "type": "object"
      +      },
      +      "type": [
      +        "array",
      +        "null"
      +      ]
      +    }
      +  },
      +  "required": [
      +    "retailers",
      +    "meta",
      +    "pagination"
      +  ],
      +  "type": "object"
      +}
  4. Added

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the readOnlyHint/idempotentHint annotations, it discloses real behavioral detail: URL normalization to domain, the marketplace exception (amazon.de / ebay.de keeping the store path, bare host listing every seller), null certificate_url when no active authorization, and the meaning of empty lists versus 'Brand not found' versus 'Tool execution failed'. It also flags the data-scope limitation that absence on authorized.by does not prove absence of authorization elsewhere — a genuine trap an agent could otherwise fall into.

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?

Front-loaded well — the mode distinction and alternatives come first, caveats after. However, the middle sentence enumerating return fields (id, name, slug, shop URL, logo, brand count, certificate links) duplicates the output schema that already exists, adding length without new information; the certificate_url null semantics could have been stated without re-listing every field.

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 search tool with three optional parameters, an output schema, and full annotation coverage, this covers everything an agent needs: matching semantics, pagination, data-scope limits, and a taxonomy of error outcomes. No significant ambiguity remains about when results are meaningful.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining what 'search' actually matches (company name, alias, shop domain), how a URL is reduced, and the marketplace-host exception. Page/size semantics are left entirely to the schema, which is acceptable since they are already documented there.

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?

Opens with a specific verb and resource plus its scope: 'Search retailers (shops) registered on authorized.by, or list them all.' It immediately clarifies the tool's dual mode (filtered search vs. full listing), which is exactly the axis on which it differs from get_retailer and get_brand_retailers, and it names verify_retailer_authorization as the tool for single-shop validation.

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?

Explicitly states the when-to-use alternatives: 'Omit search to retrieve the full index; use page and size to paginate' and 'to verify one shop against a brand, use verify_retailer_authorization.' It also warns that a partial match can hit other shops and that the result should be cross-checked against shop_url, which is actionable routing guidance rather than generic prose.

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