Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
This server has 14 tools that follow a pattern-based dispatch architecture (action + params_json) rather than individual tool definitions. While this approach is valid, it creates significant quality issues: (1) Tool descriptions are generic and don't explain when/why to use each tool or what differentiates them; (2) Parameter schemas are severely under-specified, all tools accept only 'action' (enum of actions) and 'params_json' (generic JSON string), providing no LLM guidance on what sub-parameters are valid for each action; (3) No output schemas are documented; (4) Tool names are descriptive but the descriptions fail to explain the tool's purpose beyond 'Manage adguard home X operations'; (5) No error handling guidance is present in descriptions. The architecture delegates responsibility to runtime parameter validation rather than upfront schema clarity, which increases agent failure risk and reduces discoverability. Per-tool scores reflect these structural limitations.
All 14 tools use a generic action+params_json dispatch pattern with no per-action schema definition. LLMs receive no guidance on which sub-parameters are valid for each action, forcing runtime discovery and increasing failure rates.
Tool descriptions are generic and minimal (all follow 'Manage adguard home X operations'). Descriptions lack WHAT the tool does, WHEN to use it, any prerequisites, or key differentiators. At 31-51 characters, they fall well below the 10-1024 character guidance and provide zero LLM signal for tool selection.
Decompose the 14 dispatch-based tools into individual, verb-noun named tools. Instead of adguard_home_system with action='get_version', create get_adguard_version(), set_adguard_protection(), clear_adguard_cache() as separate tools. This matches the LLM's mental model and enables precise schema definition.
For each new tool, define explicit input schemas listing all required and optional parameters with types, constraints, and descriptions. Example: get_query_log(limit: int [1-10000]=100, offset: int >=0=0, filters: dict with keys 'domain', 'client', 'response_code').
Document output schemas for every tool. Example: get_adguard_version() returns {version: string, protocol_version: string, installed_date: ISO8601}. Agents rely on this to chain calls.
Expand tool descriptions from generic boilerplate to 100-200 character LLM-optimized descriptions. Example: 'Get the current version and protocol info of the AdGuard Home instance. Use this to verify connectivity and check feature availability before calling other tools.' Include dependencies: 'Requires DNS server to be running.'
Add per-action parameter documentation. For each 'action' enum value, document which params_json keys are required/optional. Consider moving to explicit parameters instead of JSON strings to enable schema validation.
Implement tool annotations: mark read-only tools with readOnlyHint=true, destructive operations with destructiveHint=true, and idempotent operations with idempotentHint=true. This enables agents to retry safely.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
No output schemas are documented for any tool. Agents have no visibility into what fields they will receive, complicating downstream chaining and increasing hallucination risk.
Parameter descriptions are minimal. 'Action to perform. Must be one of: [list]' does not explain what each action does or when to choose between similar actions (e.g., why call 'get_dhcp_status' vs 'get_dhcp_interfaces'). 'JSON string of parameters' provides no guidance on which keys are required, what types they accept, or how they relate.
No error handling guidance. Tools lack descriptions explaining what errors might occur, how to recover, or whether failures are retryable. Agents cannot distinguish between transient network failures and permanent validation errors.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). All tools are marked as WRITE risk but lack metadata to tell agents which operations are read-only or irreversible. Agents cannot determine safe retry boundaries.
Tool naming uses 'adguard_home_X' prefix which is redundant and wastes tokens. The verb_noun convention is not followed, tools should start with action verbs (get_*, set_*, list_*, etc.) to signal intent. E.g., 'adguard_home_system' could be split into 'get_adguard_version', 'set_adguard_protection', 'clear_adguard_cache'.
Add error handling guidance to tool descriptions. Example: 'May return 401 if authentication fails (retry with valid credentials) or 503 if the service is temporarily unavailable (safe to retry after backoff).'
Consider refactoring to use fastmcp's native tool decoration (@mcp.tool with schema) instead of dispatching through a single handler. This improves discoverability, schema clarity, and LLM reasoning.
For tools managing lists (clients, filters, rewrites), implement pagination parameters (limit, offset/cursor) and always return a total_count. Cap default results at 20-50 items to prevent context explosion.
Add validation at the tool handler level that maps action + params_json to explicit parameter schemas, returning clear errors like 'Invalid action for adguard_home_dhcp: got "update_static_lease" but expected one of: [get_dhcp_status, ...]' when validation fails.