Skip to main content
Glama

brands

by by.authorized
OverviewDiscussionsAdmin

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 seal_implemented (whether the authorized.by seal is live on their shop). 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.

Input Schema

NameRequiredDescriptionDefault
pageNoZero-based page number (default 0).
sizeNoPage size (default 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. 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."
  2. 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"
+}
  3. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds substantial context: data only covers relationships registered on authorized.by, empty results do not prove absence of authorization, and error prefixes ('Brand not found' vs 'Tool execution failed') are decoded. That is genuine behavioral disclosure beyond structured fields.

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?

Front-loads purpose and mode selection, then layers matching semantics and result interpretation. Dense but nearly every sentence carries decision-relevant information; the error-prefix enumeration is slightly heavy for the space it occupies.

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?

Despite an output schema existing, the description still summarizes returned fields briefly and, more importantly, closes the interpretive gap around empty vs error results — the one thing an output schema cannot convey. Nothing material for correct invocation is missing.

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 match semantics (company name, alias, shop domain, partial match risk) and the marketplace-host exception where the store path is kept. It does not restate defaults for page/size, but those are already in the schema.

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?

Names a specific verb and resource ('Search retailers (shops) registered on authorized.by, or list them all') and immediately scopes it against siblings by pointing to verify_retailer_authorization for single-shop verification. An agent can distinguish this from get_retailer / get_retailer_brands without opening a 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 explicit when-to-use branching: omit 'search' to list the full index, use 'page'/'size' to paginate, and use verify_retailer_authorization instead when the goal is checking one shop against a brand. It also warns that a partial match can return other shops and to compare shop_url.

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

All brands toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources