From 36e35d4fbda92e3c67116ac80c3501eeabcd63b8 Mon Sep 17 00:00:00 2001 From: Riz Ashraf Date: Sun, 27 Sep 2026 21:55:33 +0100 Subject: [PATCH] docs: define strict cognitive boundaries for LLMs between MCP Tools, Resources, and Prompts --- AI_INTEGRATION_STRATEGY.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/AI_INTEGRATION_STRATEGY.md b/AI_INTEGRATION_STRATEGY.md index 704ff02..a379576 100644 --- a/AI_INTEGRATION_STRATEGY.md +++ b/AI_INTEGRATION_STRATEGY.md @@ -48,3 +48,18 @@ The `mcp-memory` server is a distinct background process (typically port 3000). ## Conclusion By treating `mcp-memory` as the durable brain, and enforcing a strict division of labor between the primary agent loop and background subagents, we achieve a highly autonomous, highly resilient AI pair-programming environment that scales across long-running projects and multiple terminal sessions. + +## 4. MCP Feature Differentiation (Cognitive Boundaries) +The MCP protocol exposes three primary primitives. To prevent LLM confusion and API hallucination, the LLM must strictly adhere to the following interaction boundaries: + +### A. Tools (For Stateful Mutation) +* **When to use:** Use tools *exclusively* for mutating state (e.g., dd_task, log_code_change) or for highly targeted semantic searches (e.g., search_nodes, query_graph_path). +* **LLM Awareness:** The LLM must not use tools to repeatedly poll for state changes. Tools represent active, expensive computing steps. + +### B. Resources (For Passive Awareness) +* **When to use:** Use URIs (e.g., memory://tasks/active, memory://pinned_files) to read holistic project state. +* **LLM Awareness:** The client integration should map these URIs to the LLM's context window. Instead of the LLM invoking a list_active_tasks tool (which costs a round-trip), the LLM should simply read the memory://tasks/active resource content if it needs to know what to do next. Resources are for passive, zero-cost reading. + +### C. Prompts (For Macro-Workflows) +* **When to use:** Use server-defined prompts to execute complex, multi-step routines that require bundled context. +* **LLM Awareness:** Instead of the user or main agent trying to manually figure out the correct sequence of tools to end a session, the LLM should trigger the handoff_routine prompt. The server will respond with a strictly formatted message array that perfectly primes the LLM on exactly what to do next. Prompts act as "macro-instructions" to prevent the LLM from wandering off-script during complex transitions.