Skip to main content
Glama

Beacon - verified-merchant index for AI shopping agents

by io.github.primoliquors
OverviewDiscussionsAdmin

find_best_merchant

Rank merchants that can actually fulfill a purchase need, by honest signals only.

Args:
    category: product category, e.g. "vodka".
    ship_to: ISO region the order must ship to, e.g. "US-FL".
    require_age_gate: only return merchants that enforce 21+.
    limit: max results.
    optimize_for: what matters to the BUYER -- "trust" (default), "price"
        (lowest matched price), or "speed" (same-day, then next-day
        fulfillment). Ties always break by earned trust.
    product_type/dest_state/channel: pass all three (e.g. "spirits", "FL",
        "ship"|"local_delivery") for STRICT COMPLIANCE mode -- only merchants
        with attested age-gate + attested license + a legal jurisdiction
        path are returned, each with its compliance verdict.
Every result carries ships_to states (match them against where the buyer
lives), best_price, and the evidence behind the record. Paid placement never
affects any ranking (ranking_basis states the basis actually used).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNo
channelNo
ship_toNo
categoryNo
dest_stateNo
ready_onlyNo
optimize_forNotrust
product_typeNo
require_age_gateNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / ready_only
      Added value: +{
+  "default": false,
+  "title": "Ready Only",
+  "type": "boolean"
+}
  2. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Since no annotations are provided, the description carries full burden. It discloses that paid placement never affects ranking, ranking_basis is stated, and every result includes ships_to states, best_price, and evidence. It also describes the strict compliance mode. However, it does not explicitly state that the tool is read-only or have any side effects, but the nature of the tool implies it.

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 description is well-structured with clear bullet points for arguments. It is fairly concise, though slightly verbose. The core purpose is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 9 parameters, no output schema, and no annotations, the description provides substantial context about tool behavior, parameter usage, and result contents. It explains the strict compliance mode and that results carry needed fields. However, it omits explanation for the 'ready_only' parameter.

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?

With 0% schema coverage (no parameter descriptions in schema), the description adds detailed meaning for 8 of 9 parameters, including explanations for category, ship_to, require_age_gate, limit, optimize_for, and the strict compliance trio. However, the 'ready_only' parameter is not described in the description.

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 first sentence clearly states the tool ranks merchants based on honest signals for purchase fulfillment. It distinguishes from siblings like get_merchant_view (single merchant detail) and search_offerings (searching offerings).

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

Usage Guidelines3/5

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

The description implies usage for finding merchants that can fulfill a purchase, but does not explicitly state when to use this tool versus siblings or when not to use it. No alternatives or exclusions provided.

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

All Beacon - verified-merchant index for AI shopping agents 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