MCP Tool Results: How Do You Know a Call Actually Succeeded?

First, identify which layer answered

The MCP tools specification distinguishes protocol-level errors from errors returned by a tool. An unknown tool or malformed request can produce a JSON-RPC error. An invoked tool can instead return a normal tool-result envelope with isError: true when its own work fails. The specification lists input problems among possible tool execution errors too, so the exact path depends on where validation happens. Do not infer from an invalid argument alone that the tool never ran.

This distinction changes the next safe action. If a request was rejected before invocation, fix the request. If a tool reports a failure, use its error details to decide whether a changed attempt is appropriate. If the connection dropped after a side-effecting call and no result arrived, neither response shape proves whether the action happened. Search for the intended record, preferably using an idempotency key or other stable identifier, before retrying. Otherwise a calendar event or payment can be duplicated.

Sources: Tools - Model Context Protocol (2025-06-18).

Read the result fields for what they actually say

An MCP tool result has content blocks, which may contain text, images or resources. It may also have structuredContent for machine-readable data. A tool can declare an outputSchema for that structured value. In the 2025-06-18 specification, servers that provide structured content must make it conform to the declared schema, while clients should validate it. The current draft continues that distinction. A schema check protects the shape of a value; it does not verify the truth of the value or the state of an external service.

The specification recommends also serializing structured data into a text content block for compatibility with older clients. Because that is a recommendation rather than a guarantee, a client should deliberately handle both fields. For example, a travel tool might return a readable summary in content and a reservation_id in structuredContent. A display can use the summary, while a follow-up lookup uses the identifier. If either field is absent, treat that as an observed property of this particular tool result, not a license to invent the missing value.

Version matters here. The 2025-06-18 page describes structuredContent as a JSON object; the current draft permits any JSON value. A client targeting a specific MCP version should validate against that version and the tool's declared schema. Do not silently apply draft behavior to an older server.

Sources: Tools - Model Context Protocol (2025-06-18), Tools - Model Context Protocol (draft).

A valid payload is not a confirmed outcome

Suppose a calendar tool returns isError: false, a structured reservation_id and a text block saying that a meeting was created. That is evidence of what the tool reported. It is not independent proof that the calendar now contains the meeting: a downstream provider might have timed out, the identifier might refer to a pending job, or the integration could be wrong. Validate the payload, then use a read operation against the calendar to confirm the event's identity, time and attendees before telling the user it is booked.

The reverse case is also possible. A tool may report isError: true after a provider accepted a request but before the integration received its acknowledgment. Blindly retrying because the flag says error can create two events. For side-effecting tools, design the action around a stable request key, make the tool document whether retries are safe, and reconcile against provider state when the result is ambiguous. This is a practical reliability rule, not a guarantee made by the MCP result envelope.

Error output needs careful schema handling. The specification says that structured content, when returned under a declared outputSchema, must conform to that schema. It also says tool execution failures should be reported using isError. It does not explicitly state that every client must skip output-schema validation for isError results. Design and test your own success and failure shapes instead of treating an implementation-specific workaround as a rule from the specification.

Sources: Tools - Model Context Protocol (2025-06-18), Tools - Model Context Protocol (draft).

Illustrative example: booking a calendar slot

A bot asks a calendar tool to book a 2pm slot with request key meeting-4821. The tool returns isError: true and a text explanation that the slot is unavailable. The bot should offer another time, not announce a booking. If the tool supplies a structured reason code and its schema allows that shape, the bot can use the code to choose a recovery path; the readable text remains useful to explain the result. A schema that only describes successful bookings may not describe that error, so the integration needs an explicit, tested error contract.

Now imagine the network times out after the same request was sent. There is no result to inspect. Retrying immediately could create a duplicate if the provider accepted the first call. The bot should query by request key or search for the event and compare its details. Only a matching record supports a claim that the booking succeeded. If the provider offers neither lookup nor idempotency, the honest user-facing state is that confirmation is pending, followed by a manual check.

Sources: Tools - Model Context Protocol (2025-06-18).

A short acceptance check for each tool

This check is small enough to run while integrating a tool, and it catches the mistake that matters most: promoting a successful-looking message into a claim that the real-world task is complete. BotBento's editorial team used AI assistance in drafting this guide and checked the technical claims against the linked primary specifications.

• Capture one successful result and one deliberate tool failure. Record the JSON-RPC envelope, isError, content and structuredContent fields actually returned.
• If outputSchema is declared, validate structuredContent using the negotiated MCP version; separately test the tool's error shape.
• For writes, verify the resulting record through an independent read. Test a dropped response and a duplicate request with the same stable key.
• Keep the user-facing wording aligned with the evidence: reported, pending and confirmed are different states.

Sources: Tools - Model Context Protocol (2025-06-18), Tools - Model Context Protocol (draft).