By name: debug-tool description: Debug a malfunctioning MCP tool — trace the full request lifecycle to find the issue argument-hint: "[tool-name and symptom description]"
Debug the tool issue: $ARGUMENTS
Do NOT guess. Trace systematically.
Phase 1 — Identify
- Which tool is affected?
- What is the expected behavior?
- What is the actual behavior? (error message, wrong data, empty response, crash)
Phase 2 — Trace the Request Lifecycle
Read the code for each layer and check for issues:
Layer 1: Tool Schema (src/tools/<category>/<tool>.ts)
- Is
namein the tool definition the same as the routing name inindex.ts? - Does
inputSchemamatch what the handler actually reads fromargs? - Are
requiredfields correctly listed? - Are
enumvalues complete?
Layer 2: Handler Logic
- Is
getApiKey(args)called correctly? - Are required params validated before use?
- Are type conversions correct? (
String(),Number()) - Is the params object passed to the endpoint builder correctly?
Layer 3: Endpoint URL (src/lib/endpoints.ts)
- Is the URL pattern correct? (
/api/mcp/${projectId}/...) - Are query params built correctly?
- Is
projectIdbeing destructured out before building query string? - Log the actual URL being built (add temporary
console.error)
Layer 4: HTTP Request (src/lib/request.ts)
- Is the right HTTP method used? (GET vs POST vs PATCH)
- Is
Content-Type: application/jsonbeing set? - Is the Authorization header present?
- For POST/PATCH: is the body being JSON.stringify'd?
Layer 5: Response Handling
- Does the API return
{ success, data }wrapper or direct data? - Is
response.okbeing checked? - Is the error text being read on failure?
- Is the response being JSON.stringify'd for the MCP return?
Phase 3 — Isolate
Once you've identified the suspect layer:
- Read the specific code carefully
- Check if other tools in the same category work (pattern comparison)
- If the issue is in
endpoints.ts, check the API docs or compare with working tools
Phase 4 — Fix & Verify
- Fix the root cause
- Run
npm run typecheck && npm run lint - If the tool's behavior or params changed, update
docs/TOOLS.md - Remove any temporary
console.errordebug lines
Common Issues Reference
| Symptom | First place to check |
|---|---|
| "Unknown tool" | Tool not in tools array or missing routing in index.ts |
| "Missing PAT" | getApiKey not receiving args, or env var not set |
| 404 from API | Wrong URL in endpoints.ts — check path and projectId placement |
| Empty response | API returns wrapped { data } but handler reads top-level |
| Wrong data | Query params not being passed — check buildQueryString input |
| Type error | Missing .js in import, or wrong param types |
| Crashes on startup | Circular import or top-level await issue |
Rules
- Trace layer by layer — don't skip to guessing
- Compare with a WORKING tool in the same category
- Fix the root cause, not the symptom
- Remove all debug logging before committing