feat(mcp): improve tool descriptions for standalone LLM use

cli/mcpserver/confirm.go

@@ -14,10 +14,14 @@ import (
 // ConfirmTool returns the MCP tool definition for confirm.
 func ConfirmTool() mcp.Tool {
 	return mcp.NewTool("confirm",
-		mcp.WithDescription("Confirm a knowledge unit proved correct, boosting its confidence score."),
+		mcp.WithDescription(
+			"Strengthen a knowledge unit that proved correct during your task. "+
+				"Call after you followed queried guidance and it resolved or avoided the described issue, "+
+				"or after you independently verified the described behavior still exists.",
+		),
 		mcp.WithString("unit_id",
 			mcp.Required(),
-			mcp.Description("ID of the knowledge unit to confirm."),
+			mcp.Description("ID of the knowledge unit to confirm (returned by query)."),
 		),
 	)
 }

cli/mcpserver/flag.go

@@ -21,21 +21,28 @@ func FlagTool() mcp.Tool {
 	}
 
 	return mcp.NewTool("flag",
-		mcp.WithDescription("Flag a knowledge unit as problematic, reducing its confidence score."),
+		mcp.WithDescription(
+			"Report that a knowledge unit is wrong, outdated, or redundant so other agents stop relying on it. "+
+				"Call when queried guidance turned out to be incorrect, describes behavior that no longer exists, "+
+				"or duplicates another unit. Always flag rather than silently ignoring bad knowledge.",
+		),
 		mcp.WithString("unit_id",
 			mcp.Required(),
-			mcp.Description("ID of the knowledge unit to flag."),
+			mcp.Description("ID of the knowledge unit to flag (returned by query)."),
 		),
-		mcp.WithString("reason",
+		mcp.WithString(
+			"reason",
 			mcp.Required(),
-			mcp.Description("Flag reason."),
+			mcp.Description(
+				"Why this unit is problematic: \"stale\" (behavior no longer exists), \"incorrect\" (guidance is wrong), or \"duplicate\" (another unit covers it).",
+			),
 			mcp.Enum(enumValues...),
 		),
 		mcp.WithString("detail",
-			mcp.Description("Optional detail for this flag."),
+			mcp.Description("Explanation of what changed or why the guidance is wrong."),
 		),
 		mcp.WithString("duplicate_of",
-			mcp.Description("Original unit ID when reason is duplicate."),
+			mcp.Description("ID of the original unit when reason is \"duplicate\"."),
 		),
 	)
 }

cli/mcpserver/propose.go

@@ -13,34 +13,58 @@ import (
 
 // ProposeTool returns the MCP tool definition for propose.
 func ProposeTool() mcp.Tool {
-	return mcp.NewTool("propose",
-		mcp.WithDescription("Propose a new knowledge unit."),
-		mcp.WithString("summary",
+	return mcp.NewTool(
+		"propose",
+		mcp.WithDescription(
+			"Share a non-obvious insight so other agents avoid the same pitfall. "+
+				"Call IMMEDIATELY after resolving a non-obvious error, discovering undocumented API behavior, "+
+				"finding a version-specific incompatibility, or working around a known issue. "+
+				"Do not batch to end-of-task. "+
+				"Strip project-specific details; the insight must be generalizable.",
+		),
+		mcp.WithString(
+			"summary",
 			mcp.Required(),
-			mcp.Description("Brief summary of the insight."),
+			mcp.Description(
+				"One-line description of the discovery (e.g. \"webpack 5 removes built-in Node.js polyfills\").",
+			),
 		),
-		mcp.WithString("detail",
+		mcp.WithString(
+			"detail",
 			mcp.Required(),
-			mcp.Description("Detailed explanation of what was discovered."),
+			mcp.Description(
+				"Fuller explanation with enough context to understand the issue. Include when you verified and against what version.",
+			),
 		),
-		mcp.WithString("action",
+		mcp.WithString(
+			"action",
 			mcp.Required(),
-			mcp.Description("Recommended action for agents encountering this situation."),
+			mcp.Description(
+				"Concrete instruction starting with an imperative verb (e.g. \"Use\", \"Set\", \"When X, do Y\"). Prefer principle and verification method over exact pinned values.",
+			),
 		),
-		mcp.WithArray("domains",
+		mcp.WithArray(
+			"domains",
 			mcp.Required(),
-			mcp.Description("Domain tags for this knowledge."),
+			mcp.Description(
+				"Subject-area tags capturing what the insight is about (e.g. \"api\", \"payments\", \"connection-pooling\"). Do not repeat languages or frameworks here.",
+			),
 			mcp.WithStringItems(),
 		),
 		mcp.WithArray("languages",
-			mcp.Description("Programming language context."),
+			mcp.Description("Programming languages the insight applies to (e.g. \"python\", \"go\")."),
 			mcp.WithStringItems(),
 		),
 		mcp.WithArray("frameworks",
-			mcp.Description("Framework context."),
+			mcp.Description("Libraries or frameworks involved (e.g. \"webpack\", \"react\", \"fastapi\")."),
 			mcp.WithStringItems(),
 		),
-		mcp.WithString("pattern", mcp.Description("Pattern name.")),
+		mcp.WithString(
+			"pattern",
+			mcp.Description(
+				"Reusable cross-cutting concern (e.g. \"shell-quoting\", \"build-tooling\"). Omit if it just rephrases the summary.",
+			),
+		),
 		mcp.WithObject(
 			"extensions",
 			mcp.Description(

cli/mcpserver/query.go

@@ -20,26 +20,41 @@ const (
 func QueryTool() mcp.Tool {
 	return mcp.NewTool("query",
 		mcp.WithDescription(
-			"Search for relevant knowledge units by domain tags.",
+			"Search for known gotchas, workarounds, and version-specific quirks before acting. "+
+				"Call when starting a task in unfamiliar territory, encountering an error, or setting up CI/CD or infrastructure. "+
+				"Returns knowledge units with confidence scores and recommended actions. "+
+				"Skip for routine edits to code you are already working in this session.",
 		),
-		mcp.WithArray("domains",
+		mcp.WithArray(
+			"domains",
 			mcp.Required(),
-			mcp.Description("Domain tags to search."),
+			mcp.Description(
+				"Subject-area tags capturing what the query is about (e.g. \"api\", \"payments\", \"connection-pooling\"). Use 2-3 specific tags.",
+			),
 			mcp.WithStringItems(),
 		),
-		mcp.WithArray("languages",
-			mcp.Description("Filter by programming languages."),
+		mcp.WithArray(
+			"languages",
+			mcp.Description(
+				"Programming languages the query applies to (e.g. \"python\", \"go\"). Do not repeat in domains.",
+			),
 			mcp.WithStringItems(),
 		),
-		mcp.WithArray("frameworks",
-			mcp.Description("Filter by frameworks."),
+		mcp.WithArray(
+			"frameworks",
+			mcp.Description(
+				"Libraries or frameworks involved (e.g. \"webpack\", \"react\", \"fastapi\"). Do not repeat in domains.",
+			),
 			mcp.WithStringItems(),
 		),
-		mcp.WithString("pattern",
-			mcp.Description("Filter by pattern."),
+		mcp.WithString(
+			"pattern",
+			mcp.Description(
+				"Cross-cutting concern useful as a search axis independent of specific technology (e.g. \"shell-quoting\", \"ci-pipeline\").",
+			),
 		),
 		mcp.WithNumber("limit",
-			mcp.Description("Maximum results to return (default 5, max 50)."),
+			mcp.Description("Maximum results to return (default 5, max 50). Increase for broad exploratory queries."),
 		),
 	)
 }

cli/mcpserver/status.go

@@ -12,7 +12,9 @@ import (
 func StatusTool() mcp.Tool {
 	return mcp.NewTool("status",
 		mcp.WithDescription(
-			"Show knowledge store statistics: tier counts, domain counts, and confidence distribution aggregated across local and the remote's private/org units (excludes the public commons), plus recent additions.",
+			"Show knowledge store statistics: tier counts (local/private/public), domain coverage, "+
+				"confidence distribution (excludes the public commons), and recent additions. "+
+				"Use on demand to check what the store contains, not as part of the regular query/propose/confirm/flag workflow.",
 		),
 	)
 }

plugins/cq/skills/cq/SKILL.md

@@ -83,7 +83,7 @@ Each piece of information belongs in one field — do not repeat the same term a
 | Scenario | `domains` | other call args |
 |----------|-----------|------------------|
 | Stripe payment integration | `["api", "payments", "stripe"]` | `languages: ["python"]` |
-| Webpack build configuration | `["bundler", "webpack", "configuration"]` | `frameworks: ["react"]` |
+| Webpack build configuration | `["bundler", "configuration"]` | `frameworks: ["webpack", "react"]` |
 | GitHub Actions CI for Rust | `["ci", "github-actions"]` | `languages: ["rust"], pattern: "ci-pipeline"` |
 | PostgreSQL connection pooling | `["database", "postgresql", "connection-pooling"]` | `languages: ["go"]` |
 
@@ -268,16 +268,16 @@ The developer asks you to integrate Stripe payments in a Python project.
 
 The developer asks you to configure a webpack build. You encounter a cryptic error: `Module not found: Can't resolve 'stream'`.
 
-1. Call `query` with `domains: ["bundler", "webpack", "nodejs-polyfills"]` and `frameworks: ["react"]`.
+1. Call `query` with `domains: ["bundler", "nodejs-polyfills"]` and `frameworks: ["webpack", "react"]`.
 2. No relevant results returned. Proceed normally.
 3. Debug the issue: webpack 5 removed Node.js polyfills. Add `resolve.fallback: { stream: require.resolve("stream-browserify") }` to the config.
 4. Call `propose` **now** — before continuing with the rest of the build configuration:
    - **summary:** `"webpack 5 removes built-in Node.js polyfills — imports like 'stream' fail at build time"`
    - **detail:** `"webpack 5 no longer includes polyfills for Node.js core modules. Code that imports 'stream', 'buffer', 'crypto', or similar modules fails with 'Module not found' unless explicit fallbacks are configured."`
    - **action:** `"Add resolve.fallback entries in webpack config mapping each required Node.js module to its browserify equivalent (e.g. stream-browserify, buffer, crypto-browserify)."`
-   - **domains:** `["bundler", "webpack", "nodejs-polyfills"]`
+   - **domains:** `["bundler", "nodejs-polyfills"]`
    - **languages:** `["typescript"]`
-   - **frameworks:** `["react"]`
+   - **frameworks:** `["webpack", "react"]`
    - **pattern:** `"build-tooling"`
 5. Resume the original task: finish wiring up the rest of the build, run the dev server, verify the developer's feature works. The `propose` was a brief interruption mid-task, not the end of the task.
 

sdk/go/prompts/SKILL.md

@@ -83,7 +83,7 @@ Each piece of information belongs in one field — do not repeat the same term a
 | Scenario | `domains` | other call args |
 |----------|-----------|------------------|
 | Stripe payment integration | `["api", "payments", "stripe"]` | `languages: ["python"]` |
-| Webpack build configuration | `["bundler", "webpack", "configuration"]` | `frameworks: ["react"]` |
+| Webpack build configuration | `["bundler", "configuration"]` | `frameworks: ["webpack", "react"]` |
 | GitHub Actions CI for Rust | `["ci", "github-actions"]` | `languages: ["rust"], pattern: "ci-pipeline"` |
 | PostgreSQL connection pooling | `["database", "postgresql", "connection-pooling"]` | `languages: ["go"]` |
 
@@ -268,16 +268,16 @@ The developer asks you to integrate Stripe payments in a Python project.
 
 The developer asks you to configure a webpack build. You encounter a cryptic error: `Module not found: Can't resolve 'stream'`.
 
-1. Call `query` with `domains: ["bundler", "webpack", "nodejs-polyfills"]` and `frameworks: ["react"]`.
+1. Call `query` with `domains: ["bundler", "nodejs-polyfills"]` and `frameworks: ["webpack", "react"]`.
 2. No relevant results returned. Proceed normally.
 3. Debug the issue: webpack 5 removed Node.js polyfills. Add `resolve.fallback: { stream: require.resolve("stream-browserify") }` to the config.
 4. Call `propose` **now** — before continuing with the rest of the build configuration:
    - **summary:** `"webpack 5 removes built-in Node.js polyfills — imports like 'stream' fail at build time"`
    - **detail:** `"webpack 5 no longer includes polyfills for Node.js core modules. Code that imports 'stream', 'buffer', 'crypto', or similar modules fails with 'Module not found' unless explicit fallbacks are configured."`
    - **action:** `"Add resolve.fallback entries in webpack config mapping each required Node.js module to its browserify equivalent (e.g. stream-browserify, buffer, crypto-browserify)."`
-   - **domains:** `["bundler", "webpack", "nodejs-polyfills"]`
+   - **domains:** `["bundler", "nodejs-polyfills"]`
    - **languages:** `["typescript"]`
-   - **frameworks:** `["react"]`
+   - **frameworks:** `["webpack", "react"]`
    - **pattern:** `"build-tooling"`
 5. Resume the original task: finish wiring up the rest of the build, run the dev server, verify the developer's feature works. The `propose` was a brief interruption mid-task, not the end of the task.
 

sdk/python/src/cq/prompts/SKILL.md

@@ -83,7 +83,7 @@ Each piece of information belongs in one field — do not repeat the same term a
 | Scenario | `domains` | other call args |
 |----------|-----------|------------------|
 | Stripe payment integration | `["api", "payments", "stripe"]` | `languages: ["python"]` |
-| Webpack build configuration | `["bundler", "webpack", "configuration"]` | `frameworks: ["react"]` |
+| Webpack build configuration | `["bundler", "configuration"]` | `frameworks: ["webpack", "react"]` |
 | GitHub Actions CI for Rust | `["ci", "github-actions"]` | `languages: ["rust"], pattern: "ci-pipeline"` |
 | PostgreSQL connection pooling | `["database", "postgresql", "connection-pooling"]` | `languages: ["go"]` |
 
@@ -268,16 +268,16 @@ The developer asks you to integrate Stripe payments in a Python project.
 
 The developer asks you to configure a webpack build. You encounter a cryptic error: `Module not found: Can't resolve 'stream'`.
 
-1. Call `query` with `domains: ["bundler", "webpack", "nodejs-polyfills"]` and `frameworks: ["react"]`.
+1. Call `query` with `domains: ["bundler", "nodejs-polyfills"]` and `frameworks: ["webpack", "react"]`.
 2. No relevant results returned. Proceed normally.
 3. Debug the issue: webpack 5 removed Node.js polyfills. Add `resolve.fallback: { stream: require.resolve("stream-browserify") }` to the config.
 4. Call `propose` **now** — before continuing with the rest of the build configuration:
    - **summary:** `"webpack 5 removes built-in Node.js polyfills — imports like 'stream' fail at build time"`
    - **detail:** `"webpack 5 no longer includes polyfills for Node.js core modules. Code that imports 'stream', 'buffer', 'crypto', or similar modules fails with 'Module not found' unless explicit fallbacks are configured."`
    - **action:** `"Add resolve.fallback entries in webpack config mapping each required Node.js module to its browserify equivalent (e.g. stream-browserify, buffer, crypto-browserify)."`
-   - **domains:** `["bundler", "webpack", "nodejs-polyfills"]`
+   - **domains:** `["bundler", "nodejs-polyfills"]`
    - **languages:** `["typescript"]`
-   - **frameworks:** `["react"]`
+   - **frameworks:** `["webpack", "react"]`
    - **pattern:** `"build-tooling"`
 5. Resume the original task: finish wiring up the rest of the build, run the dev server, verify the developer's feature works. The `propose` was a brief interruption mid-task, not the end of the task.