Source repository: rohitg00/agentmemory
Source pull request number: 904
Source URL: intentionally omitted to avoid GitHub cross-references
Title: fix: add "when to use" guidance to MCP tool descriptions (#884)
Author: NorethSea
State: open
Draft: no
Merged: no
Head: NorethSea/agentmemory:fix/884-mcp-tool-descriptions @ b835fcf
Base: main @ f6f9e3c
Labels: (none)
Changed files: 0
Commits: 0
Created: 2026-06-11T10:22:23Z
Updated: 2026-06-11T10:28:37Z
Closed: (not closed)
Merged at: (not merged)
Original PR body:
Rewrites every MCP tool description to start with "Use to…" or "Use
when…" so LLMs can instantly recognize when to call each tool. Replaces
internal jargon with plain language and labels multi-agent tools.
Problem
53 MCP tools competing for attention, but only 5 were ever called in a
real multi-agent Hermes setup with 184 sessions (91% unused). Tool
descriptions told the agent what each tool did, but not when to
call it — leaving overlapping tools indistinguishable and specialized
tools undiscoverable.
Changes
Every description now follows a consistent pattern:
"Use to/when <trigger> — <details>"
Examples:
memory_save:
before: "Explicitly save an important insight, decision, or
pattern to long-term memory."
after: "Use to persist an important insight, decision, or pattern
to long-term memory — call this when you discover a
pattern, confirm a preference, fix a recurring bug, or
make a decision worth remembering across sessions."
memory_frontier:
before: "Get all unblocked actions ranked by priority and
urgency."
after: "Use to see all unblocked actions ranked by priority —
call when you have multiple pending tasks to decide what
to work on next. For a single recommendation, use
memory_next instead."
Internal jargon replaced:
- "progressive disclosure" → plain explanation of expandIds
- "4-tier memory consolidation pipeline" → "transform observations
into structured long-term memories (episodic → semantic →
procedural)"
- "tracing its citation chain" → "checking its source evidence"
Multi-agent tools (signals, team, lease, mesh, checkpoints,
sentinels) now start with "For multi-agent setups" so single-agent
agents skip them.
Overlapping tools differentiated with cross-references
(frontier↔next, diagnose↔heal, facet_tag↔facet_query).
How to test
npm test -- test/consistency.test.ts
test/tool-count-consistency.test.ts
test/mcp-surface-default.test.ts
test/mcp-standalone.test.ts
All 43 pass. No tool names, schemas, or counts changed.
Platforms tested
Closes #884
Local branch: review/issue-884-pr-904-mcp-tool-descriptions
Fork PR: not created
Fork decision: adapted for this fork according to local review documentation. Local decision evidence: adapted import.
Verification: see local task record docs/todos/2026-06-15-issue-884-pr-904-mcp-tool-descriptions/todo.md for recorded checks and evidence.
Notes: tracker updated from local review documentation on 2026-06-16; issue remains open until separately closed.
Source repository: rohitg00/agentmemory
Source pull request number: 904
Source URL: intentionally omitted to avoid GitHub cross-references
Title: fix: add "when to use" guidance to MCP tool descriptions (#884)
Author: NorethSea
State: open
Draft: no
Merged: no
Head: NorethSea/agentmemory:fix/884-mcp-tool-descriptions @ b835fcf
Base: main @ f6f9e3c
Labels: (none)
Changed files: 0
Commits: 0
Created: 2026-06-11T10:22:23Z
Updated: 2026-06-11T10:28:37Z
Closed: (not closed)
Merged at: (not merged)
Original PR body:
Rewrites every MCP tool description to start with "Use to…" or "Use
when…" so LLMs can instantly recognize when to call each tool. Replaces
internal jargon with plain language and labels multi-agent tools.
Problem
53 MCP tools competing for attention, but only 5 were ever called in a
real multi-agent Hermes setup with 184 sessions (91% unused). Tool
descriptions told the agent what each tool did, but not when to
call it — leaving overlapping tools indistinguishable and specialized
tools undiscoverable.
Changes
Every description now follows a consistent pattern:
"Use to/when <trigger> — <details>"
Examples:
memory_save:
before: "Explicitly save an important insight, decision, or
pattern to long-term memory."
after: "Use to persist an important insight, decision, or pattern
to long-term memory — call this when you discover a
pattern, confirm a preference, fix a recurring bug, or
make a decision worth remembering across sessions."
memory_frontier:
before: "Get all unblocked actions ranked by priority and
urgency."
after: "Use to see all unblocked actions ranked by priority —
call when you have multiple pending tasks to decide what
to work on next. For a single recommendation, use
memory_next instead."
Internal jargon replaced:
into structured long-term memories (episodic → semantic →
procedural)"
Multi-agent tools (signals, team, lease, mesh, checkpoints,
sentinels) now start with "For multi-agent setups" so single-agent
agents skip them.
Overlapping tools differentiated with cross-references
(frontier↔next, diagnose↔heal, facet_tag↔facet_query).
How to test
npm test -- test/consistency.test.ts
test/tool-count-consistency.test.ts
test/mcp-surface-default.test.ts
test/mcp-standalone.test.ts
All 43 pass. No tool names, schemas, or counts changed.
Platforms tested
Closes #884
Local branch: review/issue-884-pr-904-mcp-tool-descriptions
Fork PR: not created
Fork decision: adapted for this fork according to local review documentation. Local decision evidence: adapted import.
Verification: see local task record docs/todos/2026-06-15-issue-884-pr-904-mcp-tool-descriptions/todo.md for recorded checks and evidence.
Notes: tracker updated from local review documentation on 2026-06-16; issue remains open until separately closed.