mcp_design_review

/mcp_design_review

Function
Check whether all MCP tools and specs follow the unified MCP design guidelines.

Trigger Condition
When the user types /mcp_design_review.

Behavior

1. Collect design sources

   • Read MCP-related specs (e.g. specs/agent-functionality/, specs/interactive-tools/, specs/code-quality-analysis/REFACTORING_CHECKLIST.md, specs/function-tool-ai-ergonomics/ if present).
   • Read MCP implementation files (primarily mcp/src/tools/*.ts, especially functions.ts, env.ts, storage.ts, etc).

2. Evaluate design against the guidelines
   For each tool and its surrounding design, check:

   • Confirmed target shape takes precedence

     • If the current spec, task, or explicit user feedback has already locked a shape (for example “this module must converge to one queryXxx and one manageXxx”), treat deviations as failures, not optional suggestions.
     • Do not propose a locally elegant alternative if it breaks an already confirmed module boundary, naming style, or migration target.

   • Tool responsibility & naming

     • Single clear responsibility per tool (no “god” tools).
     • Names follow verbNoun style and reflect the domain (e.g. getFunctionLayers, writeFunctionLayers).

   • Query / manage tool pattern (per module)

     • Each logical domain module (functions, env, storage, database, etc.) MUST expose at most two primary tools:
       • a query tool: queryXxx – strictly read‑only, no side effects, focused on queries.
       • a manage tool: manageXxx – performs all mutations via a required action field.
     • Benchmark-critical read-only helpers are allowed only as explicit, documented exceptions when folding them into queryXxx would materially reduce agent success rate or obscure structure discovery.
     • PostgreSQL schema-qualified structure, RLS/policy visibility, and key/index inspection should be exposed through queryPgDatabase(action="schema"), not a standalone schema tool, unless a future review explicitly approves a separate capability boundary.
     • The manageXxx tool:
       • Uses a string literal union for action (e.g. "create" | "update" | "delete" | "attachLayer" | "detachLayer").
       • Uses action-specific parameters that are easy for AI to map correctly. Prefer the repository’s established style first; do not invent namespaced actions or grouped payloads unless the surrounding modules already use that pattern.
       • Treats missing/unknown action as invalid and fails safely.
     • Tool count control: avoid creating many small tools (e.g. createX, updateX, deleteX) in the same domain when a single manageXxx with multiple actions is sufficient.
     • Before approving any new fine-grained tool, explicitly check whether the capability can be merged into an existing queryXxx / manageXxx primary entrance in the same module.
     • Do NOT add a new tool when the underlying capability already exists and the only motivation is discoverability, canonical SDK naming, evaluator familiarity, prompt phrasing, or alias convenience. In those cases, prefer improving the existing tool description, examples, schema hints, action names, docs, or evaluation contract.
     • Only approve a new tool when it introduces a genuinely different capability boundary, permission surface, or irreducible input shape that would make the existing primary entrance meaningfully worse.
     • Safety & annotations: tools must clearly indicate whether they are read‑only or mutating in their metadata, and dangerous actions (delete, publish, reset, overwrite, etc.) must require explicit confirmation flags with safe defaults.

   • Cross-module consistency

     • Compare the proposed schema with neighboring modules in mcp/src/tools/, not just the local file.
     • Flag designs that introduce one-off conventions, such as namespaced action strings or special payload grouping, when other modules use flat action names and top-level fields.
     • Check whether target identifiers stay consistent across actions (functionName, layerName, triggerName) instead of mixing generic name with domain-specific names.