MCP: standardize the two-mechanism error model (protocol errors vs isError tool results)

[hslee16]

Gap

Error reporting is inconsistent across archy's tools: some return a union with a structured error payload (archy_diff -> DiffReport | DiffErrorPayload, archy_graph -> GraphPayload | GraphTooLargePayload, archy_dsm -> ... | DSMErrorPayload), while others raise. There is no single documented convention an agent can rely on to detect and recover from a failure.

Best practice (sourced)

MCP defines two error-reporting mechanisms, and they are for different cases:

• Protocol-level JSON-RPC errors -- unknown tool, invalid arguments, server errors.
• Tool-execution errors inside the tool result with isError:true -- API failures, invalid input data, business-logic errors (so the model sees the error and can react). [modelcontextprotocol.io 2025-06-18 server spec]

Concrete fix

• Let the framework surface unknown-tool / invalid-argument failures as JSON-RPC protocol errors (FastMCP handles this).
• Standardize business/domain failures (bad config, scan-too-large, unbuildable path) on the isError:true tool-result mechanism, and decide whether the current *ErrorPayload-in-union shapes become the structuredContent of an isError result vs staying as a normal union member. Pick ONE pattern and apply it to all tools.
• Document the convention so agents have a single recovery contract.

Effort / impact

Medium; improves agent recoverability and consistency. Coordinate the shape decision with the structured-output ticket. Part of the MCP-modernization sweep.