Reading Tool Results

Every tool call returns a JSON-RPC response containing either a result or an error. Understanding the response structure helps you debug issues, evaluate store implementations, and interpret what the AI agent sees.

Response Structure

A successful JSON-RPC response contains a result object. The exact shape depends on the tool, but most follow predictable patterns:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": { "products": [...], "pagination": {...} },
    "content": [
      {
        "type": "text",
        "text": "{ \"products\": [...], \"pagination\": {...} }"
      }
    ]
  }
}

Under the UCP MCP binding, a store returns its payload in structuredContent and may also put a text copy in the content array for clients that don't read it. Some stores send only the content text, with a JSON string inside it. The Inspector and the agent read structuredContent first and fall back to content, then show the parsed result in a structured view.

Common Response Fields

Depending on the tool, you will encounter these common fields in the parsed result:

• products — An array of product summaries from search results, each with a title, handle or ID, price, and availability status.
• variants — Product variants with their own IDs, prices, and option values (e.g., "Blue / Large"). Required for adding specific items to a cart.
• pricing — Prices may appear as dollar strings in search results (e.g., "29.99") but as integer cents in checkout responses (e.g., 2999). Be aware of this difference when comparing values.
• availability — Stock status per variant. Some stores include an availabilityMatrix that maps option combinations to available variants using a slash-separated format like "Blue/5".
• pagination — Cursor-based pagination with hasNextPage and endCursor fields. Pass the cursor as the after parameter in subsequent requests.

Response Instructions

Stores can embed response_instructions in their tool responses: guidance aimed at AI agents on how to present results, handle edge cases, or follow store policies. For example, a store might ask the agent to show shipping costs before checkout.

Playground agents treat text written by the merchant or third parties in tool replies (descriptions, reviews, store notices, instructions like these) as information, not instructions. It never changes what the user asked for or what is bought. A tool's own guidance on which tool to call next is followed.

Error Responses

When a tool call fails, the response contains an error object instead of a result. The error includes a numeric code and a human-readable message:

• -32601 (Method not found) — The tool name is not recognized by the store. This typically means the store does not implement that particular tool, or there is a typo in the tool name.
• -32000 (Authentication failed) — The store requires OAuth authentication before accepting tool calls. You need to authorize with the store's OAuth provider first.
• -32603 (Internal error) — The store accepted the tool call but encountered an internal failure while processing it. This is distinct from a transport error — the MCP connection itself is working, but the underlying operation failed.

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

Timing

Every tool call in the Inspector displays its duration in milliseconds. This timing covers the full round trip from sending the JSON-RPC request to receiving the response. Use it to identify slow tools, compare store performance, and understand where agents spend the most time during a session.

Timing data is also captured in agent sessions and appears in the session timeline, making it possible to spot performance bottlenecks across an entire shopping flow.

Store-page (WebMCP) results

Tools a store page registers through WebMCP have no fixed result shape. In the Inspector's WebMCP view, a read-only tool's result is shown raw, as the page returned it, with the time taken and the page it ended on. See WebMCP: the store page.