From 51f7bd93eccc46e4fbb8e1be69633312690c2652 Mon Sep 17 00:00:00 2001 From: Shivakumar Date: Sun, 19 Jul 2026 20:41:35 +0530 Subject: [PATCH 1/2] docs(mcp): nudge handoff toward reusing existing items over creating new ones --- src/mcp_prompts.rs | 7 +++++++ src/mcp_server.rs | 2 +- src/mcp_server/types.rs | 2 +- 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/src/mcp_prompts.rs b/src/mcp_prompts.rs index 5e1ac9be..89c9e655 100644 --- a/src/mcp_prompts.rs +++ b/src/mcp_prompts.rs @@ -214,6 +214,13 @@ fn get_handoff_command(request: &GetPromptRequestParams, agent: Option<&str>) -> item_id= (so the reply becomes the next asset version instead of a new \ item) and reply_to=, 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=) plus `item` (action=update, \ + assignee_agent=) 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 \ diff --git a/src/mcp_server.rs b/src/mcp_server.rs index fc916c74..9887449b 100644 --- a/src/mcp_server.rs +++ b/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, 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) -> Result { self.handoff_impl(req) diff --git a/src/mcp_server/types.rs b/src/mcp_server/types.rs index 38ca0a19..9f6f9bc7 100644 --- a/src/mcp_server/types.rs +++ b/src/mcp_server/types.rs @@ -155,7 +155,7 @@ pub(crate) struct HandoffRequest { #[serde(default)] pub(crate) r#type: Option, #[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, From 1a91b306da8dba51065aea36e9ac58fe04af690a Mon Sep 17 00:00:00 2001 From: Shivakumar Date: Sun, 19 Jul 2026 20:53:52 +0530 Subject: [PATCH 2/2] fix(mcp): include required item id in handoff's status-update guidance --- src/mcp_prompts.rs | 2 +- src/mcp_server.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/mcp_prompts.rs b/src/mcp_prompts.rs index 89c9e655..340449d9 100644 --- a/src/mcp_prompts.rs +++ b/src/mcp_prompts.rs @@ -219,7 +219,7 @@ fn get_handoff_command(request: &GetPromptRequestParams, agent: Option<&str>) -> 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=) plus `item` (action=update, \ + (action=create, item_id=) plus `item` (action=update, id=, \ assignee_agent=) 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 \ diff --git a/src/mcp_server.rs b/src/mcp_server.rs index 9887449b..1cf7c631 100644 --- a/src/mcp_server.rs +++ b/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. 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, assignee_agent=...) instead of this tool — lighter, no new item, no asset. 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=, 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) -> Result { self.handoff_impl(req)