docs(mcp): nudge handoff toward reusing existing items

src/mcp_prompts.rs

@@ -214,6 +214,13 @@ fn get_handoff_command(request: &GetPromptRequestParams, agent: Option<&str>) ->
          item_id=<that item's id> (so the reply becomes the next asset version instead of a new \
          item) and reply_to=<id of the specific message you're answering>, reusing its \
          thread_id.\n\
+         If the work already lives on some other existing item (not just your \
+         own inbox reply), pass that item's id as item_id too — omitting it \
+         always creates a new item, even when one covering this work already \
+         exists. And if this is just a plain-text status update with no \
+         versioned artifact to attach, skip `handoff` entirely: call `comment` \
+         (action=create, item_id=<id>) plus `item` (action=update, id=<id>, \
+         assignee_agent=<recipient>) instead — lighter, no new item, no asset.\n\
          - `inbox [me]` → call the `item` tool (action=list, state_group=\"backlog,unstarted,started\" \
          by default to hide completed/cancelled items — omit state_group only if the command \
          explicitly says `all`) — already scoped to this repo's linked project — and filter to \

src/mcp_server.rs

@@ -409,7 +409,7 @@ impl AgentflareMcp {
         self.artifact_impl(req)
     }
     #[tool(
-        description = "Hand a work product to another agent: assigns/creates an item for the recipient (in the repo's linked project) and attaches the content to it as an asset. Re-attaching under the same item_id creates the next asset version, not a duplicate. Sender is this runtime's own identity."
+        description = "Hand a work product to another agent: assigns/creates an item for the recipient (in the repo's linked project) and attaches the content to it as an asset. Pass `item_id` to target an existing item instead of creating a new one — omitting it always mints a new item, so if the work already has a home item, pass its id. Re-attaching under the same item_id creates the next asset version, not a duplicate. For a plain-text status update with no versioned artifact to attach, prefer `comment` (action=create) + `item` (action=update, id=<id>, assignee_agent=...) instead of this tool — lighter, no new item, no asset. Sender is this runtime's own identity."
     )]
     fn handoff(&self, Parameters(req): Parameters<HandoffRequest>) -> Result<String, ErrorData> {
         self.handoff_impl(req)

src/mcp_server/types.rs

@@ -155,7 +155,7 @@ pub(crate) struct HandoffRequest {
     #[serde(default)]
     pub(crate) r#type: Option<String>,
     #[schemars(
-        description = "Existing item ID to assign and attach to, instead of creating a new item"
+        description = "Existing item ID to assign and attach to, instead of creating a new one. If the work already has a home item, always pass its id here — omitting it unconditionally creates a new item, even when one covering this work already exists."
     )]
     #[serde(default)]
     pub(crate) item_id: Option<String>,