mcp-tool-auditor

Audit builtin MCP tool implementations against the Tool Design Manifesto. Use when reviewing builtin tools for compliance, checking context_prompt usage, validating text-first MCPResult design, or aud

SKILL.md

GitHub

MCP Tool Auditor

Audit builtin MCP tool implementations in LibrAgent for compliance with the Tool Design Manifesto.

Audit Checklist

1. context_prompt vs structured_state

  • context_prompt contains all information the AI needs (readable text, short IDs ok)
  • structured_state is NOT relied upon for AI decision-making (AI never sees it)
  • Critical IDs (full session IDs, process IDs, file paths) are in context_prompt text

2. MCPResult Text-First Design

  • Critical data appears in content (text), not just structured_content
  • Process IDs, file paths, status messages are copy-pasteable from text
  • Error details are in text output
  • structured_content is supplementary for UI rendering only

3. Canonical Naming

  • Tool names follow project conventions (no alias proliferation)
  • No redundant tools that could be consolidated

4. Session Isolation

  • No global state in builtin server implementations
  • Per-session state is scoped to session ID
  • MCPServiceProxy instances are session-specific

5. Error Handling

  • Errors return Result<MCPResult, String> consistently
  • Error messages are actionable with next steps
  • No unwrap() in production code paths

Usage

Run audits against:

  • src-tauri/src/mcp/builtin/ - All builtin MCP servers
  • src-tauri/src/mcp/ - MCP integration layer
  • docs/guides/builtin_tool_bp.md - Design standard reference

Anti-Patterns to Flag

// ❌ WRONG: Critical ID only in structured_content
let result = MCPResult {
    content: vec![text("Background process started")],
    structured_content: Some(json!({
        "process_id": "7573a69b",  // AI can't see this!
    })),
    is_error: Some(false),
};

// ✅ CORRECT: ID visible in text output
let result = MCPResult {
    content: vec![text("Background process started (ID: 7573a69b)\nUse pollProcess(\"7573a69b\") to check status")],
    structured_content: Some(json!({
        "process_id": "7573a69b",  // Redundant but useful for UI
    })),
    is_error: Some(false),
};