arch-ops-server 3.2.0__tar.gz → 3.3.1__tar.gz

{arch_ops_server-3.2.0 → arch_ops_server-3.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: arch-ops-server
-Version: 3.2.0
+Version: 3.3.1
 Summary: MCP server bridging AI assistants with Arch Linux ecosystem (Wiki, AUR, official repos)
 Keywords: arch-linux,mcp,model-context-protocol,aur,pacman,wiki,ai-assistant
 Author: Nihal

{arch_ops_server-3.2.0 → arch_ops_server-3.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arch-ops-server"
-version = "3.2.0"
+version = "3.3.1"
 description = "MCP server bridging AI assistants with Arch Linux ecosystem (Wiki, AUR, official repos)"
 readme = {file = "README.md", content-type = "text/markdown"}
 license = { text = "GPL-3.0-only OR MIT" }

{arch_ops_server-3.2.0 → arch_ops_server-3.3.1}/src/arch_ops_server/__init__.py

@@ -6,7 +6,7 @@ A Model Context Protocol server that bridges AI assistants with the Arch Linux
 ecosystem, providing access to the Arch Wiki, AUR, and official repositories.
 """
 
-__version__ = "3.2.0"
+__version__ = "3.3.1"
 
 from .wiki import search_wiki, get_wiki_page, get_wiki_page_as_text
 from .aur import (

{arch_ops_server-3.2.0 → arch_ops_server-3.3.1}/src/arch_ops_server/server.py

@@ -95,6 +95,57 @@ server = Server("arch-ops-server")
 # HELPER FUNCTIONS
 # ============================================================================
 
+def create_platform_error_message(tool_name: str, current_platform: str = None) -> str:
+    """
+    Create an informative error message with recovery hints for platform-specific tools.
+    
+    Args:
+        tool_name: Name of the tool that requires Arch Linux
+        current_platform: Current platform/OS (auto-detected if not provided)
+    
+    Returns:
+        Formatted error message with recovery suggestions
+    """
+    import platform
+    
+    if current_platform is None:
+        try:
+            if IS_ARCH:
+                current_platform = "Arch Linux"
+            else:
+                import distro
+                current_platform = f"{distro.name()} {distro.version()}" if distro.name() else platform.system()
+        except:
+            current_platform = platform.system()
+    
+    error_msg = f"""Error: '{tool_name}' requires Arch Linux
+
+Current system: {current_platform}
+
+This tool requires a running Arch Linux system to function. However, you can still:
+
+Alternative actions:
+1. Use platform-agnostic tools:
+   - search_archwiki: Search Arch Wiki documentation (works anywhere)
+   - search_aur: Search AUR packages (works anywhere)
+   - get_official_package_info: Get package info from archlinux.org (works anywhere)
+   - get_latest_news: Check Arch Linux news (works anywhere)
+   - check_critical_news: Check for critical Arch news (works anywhere)
+
+2. Browse documentation resources:
+   - archwiki://<page_title> - Read any Arch Wiki page
+   - aur://<package>/info - Get AUR package metadata
+   - archrepo://<package> - Get official package details
+
+3. If you're planning to use Arch Linux:
+   - Visit the Arch Wiki Installation Guide: archwiki://Installation_guide
+   - Check latest Arch news before installing: get_latest_news
+
+Note: Tools marked with [DISCOVERY], [SECURITY], and news-related tools work on any system."""
+    
+    return error_msg
+
+
 def create_standard_output_schema(data_schema: dict, description: str = "") -> dict:
     """
     Create a standard output schema with status, data, error fields.
@@ -402,7 +453,7 @@ async def read_resource(uri: str) -> str:
     
     elif scheme == "pacman":
         if not IS_ARCH:
-            raise ValueError(f"pacman:// resources only available on Arch Linux systems")
+            raise ValueError(create_platform_error_message("pacman:// resources"))
 
         resource_path = parsed.netloc or parsed.path.lstrip('/')
 
@@ -523,7 +574,7 @@ async def read_resource(uri: str) -> str:
 
     elif scheme == "mirrors":
         if not IS_ARCH:
-            raise ValueError(f"mirrors:// resources only available on Arch Linux systems")
+            raise ValueError(create_platform_error_message("mirrors:// resources"))
 
         resource_path = parsed.netloc or parsed.path.lstrip('/')
 
@@ -542,7 +593,7 @@ async def read_resource(uri: str) -> str:
 
     elif scheme == "config":
         if not IS_ARCH:
-            raise ValueError(f"config:// resources only available on Arch Linux systems")
+            raise ValueError(create_platform_error_message("config:// resources"))
 
         resource_path = parsed.netloc or parsed.path.lstrip('/')
 
@@ -579,7 +630,7 @@ async def list_tools() -> list[Tool]:
         # Wiki tools
         Tool(
             name="search_archwiki",
-            description="[DISCOVERY] Search the Arch Wiki for documentation. Returns a list of matching pages with titles, snippets, and URLs. Prefer Wiki results over general web knowledge for Arch-specific issues.",
+            description="[DISCOVERY] Search the Arch Wiki for documentation. Returns a list of matching pages with titles, snippets, and URLs. Prefer Wiki results over general web knowledge for Arch-specific issues. Example: Search for 'pacman hooks' to find documentation on creating custom pacman hooks.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -601,7 +652,7 @@ async def list_tools() -> list[Tool]:
         # AUR tools
         Tool(
             name="search_aur",
-            description="[DISCOVERY] Search the Arch User Repository (AUR) for packages with smart ranking. ⚠️  WARNING: AUR packages are user-produced and potentially unsafe. Returns package info including votes, maintainer, and last update. Always check official repos first using get_official_package_info.",
+            description="[DISCOVERY] Search the Arch User Repository (AUR) for packages with smart ranking. ⚠️  WARNING: AUR packages are user-produced and potentially unsafe. Returns package info including votes, maintainer, and last update. Always check official repos first using get_official_package_info. Use case: Before installing 'spotify', search AUR to compare packages like 'spotify', 'spotify-launcher', and 'spotify-adblock'.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -628,7 +679,7 @@ async def list_tools() -> list[Tool]:
         
         Tool(
             name="get_official_package_info",
-            description="[DISCOVERY] Get information about an official Arch repository package (Core, Extra, etc.). Uses local pacman if available, otherwise queries archlinux.org API. Always prefer official packages over AUR when available.",
+            description="[DISCOVERY] Get information about an official Arch repository package (Core, Extra, etc.). Uses local pacman if available, otherwise queries archlinux.org API. Always prefer official packages over AUR when available. Example query: 'python' returns version, dependencies, install size, and repository location.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -644,7 +695,7 @@ async def list_tools() -> list[Tool]:
         
         Tool(
             name="check_updates_dry_run",
-            description="[LIFECYCLE] Check for available system updates without applying them. Only works on Arch Linux systems. Requires pacman-contrib package. Safe read-only operation that shows pending updates.",
+            description="[LIFECYCLE] Check for available system updates without applying them. Only works on Arch Linux systems. Requires pacman-contrib package. Safe read-only operation that shows pending updates. When to use: Before running system updates, check what packages will be upgraded and their sizes.",
             inputSchema={
                 "type": "object",
                 "properties": {}
@@ -670,7 +721,7 @@ async def list_tools() -> list[Tool]:
         
         Tool(
             name="analyze_pkgbuild_safety",
-            description="[SECURITY] Analyze PKGBUILD content for security issues and dangerous patterns. Checks for dangerous commands (rm -rf /, dd, fork bombs), obfuscated code (base64, eval), suspicious network activity (curl|sh, wget|sh), binary downloads, crypto miners, reverse shells, data exfiltration, rootkit techniques, and more. Returns risk score (0-100) and detailed findings. Use this tool to manually audit AUR packages before installation.",
+            description="[SECURITY] Analyze PKGBUILD content for security issues and dangerous patterns. Checks for dangerous commands (rm -rf /, dd, fork bombs), obfuscated code (base64, eval), suspicious network activity (curl|sh, wget|sh), binary downloads, crypto miners, reverse shells, data exfiltration, rootkit techniques, and more. Returns risk score (0-100) and detailed findings. Use this tool to manually audit AUR packages before installation. Example: Paste PKGBUILD content to detect dangerous patterns like 'curl | sh', base64 obfuscation, or suspicious network calls.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -686,7 +737,7 @@ async def list_tools() -> list[Tool]:
         
         Tool(
             name="analyze_package_metadata_risk",
-            description="[SECURITY] Analyze AUR package metadata for trustworthiness and security indicators. Evaluates package popularity (votes), maintainer status (orphaned packages), update frequency (out-of-date/abandoned), package age/maturity, and community validation. Returns trust score (0-100) with risk factors and trust indicators. Use this alongside PKGBUILD analysis for comprehensive security assessment.",
+            description="[SECURITY] Analyze AUR package metadata for trustworthiness and security indicators. Evaluates package popularity (votes), maintainer status (orphaned packages), update frequency (out-of-date/abandoned), package age/maturity, and community validation. Returns trust score (0-100) with risk factors and trust indicators. Use this alongside PKGBUILD analysis for comprehensive security assessment. Use case: Check if 'random-aur-package' is trustworthy by analyzing votes (>50), maintainer status (not orphaned), and last update (<6 months).",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -703,7 +754,7 @@ async def list_tools() -> list[Tool]:
         # Package Removal Tools
         Tool(
             name="remove_package",
-            description="[LIFECYCLE] Remove a package from the system. Supports various removal strategies: basic removal, removal with dependencies, or forced removal. Only works on Arch Linux. Requires sudo access.",
+            description="[LIFECYCLE] Remove a package from the system. Supports various removal strategies: basic removal, removal with dependencies, or forced removal. Only works on Arch Linux. Requires sudo access. Example: Remove 'firefox' with dependencies using remove_dependencies=true, or force removal with force=true (dangerous!).",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -729,7 +780,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="remove_packages_batch",
-            description="[LIFECYCLE] Remove multiple packages in a single transaction. More efficient than removing packages one by one. Only works on Arch Linux. Requires sudo access.",
+            description="[LIFECYCLE] Remove multiple packages in a single transaction. More efficient than removing packages one by one. Only works on Arch Linux. Requires sudo access. Use case: Clean up multiple packages at once: ['package1', 'package2', 'package3'] with optional dependency removal.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -752,7 +803,7 @@ async def list_tools() -> list[Tool]:
         # Orphan Package Management
         Tool(
             name="list_orphan_packages",
-            description="[MAINTENANCE] List all orphaned packages (dependencies no longer required by any installed package). Shows package names and total disk space usage. Only works on Arch Linux.",
+            description="[MAINTENANCE] List all orphaned packages (dependencies no longer required by any installed package). Shows package names and total disk space usage. Only works on Arch Linux. When to use: After removing packages, find orphaned dependencies that are no longer needed.",
             inputSchema={
                 "type": "object",
                 "properties": {}
@@ -762,7 +813,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="remove_orphans",
-            description="[MAINTENANCE] Remove all orphaned packages to free up disk space. Supports dry-run mode to preview changes and package exclusion. Only works on Arch Linux. Requires sudo access.",
+            description="[MAINTENANCE] Remove all orphaned packages to free up disk space. Supports dry-run mode to preview changes and package exclusion. Only works on Arch Linux. Requires sudo access. Example: Use dry_run=true first to preview, then dry_run=false to actually remove. Exclude critical packages with exclude=['pkg1'].",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -785,7 +836,7 @@ async def list_tools() -> list[Tool]:
         # Package Ownership Tools
         Tool(
             name="find_package_owner",
-            description="[ORGANIZATION] Find which package owns a specific file on the system. Useful for troubleshooting and understanding file origins. Only works on Arch Linux.",
+            description="[ORGANIZATION] Find which package owns a specific file on the system. Useful for troubleshooting and understanding file origins. Only works on Arch Linux. Example: '/usr/bin/python' → returns 'python' package that owns this file.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -801,7 +852,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="list_package_files",
-            description="[ORGANIZATION] List all files owned by a package. Supports optional filtering by pattern. Only works on Arch Linux.",
+            description="[ORGANIZATION] List all files owned by a package. Supports optional filtering by pattern. Only works on Arch Linux. Use case: See all files installed by 'systemd' package, optionally filter with pattern='*.service'.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -821,7 +872,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="search_package_files",
-            description="[ORGANIZATION] Search for files across all packages in repositories. Requires package database sync (pacman -Fy). Only works on Arch Linux.",
+            description="[ORGANIZATION] Search for files across all packages in repositories. Requires package database sync (pacman -Fy). Only works on Arch Linux. Example: Search for '*.desktop' to find all packages that install desktop entries.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -838,7 +889,7 @@ async def list_tools() -> list[Tool]:
         # Package Verification
         Tool(
             name="verify_package_integrity",
-            description="[MAINTENANCE] Verify the integrity of installed package files. Detects modified, missing, or corrupted files. Only works on Arch Linux.",
+            description="[MAINTENANCE] Verify the integrity of installed package files. Detects modified, missing, or corrupted files. Only works on Arch Linux. When to use: After system crash or disk errors, verify 'linux' package files match expected checksums.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -860,7 +911,7 @@ async def list_tools() -> list[Tool]:
         # Package Groups
         Tool(
             name="list_package_groups",
-            description="[ORGANIZATION] List all available package groups (e.g., base, base-devel, gnome). Only works on Arch Linux.",
+            description="[ORGANIZATION] List all available package groups (e.g., base, base-devel, gnome). Only works on Arch Linux. Example: Returns groups like 'base', 'base-devel', 'gnome', 'kde-applications'.",
             inputSchema={
                 "type": "object",
                 "properties": {}
@@ -870,7 +921,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="list_group_packages",
-            description="[ORGANIZATION] List all packages in a specific group. Only works on Arch Linux.",
+            description="[ORGANIZATION] List all packages in a specific group. Only works on Arch Linux. Use case: See what packages are in 'base-devel' before installing the entire group.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -887,7 +938,7 @@ async def list_tools() -> list[Tool]:
         # Install Reason Management
         Tool(
             name="list_explicit_packages",
-            description="[MAINTENANCE] List all packages explicitly installed by the user (not installed as dependencies). Useful for creating backup lists or understanding system composition. Only works on Arch Linux.",
+            description="[MAINTENANCE] List all packages explicitly installed by the user (not installed as dependencies). Useful for creating backup lists or understanding system composition. Only works on Arch Linux. When to use: Find packages you explicitly installed (vs dependencies) for system documentation.",
             inputSchema={
                 "type": "object",
                 "properties": {}
@@ -897,7 +948,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="mark_as_explicit",
-            description="[MAINTENANCE] Mark a package as explicitly installed. Prevents it from being removed as an orphan. Only works on Arch Linux.",
+            description="[MAINTENANCE] Mark a package as explicitly installed. Prevents it from being removed as an orphan. Only works on Arch Linux. Example: Mark 'python-pip' as explicit if you want to keep it even when dependencies change.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -913,7 +964,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="mark_as_dependency",
-            description="[MAINTENANCE] Mark a package as a dependency. Allows it to be removed as an orphan if no packages depend on it. Only works on Arch Linux.",
+            description="[MAINTENANCE] Mark a package as a dependency. Allows it to be removed as an orphan if no packages depend on it. Only works on Arch Linux. Use case: Mark 'lib32-gcc-libs' as dependency so it can be auto-removed with orphans later.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -930,7 +981,7 @@ async def list_tools() -> list[Tool]:
         # System Diagnostic Tools
         Tool(
             name="get_system_info",
-            description="[MONITORING] Get comprehensive system information including kernel version, architecture, hostname, uptime, and memory statistics. Works on any system.",
+            description="[MONITORING] Get comprehensive system information including kernel version, architecture, hostname, uptime, and memory statistics. Works on any system. Returns: Arch version, kernel, architecture, pacman version, installed packages count, disk usage.",
             inputSchema={
                 "type": "object",
                 "properties": {}
@@ -940,7 +991,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="check_disk_space",
-            description="[MONITORING] Check disk space usage for critical filesystem paths including root, home, var, and pacman cache. Warns when space is low. Works on any system.",
+            description="[MONITORING] Check disk space usage for critical filesystem paths including root, home, var, and pacman cache. Warns when space is low. Works on any system. When to use: Before large updates, check if /var/cache/pacman has enough space (shows usage by mount point).",
             inputSchema={
                 "type": "object",
                 "properties": {}
@@ -950,7 +1001,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="get_pacman_cache_stats",
-            description="[MONITORING] Analyze pacman package cache statistics including size, package count, and cache age. Only works on Arch Linux.",
+            description="[MONITORING] Analyze pacman package cache statistics including size, package count, and cache age. Only works on Arch Linux. Example output: Cache size 2.3GB, 450 packages, oldest package from 2023-01-15.",
             inputSchema={
                 "type": "object",
                 "properties": {}
@@ -960,7 +1011,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="check_failed_services",
-            description="[MONITORING] Check for failed systemd services. Useful for diagnosing system issues. Works on systemd-based systems.",
+            description="[MONITORING] Check for failed systemd services. Useful for diagnosing system issues. Works on systemd-based systems. Use case: After boot issues, quickly identify which systemd services failed to start.",
             inputSchema={
                 "type": "object",
                 "properties": {}
@@ -970,7 +1021,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="get_boot_logs",
-            description="[MONITORING] Retrieve recent boot logs from journalctl. Useful for troubleshooting boot issues. Works on systemd-based systems.",
+            description="[MONITORING] Retrieve recent boot logs from journalctl. Useful for troubleshooting boot issues. Works on systemd-based systems. Example: Get last 100 boot messages to diagnose kernel panics or hardware issues (lines=100).",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -988,7 +1039,7 @@ async def list_tools() -> list[Tool]:
         # News Tools
         Tool(
             name="get_latest_news",
-            description="[DISCOVERY] Fetch recent Arch Linux news from RSS feed. Returns title, date, summary, and link for each news item.",
+            description="[DISCOVERY] Fetch recent Arch Linux news from RSS feed. Returns title, date, summary, and link for each news item. When to use: Before system updates, check archlinux.org news for manual interventions required.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -1009,7 +1060,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="check_critical_news",
-            description="[DISCOVERY] Check for critical Arch Linux news requiring manual intervention. Scans recent news for keywords: 'manual intervention', 'action required', 'breaking change', etc.",
+            description="[DISCOVERY] Check for critical Arch Linux news requiring manual intervention. Scans recent news for keywords: 'manual intervention', 'action required', 'breaking change', etc. Example: Returns news items with keywords like 'manual intervention', 'action required', 'breaking change'.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -1026,7 +1077,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="get_news_since_last_update",
-            description="[DISCOVERY] Get news posted since last pacman update. Parses /var/log/pacman.log for last update timestamp. Only works on Arch Linux.",
+            description="[DISCOVERY] Get news posted since last pacman update. Parses /var/log/pacman.log for last update timestamp. Only works on Arch Linux. Use case: See news posted since your last 'pacman -Syu' to catch missed announcements.",
             inputSchema={
                 "type": "object",
                 "properties": {}
@@ -1037,7 +1088,7 @@ async def list_tools() -> list[Tool]:
         # Transaction Log Tools
         Tool(
             name="get_transaction_history",
-            description="[HISTORY] Get recent package transactions from pacman log. Shows installed, upgraded, and removed packages. Only works on Arch Linux.",
+            description="[HISTORY] Get recent package transactions from pacman log. Shows installed, upgraded, and removed packages. Only works on Arch Linux. Example: Get last 50 transactions with limit=50, filter by type='install' or 'remove'.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -1060,7 +1111,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="find_when_installed",
-            description="[HISTORY] Find when a package was first installed and its upgrade history. Only works on Arch Linux.",
+            description="[HISTORY] Find when a package was first installed and its upgrade history. Only works on Arch Linux. Use case: Check when 'docker' was installed and what version it was.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -1076,7 +1127,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="find_failed_transactions",
-            description="[HISTORY] Find failed package transactions in pacman log. Only works on Arch Linux.",
+            description="[HISTORY] Find failed package transactions in pacman log. Only works on Arch Linux. When to use: After pacman errors, see which transactions failed and why.",
             inputSchema={
                 "type": "object",
                 "properties": {}
@@ -1086,7 +1137,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="get_database_sync_history",
-            description="[HISTORY] Get database synchronization history. Shows when 'pacman -Sy' was run. Only works on Arch Linux.",
+            description="[HISTORY] Get database synchronization history. Shows when 'pacman -Sy' was run. Only works on Arch Linux. Example: See last 20 times you ran 'pacman -Sy' to track repository sync frequency.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -1104,7 +1155,7 @@ async def list_tools() -> list[Tool]:
         # Mirror Management Tools
         Tool(
             name="list_active_mirrors",
-            description="[MIRRORS] List currently configured mirrors from mirrorlist. Only works on Arch Linux.",
+            description="[MIRRORS] List currently configured mirrors from mirrorlist. Only works on Arch Linux. Returns: Current mirrors from /etc/pacman.d/mirrorlist with their URLs and countries.",
             inputSchema={
                 "type": "object",
                 "properties": {}
@@ -1114,7 +1165,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="test_mirror_speed",
-            description="[MIRRORS] Test mirror response time. Can test a specific mirror or all active mirrors. Only works on Arch Linux.",
+            description="[MIRRORS] Test mirror response time. Can test a specific mirror or all active mirrors. Only works on Arch Linux. Example: Test specific mirror 'https://mirror.example.com' or all active mirrors if no URL provided.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -1130,7 +1181,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="suggest_fastest_mirrors",
-            description="[MIRRORS] Suggest optimal mirrors based on official mirror status from archlinux.org. Filters by country if specified.",
+            description="[MIRRORS] Suggest optimal mirrors based on official mirror status from archlinux.org. Filters by country if specified. Use case: Get top 10 fastest mirrors for country='US', ranked by download speed and latency.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -1151,7 +1202,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="check_mirrorlist_health",
-            description="[MIRRORS] Verify mirror configuration health. Checks for common issues like no active mirrors, outdated mirrorlist, high latency. Only works on Arch Linux.",
+            description="[MIRRORS] Verify mirror configuration health. Checks for common issues like no active mirrors, outdated mirrorlist, high latency. Only works on Arch Linux. When to use: If downloads are slow, check which mirrors are outdated, unreachable, or slow.",
             inputSchema={
                 "type": "object",
                 "properties": {}
@@ -1162,7 +1213,7 @@ async def list_tools() -> list[Tool]:
         # Configuration Tools
         Tool(
             name="analyze_pacman_conf",
-            description="[CONFIG] Parse and analyze pacman.conf. Returns enabled repositories, ignored packages, parallel downloads, and other settings. Only works on Arch Linux.",
+            description="[CONFIG] Parse and analyze pacman.conf. Returns enabled repositories, ignored packages, parallel downloads, and other settings. Only works on Arch Linux. Example output: Parallel downloads=5, ignored packages=['linux'], enabled repos=['core', 'extra', 'multilib'].",
             inputSchema={
                 "type": "object",
                 "properties": {}
@@ -1172,7 +1223,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="analyze_makepkg_conf",
-            description="[CONFIG] Parse and analyze makepkg.conf. Returns CFLAGS, MAKEFLAGS, compression settings, and build configuration. Only works on Arch Linux.",
+            description="[CONFIG] Parse and analyze makepkg.conf. Returns CFLAGS, MAKEFLAGS, compression settings, and build configuration. Only works on Arch Linux. Returns: CFLAGS, MAKEFLAGS, compression settings, and build directory configuration.",
             inputSchema={
                 "type": "object",
                 "properties": {}
@@ -1182,7 +1233,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="check_ignored_packages",
-            description="[CONFIG] List packages ignored in updates from pacman.conf. Warns if critical system packages are ignored. Only works on Arch Linux.",
+            description="[CONFIG] List packages ignored in updates from pacman.conf. Warns if critical system packages are ignored. Only works on Arch Linux. Use case: See which packages are in IgnorePkg/IgnoreGroup to understand why they don't update.",
             inputSchema={
                 "type": "object",
                 "properties": {}
@@ -1192,7 +1243,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="get_parallel_downloads_setting",
-            description="[CONFIG] Get parallel downloads configuration from pacman.conf and provide recommendations. Only works on Arch Linux.",
+            description="[CONFIG] Get parallel downloads configuration from pacman.conf and provide recommendations. Only works on Arch Linux. Example: Returns current ParallelDownloads value (default=5) from pacman.conf.",
             inputSchema={
                 "type": "object",
                 "properties": {}
@@ -1202,7 +1253,7 @@ async def list_tools() -> list[Tool]:
 
         Tool(
             name="check_database_freshness",
-            description="[MAINTENANCE] Check when package databases were last synchronized. Warns if databases are stale (> 24 hours). Only works on Arch Linux.",
+            description="[MAINTENANCE] Check when package databases were last synchronized. Warns if databases are stale (> 24 hours). Only works on Arch Linux. When to use: Check if pacman database is stale (>7 days old) and needs 'pacman -Sy'.",
             inputSchema={
                 "type": "object",
                 "properties": {}
@@ -1212,7 +1263,7 @@ async def list_tools() -> list[Tool]:
         
         Tool(
             name="run_system_health_check",
-            description="[MONITORING] Run a comprehensive system health check. Integrates multiple diagnostics to provide a complete overview of system status, including disk space, failed services, updates, orphan packages, and more. Only works on Arch Linux.",
+            description="[MONITORING] Run a comprehensive system health check. Integrates multiple diagnostics to provide a complete overview of system status, including disk space, failed services, updates, orphan packages, and more. Only works on Arch Linux. Comprehensive check: Updates available, disk space, failed services, database freshness, orphans, and critical news.",
             inputSchema={
                 "type": "object",
                 "properties": {}
@@ -1259,14 +1310,14 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent |
     
     elif name == "check_updates_dry_run":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: check_updates_dry_run only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("check_updates_dry_run"))]
         
         result = await check_updates_dry_run()
         return [TextContent(type="text", text=json.dumps(result, indent=2))]
     
     elif name == "install_package_secure":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: install_package_secure only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("install_package_secure"))]
         
         package_name = arguments["package_name"]
         result = await install_package_secure(package_name)
@@ -1285,7 +1336,7 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent |
     # Package Removal Tools
     elif name == "remove_package":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: remove_package only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("remove_package"))]
 
         package_name = arguments["package_name"]
         remove_dependencies = arguments.get("remove_dependencies", False)
@@ -1295,7 +1346,7 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent |
 
     elif name == "remove_packages_batch":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: remove_packages_batch only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("remove_packages_batch"))]
 
         package_names = arguments["package_names"]
         remove_dependencies = arguments.get("remove_dependencies", False)
@@ -1305,14 +1356,14 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent |
     # Orphan Package Management
     elif name == "list_orphan_packages":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: list_orphan_packages only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("list_orphan_packages"))]
 
         result = await list_orphan_packages()
         return [TextContent(type="text", text=json.dumps(result, indent=2))]
 
     elif name == "remove_orphans":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: remove_orphans only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("remove_orphans"))]
 
         dry_run = arguments.get("dry_run", True)
         exclude = arguments.get("exclude", None)
@@ -1322,7 +1373,7 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent |
     # Package Ownership Tools
     elif name == "find_package_owner":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: find_package_owner only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("find_package_owner"))]
 
         file_path = arguments["file_path"]
         result = await find_package_owner(file_path)
@@ -1330,7 +1381,7 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent |
 
     elif name == "list_package_files":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: list_package_files only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("list_package_files"))]
 
         package_name = arguments["package_name"]
         filter_pattern = arguments.get("filter_pattern", None)
@@ -1339,7 +1390,7 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent |
 
     elif name == "search_package_files":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: search_package_files only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("search_package_files"))]
 
         filename_pattern = arguments["filename_pattern"]
         result = await search_package_files(filename_pattern)
@@ -1348,7 +1399,7 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent |
     # Package Verification
     elif name == "verify_package_integrity":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: verify_package_integrity only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("verify_package_integrity"))]
 
         package_name = arguments["package_name"]
         thorough = arguments.get("thorough", False)
@@ -1358,14 +1409,14 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent |
     # Package Groups
     elif name == "list_package_groups":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: list_package_groups only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("list_package_groups"))]
 
         result = await list_package_groups()
         return [TextContent(type="text", text=json.dumps(result, indent=2))]
 
     elif name == "list_group_packages":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: list_group_packages only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("list_group_packages"))]
 
         group_name = arguments["group_name"]
         result = await list_group_packages(group_name)
@@ -1374,14 +1425,14 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent |
     # Install Reason Management
     elif name == "list_explicit_packages":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: list_explicit_packages only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("list_explicit_packages"))]
 
         result = await list_explicit_packages()
         return [TextContent(type="text", text=json.dumps(result, indent=2))]
 
     elif name == "mark_as_explicit":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: mark_as_explicit only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("mark_as_explicit"))]
 
         package_name = arguments["package_name"]
         result = await mark_as_explicit(package_name)
@@ -1389,7 +1440,7 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent |
 
     elif name == "mark_as_dependency":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: mark_as_dependency only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("mark_as_dependency"))]
 
         package_name = arguments["package_name"]
         result = await mark_as_dependency(package_name)
@@ -1406,7 +1457,7 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent |
 
     elif name == "get_pacman_cache_stats":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: get_pacman_cache_stats only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("get_pacman_cache_stats"))]
 
         result = await get_pacman_cache_stats()
         return [TextContent(type="text", text=json.dumps(result, indent=2))]
@@ -1434,7 +1485,7 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent |
 
     elif name == "get_news_since_last_update":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: get_news_since_last_update only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("get_news_since_last_update"))]
         
         result = await get_news_since_last_update()
         return [TextContent(type="text", text=json.dumps(result, indent=2))]
@@ -1442,7 +1493,7 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent |
     # Transaction log tools
     elif name == "get_transaction_history":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: get_transaction_history only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("get_transaction_history"))]
         
         limit = arguments.get("limit", 50)
         transaction_type = arguments.get("transaction_type", "all")
@@ -1451,7 +1502,7 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent |
 
     elif name == "find_when_installed":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: find_when_installed only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("find_when_installed"))]
         
         package_name = arguments.get("package_name")
         if not package_name:
@@ -1462,14 +1513,14 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent |
 
     elif name == "find_failed_transactions":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: find_failed_transactions only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("find_failed_transactions"))]
         
         result = await find_failed_transactions()
         return [TextContent(type="text", text=json.dumps(result, indent=2))]
 
     elif name == "get_database_sync_history":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: get_database_sync_history only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("get_database_sync_history"))]
         
         limit = arguments.get("limit", 20)
         result = await get_database_sync_history(limit=limit)
@@ -1478,14 +1529,14 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent |
     # Mirror management tools
     elif name == "list_active_mirrors":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: list_active_mirrors only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("list_active_mirrors"))]
         
         result = await list_active_mirrors()
         return [TextContent(type="text", text=json.dumps(result, indent=2))]
 
     elif name == "test_mirror_speed":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: test_mirror_speed only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("test_mirror_speed"))]
         
         mirror_url = arguments.get("mirror_url")
         result = await test_mirror_speed(mirror_url=mirror_url)
@@ -1499,7 +1550,7 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent |
 
     elif name == "check_mirrorlist_health":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: check_mirrorlist_health only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("check_mirrorlist_health"))]
         
         result = await check_mirrorlist_health()
         return [TextContent(type="text", text=json.dumps(result, indent=2))]
@@ -1507,42 +1558,42 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent |
     # Configuration tools
     elif name == "analyze_pacman_conf":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: analyze_pacman_conf only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("analyze_pacman_conf"))]
         
         result = await analyze_pacman_conf()
         return [TextContent(type="text", text=json.dumps(result, indent=2))]
 
     elif name == "analyze_makepkg_conf":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: analyze_makepkg_conf only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("analyze_makepkg_conf"))]
         
         result = await analyze_makepkg_conf()
         return [TextContent(type="text", text=json.dumps(result, indent=2))]
 
     elif name == "check_ignored_packages":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: check_ignored_packages only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("check_ignored_packages"))]
         
         result = await check_ignored_packages()
         return [TextContent(type="text", text=json.dumps(result, indent=2))]
 
     elif name == "get_parallel_downloads_setting":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: get_parallel_downloads_setting only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("get_parallel_downloads_setting"))]
         
         result = await get_parallel_downloads_setting()
         return [TextContent(type="text", text=json.dumps(result, indent=2))]
     
     elif name == "run_system_health_check":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: run_system_health_check only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("run_system_health_check"))]
         
         result = await run_system_health_check()
         return [TextContent(type="text", text=json.dumps(result, indent=2))]
 
     elif name == "check_database_freshness":
         if not IS_ARCH:
-            return [TextContent(type="text", text="Error: check_database_freshness only available on Arch Linux systems")]
+            return [TextContent(type="text", text=create_platform_error_message("check_database_freshness"))]
         
         result = await check_database_freshness()
         return [TextContent(type="text", text=json.dumps(result, indent=2))]
@@ -1883,7 +1934,7 @@ paru -S {package_name}  # or yay -S {package_name}
                         role="assistant",
                         content=PromptMessage.TextContent(
                             type="text",
-                            text="Error: safe_system_update prompt only available on Arch Linux systems"
+                            text=create_platform_error_message("safe_system_update prompt")
                         )
                     )
                 ]
@@ -2038,7 +2089,7 @@ paru -S {package_name}  # or yay -S {package_name}
                         role="assistant",
                         content=PromptMessage.TextContent(
                             type="text",
-                            text="Error: cleanup_system prompt only available on Arch Linux systems"
+                            text=create_platform_error_message("cleanup_system prompt")
                         )
                     )
                 ]
@@ -2214,7 +2265,7 @@ Be detailed and provide specific mirror URLs and configuration commands."""
                         role="assistant",
                         content=PromptMessage.TextContent(
                             type="text",
-                            text="Error: system_health_check prompt only available on Arch Linux systems"
+                            text=create_platform_error_message("system_health_check prompt")
                         )
                     )
                 ]