List the shop's listings (all statuses). Keyset-paginated — pass the returned next_cursor to page.
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": "list_listings"
}
}| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | ||
| status | No |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden; it does disclose the important pagination contract (keyset pagination, feed next_cursor back in), which is genuinely useful. It omits ordering guarantees, default page size, and any permission/auth context for a shop-scoped read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the purpose and followed by the pagination mechanic — no filler. The parenthetical scope note is the only slightly muddy element.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no annotations mean the description is the sole source of behavioral detail, yet it covers neither the returned record shape nor the meaning of the two filtering/paging parameters. For a three-parameter list tool with zero schema coverage, this leaves real gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for three undocumented parameters. It clarifies only that a cursor is a continuation token from a previous response; limit (max 100) and the active/sold/hidden status filter are never explained, and the "all statuses" phrasing may even mislead about the status param.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("List the shop's listings") with a scope note ("all statuses"), which distinguishes it from the single-item get_listing and the analytics tools. The parenthetical is slightly ambiguous though: the schema exposes a status filter, so "all statuses" reads as a default-behavior claim rather than a hard constraint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied — the description suggests this is the broad/unfiltered enumeration path, but it never says when to prefer get_listing, analytics_listings, or a status-filtered call. No prerequisites or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.