<!-- mcp-tool-guidance-callout --> > [!note] > **Before picking up this work:** this issue adds an MCP tool. Please follow the [Adding a new tool](https://docs.gitlab.com/development/duo_agent_platform/mcp/#adding-a-new-tool) guidance first. That includes creating an MCP Tool Proposal, using `verb_object` naming (`get_` / `list_` / `save_` / `delete_`), and the shared resource-identification input base classes. ## Problem Statement / Use Case Agents need to comment on work items (issues, epics, tasks, objectives, key results) and merge requests and reply within existing discussion threads. This is a distinct action class from mutating a work item's fields, so note creation is extracted from `save_work_item` and `save_merge_request` into its own dedicated `save_note` tool. It folds the shipped `create_work_item_note` / `gitlab_create_workitem_note` behavior, and pairs with `get_work_item` (`include: notes`) on the read side. **Rationale for the split:** keeping note creation separate from `save_work_item` mirrors the read/save separation already used elsewhere and keeps each saver focused on one concern (field mutation vs. discussion). It matches the intent of the shipped standalone note tool rather than overloading the field saver. **Backward compatibility:** implement the tool as `save_work_item_note` and register the previous name `create_work_item_note` via `tool_aliases`, so cached MCP clients keep working — the input schema is unchanged. Follow the tool-renaming guidance in `doc/development/duo_agent_platform/mcp/_index.md`. ## Scope and Non-Goals - **In scope:** create a standalone comment on a work item; reply to an existing discussion via `note_id`; post internal (member-only) notes. create a standalone or inline comment on a merge request - **Non-goals:** field mutation (`save_work_item`), reading notes/discussions (`get_work_item` with `include: notes`), linking work items (`link_work_items`). - **Follow-ups:** none. ## Data Shape and Context Engineering Identification follows the standard convention: `url` OR (`group_id`/`project_id` + `work_item_iid`). Passing `note_id` targets the discussion containing that note (reply); omitting it creates a top-level comment. `internal` marks the note visible only to members with at least the Reporter role. Output is a compact reference to the created note. This saver is create/reply only — there is no update path, and `note_id` is a reply target, not an id-presence update selector. - Input schema (example): ```json { "name": "save_note", "description": "Add a comment to a merge request or work item, or reply to an existing discussion thread. Provide a `url` (which determines the target type), or one of merge_request_iid / work_item_iid together with its project_id or group_id.", "annotations": { "readOnlyHint": false, "destructiveHint": false }, "inputSchema": { "type": "object", "properties": { "url": { "type": "string", "description": "GitLab URL of the merge request or work item. The URL determines the target type, so no other identifier is needed." }, "project_id": { "type": "string", "description": "ID or path of the project. Required with merge_request_iid, and with work_item_iid for project-level work items." }, "group_id": { "type": "string", "description": "ID or path of the group. Required with work_item_iid for group-level work items." }, "merge_request_iid": { "type": "integer", "description": "Internal ID of the merge request. Provide with project_id. Mutually "type": "integer", "description": "Internal ID of the merge request. Provide with project_id. Mutually exclusive with work_item_iid." }, "work_item_iid": { "type": "integer", "description": "Internal ID of the work item. Provide with project_id or group_id. Mutually exclusive with merge_request_iid." }, "body": { "type": "string", "description": "Content of the note/comment (max 1,048,576 characters). Lines beginning with \"/\" are rejected to avoid triggering quick actions such as /merge.", "maxLength": 1048576 }, "internal": { "type": "boolean", "description": "Mark note as internal (visible only to project members with Reporter role or higher).", "default": false }, "discussion_id": { "type": "string", "description": "Global ID of the discussion to reply to (format: gid://gitlab/Discussion/<id>). If omitted, creates a new top-level note." } }, "required": ["body"], "additionalProperties": false } } ``` - Output schema (JSON example): ```json { "note": { "id": "gid://gitlab/Note/123", "body": "…", "internal": false, "createdAt": "2026-08-13T…", "updatedAt": "2026-08-13T…", "url": "https://gitlab.com/…#note_123", "author": { "id": "gid://gitlab/User/1", "name": "…", "username": "…" }, "discussion": { "id": "gid://gitlab/Discussion/…" } }, "errors": [] } ``` ### Resources (already implemented similar tools etc.) - Shipped MCP/DAP tool: `create_work_item_note` / `gitlab_create_workitem_note` (extracted here from the work-item field saver; params reused verbatim). Renamed to `save_work_item_note` with `create_work_item_note` kept as a `tool_aliases` entry. - Paired read: `get_work_item` and `get_merge_request` with `include: notes`. - MCP dev guidelines: `doc/development/duo_agent_platform/mcp/_index.md` (resource-identification convention; note creation as its own tool, separate from `save_`). ### Implementation Plan 1. Enforce identification (`url` OR `group_id`/`project_id` + `work_item_iid`) and required `body`. 2. Reuse `note_id`/`discussion_id` reply resolution and `internal` handling verbatim. 3. Name the tool `save_note`; register `create_work_item_note` as a `tool_aliases` entry (schema unchanged) per the renaming guidance.