Whatever message this page gives is out now! Go check it out!
Return Value Requirements
Last update:
May 18, 2026
Tool outputs must be structured, predictable, and machine-friendly, while still understandable to humans where needed.
Overview
Tool outputs must be structured, predictable, and machine-friendly, while still understandable to humans where needed.
Basic Response Shape
At the MCP protocol level, a successful tool call returns:
content– a list of output blocks (text, JSON, or other supported types)isError– a boolean indicating success or failure
Example (simple text output):
"result": {
"content": [
{
"type": "text",
"text": "Project PRJ-123 is on track with 80% completion."
}
],
"isError": false
}
Example (structured JSON output):
"result": {
"content": [
{
"type": "json",
"json": {
"projectId": "PRJ-123",
"status": "on_track",
"completionPercent": 80
}
}
],
"isError": false
}
Consistency with Output Schema
For tools that declare an output schema (strongly recommended):
- The returned JSON must match the declared structure, including field names and types.
- Clients and agents rely on this to:
- Chain tool outputs into further tools
- Parse results reliably
- Render custom UI components (tables, summaries, charts)
As a user, you can expect:
- The same tool called with similar inputs will produce structurally consistent outputs from run to run.
- Changes to the output format are rare and tied to server version changes.
Error Responses
When a tool encounters a problem it cannot solve with the given inputs, it must set
isError: true and provide diagnostic information. A typical error result:
"result": {
"content": [
{
"type": "text",
"text": "Invalid project ID: PRJ-XYZ. Project not found."
}
],
"isError": true
}
Some servers also include structured error fields (
error_code, error_category, etc.), which agents can use to decide whether to retry, ask for clarification, or stop. Users should expect:
- Clear indications that the tool failed (no pretending success).
- Plain-language error messages that explain what went wrong and how to fix it if possible.
- No partial or corrupt data masquerading as success.
Side Effects and Idempotence
Tools may be:
- Read-only – no side effects (ideal for “get_” and “list_” tools).
- Write / action tools – changing system state (e.g., create_task, update_profile).
For write tools:
- The result should clearly indicate whether the action was performed and, if so, what was created or changed.
- If an operation is idempotent (safe to repeat without additional effect), it should behave that way across repeated calls with the same parameters.
As a user:
- You should be able to trust that a “success” result means the action really happened.
- You should see enough details (IDs, timestamps, statuses) to confirm the outcome.
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Share additional feedback to help us improve.
0/255
|
