Skip to main content
Glama
Sign In

agentcard

by sh.agentcard
OverviewDiscussionsAdmin

buy_list_merchants

Read-onlyIdempotent

List where Agentcard shops. With no arguments: the merchants that use an account (DoorDash, flights, the retail stores) and whether this user has linked each, plus how many online stores Agentcard buys from with no account. To check one store, pass query with its name or domain (Nike, nordstrom.com): the search covers both kinds. An online store needs no link: ask buy for the product and name the store.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "buy_list_merchants"
  }
}

Input Schema

NameRequiredDescriptionDefault
kindNoWhich merchants to list: `direct` (merchants that use an account), `catalog` (online stores with no account) or `all`. Without it, `direct`, or `all` with a `query`.
queryNoA store's name or domain, e.g. 'Nike' or 'nordstrom.com'.
cursorNoThe `next_cursor` an earlier call returned. Pass the same `query` and `kind` with it.

Output Schema

NameRequiredDescriptionDefault
countNoNumber of merchants returned on this page.
countsNoHow many merchants of each kind match the query, across every page.
statusNoOutcome: 'ok', 'empty', or 'error'.
messageYesHuman-readable merchant list (or an error / empty note).
merchantsNoThe merchants on this page: `direct` ones with this user's link status, then `catalog` online stores.
next_cursorNoPass as `cursor`, with the same `query` and `kind`, for the next page; `null` on the last page.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changed
    • addedInput schema / properties / cursor
      Added value: +{
+  "description": "The `next_cursor` an earlier call returned. Pass the same `query` and `kind` with it.",
+  "type": "string"
+}
    • addedInput schema / properties / kind
      Added value: +{
+  "description": "Which merchants to list: `direct` (merchants that use an account), `catalog` (online stores with no account) or `all`. Without it, `direct`, or `all` with a `query`.",
+  "enum": [
+    "direct",
+    "catalog",
+    "all"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / query
      Added value: +{
+  "description": "A store's name or domain, e.g. 'Nike' or 'nordstrom.com'.",
+  "type": "string"
+}
    • changedOutput schema / properties / count / description
      Previous value: -"Number of merchants returned."New value: +"Number of merchants returned on this page."
    • addedOutput schema / properties / counts
      Added value: +{
+  "description": "How many merchants of each kind match the query, across every page.",
+  "properties": {
+    "catalog": {
+      "type": "number"
+    },
+    "direct": {
+      "type": "number"
+    }
+  },
+  "type": "object"
+}
    • changedOutput schema / properties / merchants / description
      Previous value: -"Available commerce merchants and this user's link status for each."New value: +"The merchants on this page: `direct` ones with this user's link status, then `catalog` online stores."
    • addedOutput schema / properties / merchants / items / properties / domain
      Added value: +{
+  "description": "Catalog stores only: the store's website, e.g. nike.com.",
+  "type": "string"
+}
    • addedOutput schema / properties / merchants / items / properties / kind
      Added value: +{
+  "description": "`direct`: a merchant that uses an account. `catalog`: an online store Agentcard buys from with no account.",
+  "type": "string"
+}
    • changedOutput schema / properties / merchants / items / properties / link_status / description
      Previous value: -"'ready' (no account needed) or 'linked' (account linked): shop now. 'unlinked': no account linked yet. 'pending': a link was started and not finished. 'error': the last link attempt failed."New value: +"Direct merchants only. 'ready' (no account needed) or 'linked' (account linked): shop now. 'unlinked': no account linked yet. 'pending': a link was started and not finished. 'error': the last link attempt failed."
    • changedOutput schema / properties / merchants / items / properties / slug / description
      Previous value: -"Merchant slug identifier."New value: +"Merchant id. A catalog store has no account to link, so buy_connect refuses it."
    • addedOutput schema / properties / next_cursor
      Added value: +{
+  "description": "Pass as `cursor`, with the same `query` and `kind`, for the next page; `null` on the last page.",
+  "type": [
+    "string",
+    "null"
+  ]
+}
  2. Changed2 schema fields changed
    • changedOutput schema / properties / merchants / items / properties / link_status / description
      Previous value: -"Whether the user has linked this merchant (e.g. 'linked', 'not_linked')."New value: +"'ready' (no account needed) or 'linked' (account linked): shop now. 'unlinked': no account linked yet. 'pending': a link was started and not finished. 'error': the last link attempt failed."
    • removedOutput schema / properties / merchants / items / properties / money_path
      Removed value: -{
-  "description": "Funding/money path for the merchant, when applicable.",
-  "type": "string"
-}
  3. First observed

TDQS

A3.9/5.0
Behavior4/5

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

The read-only and idempotent annotations already establish the safety profile, and the description adds useful context about linked status, online stores needing no link, and that search covers both merchant kinds. It does not describe pagination behavior beyond what the schema provides, but it adds meaningful operational context.

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 front-loaded with the core purpose and then explains the query mode and purchase alternative. It is slightly conversational and example-heavy, but every sentence contributes to understanding the tool's use.

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?

For a read-only listing tool with full schema coverage and an output schema, the description is mostly complete: it explains both listing modes and the no-link nature of online stores. The main gap is that pagination via `cursor` is left entirely to the schema.

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 input schema already documents `kind`, `query`, and `cursor` thoroughly. The description reinforces the no-arguments default and that `query` searches both merchant kinds, but it does not add much beyond the schema and omits any explanation of how `cursor` continues a result set.

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 states a specific verb and resource: it lists merchants Agentcard can buy from, distinguishes account-based merchants from online stores, and explains the one-store query mode. It does not explicitly contrast itself with adjacent tools like buy_connect or allow_card_merchant, but the listing purpose is clear.

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

Usage Guidelines4/5

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

It gives clear usage modes: no arguments lists account merchants plus catalog count, while `query` checks a single store by name or domain across both kinds. It also routes product purchases to `buy` instead of this tool. It does not explicitly cover when to paginate with `cursor`, but the main selection guidance is present.

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

All agentcard 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