fix: add "when to use" guidance to MCP tool descriptions (#884)

[NorethSea]

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

• macOS 26.5.1, Node v22

Closes #884

[vercel]

@NorethSea is attempting to deploy a commit to the rohitg00's projects Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR updates MCP tool descriptions across eight tool registry versions to add explicit "when to use" guidance. Descriptions are reworded from vague feature descriptions into prescriptive usage instructions with operational details. No tool names, schemas, types, or control flow logic are altered.

Changes

MCP Tool Description Updates

Layer / File(s)	Summary
Core memory tools usage guidance src/mcp/tools-registry.ts (lines 42–239)	CORE_TOOLS descriptions for compress, save, history, patterns, sessions, smart search, vision, timeline, profile, export, relations, commit lookup, and commits are reworded into "Use to..." format with explicit usage triggers.
Action lifecycle and multi-agent coordination tools src/mcp/tools-registry.ts (lines 252–363, 374–578, 596–732)	V040_TOOLS, V050_TOOLS, and V051_TOOLS descriptions updated for action lifecycle, frontier/next selection, leases, routine runs, signals, checkpoints, sentinels, triggers, sketch lifecycle, crystallization, diagnostics, healing, and facet operations—reworded to clarify purpose and operational constraints.
Verification, lessons, and synthesis tools src/mcp/tools-registry.ts (lines 757, 772–818, 836–854)	V061_TOOLS, V070_TOOLS, and V073_TOOLS descriptions for memory_verify, lesson save/recall, Obsidian export, memory_reflect, and memory_insight_list are clarified to explain verification goals, confidence ordering, and synthesis semantics.
Memory slots API descriptions src/mcp/tools-registry.ts (lines 873–934)	V010_SLOTS_TOOLS descriptions updated for listing, getting, creating, appending, replacing, and deleting memory slots with added detail about slot behavior and rejection constraints.

Estimated Code Review Effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 Hop, hop, descriptions bloom anew,
"Use to..." guides the agent through,
Fifty-three tools now show their way,
With "when to use" they'll come to play! 🌟

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix: add "when to use" guidance to MCP tool descriptions (#884)' clearly summarizes the main change: enriching tool descriptions with usage guidance to help LLMs determine when to call each tool.
Linked Issues check	✅ Passed	The PR directly addresses issue #884 by rewriting descriptions with 'Use to/when' guidance, replacing jargon with plain language, marking multi-agent tools, and adding cross-references—all core objectives listed in the issue.
Out of Scope Changes check	✅ Passed	The changeset only modifies tool descriptions across multiple registry versions without altering tool names, schemas, types, exported registries, or control flow logic—all changes remain focused on issue #884 objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}