Reading Tool Results

Reading tool results

Every tool call returns a JSON-RPC response containing either a result or an error. Knowing its structure helps you debug a store, judge how well it implements UCP, and read what the agent saw.

Response structure

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

json
{
  "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. Inspect and the agent read structuredContent first and fall back to content. In Inspect, Readable shows the result with JSON held inside strings unfolded, and As received shows the exact bytes.

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.

Note

Response instructions are always visible in the Trace, kept whole, so you can see what guidance a store puts into the conversation and compare it with what the agent did.

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.
json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

Timing

Every call in Inspect shows its duration in milliseconds, under Timing. 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 see where agents spend the most time during a run.

Runs record the same timing on every line of the Trace, and the Timeline tab lays the calls out by stage and tool, so you can spot the slow part of a whole shopping flow.

Website (WebMCP) results

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

Something wrong on this page?