feat(mcp): structured error responses

[marcossevilla]

Description

Since agents work better if structured explicit errors are passed to it with possible solutions and thorough failure reasoning, we should return this type of error from the MCP so the agent loop doesn't take longer or fails unexpectedly due to missing error context.

Take this error response as example:

{
  "status": "partial_failure",
  "failureType": "transient",
  "attemptedAction": {
    "tool": "search_academic_db",
    "query": "renewable energy policy",
    "dateRange": "2022-2024"
  },
  "partialResults": [
    {
      "title": "EU Renewable Energy Directive 2023",
      "source": "EUR-Lex",
      "retrieved": true
    }
  ],
  "alternativeApproaches": [
    "Retry with narrower date range (2023-2024)",
    "Search alternative database: government_publications",
    "Use cached results from previous research session"
  ]
}

for failure types, consider these categories:

• transient (timeout, rate limit — may succeed on retry)
• validation (bad input — fix the query)
• business (rule violation — escalate or find alternative)
• permission (access denied — cannot be retried without authorization changes)

remember to also include:

• What was attempted. The specific query, parameters used, and target system.
• Partial results gathered before failure. If the subagent retrieved three of five sources before timing out, those three results are valuable.
• Potential alternative approaches. These suggestions help the coordinator decide on recovery strategy.

Requirements

• All CI/CD checks are passing.
• There is no drop in the test coverage percentage.

Additional Context

No response