[docs] MCP Tool Audit & Optimization Guide

[justfinethanku]

Summary

• Adds docs/05-tool-audit.md — a comprehensive guide for auditing, merging, and scoping MCP tools to reduce context weight and improve AI routing accuracy
• Links the guide from all 6 extension READMEs with contextually appropriate callouts that escalate in urgency as tool count accumulates through the learning path

Why this exists

A community member built a single MCP server with 45+ tools covering all his tables. While it works on strong models, it burns significant context tokens and degrades routing accuracy — especially on weaker models. From Issue #36:

"This is the difference between new OpenClaw users who are wow'd and three weeks in and everything falls over in context weight."

The OB1 extensions themselves expose 40 tools across 6 servers when fully deployed. Users who connect everything simultaneously hit this wall. There's no guidance in the repo on how to be intentional about tool design.

What the guide covers

1. Auditing tools — Quick and deep audit approaches, what to look for (CRUD bloat, search overlap, unused tools), estimated context token costs
2. Three merge patterns — Unified CRUD tool, read/write split, generic entity manager — each with before/after examples, token savings, and tradeoffs
3. Scoping by use case — Capture/query/admin server split pattern with decision criteria
4. Four prompt kits — Ready-to-paste prompts users can drop into any MCP-connected AI:
   • "Audit My MCP Tools" — full inventory with redundancy flags
   • "Suggest Tool Merges" — concrete before/after consolidation recommendations
   • "Design My MCP Scoping" — interactive workflow-based server splitting
   • "Estimate My Context Cost" — quick token cost calculator

Extension cross-links

Each extension README now references the guide at the appropriate point in the learning path:

Extension	Tool count (cumulative)	Link placement
1. Household Knowledge	5	Next Steps — light "heads up"
2. Home Maintenance	9	Next Steps — tip about managing servers
3. Family Calendar	15	Next Steps — "now is a good time to read this"
4. Meal Planning	25	Next Steps — ties to shared server concept taught here
5. Professional CRM	32	Next Steps — "32 tools and counting" with specific symptoms
6. Job Hunt Pipeline	40	What's Next — promoted to #1 recommendation

Related issues

• Addresses MCP Scoping & Cross-Entity Orchestration #36 (MCP Scoping & Cross-Entity Orchestration) — context weight and routing accuracy
• References [architecture] Standardize thought ingestion patterns across recipes and integrations #61 (Standardize ingestion patterns) — related standardization work

Test plan

• Verify all 6 extension README links resolve correctly (relative paths)
• Verify internal anchor links within the guide work (#4-prompt-kits)
• Verify GitHub issue links (MCP Scoping & Cross-Entity Orchestration #36, [architecture] Standardize thought ingestion patterns across recipes and integrations #61) resolve correctly
• Review prompt kits for clarity with a fresh AI conversation
• Confirm guide matches existing docs/ style (no badges, direct language, copy-paste blocks)

🤖 Generated with Claude Code

[github-actions]

OB1 Automated Review

This PR modifies docs or repo governance files. Contribution checks skipped.

✅ No issues found.

[justfinethanku]

Review: MCP Tool Audit & Optimization Guide

What's Good

Addresses a real, documented pain point. Issue #36 is well-cited throughout, and the guide directly tackles the context weight and routing accuracy problems that users hit as they add extensions. The escalating urgency across the extension READMEs (from light heads-up in Extension 1 to prominent recommendation in Extension 6) is contextually appropriate.

Comprehensive and actionable. The guide covers:

• Clear explanation of why tool count matters (token math, routing degradation)
• Concrete audit methods (quick + deep)
• Three merge patterns with before/after examples and tradeoffs
• Scoping strategy (capture/query/admin server split)
• Four copy-paste prompt kits that users can drop into any AI

Prompt kits are strong. Each has clear role/instructions structure, produces actionable output, and asks for user input where needed. The "Audit My MCP Tools" kit is particularly thorough — it'll catch CRUD bloat, search overlap, and orphan tools.

Proper integration with the learning path. The cross-links from all 6 extensions are well-placed and escalate appropriately. By Extension 6 (Job Hunt), the tool audit link is promoted to #1 in "What's Next" — exactly right given the cumulative tool count.

Automated enforcement. Rule 15 in the workflow ensures future extensions/integrations can't be merged without linking to this guide. Good guardrail.

---

Issues Found

1. Missing metadata.json

This is a docs contribution, not an extension/recipe/integration, so it doesn't technically fall under the "every contribution needs metadata.json" rule. However, the automated review workflow doesn't have a special case for docs/ contributions — it only checks extensions/, recipes/, schemas/, dashboards/, integrations/, and primitives/.

Recommendation: Explicitly document in CONTRIBUTING.md that docs/ contributions are exempt from the metadata.json requirement. The workflow already scopes to specific categories, so this is fine — just needs to be stated clearly.

2. Workflow rule implementation has a gap

Rule 15 checks for the presence of 05-tool-audit in any extension/integration README, but it doesn't verify:

• That the link is in an appropriate section (Next Steps, What's Next, or Troubleshooting)
• That the link actually resolves (though Rule 13 "Internal links" should catch broken links)

Impact: Low. The rule will catch missing links, and broken links are caught by Rule 13. The placement check would be a nice-to-have but isn't critical.

Recommendation: Accept as-is. If link placement becomes an issue in future PRs, add a comment in the workflow suggesting where the link should appear.

3. Minor style inconsistency in prompt kits

The four prompt kits use triple backticks for fencing the prompts, but the companion prompts in docs/02-companion-prompts.md use quadruple backticks. This makes it harder for users to copy-paste if they're used to the pattern from the main companion prompts doc.

Recommendation: Change triple backticks to quadruple backticks in the four prompt kits to match the existing 02-companion-prompts.md style. This is a minor consistency fix.

4. Deferred loading context could be clearer

The guide mentions Claude's MCP Tool Search feature and its ~85% context reduction, then says "This helps with the context weight problem. But it doesn't help with routing accuracy."

This is true for the current implementation, but it's worth clarifying that deferred loading still requires the AI to discover and choose between all available tools — it just doesn't load the full parameter schemas until a tool is selected. The routing step still sees all tool names and short descriptions.

Recommendation: Add a sentence clarifying that deferred loading defers schema loading but not tool discovery/routing. Something like: "The AI still sees all tool names and descriptions during routing — only the detailed parameter schemas are deferred until a tool is selected."

---

Specific Corrections

docs/05-tool-audit.md, line 93:

"What deferred loading solves (and doesn't)"

The phrase "10% of context" is mentioned as the threshold for deferring tools. Verify this is the current Claude Desktop behavior — I don't have direct access to the MCP spec changelog to confirm this number.

CONTRIBUTING.md, line 255:
The rule count section header was changed from "The 11 Automated Review Rules" to "The Automated Review Rules" — good change, but the intro sentence still says "Every PR is checked against these rules. All must pass before human review." Consider adding a sentence: "Currently 15 rules. This number grows as the project matures."

extensions/job-hunt/README.md, line 594:
The "What's Next?" section now has 5 items instead of 4. The numbering is correct, but the tool audit link is #1 instead of appended at the end. This is intentional and correct — just noting it's a reordering, not just an addition.

---

Verification Checklist

• PR title follows [category] description format
• All 6 extension READMEs updated with contextually appropriate links
• Both templates updated (extensions/_template and integrations/_template)
• New guide links to relevant issues (#36, #61)
• Internal links use relative paths and should resolve correctly
• No credentials, API keys, or secrets
• No SQL (not applicable — this is a docs contribution)
• No binary blobs
• Workflow rule 15 implemented and should pass on future PRs
• CONTRIBUTING.md updated to document the new rule

---

Test Plan Follow-Up

The PR body includes a test plan with 5 checkboxes. I recommend the PR author verify:

1. All 6 extension README links resolve correctly — test by clicking each one in the GitHub preview
2. Internal anchor links within the guide work (e.g., #4-prompt-kits resolves to the Prompt Kits section)
3. Issue links (#36, #61) resolve correctly
4. Run one of the prompt kits in a fresh AI conversation to confirm clarity

---

Verdict: Minor fixes needed

Required changes:

1. Change triple backticks to quadruple backticks in the four prompt kits (lines 317, 371, 425, 473) to match existing companion prompts style

Recommended (but not blocking):

1. Clarify the deferred loading behavior (see Issue 4 above)
2. Add a note in CONTRIBUTING.md that docs/ contributions are exempt from metadata.json
3. Add "Currently 15 rules. This number grows as the project matures." to the Automated Review Rules intro

Why minor and not ready to merge: The backtick inconsistency is a user-facing copy-paste issue that should be fixed pre-merge. The other items are documentation clarifications that can be addressed now or in a follow-up.

---

Summary

This is a high-quality contribution that directly addresses a community-reported issue with a comprehensive, actionable guide. The prompt kits are well-structured and immediately useful. The automated enforcement via Rule 15 ensures this guidance propagates to future contributions. Fix the backtick style consistency issue and this is ready to merge.

[justfinethanku]

Fixed the backtick nesting and merged — nice guide!