docs: trim protocol docs for clarity

Author: davenpi

src/conduit/protocol/completions.py

@@ -1,17 +1,6 @@
 """
 Autocomplete support for MCP prompt and resource arguments.
 
-MCP enables servers to offer reusable, parameterized prompts - think "code review"
-templates that take language, focus area, and code as arguments. When users fill
-out these templates, they need smart autocomplete for argument values.
-
-## The Completion Flow
-
-1. **Discovery**: Client discovers available prompts and their argument schemas
-2. **User Input**: User selects a prompt and starts filling argument values
-3. **Completion**: As they type, client requests suggestions for the current argument
-4. **Suggestions**: Server responds with relevant completions based on partial input
-
 For example, a "weather" prompt with a `city` argument might suggest
 "San Francisco", "San Diego", "San Antonio" when the user types "San".
 

src/conduit/protocol/roots.py

@@ -33,15 +33,6 @@
 class Root(ProtocolModel):
     """
     A filesystem resource that the server can access.
-
-    Roots define the boundaries of what a server can work with—think of them as
-    declaring "here are the directories and files you're allowed to touch."
-    This creates a secure sandbox while enabling servers to apply their domain
-    expertise to your local content.
-
-    Instead of manually feeding files into conversations, you can point servers
-    at project directories and let them intelligently traverse, analyze, and
-    work with the file structure as their capabilities require.
     """
 
     uri: str
@@ -69,10 +60,6 @@ class Root(ProtocolModel):
 class ListRootsRequest(Request):
     """
     Server request to discover what filesystem locations it can access.
-
-    Servers send this to understand their operating boundaries—what directories
-    and files the client has made available. This shapes how the server can
-    apply its capabilities to the client's content.
     """
 
     method: Literal["roots/list"] = "roots/list"
@@ -96,11 +83,6 @@ class ListRootsResult(Result):
 class RootsListChangedNotification(Notification):
     """
     Client notification that filesystem access boundaries have changed.
-
-    Sent when roots are added, removed, or modified—perhaps when users
-    open new projects or revoke access to directories. Servers typically
-    respond by requesting the updated root list to understand their new
-    operating scope.
     """
 
     method: Literal["notifications/roots/list_changed"] = (

src/conduit/protocol/tools.py

@@ -1,19 +1,6 @@
 """
 Tool system for extending LLM capabilities beyond text generation.
 
-Tools solve a fundamental limitation: LLMs can describe actions but can't perform them.
-By defining callable functions through MCP, you enable LLMs to interact with your
-systems, APIs, and data sources automatically based on conversation context.
-
-## The Tool Lifecycle
-
-1. **Discovery** - Clients ask servers "what can you do?" via ListToolsRequest
-2. **Selection** - LLMs choose appropriate tools based on descriptions and behavioral
-    hints
-3. **Execution** - Clients invoke tools with CallToolRequest, passing structured
-    arguments
-4. **Integration** - Tool results become conversation context the LLM can build upon
-
 ## Designing Effective Tools
 
 Tools work best when they represent clear, focused capabilities. Instead of a generic
@@ -28,11 +15,6 @@
 Use ToolAnnotations to guide LLM decision-making. For example, mark tools as
 read-only, destructive, or open-world to help LLMs understand when and how to
 use them.
-
-Tool results can include rich content: text responses, images, audio, or embedded
-server resources. The error handling model keeps failures visible to the LLM rather
-than breaking the conversation flow, enabling intelligent recovery and alternative
-approaches.
 """
 
 from typing import Any, Literal