Feature: Conversations API response structure is undocumented and deeply nested

[charliebirch]

Summary

The conversations API (GET /agents/conversations/list) returns a non-obvious data structure that is difficult to work with. Key conversation fields are nested under metadata.conversation rather than at the top level.

Current Response Structure

{
  "results": [
    {
      "knowledge_set": "uuid",
      "metadata": {
        "_id": "...",
        "project": "...",
        "knowledge_set": "...",
        "insert_date": "...",
        "conversation": {
          "user_id": "...",
          "agent_id": "...",
          "title": "...",
          "active_execution_time_ms": 294488,
          "has_errored": true,
          "state": "completed",
          "params_from_previous_trigger": { ... }
        }
      }
    }
  ]
}

Issues

1. Deep nesting: Useful fields (title, user_id, state, has_errored) are 3 levels deep at results[].metadata.conversation.*
2. No user name resolution: user_id is a UUID with no way to resolve it to a user name/email via current MCP tools
3. Undocumented: The relevance_list_conversations tool description says "Returns summaries (title, date)" but the tool itself returns 0 results (see separate bug), and the raw API structure doesn't match that description

Suggestions

1. Fix relevance_list_conversations to actually return results (separate issue filed)
2. Flatten the response in the MCP tool to surface key fields: conversation_id, title, user_id, user_name, state, has_errored, created_at, execution_time_ms
3. Add user name resolution — either enrich conversation results with user names, or provide a relevance_get_user tool