mcp server returning errors in a format the agent actually understands
Built an mcp server for a postgres db and spent way too long figuring out error formats. Tried three approaches: 1. JSON with error codes - agent ignored them completely 2. Plain text errors - agent hallucinated that the query succeeded anyway 3. Structured response with success:false and human-readable message - this actually worked Example: `{"success": false, "error": "Query returned 0 rows. Try broadening your WHERE clause.", "suggestion": "SELECT * FROM users WHERE created_at > '2024-01-01'"}` Agent started refining queries correctly after we added the suggestion field. Anyone else finding that agents need way more hand-holding on error cases than you'd expect?
1. return errors as {"error": true, "message": "...", "code": "SPECIFIC_ERROR_CODE"} 2. claude actually parses structured errors way better than plain strings in our testing
1. +1 on structured errors, we switched to this pattern in october and tool call success rate jumped from 67% to 89% 2. did you test whether claude actually uses the error code to change behavior or just logs it
does the agent actually retry with different args when it gets a structured error or does it just give up