mcp-server

list_marketplace_items

Read-onlyIdempotent

MARKETPLACE items — list the individual listing items of one marketplace, the per-product rows of what is (or should be) listed on the channel. Use this to find individual marketplace listings and their status. Applies to marketplace integrations. Returns {integrationId, total, returned, items:[{itemId, koongoProductId, parentId, productType, status, channelStatus, listingId, listingUrl, hasErrors, errorCount}], searchStatus}. status is the Koongo-side listing state; channelStatus is the channel's own state; listingId / listingUrl are the item's identity on the channel. Rows carry only identifiers and statuses — never a raw product attribute VALUE — so no confirmation is needed here; to see an item's actual attribute value plus its full error report, use get_marketplace_item_report (which gates the value behind a user confirmation). Filter with koongo_status (e.g. the failed items), channel_status, listing_id or product_id to drive a fix, or find a product with fulltext (SKU, name, EAN, listing id; searchStatus ok|capped|timeout|error); page with limit / offset. itemId is what you pass as item_id to get_marketplace_item_report / get_marketplace_item. marketplace_id is the id from list_marketplaces. project_id is OPTIONAL (inferred for a single-project customer; 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>"
    },
    "name": "list_marketplace_items"
  }
}

Input Schema

Name	Required	Description
`limit`	No	Max items to return (page size).
`offset`	No	Number of items to skip (paging).
`fulltext`	No	Search like the integration detail table: SKU, product name, parent SKU/name, EAN/GTIN or the channel listing id (case-insensitive substring, at least 3 characters) or an exact numeric itemId.
`listing_id`	No	Filter by the item's listing id on the channel.
`product_id`	No	Filter to one Koongo product id.
`project_id`	No
`koongo_status`	No	Filter by the Koongo-side listing status.
`channel_status`	No	Filter by the channel's own listing status.
`marketplace_id`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 3, 2026

addedInput schema / properties / fulltext

Added value: +{
+  "description": "Search like the integration detail table: SKU, product name, parent SKU/name, EAN/GTIN or the channel listing id (case-insensitive substring, at least 3 characters) or an exact numeric itemId.",
+  "minLength": 1,
+  "type": "string"
+}

First observedSep 1, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations: it discloses that rows carry only identifiers and statuses, never a raw attribute value, so no confirmation prompt is triggered here, whereas the report tool gates values behind a user confirmation. It also documents the searchStatus outcome set (ok|capped|timeout|error) and the project-inference behavior, which are not visible in the schema.

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?

Purpose and routing are front-loaded in the first two sentences, which is good. But the remainder is one dense run-on paragraph that partly restates the schema (fulltext fields, limit/offset paging) and buries the important confirmation-gating distinction mid-sentence, costing more reading effort than the tool warrants.

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 9-parameter read-only list tool with no output schema, the description fully supplies what is missing: the returned shape and field meanings, paging, filter vocabulary, prerequisite id sources, and the escalation path to the report tool. Nothing an agent needs to call it correctly is absent.

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 78% schema coverage already, the description still adds meaning: koongo_status is the Koongo-side listing state versus channel_status the channel's own state, koongo_status can be used to isolate failed items, and itemId is the value to pass as item_id downstream. project_id and marketplace_id have no schema descriptions and are explained here (optional/inferred; sourced from list_marketplaces).

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 precise verb and resource ("list the individual listing items of one marketplace, the per-product rows of what is listed on the channel") and explicitly scopes it against siblings, noting that get_marketplace_item_report returns raw attribute values and full error reports. An agent can distinguish it from list_marketplaces, get_marketplace_item, and get_marketplace_item_report without opening any 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 ("use this to find individual marketplace listings and their status") and names the alternative for the adjacent job: use get_marketplace_item_report for actual attribute values plus the full error report. It also supplies prerequisite routing — marketplace_id comes from list_marketplaces, and project_id is optional/inferred but requires list_projects when project_id_required is raised.

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?