> **TL;DR:** `get_duo_session` should return the session's real output, use a smarter poll hint, avoid a costly duplicate GraphQL query, use one status format, and stop naming tools that do not exist. ## What - Follow-up to !250316, which adds `get_duo_session`. Fix what we can there first. This issue covers what is left after it merges. - Gap 1: the GraphQL query only reads the latest checkpoint messages. A session often produces a merge request or an issue. The last chat message is not what the caller wants. - Gap 2: `POLL_AFTER_SECONDS = 30` is hardcoded in `get_duo_session_tool.rb`. Starting the CI job for a session can take minutes. A fixed 30 second hint is often wrong. - Gap 3: the tool description, the `workflow_id` param description, and the docs table in `doc/user/model_context_protocol/mcp_server_tools.md` name `trigger_duo_flow`, `ask_duo_agent`, and `approve_duo_agent_action`. None of these tools exist or will exist. - Gap 4, performance: `ee/app/graphql/queries/mcp/duo_workflows/get_duo_session.query.graphql` requests both `lastDuoMessage` and `duoMessages` on `latestCheckpoint`. `duoMessages` resolves through `Ai::DuoWorkflows::Workflow#channel_message_history` at `ee/app/models/ai/duo_workflows/workflow.rb:1251`. This method walks the full checkpoint history, loads every `ui_chat_log` blob for the session, and rebuilds the whole message history. `lastDuoMessage` reads only the newest blob and costs much less. Because the query asks for both, every call pays the full history cost. Callers poll the tool about every 30 seconds, and the chat log only grows, so the cost grows as the session gets longer. - Gap 4b, redundancy: `duoMessages` already contains the message that `lastDuoMessage` returns. So the `last_message` fast path in `latest_agent_message` (in `ee/app/services/mcp/tools/duo_workflows/get_duo_session_tool.rb`) gives the same answer as the `reverse_each.find` scan below it. One of the two is dead weight. - Gap 5, inconsistent status values: `get_duo_session_tool.rb` runs `status_name.tr('_', ' ')`, so `structuredContent['status']` shows as `input required`. `list_duo_sessions_tool.rb` returns the raw `statusName` value, so the same state shows as `input_required`. A caller that lists sessions and then checks one gets two different strings for one state. We need to pick one format for both tools. - Gap 6, minor: `truncate(500)` applies only in `running_response`. The finished, input required, approval, and paused branches return the agent message at full length. This may be intended for the final answer. It is less clear for the approval and paused branches, which can also carry long messages. We need to confirm the intended behaviour. - Gap 7, spec coverage: there are two gaps in `ee/spec/services/mcp/tools/duo_workflows/get_duo_session_tool_spec.rb`. No spec checks the 500 character truncation. No spec covers a `finished` session with no checkpoint at all. Only the `created` case tests the nil checkpoint path. ## Why - A caller needs the session's actual result, such as a link to a new MR, not just the last message. - A poll hint that matches reality stops callers polling too soon or waiting too long. - A polling tool must stay cheap. A read that grows with the length of the session does not scale. - Two names for one state make an agent that chains the two tools unreliable. - Wrong tool names in docs and descriptions will confuse anyone using the real tools, `start_duo_session` and `send_duo_session_input`. ## Scope - Use the `merge_request_links` and `work_item_links` connections on `WorkflowType`, not the `merge_request` and `work_item` fields, which point to the source item the session was started about, not what the session produced. - Make the poll hint depend on status: longer while `created` with no job yet, shorter once `running`. - Replace all wrong tool names with `start_duo_session` and `send_duo_session_input`. - Decide how to keep the per poll read cheap. Either request `lastDuoMessage` only and accept that a trailing empty or tool only turn hides the answer, or keep `duoMessages` and bound how much of the history the tool reads. Then remove whichever of the two fields the decision makes redundant, along with its branch in `latest_agent_message`. - Use one status format in both `get_duo_session_tool.rb` and `list_duo_sessions_tool.rb`. - Confirm whether the approval and paused branches should also truncate the message to 500 characters. - Add spec coverage for the 500 character truncation and for a finished session with no checkpoint. ## Acceptance criteria - [ ] Returns a link to the produced MR or issue, when one exists. - [ ] Spec covers a session with a linked MR. - [ ] Spec covers a session with no linked MR or issue. - [ ] Poll hint differs by status, with a spec per status. - [ ] All tool names in descriptions and docs match real tools only. - [ ] The query no longer requests both `lastDuoMessage` and `duoMessages`, and the cost of one poll does not grow with the length of the session. - [ ] `latest_agent_message` has one code path, not a fast path plus an equivalent fallback. - [ ] `get_duo_session` and `list_duo_sessions` return the same status string for the same state. - [ ] The truncation behaviour for the approval and paused branches matches the confirmed intent. - [ ] Spec covers the 500 character truncation. - [ ] Spec covers a finished session with no checkpoint. ## Links - !250316, #607634 - `ee/app/services/mcp/tools/duo_workflows/get_duo_session_tool.rb` - `ee/app/graphql/queries/mcp/duo_workflows/get_duo_session.query.graphql` - `ee/app/services/mcp/tools/duo_workflows/list_duo_sessions_tool.rb` - `ee/app/graphql/types/ai/duo_workflows/workflow_type.rb` - `doc/user/model_context_protocol/mcp_server_tools.md` Part of gitlab-org&21395