mcp-server

get_marketplace_item

Read-onlyIdempotent

Get ONE marketplace listing item with the product's source values and what Koongo last exported for the channel. Use this to check a price or stock complaint for one product: compare the store's values with the exported ones. Returns {itemId, koongoProductId, parentId, productType, status, statusDescription, channelStatus, channelStatusLabel, listingId, listingUrl, itemLocked, lockedReason, source:{sku, name, priceFinalInclTax, priceFinalExclTax, priceOriginalInclTax, priceOriginalExclTax, qty, stockStatus, sourceUpdatedAt, koongoUpdatedAt, deleted}, lastExport:{state, exportedAt, submittedAt, submissionStatus, values:[{code, label, value}], diff:[{code, label, previous, current}], channelValues}, sensitiveGate}. source is null when the product is no longer in the store data. lastExport.state: sent = the exported change was processed, pending = it waits to be sent, failed = the channel refused the last submission, not_exported = nothing exported yet. values are the exported channel attributes (codes differ per channel); diff is what changed in the last export; submittedAt and channelValues exist only for channels that record them. SENSITIVE-GATE: the first call (acknowledge_sensitive absent/false) withholds every product value and returns {sensitiveGate:{confirmationRequired:true, itemCount, fields, kind}} — present that gate to the USER, get their approval, then re-call with acknowledge_sensitive:true. Find item_id with list_marketplace_items (fulltext = SKU, name, EAN or listing id); marketplace_id is the id from list_marketplaces. For why the item fails use get_marketplace_item_report. project_id is OPTIONAL (project_id_required otherwise — then call list_projects).

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": {
      "marketplace_id": "<marketplace_id>",
      "item_id": "<item_id>"
    },
    "name": "get_marketplace_item"
  }
}

Input Schema

Name	Required	Description
`item_id`	Yes	The listing itemId (from list_marketplace_items).
`project_id`	No
`marketplace_id`	Yes	integrationId of the marketplace (from list_marketplaces).
`acknowledge_sensitive`	No	Set true only AFTER the user approves seeing the product's real values; absent/false returns a sensitiveGate instead.

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 3, 2026

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, but the description adds behavior the agent cannot infer: the sensitive-gate two-call flow with withheld values on the first call, the null-source case when a product left the store, and the meaning of each lastExport.state. That is rich, call-affecting context beyond the 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?

Purpose and alternative routing are front-loaded before the return-shape enumeration and the gate instructions. The long nested return-shape listing is dense but justified because no output schema exists; a few parenthetical asides could be tightened.

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?

With no output schema, the description carries the return contract and does so thoroughly (item fields, source, lastExport states, diff/values, sensitiveGate). Combined with the gate workflow and id sourcing, an agent has everything needed to call it correctly.

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 75%, but the description fills the gap for project_id (optional, project_id_required otherwise) and acknowledges the acknowledge_sensitive workflow, and explains where item_id and marketplace_id come from. It adds real meaning, though it does not restate every field's format.

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 ('Get ONE marketplace listing item') and immediately scopes it to the product's source values plus last export. The singular 'ONE' plus the routing to list_marketplace_items and get_marketplace_item_report clearly separates it from its siblings.

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 a concrete use case ('check a price or stock complaint for one product'), names the sibling to use for failure diagnosis (get_marketplace_item_report), and tells the agent how to obtain each id (list_marketplace_items, list_marketplaces, list_projects for the optional project_id). Exclusions and alternatives are explicit.

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

All mcp-server tools Inspect

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

Need Help?