fix(mcp): restore compliance-nudging text in 4 thin tool descriptions (QUEST-40) (#34)

kunallanjewar · web-flow · commit 3f6697dfd5c3 · 2026-04-22T22:24:56.000-07:00
Four MCP tool descriptions were trimmed during an earlier lean-pass and
lost the behavioral nudges that peer descriptions still carry. Restore
the 'before X / after Y' hints so cold agents pick the right tool by
reading the description alone.

Restored phrasing per QUEST-40 acceptance:

- guild_session_start: "before any other guild tool will work" +
  "you do not need to pass project to them again"
- lore_appraise: "before storing new knowledge or spawning research
  subagents"
- lore_inscribe: "that transcends the current task" (differentiates
  from quest_journal, whose Long already carries the 'dies when quest
  clears' counterpart)
- quest_post: "well-specced quest = no human follow-up needed to
  execute it"

Totals: 156 words across the four descriptions (target &gt;= 149, prior
135). Every tool stays under the 100-token per-tool budget gate; total
static cost still well under the 4700-token ceiling enforced by
TestDescriptionBudget. Regenerated docs/generated/{cli,mcp}.md to match.
make check clean.

Co-authored-by: Kunal Lanjewar &lt;5488221+kunallanjewar@users.noreply.github.com&gt;
diff --git a/docs/generated/cli.md b/docs/generated/cli.md
@@ -345,7 +345,7 @@ guild lore inscribe TITLE... [flags]
 
 **Aliases:** add
 
-Store knowledge that should outlive this quest. Call lore_appraise first; when the search returns entries that informed this one, pass them as informs=[IDs] to create provenance edges at write-time. Cross-project dedup and principle hygiene warnings are built in. Summary distills the durable knowledge; implementation specifics belong in the quest acceptance that called for this inscribe.
+Store knowledge that transcends the current task — patterns, decisions, research that outlive the quest. Call lore_appraise first; pass informs=[IDs] for entries that informed this one to create provenance edges at write-time. Cross-project dedup and principle-hygiene warnings are built in.
 
 **Flags**
 
@@ -951,7 +951,7 @@ create a new quest
 guild quest post SUBJECT... [flags]
 ```
 
-Create a quest another agent can accept without human follow-up. For non-trivial quests, include rich WHY + HOW (rationale, approach, constraints) so a cold agent can execute without re-deriving context from chat. Pass spec=... to atomically attach a kind=decision lore entry with full rationale (QUEST-63).
+Create a quest another agent can accept without human follow-up — well-specced quest = no human follow-up needed to execute it. Include rich WHY + HOW (rationale, approach, constraints) so a cold agent executes without re-deriving context from chat. Pass spec=... to atomically attach a kind=decision lore entry with full rationale (QUEST-63).
 
 **Flags**
 
diff --git a/docs/generated/mcp.md b/docs/generated/mcp.md
@@ -6,16 +6,16 @@ Every tool a registered MCP client sees. 38 tools.
 
 ## Tools
 
-- [`guild_session_start`](#guild_session_start) — Call FIRST.
+- [`guild_session_start`](#guild_session_start) — Call FIRST — before any other guild tool will work.
 - [`guild_set_project`](#guild_set_project) — Switch the active project for the rest of this session.
 - [`guild_status`](#guild_status) — On-demand dashboard mirroring guild_session_start — last brief, oath, echoes, top bounty, parallelism.
-- [`lore_appraise`](#lore_appraise) — Search lore before researching or inscribing.
+- [`lore_appraise`](#lore_appraise) — Search lore before storing new knowledge or spawning research subagents.
 - [`lore_catalog`](#lore_catalog) — Bulk-import .md files under DIR as lore entries.
 - [`lore_commune`](#lore_commune) — Health report for oath bloat and duplicate lore.
 - [`lore_dossier`](#lore_dossier) — Compile ~2000-token project context for subagent spawn prompts.
 - [`lore_echoes`](#lore_echoes) — List stale/decayed entries the next agent should review or reforge.
 - [`lore_inquest`](#lore_inquest) — Audit the oath wall for narrative-bloat principles (>60 words).
-- [`lore_inscribe`](#lore_inscribe) — Store knowledge that should outlive this quest.
+- [`lore_inscribe`](#lore_inscribe) — Store knowledge that transcends the current task — patterns, decisions, research that outlive the quest.
 - [`lore_link`](#lore_link) — Create an informs provenance edge between two entries.
 - [`lore_list`](#lore_list) — Browse entries with optional filters.
 - [`lore_meld`](#lore_meld) — Find duplicate lore entries across projects.
@@ -39,15 +39,15 @@ Every tool a registered MCP client sees. 38 tools.
 - [`quest_journal`](#quest_journal) — Task-scoped scratchpad.
 - [`quest_list`](#quest_list) — All open tasks.
 - [`quest_orders`](#quest_orders) — List quests currently assigned to a given agent owner.
-- [`quest_post`](#quest_post) — Create a quest another agent can accept without human follow-up.
+- [`quest_post`](#quest_post) — Create a quest another agent can accept without human follow-up — well-specced quest = no human follow-up needed to execute it.
 - [`quest_pulse`](#quest_pulse) — Rework rate, churn rate, hot files, untested quests.
 - [`quest_scroll`](#quest_scroll) — Full quest history: status, journal, timeline.
 - [`quest_summon`](#quest_summon) — Reassign a quest to a named teammate agent.
 - [`quest_update`](#quest_update) — Modify a quest's spec after post.
 
 ## `guild_session_start`
 
-Call FIRST. Set the active project, load the briefing, oath, and top task, and default later guild tools to it.
+Call FIRST — before any other guild tool will work. Sets the active project, loads the briefing, oath, and top task, and defaults later guild tools to it (you do not need to pass project to them again).
 
 _no arguments_
 
@@ -123,7 +123,7 @@ _no arguments_
 
 ## `lore_appraise`
 
-Search lore before researching or inscribing. Returns ranked entries with project, kind, age, and summary.
+Search lore before storing new knowledge or spawning research subagents. Returns ranked entries with project, kind, age, and summary — if current results exist, use them instead of re-deriving.
 
 _no arguments_
 
@@ -310,7 +310,7 @@ _no arguments_
 
 ## `lore_inscribe`
 
-Store knowledge that should outlive this quest. Call lore_appraise first; when the search returns entries that informed this one, pass them as informs=[IDs] to create provenance edges at write-time. Cross-project dedup and principle hygiene warnings are built in. Summary distills the durable knowledge; implementation specifics belong in the quest acceptance that called for this inscribe.
+Store knowledge that transcends the current task — patterns, decisions, research that outlive the quest. Call lore_appraise first; pass informs=[IDs] for entries that informed this one to create provenance edges at write-time. Cross-project dedup and principle-hygiene warnings are built in.
 
 _no arguments_
 
@@ -1175,7 +1175,7 @@ _no arguments_
 
 ## `quest_post`
 
-Create a quest another agent can accept without human follow-up. For non-trivial quests, include rich WHY + HOW (rationale, approach, constraints) so a cold agent can execute without re-deriving context from chat. Pass spec=... to atomically attach a kind=decision lore entry with full rationale (QUEST-63).
+Create a quest another agent can accept without human follow-up — well-specced quest = no human follow-up needed to execute it. Include rich WHY + HOW (rationale, approach, constraints) so a cold agent executes without re-deriving context from chat. Pass spec=... to atomically attach a kind=decision lore entry with full rationale (QUEST-63).
 
 _no arguments_
 
diff --git a/internal/lore/appraise_cmd.go b/internal/lore/appraise_cmd.go
@@ -29,7 +29,7 @@ var AppraiseCommand = &command.Command[AppraiseInput, AppraiseCmdOutput]{
 	CLIPath:    []string{"lore", "appraise"},
 	CLIAliases: []string{"check"},
 	Short:      "search lore before researching or inscribing",
-	Long:       "Search lore before researching or inscribing. Returns ranked entries with project, kind, age, and summary.",
+	Long:       "Search lore before storing new knowledge or spawning research subagents. Returns ranked entries with project, kind, age, and summary — if current results exist, use them instead of re-deriving.",
 	Args: []command.ArgSpec{
 		{Name: "query", Kind: command.ArgPositional, Type: command.ArgString, Required: true, Variadic: true, Help: "search query (remaining positional args joined on CLI)"},
 		{Name: "all_projects", Kind: command.ArgFlag, Type: command.ArgBool, Help: "search every project"},
diff --git a/internal/lore/inscribe_cmd.go b/internal/lore/inscribe_cmd.go
@@ -33,7 +33,7 @@ var InscribeCommand = &command.Command[InscribeInput, InscribeCmdOutput]{
 	CLIPath:    []string{"lore", "inscribe"},
 	CLIAliases: []string{"add"},
 	Short:      "inscribe a new knowledge entry into the lore",
-	Long:       "Store knowledge that should outlive this quest. Call lore_appraise first; when the search returns entries that informed this one, pass them as informs=[IDs] to create provenance edges at write-time. Cross-project dedup and principle hygiene warnings are built in. Summary distills the durable knowledge; implementation specifics belong in the quest acceptance that called for this inscribe.",
+	Long:       "Store knowledge that transcends the current task — patterns, decisions, research that outlive the quest. Call lore_appraise first; pass informs=[IDs] for entries that informed this one to create provenance edges at write-time. Cross-project dedup and principle-hygiene warnings are built in.",
 	Args: []command.ArgSpec{
 		{Name: "title", Kind: command.ArgPositional, Type: command.ArgString, Required: true, Variadic: true, Help: "short distinctive title"},
 		{Name: "kind", Short: "k", Kind: command.ArgFlag, Type: command.ArgString, Required: true, Help: "entry kind (required): idea|research|decision|observation|principle"},
diff --git a/internal/mcp/session_tool.go b/internal/mcp/session_tool.go
@@ -50,9 +50,10 @@ type sessionStartInput struct {
 // INSTRUCTIONS, loaded once per session rather than repeated per-tool.
 var sessionStartTool = &sdkmcp.Tool{
 	Name: "guild_session_start",
-	Description: "Call FIRST. Set the active project, load the " +
-		"briefing, oath, and top task, and default later guild " +
-		"tools to it.",
+	Description: "Call FIRST — before any other guild tool will work. " +
+		"Sets the active project, loads the briefing, oath, and top " +
+		"task, and defaults later guild tools to it (you do not need " +
+		"to pass project to them again).",
 }
 
 // registerSessionStart wires guild_session_start onto s. Package-
diff --git a/internal/quest/post_cmd.go b/internal/quest/post_cmd.go
@@ -49,8 +49,8 @@ var PostCommand = &command.Command[PostInput, PostOutput]{
 	Name:    "quest_post",
 	CLIPath: []string{"quest", "post"},
 	Short:   "create a new quest",
-	Long: "Create a quest another agent can accept without human follow-up. " +
-		"For non-trivial quests, include rich WHY + HOW (rationale, approach, constraints) so a cold agent can execute without re-deriving context from chat. " +
+	Long: "Create a quest another agent can accept without human follow-up — well-specced quest = no human follow-up needed to execute it. " +
+		"Include rich WHY + HOW (rationale, approach, constraints) so a cold agent executes without re-deriving context from chat. " +
 		"Pass spec=... to atomically attach a kind=decision lore entry with full rationale (QUEST-63).",
 	Args: []command.ArgSpec{
 		{
