Skip to main content
Glama

Offers of one product

get_offers
Read-onlyIdempotent

Every business offering one product, by its barcode: each one's price as last checked, stock, where it is offered, and its own door to order through. Single units unless multipack names a pack (each offer then with its price per unit); product.packs lists every multipack it is offered in. The price that counts is the door's: read it there, show it to your person, and order there.

Input Schema

NameRequiredDescriptionDefault
gtinYesThe product's barcode: GTIN-8, -12, -13 or -14, EAN, UPC or ISBN, in any length.
nearNoOnly offers of businesses within radius_km of this point, each with its distance.
limitNoUp to 20; 10 when left out.
orderNopublished (the default): each offer in its business's place in the directory's published order. price: lowest price as sold first (a pack's whole price), with currency. nearest: nearest first, with near.
cursorNonext_cursor from the previous page, with the same arguments.
countryNoOnly businesses in this country: ISO 3166-1 alpha-2, like PT.
currencyNoOnly offers in this currency (ISO 4217, like EUR). Prices are never converted.
ships_toNoOnly businesses that say they deliver to this country: ISO 3166-1 alpha-2.
conditionNoOnly offers in one of these conditions: any when left out.
has_inboxNoEvery offer here comes from a business's own inbox: false leaves nothing.
multipackNoThe pack: 12 for the barcode's packs of 12 (each offer with its price per unit); single units (1) when left out.
price_maxNoAt most this price as sold (a pack's whole price), in the currency's minor unit. Needs currency.
price_minNoAt least this price as sold (a pack's whole price, not its price per unit), in the currency's minor unit (cents for EUR, yen for JPY). Needs currency.
availabilityNoOnly offers with one of these: in_stock and on_sale (available, its stock not counted) when left out.

Output Schema

NameRequiredDescriptionDefault
noteYes
orderYes
rulesYes
offersYes
productYes
next_cursorYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changed
    • addedInput schema / properties / multipack
      Added value: +{
      +  "description": "The pack: 12 for the barcode's packs of 12 (each offer with its price per unit); single units (1) when left out.",
      +  "maximum": 10000,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • changedInput schema / properties / order / description
      Previous value: -"published (the default): each offer in its business's place in the directory's published order. price: lowest first, with currency. nearest: nearest first, with near."New value: +"published (the default): each offer in its business's place in the directory's published order. price: lowest price as sold first (a pack's whole price), with currency. nearest: nearest first, with near."
    • changedInput schema / properties / price_max / description
      Previous value: -"At most this, in the currency's minor unit. Needs currency."New value: +"At most this price as sold (a pack's whole price), in the currency's minor unit. Needs currency."
    • changedInput schema / properties / price_min / description
      Previous value: -"At least this, in the currency's minor unit (cents for EUR, yen for JPY). Needs currency."New value: +"At least this price as sold (a pack's whole price, not its price per unit), in the currency's minor unit (cents for EUR, yen for JPY). Needs currency."
    • addedOutput schema / properties / offers / items / properties / multipack
      Added value: +{
      +  "maximum": 10000,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / offers / items / properties / unit_price
      Added value: +{
      +  "properties": {
      +    "currency": {
      +      "pattern": "^[A-Z]{3}$",
      +      "type": "string"
      +    },
      +    "value": {
      +      "minimum": 0,
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "value",
      +    "currency"
      +  ],
      +  "type": "object"
      +}
    • changedOutput schema / properties / offers / items / required
      Previous value: -[
      -  "id",
      -  "offered_by",
      -  "name",
      -  "gtin",
      -  "price",
      -  "tax",
      -  "availability",
      -  "condition",
      -  "where",
      -  "checked_at",
      -  "order"
      -]New value: +[
      +  "id",
      +  "offered_by",
      +  "name",
      +  "gtin",
      +  "multipack",
      +  "price",
      +  "tax",
      +  "availability",
      +  "condition",
      +  "where",
      +  "checked_at",
      +  "order"
      +]
    • addedOutput schema / properties / product / properties / multipack
      Added value: +{
      +  "maximum": 10000,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / product / properties / packs
      Added value: +{
      +  "items": {
      +    "properties": {
      +      "businesses": {
      +        "minimum": 1,
      +        "type": "integer"
      +      },
      +      "multipack": {
      +        "maximum": 10000,
      +        "minimum": 1,
      +        "type": "integer"
      +      }
      +    },
      +    "required": [
      +      "multipack",
      +      "businesses"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / product / required
      Previous value: -[
      -  "key",
      -  "gtin",
      -  "kind",
      -  "businesses"
      -]New value: +[
      +  "key",
      +  "gtin",
      +  "kind",
      +  "multipack",
      +  "businesses",
      +  "packs"
      +]
  2. Changed33 schema fields changed
    • removedInput schema / $schema
      Removed value: -"https://json-schema.org/draft/2020-12/schema"
    • removedInput schema / title
      Removed value: -"MCP get_offers: arguments"
    • removedOutput schema / $schema
      Removed value: -"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / description
      Added value: +"Every field is described in this tool's outputSchema at https://network.surfingdog.ai/.well-known/mcp/server-card.json."
    • removedOutput schema / properties / next_cursor / description
      Removed value: -"Pass it as cursor, with the same arguments, for the next page; null on the last."
    • removedOutput schema / properties / note / description
      Removed value: -"Prices are each business's as this network last checked them; the door's price is the one that counts."
    • removedOutput schema / properties / offers / items / properties / availability / description
      Removed value: -"in_stock, out_of_stock, or on_sale (available, its stock not counted; never a discount). Never a count."
    • removedOutput schema / properties / offers / items / properties / brand / description
      Removed value: -"As the business wrote it."
    • removedOutput schema / properties / offers / items / properties / checked_at / description
      Removed value: -"When this network last confirmed the business's catalogue."
    • removedOutput schema / properties / offers / items / properties / gtin / description
      Removed value: -"The barcode, as 14 digits; null for a product with none."
    • removedOutput schema / properties / offers / items / properties / id / description
      Removed value: -"This network's id of the offer."
    • removedOutput schema / properties / offers / items / properties / image_url / description
      Removed value: -"A picture of it, where the business keeps it."
    • removedOutput schema / properties / offers / items / properties / name / description
      Removed value: -"As the business wrote it."
    • removedOutput schema / properties / offers / items / properties / offered_by / description
      Removed value: -"The business that offers it, in this network's words."
    • removedOutput schema / properties / offers / items / properties / offered_by / properties / country / description
      Removed value: -"ISO 3166-1 alpha-2."
    • removedOutput schema / properties / offers / items / properties / offered_by / properties / distance_km / description
      Removed value: -"Searches near a point only."
    • removedOutput schema / properties / offers / items / properties / offered_by / properties / domain / description
      Removed value: -"The business's own domain, where its inbox is."
    • removedOutput schema / properties / offers / items / properties / offered_by / properties / name / description
      Removed value: -"As the business wrote it."
    • removedOutput schema / properties / offers / items / properties / offered_by / properties / standing / description
      Removed value: -"Its standing in the directory, in words, as get_business gives it."
    • removedOutput schema / properties / offers / items / properties / order / description
      Removed value: -"The business's own door: read the price that counts there with read_first, then order with then; over HTTP, the same at rest."
    • removedOutput schema / properties / offers / items / properties / order / properties / openapi / description
      Removed value: -"The door's OpenAPI description."
    • removedOutput schema / properties / offers / items / properties / order / properties / product_id / description
      Removed value: -"The product's id at the business's door."
    • removedOutput schema / properties / offers / items / properties / order / properties / rest / description
      Removed value: -"Over HTTP: GET {rest}/products?ids={product_id} reads the price that counts, and POST {rest}/orders orders."
    • removedOutput schema / properties / offers / items / properties / price / description
      Removed value: -"As this network last checked it, in the currency's minor unit."
    • removedOutput schema / properties / offers / items / properties / price / properties / currency / description
      Removed value: -"ISO 4217."
    • removedOutput schema / properties / offers / items / properties / tax / description
      Removed value: -"Whether the price includes tax, as the business said: unknown when it said nothing."
    • removedOutput schema / properties / offers / items / properties / url / description
      Removed value: -"The product's page, on the business's own site."
    • removedOutput schema / properties / offers / items / properties / where / description
      Removed value: -"Where it is offered: pickup when the business says it takes collection in person, and the countries it says it delivers to."
    • removedOutput schema / properties / offers / items / properties / where / properties / ships_to / description
      Removed value: -"ISO 3166-1 alpha-2 codes, or * for anywhere."
    • removedOutput schema / properties / product / properties / businesses / description
      Removed value: -"How many businesses offer it, each once."
    • removedOutput schema / properties / product / properties / kind / description
      Removed value: -"global, book, or serial (an issue's number: each business's own, matched to no other's)."
    • removedOutput schema / properties / rules / description
      Removed value: -"The rules that make the published order."
    • removedOutput schema / title
      Removed value: -"MCP get_offers: structuredContent"
  3. Added

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description does add genuinely useful context beyond that: prices are 'as last checked' (freshness caveat) and the authoritative price is the door's own, which discourages presenting a stale or derived figure. It says nothing, however, about coverage limits or what an empty result means.

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 is front-loaded, but the prose is decorative ('its own door to order through', 'the price that counts is the door's') and the second multipack clause restates something the schema already says. It is not bloated enough to obscure the point, but several words do not earn their place.

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?

With rich annotations, full schema coverage and an output schema in place, the description only needs to carry the non-structured semantics, and it does: price freshness, the authoritative-source rule, and unit vs pack pricing. A brief note on result shape or paging would make it complete, but little essential information is missing.

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 schema already documents all 14 parameters, including multipack, price_min/price_max and availability defaults. The description's one contribution is clarifying single-unit vs multipack semantics ('single units unless multipack names a pack'), which duplicates the schema's own wording. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies a specific resource (every business offering one product, keyed by barcode) and enumerates what each offer carries: price as last checked, stock, where it is offered, and its ordering channel. It never states a plain verb like 'list' and leans on metaphor ('its own door to order through'), which costs some immediacy, but an agent can tell this is a per-product offer lookup rather than a product search.

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?

Usage is implied: you have a barcode and want prices/stock/where-to-buy, and the final clause directs the agent to read the price at the source and order there. There is no explicit when-not guidance and no mention of search_products as the alternative path when you don't yet have a barcode.

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