Implement Structured Error Responses for MCP Tools

// STRUCTURED ERROR (isError: true) - triggers recovery logic
{
  "type": "tool_result",
  "isError": true,
  "content": [{"type": "text", "text": "{errorCategory: transient, isRetryable: true, retryAfterSeconds: 30}"}]
}

// VALID EMPTY RESULT (isError: false) - tool succeeded, nothing found
{
  "type": "tool_result",
  "isError": false,
  "content": [{"type": "text", "text": "{found: false, message: No orders found for CUST-00123}"}]
}

async def lookup_order(order_id: str) -> dict:
    try:
        result = await order_db.get(order_id)
        return result
    except Exception as e:
        # All exceptions: same generic message - Claude cannot route recovery
        return {"isError": True, "error": "Operation failed"}

async def lookup_order(order_id: str) -> dict:
    # 1. Validate input format FIRST (prevent hitting DB with bad input)
    if not order_id.startswith("ORD-"):
        return {
            "isError": True,
            "errorCategory": "validation",
            "isRetryable": False,
            "description": f"Invalid order_id format. Expected ORD-XXXXX, got: {order_id}",
            "customerFriendlyMessage": "I wasn't able to look up that order. Could you double-check the order number?"
        }
    try:
        result = await order_db.get(order_id)
        # 2. Valid empty result (NOT an error)
        if result is None:
            return {"found": False, "message": f"No order found with ID {order_id}."}
        return {"found": True, "order": result}

    except TimeoutError:
        # 3. Transient: temporary, retry after delay
        return {
            "isError": True, "errorCategory": "transient",
            "isRetryable": True, "retryAfterSeconds": 30,
            "description": "Order DB timed out. Service under load.",
            "customerFriendlyMessage": "I'm having trouble reaching the order system. Let me try again shortly."
        }
    except PermissionDeniedError:
        # 4. Permission: escalate immediately, no retry
        return {
            "isError": True, "errorCategory": "permission",
            "isRetryable": False,
            "description": "Agent lacks authorization to access order records.",
            "customerFriendlyMessage": "I need to transfer you to a specialist who can access your order details."
        }
    except RefundPolicyViolation as e:
        # 5. Business rule: explain policy, no retry
        return {
            "isError": True, "errorCategory": "business",
            "isRetryable": False,
            "description": f"Refund rejected: {e.reason}",
            "customerFriendlyMessage": f"This order isn't eligible for a refund because {e.customer_reason}."
        }

def build_propagation_payload(error, partial_results, attempted):
    """Structured payload for coordinator - all context without subagent history."""
    import json
    return json.dumps({
        "status": "partial_failure",
        "errorCategory": error["errorCategory"],
        "isRetryable": error["isRetryable"],
        "description": error["description"],
        "partialResults": partial_results, # What was obtained before failure
        "attemptedActions": attempted,   # Prevents coordinator duplication
        "recommendation": "Continue with partial results; flag gap in report."
    })