@hybridlabor-api/aos 4.2.0 → 4.4.0

package/mcps/windows-computer-use-mcp/docs/_stale/development/archive/mcp-tool-documentation-standards.md

@@ -1,1153 +0,0 @@
-> **Archived fleet import** — From **notepadpp-mcp** / generic fleet dev notes. **Not** pywinauto-mcp source of truth. See [DEVELOPMENT.md](../../DEVELOPMENT.md) and [TESTING.md](../../TESTING.md).
-# MCP Tool Documentation Standards
-## Making AI Assistants Succeed on the First Try
-
-**Version**: 1.0  
-**Last Updated**: 2025-10-10  
-**Status**: Community Best Practices  
-**Target Audience**: MCP Server Developers
-
----
-
-## Executive Summary
-
-**The Problem**: AI assistants like Claude frequently fail when using MCP tools because docstrings lack critical information. This leads to:
-- Multiple failed attempts before success ("flailing")
-- User frustration and lost trust
-- Wasted API tokens and latency
-- Poor user experience
-
-**The Solution**: Comprehensive tool documentation that provides:
-- Clear prerequisites and constraints
-- Concrete examples with realistic values
-- Error conditions with actionable solutions
-- Complete parameter and return format specifications
-
-**The Impact**: Well-documented tools achieve >90% first-call success rate vs <50% for poorly documented tools.
-
-**Quick Win**: Adding 3 realistic examples to each tool can double the success rate.
-
----
-
-## Table of Contents
-
-1. [Why This Matters](#why-this-matters)
-2. [The Golden Rule](#the-golden-rule)
-3. [Required Documentation Elements](#required-documentation-elements)
-4. [Complete Documentation Template](#complete-documentation-template)
-5. [Real-World Example: Before and After](#real-world-example-before-and-after)
-6. [Anti-Patterns to Avoid](#anti-patterns-to-avoid)
-7. [Implementation Checklist](#implementation-checklist)
-8. [Measuring Success](#measuring-success)
-9. [Quick Reference Guide](#quick-reference-guide)
-10. [Community Resources](#community-resources)
-
----
-
-## Why This Matters
-
-### The Real Cost of Poor Documentation
-
-When an AI assistant encounters a poorly documented tool, here's what happens:
-
-1. **First attempt fails** (wrong parameter format)
-2. **Second attempt fails** (missing required parameter)
-3. **Third attempt fails** (incorrect prerequisite state)
-4. **Fourth attempt succeeds** (finally figured it out)
-
-**User Experience**: "Why is Claude so dumb? It took 4 tries to do something simple!"
-
-**Reality**: Claude isn't dumb - the tool documentation is inadequate.
-
-### Success Metrics
-
-| Documentation Quality | First-Call Success | User Satisfaction | Token Efficiency |
-|----------------------|-------------------|-------------------|------------------|
-| Poor (one-liner)     | 30-50%            | Low               | 3-5x waste       |
-| Average (basic types)| 60-70%            | Medium            | 1.5-2x waste     |
-| Good (this standard) | 90-95%            | High              | Optimal          |
-
-### ROI Calculation
-
-- **Time to write good docs**: 15-30 minutes per tool
-- **Time saved per user**: 2-5 minutes per use
-- **Break-even**: 10-15 tool calls
-- **Typical tool usage**: 100s-1000s of calls
-
-**Every hour spent on documentation saves 10-50 hours of user frustration.**
-
----
-
-## The Golden Rule
-
-> **Your docstring should enable the AI assistant to succeed on the FIRST try, not after multiple failed attempts.**
-
-If you have to explain how to use your tool in chat more than once, your documentation is inadequate.
-
----
-
-## Required Documentation Elements
-
-Every MCP tool must include these 7 elements:
-
-### 1. One-Line Summary (with Key Constraint)
-
-State the purpose AND critical constraint in one line.
-
-**❌ BAD**: "Search bookmarks by title or URL."  
-**✅ GOOD**: "Search Firefox bookmarks by title/URL (requires Firefox closed)."
-
-**Why it matters**: The AI needs to know upfront if there are blockers.
-
----
-
-### 2. Prerequisites Section
-
-List everything that must be true BEFORE calling the tool.
-
-```python
-"""
-Prerequisites:
-    - Firefox must be completely closed (check system tray)
-    - Profile path must exist and be readable
-    - places.sqlite database must not be locked
-    - Minimum Firefox version: 57+ (uses SQLite FTS5)
-"""
-```
-
-**Why it matters**: Prevents 90% of "database locked" errors.
-
----
-
-### 3. Parameter Documentation (The Critical Part)
-
-Every parameter needs **5 things**:
-
-1. **Type**: `(str, REQUIRED)` or `(int, OPTIONAL)` in CAPS
-2. **Purpose**: What it does in plain language
-3. **Format/Constraints**: Pattern, range, or validation rules
-4. **Concrete Example**: Real value, not placeholder
-5. **Default**: For optional parameters
-
-**❌ BAD**:
-```python
-"""
-Args:
-    query: Search term
-    profile_path: Path to profile
-"""
-```
-
-**✅ GOOD**:
-```python
-"""
-Args:
-    query (str, REQUIRED):
-        Search term to find in bookmark titles or URLs
-        Case-insensitive, supports partial matches
-        Examples: "plex", "github.com", "machine learning tutorial"
-        Min length: 1 character
-        
-    profile_path (str, OPTIONAL):
-        Full absolute path to Firefox profile directory
-        Format: "C:\\Users\\{username}\\AppData\\Roaming\\Mozilla\\Firefox\\Profiles\\{profile_id}"
-        Example: "C:\\Users\\sandr\\AppData\\Roaming\\Mozilla\\Firefox\\Profiles\\airiswdq.default-release"
-        Default: Auto-detects from profiles.ini (may fail with multiple profiles)
-        Get path: Use get_firefox_profiles() tool first
-        Platform: Windows requires double backslashes, Linux/Mac use forward slashes
-        
-    limit (int, OPTIONAL):
-        Maximum number of bookmark results to return
-        Range: 1-100 (values outside range will be clamped)
-        Default: 50
-        Performance: <20 is fast, 50-100 may take 1-2 seconds with large databases
-"""
-```
-
-**Why it matters**: The AI knows exactly how to construct the call correctly.
-
----
-
-### 4. Return Format (Show Structure, Not Just Type)
-
-Don't just say "returns dict" - show the ACTUAL structure with field descriptions.
-
-**❌ BAD**:
-```python
-"""
-Returns:
-    dict: Search results
-"""
-```
-
-**✅ GOOD**:
-```python
-"""
-Returns:
-    dict: Search results with metadata
-    
-    Structure:
-    {
-        "status": str,              # "success" or "error"
-        "query": str,               # Echo of search query
-        "count": int,               # Number of results found
-        "profile": str,             # Profile path used
-        "results": [                # List of bookmark objects (may be empty)
-            {
-                "id": int,          # Unique bookmark ID (for other operations)
-                "title": str,       # Bookmark title (may be empty)
-                "url": str,         # Full URL including protocol
-                "dateAdded": int,   # Unix timestamp in microseconds
-                "lastModified": int,# Unix timestamp in microseconds  
-                "parent": int,      # Parent folder ID (0 = root)
-                "tags": [str]       # List of tags (may be empty)
-            }
-        ],
-        "truncated": bool,          # True if results limited by 'limit' parameter
-        "execution_time_ms": float  # Query execution time
-    }
-    
-    On Error:
-    {
-        "status": "error",
-        "error": str,               # Error message
-        "error_code": str,          # Machine-readable error code
-        "suggestion": str           # How to fix the error
-    }
-"""
-```
-
-**Why it matters**: The AI knows how to parse the response and handle errors.
-
----
-
-### 5. Common Errors with Actionable Solutions
-
-Don't just list errors - tell the AI (and user) HOW TO FIX THEM.
-
-**❌ BAD**:
-```python
-"""
-Raises:
-    DatabaseError: Database connection failed
-    ValueError: Invalid input
-"""
-```
-
-**✅ GOOD**:
-```python
-"""
-Common Issues & Solutions:
-
-1. "Failed to connect to database" / "Database is locked"
-   CAUSE: Firefox is still running
-   FIX: Close Firefox completely
-   - Windows: Check Task Manager for firefox.exe processes
-   - Linux: killall firefox
-   - macOS: Check Activity Monitor
-   - Also check system tray for hidden Firefox instance
-   WORKAROUND: Use export_bookmarks() tool instead (works while Firefox open)
-
-2. "Profile not found" / "places.sqlite not found"
-   CAUSE: Invalid profile path or profile doesn't exist
-   FIX: Get correct path first
-   - Call get_firefox_profiles() to list available profiles
-   - Verify path exists: "C:\\Users\\...\\Profiles\\{profile_name}"
-   - Check for typos (path is case-sensitive on Linux/Mac)
-   
-3. "No results found" (empty results array)
-   CAUSE: Search term doesn't match any bookmarks
-   FIX: Try different search strategies
-   - Broaden search: "plex" instead of "plex media server"
-   - Check spelling
-   - Try URL domain: "github.com" instead of project name
-   - Use list_bookmarks() to browse all bookmarks
-   
-4. "Permission denied"
-   CAUSE: Insufficient file system permissions
-   FIX: Check file permissions
-   - Windows: Run as administrator or check file properties
-   - Linux/Mac: Check places.sqlite permissions (should be 0600 or 0644)
-   - Verify user owns the Firefox profile directory
-"""
-```
-
-**Why it matters**: Self-service error resolution without needing to ask for help.
-
----
-
-### 6. Complete Working Examples (The Most Important Part)
-
-Provide **3+ realistic examples** covering common use cases.
-
-**❌ BAD**:
-```python
-"""
-Example:
-    search_bookmarks("query")
-"""
-```
-
-**✅ GOOD**:
-```python
-"""
-Examples:
-
-    # Example 1: Basic search with auto-detected profile (most common case)
-    # Use when: You have only one Firefox profile and Firefox is closed
-    result = search_bookmarks(
-        query="plex"
-    )
-    # Returns: All bookmarks with "plex" in title or URL
-    
-    
-    # Example 2: Search specific profile with limit (multiple profiles)
-    # Use when: You have multiple Firefox profiles or need to specify which one
-    result = search_bookmarks(
-        query="immich",
-        profile_path="C:\\Users\\sandr\\AppData\\Roaming\\Mozilla\\Firefox\\Profiles\\airiswdq.default-release",
-        limit=20
-    )
-    # Returns: Up to 20 bookmarks matching "immich"
-    
-    
-    # Example 3: Search by domain name (finding all bookmarks from a site)
-    # Use when: You want all bookmarks from a specific website
-    result = search_bookmarks(
-        query="github.com",
-        limit=100
-    )
-    # Returns: All GitHub bookmarks (up to 100)
-    
-    
-    # Example 4: Broad search with high limit (comprehensive search)
-    # Use when: You want to find everything related to a topic
-    result = search_bookmarks(
-        query="AI",
-        limit=100
-    )
-    # Returns: All bookmarks with "AI" in title or URL
-    
-    
-    # Example 5: Error handling pattern (production code)
-    # Use when: You need robust error handling
-    try:
-        result = search_bookmarks(
-            query="machine learning",
-            limit=50
-        )
-        
-        if result["status"] == "success":
-            print(f"Found {result['count']} bookmarks")
-            for bookmark in result["results"]:
-                print(f"- {bookmark['title']}: {bookmark['url']}")
-        else:
-            print(f"Error: {result['error']}")
-            print(f"Suggestion: {result['suggestion']}")
-            
-    except Exception as e:
-        print(f"Unexpected error: {e}")
-        # Fallback: try export_bookmarks() instead
-"""
-```
-
-**Why it matters**: The AI can copy-paste and adapt examples directly.
-
----
-
-### 7. Platform-Specific Notes
-
-Document Windows/Linux/Mac differences explicitly.
-
-**✅ GOOD**:
-```python
-"""
-Platform Notes:
-
-    WINDOWS:
-        - Profile location: %APPDATA%\\Mozilla\\Firefox\\Profiles\\
-        - Path format: Use DOUBLE backslashes "C:\\Users\\..."
-        - Check Firefox: Task Manager → Details tab → firefox.exe
-        - Common issue: OneDrive may sync profile (causes locks)
-        
-    LINUX:
-        - Profile location: ~/.mozilla/firefox/
-        - Path format: /home/{user}/.mozilla/firefox/{profile}
-        - Check Firefox: ps aux | grep firefox
-        - Common issue: Snap Firefox uses different profile path
-        
-    MACOS:
-        - Profile location: ~/Library/Application Support/Firefox/Profiles/
-        - Path format: /Users/{user}/Library/Application Support/...
-        - Check Firefox: Activity Monitor or ps aux | grep firefox
-        - Common issue: Firefox may run in background (check menu bar)
-        
-    Cross-Platform:
-        - places.sqlite is portable across platforms
-        - Bookmark IDs are consistent across platforms
-        - Timestamps are Unix microseconds (same everywhere)
-"""
-```
-
-**Why it matters**: The AI knows platform-specific quirks upfront.
-
----
-
-## Complete Documentation Template
-
-Here's the complete template you can copy-paste:
-
-```python
-def tool_name(param1: str, param2: Optional[int] = None) -> Dict:
-    """[One-line purpose with critical constraint]
-    
-    [2-3 sentences describing what this tool does and when to use it.
-    Mention any important limitations or considerations.]
-    
-    Prerequisites:
-        - [Requirement 1: specific condition that must be true]
-        - [Requirement 2: external state needed]
-        - [Requirement 3: permissions/access required]
-    
-    Args:
-        param1 (str, REQUIRED):
-            [What this parameter does in plain language]
-            Format: [pattern/structure with curly braces for variables]
-            Example: [concrete realistic value]
-            Validation: [constraints, min/max, allowed values]
-            
-        param2 (int, OPTIONAL):
-            [What this parameter does]
-            Range: [min-max values]
-            Default: [default value and why it's chosen]
-            Example: [realistic value]
-            Performance: [impact of different values if relevant]
-    
-    Returns:
-        [type]: [Brief description]
-        
-        Structure (Success):
-        {
-            "field1": type,  # Description and valid values
-            "field2": type,  # Description
-            "nested": {      # Nested structure
-                "subfield": type  # Description
-            }
-        }
-        
-        Structure (Error):
-        {
-            "status": "error",
-            "error": str,        # Human-readable error
-            "error_code": str,   # Machine-readable code
-            "suggestion": str    # How to fix
-        }
-    
-    Common Issues & Solutions:
-        
-        1. [Error message or condition]
-           CAUSE: [Why this happens]
-           FIX: [Step-by-step solution]
-           - [Specific action 1]
-           - [Specific action 2]
-           WORKAROUND: [Alternative approach if fix isn't possible]
-           
-        2. [Another error or issue]
-           CAUSE: [Root cause]
-           FIX: [How to resolve]
-           
-        3. [Edge case or unexpected behavior]
-           CAUSE: [Explanation]
-           FIX: [Solution]
-    
-    Examples:
-        
-        # Example 1: [Most common use case - describe when to use]
-        result = tool_name(
-            param1="realistic_value"
-        )
-        # Returns: [What to expect]
-        # Use when: [Scenario description]
-        
-        
-        # Example 2: [Second common case - with optional param]
-        result = tool_name(
-            param1="another_realistic_value",
-            param2=42
-        )
-        # Returns: [What to expect]
-        # Use when: [Scenario description]
-        
-        
-        # Example 3: [Advanced or edge case]
-        result = tool_name(
-            param1="special_case_value",
-            param2=100
-        )
-        # Returns: [What to expect]
-        # Use when: [Scenario description]
-        
-        
-        # Example 4: [Error handling pattern]
-        try:
-            result = tool_name(param1="value")
-            if result["status"] == "success":
-                # Handle success
-                pass
-            else:
-                # Handle error
-                print(result["suggestion"])
-        except Exception as e:
-            # Handle unexpected error
-            pass
-    
-    Platform Notes:
-        
-        WINDOWS:
-            - [Windows-specific information]
-            - [Common Windows issues]
-            
-        LINUX:
-            - [Linux-specific information]
-            - [Common Linux issues]
-            
-        MACOS:
-            - [macOS-specific information]
-            - [Common macOS issues]
-            
-        Cross-Platform:
-            - [Things that work the same everywhere]
-            - [Portable aspects]
-    
-    Performance:
-        - Typical: [Expected performance for normal case]
-        - Best case: [Fastest scenario]
-        - Worst case: [Slowest scenario]
-        - Optimization tips: [How to make it faster]
-    
-    See Also:
-        - [related_tool_1()]: [When to use instead of this tool]
-        - [related_tool_2()]: [Tool to get required parameters]
-        - [related_tool_3()]: [Alternative approach for same goal]
-    
-    Version History:
-        - v1.0: Initial release
-        - v1.1: Added [feature]
-        - v2.0: Breaking change - [what changed]
-    """
-```
-
----
-
-## Real-World Example: Before and After
-
-### BEFORE (Typical Current State)
-
-This is what most MCP tools look like today:
-
-```python
-def search_bookmarks(query, profile_path=None, limit=50):
-    """Search bookmarks by title or URL."""
-```
-
-**Problems**:
-- No indication Firefox must be closed
-- No parameter format/examples
-- No return structure documented
-- No error handling guidance
-- No platform differences noted
-
-**Result**: AI tries 3-5 times before success, users frustrated
-
----
-
-### AFTER (Following This Standard)
-
-```python
-def search_bookmarks(query: str, profile_path: Optional[str] = None, limit: int = 50) -> Dict:
-    """Search Firefox bookmarks by title/URL (requires Firefox closed).
-    
-    Performs case-insensitive search across bookmark titles and URLs using
-    SQLite FTS5 full-text search. Efficient for large bookmark collections
-    (tested with 10,000+ bookmarks). Returns results sorted by relevance.
-    
-    Prerequisites:
-        - Firefox must be completely closed (database will be locked otherwise)
-        - Profile must exist and contain places.sqlite database
-        - Read permissions on Firefox profile directory
-        - Firefox version 57+ (uses FTS5 features)
-    
-    Args:
-        query (str, REQUIRED):
-            Search term to find in bookmark titles or URLs
-            Case-insensitive, supports partial matches
-            Examples: "plex", "github.com", "machine learning tutorial"
-            Min length: 1 character
-            Special chars: Automatically escaped for SQLite FTS
-            
-        profile_path (str, OPTIONAL):
-            Full absolute path to Firefox profile directory containing places.sqlite
-            Format: "C:\\Users\\{username}\\AppData\\Roaming\\Mozilla\\Firefox\\Profiles\\{profile_id}"
-            Example: "C:\\Users\\sandr\\AppData\\Roaming\\Mozilla\\Firefox\\Profiles\\airiswdq.default-release"
-            Default: Auto-detects from profiles.ini (may fail with multiple profiles)
-            Get path: Use get_firefox_profiles() tool first
-            Platform: Windows requires double backslashes, Linux/Mac use forward slashes
-            
-        limit (int, OPTIONAL):
-            Maximum number of bookmark results to return
-            Range: 1-100 (values outside range will be clamped)
-            Default: 50
-            Performance: <20 is instant, 50-100 may take 1-2 seconds with large databases
-    
-    Returns:
-        dict: Search results with metadata
-        
-        Structure (Success):
-        {
-            "status": "success",
-            "query": str,               # Echo of search query
-            "count": int,               # Number of results found (0 if no matches)
-            "profile": str,             # Profile path used
-            "results": [                # List of bookmark objects (empty if no matches)
-                {
-                    "id": int,          # Unique bookmark ID (for other operations)
-                    "title": str,       # Bookmark title (may be empty string)
-                    "url": str,         # Full URL including protocol
-                    "dateAdded": int,   # Unix timestamp in microseconds
-                    "lastModified": int,# Unix timestamp in microseconds  
-                    "parent": int,      # Parent folder ID (0 = root)
-                    "tags": [str]       # List of tags (may be empty)
-                }
-            ],
-            "truncated": bool,          # True if results limited by 'limit' parameter
-            "execution_time_ms": float  # Query execution time
-        }
-        
-        Structure (Error):
-        {
-            "status": "error",
-            "error": str,               # Human-readable error message
-            "error_code": str,          # Machine-readable error code
-            "suggestion": str,          # How to fix the error
-            "profile": str              # Profile path attempted (if known)
-        }
-    
-    Common Issues & Solutions:
-        
-        1. "Failed to connect to database" / "Database is locked"
-           CAUSE: Firefox is still running (even in background)
-           FIX: Close Firefox completely
-           - Windows: Task Manager → Details → End all firefox.exe processes
-           - Linux: killall firefox
-           - macOS: Activity Monitor → Quit Firefox (check menu bar icon)
-           - System tray: Check for hidden Firefox icon
-           WORKAROUND: Use export_bookmarks() tool instead (works while Firefox is open)
-           
-        2. "Profile not found" / "places.sqlite not found"
-           CAUSE: Invalid profile path or profile doesn't exist
-           FIX: Get correct path first
-           - Call get_firefox_profiles() to list available profiles
-           - Verify path exists: Check "C:\\Users\\...\\Profiles\\{profile_name}"
-           - Check for typos (path is case-sensitive on Linux/Mac)
-           - Ensure you're using the correct profile (not "default" but "default-release")
-           
-        3. "No results found" (count: 0, empty results array)
-           CAUSE: Search term doesn't match any bookmarks
-           FIX: Try different search strategies
-           - Broaden search: "plex" instead of "plex media server"
-           - Check spelling and punctuation
-           - Try URL domain: "github.com" instead of project name
-           - Try partial words: "mach learn" instead of "machine learning"
-           - Use list_bookmarks() to browse all bookmarks
-           
-        4. "Permission denied"
-           CAUSE: Insufficient file system permissions
-           FIX: Check file permissions
-           - Windows: Run as administrator OR right-click places.sqlite → Properties → Security
-           - Linux/Mac: chmod 644 places.sqlite OR run with sudo
-           - Verify user owns the Firefox profile directory
-           - Check OneDrive/Dropbox sync (may cause permission issues)
-           
-        5. "Timeout" / Slow performance
-           CAUSE: Large database or complex search
-           FIX: Optimize search
-           - Reduce 'limit' parameter (try 20 instead of 100)
-           - Use more specific search terms
-           - Consider export_bookmarks() + local search for large datasets
-    
-    Examples:
-        
-        # Example 1: Basic search with auto-detected profile (most common case)
-        # Use when: You have only one Firefox profile and Firefox is closed
-        result = search_bookmarks(
-            query="plex"
-        )
-        # Returns: All bookmarks with "plex" in title or URL (up to 50)
-        # Use when: Quick search, single profile, Firefox closed
-        
-        
-        # Example 2: Search specific profile with limit (multiple profiles)
-        # Use when: You have multiple Firefox profiles or need to specify which one
-        result = search_bookmarks(
-            query="immich",
-            profile_path="C:\\Users\\sandr\\AppData\\Roaming\\Mozilla\\Firefox\\Profiles\\airiswdq.default-release",
-            limit=20
-        )
-        # Returns: Up to 20 bookmarks matching "immich" from specified profile
-        # Use when: Multiple profiles, need specific profile, or auto-detect fails
-        
-        
-        # Example 3: Search by domain name (finding all bookmarks from a site)
-        # Use when: You want all bookmarks from a specific website
-        result = search_bookmarks(
-            query="github.com",
-            limit=100
-        )
-        # Returns: All GitHub bookmarks (up to 100)
-        # Use when: Finding all links from a domain, organizing bookmarks
-        
-        
-        # Example 4: Broad search with high limit (comprehensive search)
-        # Use when: You want to find everything related to a topic
-        result = search_bookmarks(
-            query="AI",
-            limit=100
-        )
-        # Returns: All bookmarks with "AI" in title or URL (up to 100)
-        # Use when: Research, discovering connections, topic exploration
-        
-        
-        # Example 5: Error handling pattern (production code)
-        # Use when: You need robust error handling in production
-        try:
-            result = search_bookmarks(
-                query="machine learning",
-                limit=50
-            )
-            
-            if result["status"] == "success":
-                if result["count"] == 0:
-                    print("No bookmarks found - try broader search terms")
-                else:
-                    print(f"Found {result['count']} bookmarks:")
-                    for bookmark in result["results"]:
-                        print(f"  - {bookmark['title']}: {bookmark['url']}")
-                    
-                    if result["truncated"]:
-                        print(f"(showing first {limit}, increase limit for more)")
-            else:
-                print(f"Error: {result['error']}")
-                print(f"Suggestion: {result['suggestion']}")
-                
-        except Exception as e:
-            print(f"Unexpected error: {e}")
-            print("Fallback: Try export_bookmarks() tool instead")
-        
-        
-        # Example 6: Linux/Mac path format
-        # Use when: Running on Linux or macOS
-        result = search_bookmarks(
-            query="python",
-            profile_path="/home/user/.mozilla/firefox/abc123.default-release"
-        )
-        # Note: Forward slashes, no drive letter
-    
-    Platform Notes:
-        
-        WINDOWS:
-            - Profile location: %APPDATA%\\Mozilla\\Firefox\\Profiles\\
-            - Full path: C:\\Users\\{username}\\AppData\\Roaming\\Mozilla\\Firefox\\Profiles\\{profile}
-            - Path format: MUST use DOUBLE backslashes "C:\\Users\\..."
-            - Check Firefox: Task Manager → Details tab → Look for firefox.exe
-            - Common issue: OneDrive may sync profile causing database locks
-            
-        LINUX:
-            - Profile location: ~/.mozilla/firefox/
-            - Full path: /home/{user}/.mozilla/firefox/{profile}.{type}
-            - Path format: Forward slashes /home/user/...
-            - Check Firefox: ps aux | grep firefox
-            - Common issue: Snap Firefox uses /home/{user}/snap/firefox/common/.mozilla/
-            
-        MACOS:
-            - Profile location: ~/Library/Application Support/Firefox/Profiles/
-            - Full path: /Users/{user}/Library/Application Support/Firefox/Profiles/{profile}
-            - Path format: Forward slashes with spaces (use quotes)
-            - Check Firefox: Activity Monitor or ps aux | grep firefox
-            - Common issue: Firefox may run in background (check menu bar icon)
-            
-        Cross-Platform:
-            - places.sqlite format is identical across platforms
-            - Bookmark IDs are consistent across platforms
-            - Timestamps are Unix microseconds (same everywhere)
-            - Can copy places.sqlite between systems (paths may need adjustment)
-    
-    Performance:
-        - Typical: 10-50ms for database with <1000 bookmarks
-        - Large: 100-500ms for database with 10,000+ bookmarks
-        - Best case: Instant for simple queries with low limit
-        - Worst case: 1-2 seconds for complex queries on large databases
-        - Optimization: Use specific search terms, lower limit, close background apps
-        - Database size: places.sqlite grows 1MB per ~1000 bookmarks
-    
-    See Also:
-        - get_firefox_profiles(): List available Firefox profiles (use this first)
-        - list_bookmarks(): Browse all bookmarks without search (slower but comprehensive)
-        - export_bookmarks(): Export to JSON/CSV (works while Firefox is open)
-        - find_duplicates(): Find duplicate bookmark URLs
-        - get_bookmark_stats(): Get overall bookmark statistics
-        - add_bookmark(): Add new bookmarks programmatically
-    
-    Version History:
-        - v1.0 (2024-01): Initial release with basic search
-        - v1.1 (2024-03): Added FTS5 support for faster search
-        - v1.2 (2024-06): Added tag support in results
-        - v2.0 (2024-09): Breaking change - returns dict instead of list
-    """
-```
-
-**Result**: AI succeeds on first try, users are happy, documentation is reference material
-
----
-
-## Anti-Patterns to Avoid
-
-### ❌ Don't: Use Placeholder Examples
-```python
-"""Example: tool(foo="bar", baz=123)"""
-```
-Nobody's parameter is actually called "foo" or "bar".
-
-### ✅ Do: Use Realistic Examples
-```python
-"""Example: search_bookmarks(query="plex", limit=20)"""
-```
-
----
-
-### ❌ Don't: Say "Returns results"
-```python
-"""Returns: Search results"""
-```
-What structure? What fields?
-
-### ✅ Do: Show the Actual Structure
-```python
-"""
-Returns:
-    dict: {
-        "count": int,
-        "results": [{"id": int, "title": str, "url": str}]
-    }
-"""
-```
-
----
-
-### ❌ Don't: List Errors Without Solutions
-```python
-"""
-Raises:
-    DatabaseError: Database error occurred
-    ValueError: Invalid value
-"""
-```
-
-### ✅ Do: Provide Actionable Solutions
-```python
-"""
-Common Issues:
-    1. "Database error" → Close Firefox completely
-    2. "Invalid value" → Use get_firefox_profiles() to find valid path
-"""
-```
-
----
-
-### ❌ Don't: Assume Users Know Your Tools
-```python
-"""Args:
-    profile: Profile to use
-"""
-```
-How do they get a profile? What format?
-
-### ✅ Do: Guide Users to Prerequisites
-```python
-"""Args:
-    profile_path (str): Full path to profile directory
-        Get path: Use get_firefox_profiles() tool first
-        Format: "C:\\Users\\{user}\\AppData\\..."
-"""
-```
-
----
-
-### ❌ Don't: Use Technical Jargon Without Explanation
-```python
-"""Uses FTS5 for efficient querying of the places.sqlite relational store."""
-```
-
-### ✅ Do: Explain or Link to Resources
-```python
-"""
-Uses Firefox's full-text search (FTS5) for fast searching.
-Searches both bookmark titles and URLs efficiently, even
-with 10,000+ bookmarks.
-"""
-```
-
----
-
-### ❌ Don't: Forget Platform Differences
-```python
-"""Path: ~/.mozilla/firefox/profile"""
-```
-That's Linux-only!
-
-### ✅ Do: Document All Platforms
-```python
-"""
-Path:
-    - Windows: %APPDATA%\\Mozilla\\Firefox\\Profiles\\
-    - Linux: ~/.mozilla/firefox/
-    - macOS: ~/Library/Application Support/Firefox/Profiles/
-"""
-```
-
----
-
-### ❌ Don't: Write Documentation Once and Never Update
-Documentation gets stale fast.
-
-### ✅ Do: Version Your Documentation
-```python
-"""
-Version History:
-    - v2.0: Breaking change - returns dict instead of list
-    - v1.1: Added tag support
-"""
-```
-
----
-
-## Implementation Checklist
-
-Use this checklist when writing or reviewing tool documentation:
-
-### Basic Requirements (Must Have)
-- [ ] One-line summary includes critical constraints
-- [ ] Prerequisites section lists all requirements
-- [ ] Every parameter has type (REQUIRED/OPTIONAL in CAPS)
-- [ ] Every parameter has concrete example with realistic value
-- [ ] Every optional parameter shows default value
-- [ ] Return structure shown with actual field names and types
-- [ ] At least 3 realistic examples covering common use cases
-- [ ] Common errors documented with actionable solutions
-
-### Good Documentation (Should Have)
-- [ ] Parameter format/constraints specified
-- [ ] Error responses structure documented
-- [ ] Platform differences noted (Windows/Linux/Mac)
-- [ ] Performance characteristics mentioned
-- [ ] Related tools listed in "See Also"
-- [ ] Examples include comments explaining when to use
-- [ ] Validation rules for parameters stated
-
-### Excellent Documentation (Nice to Have)
-- [ ] Version history included
-- [ ] Performance benchmarks provided
-- [ ] Error handling example included
-- [ ] Edge cases documented
-- [ ] Cross-platform example provided
-- [ ] Troubleshooting section with FAQs
-- [ ] Links to external resources
-- [ ] Migration guide for breaking changes
-
-### Documentation Validation
-- [ ] Ran tool with each example - all work correctly
-- [ ] AI assistant succeeded on first try using only docs
-- [ ] No ambiguous terms or unclear requirements
-- [ ] No placeholders ("foo", "bar", "example", "test")
-- [ ] Formatted consistently with rest of codebase
-- [ ] Spell-checked and grammar-checked
-- [ ] Reviewed by someone unfamiliar with the tool
-
----
-
-## Measuring Success
-
-### Key Performance Indicators (KPIs)
-
-Track these metrics to measure documentation quality:
-
-1. **First-Call Success Rate**: % of times AI gets it right on first attempt
-   - Target: >90%
-   - Measure: Log successful vs failed first attempts
-
-2. **Average Attempts to Success**: How many tries before success
-   - Target: <1.2 (20% need retry)
-   - Measure: Count API calls per successful operation
-
-3. **Documentation Issue Reports**: Users reporting "how do I...?"
-   - Target: <1 per 1000 tool calls
-   - Measure: Support tickets and forum questions
-
-4. **Token Efficiency**: Tokens used vs optimal usage
-   - Target: <1.5x optimal
-   - Measure: Actual tokens / minimum required tokens
-
-### Quick Self-Assessment
-
-Answer these questions honestly:
-
-1. Can an AI assistant use your tool successfully on the FIRST try using only the docstring?
-2. Can you copy-paste an example from your docs and have it work immediately?
-3. If there's an error, does your documentation tell the user exactly how to fix it?
-4. Would you be comfortable having no other documentation than the docstring?
-5. Could someone from a different platform (Windows/Linux/Mac) use your tool?
-
-**If you answered "no" to any question, your documentation needs improvement.**
-
-### A/B Testing Framework
-
-Compare documentation quality experimentally:
-
-```python
-# Test Group A: Old documentation (one-liner)
-# Test Group B: New documentation (this standard)
-
-# Measure over 100 tool calls each:
-# - First-call success rate
-# - Average attempts to success  
-# - User satisfaction rating
-# - Support ticket volume
-
-# Expected improvements with new docs:
-# - First-call success: 50% → 90% (80% improvement)
-# - Avg attempts: 2.5 → 1.1 (56% reduction)
-# - User satisfaction: 3.2/5 → 4.5/5 (41% improvement)
-# - Support tickets: 5/100 → 0.5/100 (90% reduction)
-```
-
----
-
-## Quick Reference Guide
-
-### Minimum Viable Documentation (5 minutes)
-
-If you only have 5 minutes, add these:
-
-1. **Constraint in summary**: "Search bookmarks (Firefox must be closed)"
-2. **Mark REQUIRED params**: `query (str, REQUIRED)`
-3. **One realistic example**: `search_bookmarks(query="plex")`
-4. **Top error with fix**: "Database locked → Close Firefox"
-5. **Return structure basics**: `{"count": int, "results": [...]}`
-
-**Impact**: ~50% → ~70% first-call success rate
-
----
-
-### Standard Documentation (15 minutes)
-
-For complete documentation, add:
-
-1. Everything from "Minimum Viable" above
-2. All parameters with format and examples
-3. 3 realistic examples covering common cases
-4. Top 3 errors with solutions
-5. Complete return structure with field descriptions
-6. Platform notes if applicable
-
-**Impact**: ~70% → ~90% first-call success rate
-
----
-
-### Gold Standard Documentation (30 minutes)
-
-For best-in-class documentation, add:
-
-1. Everything from "Standard" above
-2. Prerequisites section
-3. Performance characteristics
-4. 5+ examples including error handling
-5. All common errors with solutions
-6. Platform-specific sections
-7. See Also with related tools
-8. Version history
-
-**Impact**: ~90% → ~95% first-call success rate + happy users
-
----
-
-## Community Resources
-
-### For MCP Server Developers
-
-- **FastMCP Documentation**: https://github.com/jlowin/fastmcp
-- **MCP Protocol Spec**: https://modelcontextprotocol.io
-- **Glama.ai MCP Servers**: https://glama.ai/mcp/servers
-- **MCP Community Discord**: [Link to community]
-
-### Templates and Tools
-
-- **Documentation Template** (above): Copy-paste ready
-- **Documentation Linter**: [Tool to validate docs against this standard]
-- **Example MCP Servers**: [List of well-documented examples]
-
-### Getting Help
-
-- **Questions**: Post in MCP community forums
-- **Suggestions**: Open issues on this document's repo
-- **Contributions**: PRs welcome to improve this standard
-
----
-
-## Call to Action
-
-### For Tool Authors
-
-1. **Audit your existing tools**: Which have inadequate docstrings?
-2. **Start with high-traffic tools**: Fix the ones Claude uses most
-3. **Measure improvement**: Track first-call success rate before/after
-4. **Share your learnings**: Help other developers avoid the same mistakes
-
-### For the MCP Community
-
-1. **Adopt this standard**: Make it part of MCP best practices
-2. **Create tooling**: Build linters and validators
-3. **Reward good documentation**: Feature well-documented servers on Glama.ai
-4. **Share examples**: Build a library of exemplary tool documentation
-
-### For Framework Maintainers
-
-1. **Integrate into FastMCP**: Make this template the default
-2. **Add validation**: Lint docstrings at build time
-3. **Generate from docs**: Auto-create OpenAPI/JSON schemas from docstrings
-4. **Provide templates**: IDE snippets for quick documentation
-
----
-
-## Conclusion
-
-**The Bottom Line**: Good documentation is not optional - it's the difference between an AI assistant that looks brilliant and one that looks incompetent.
-
-**The ROI**: 15-30 minutes per tool saves 10-50 hours of user frustration.
-
-**The Standard**: If your tool documentation doesn't enable first-call success, it's not done.
-
-**The Call**: Let's make all MCP tools as easy to use as they are powerful.
-
----
-
-## Document History
-
-- **v1.0** (2025-10-10): Initial publication
-- **Author**: MCP Community
-- **License**: CC0 (Public Domain)
-- **Contributing**: PRs welcome at [repo link]
-
----
-
-*"Documentation is a love letter that you write to your future self." - Damian Conway*
-
-*"The best interface is no interface - but the second best is a well-documented one." - Adapted from Golden Krishna*