debug-tool— agent skill

Debug the tool issue: $ARGUMENTS

Do NOT guess. Trace systematically.

Phase 1 — Identify

1. Which tool is affected?
2. What is the expected behavior?
3. 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 name in the tool definition the same as the routing name in index.ts?
• Does inputSchema match what the handler actually reads from args?
• Are required fields correctly listed?
• Are enum values 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 projectId being 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/json being 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.ok being 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:

1. Read the specific code carefully
2. Check if other tools in the same category work (pattern comparison)
3. If the issue is in endpoints.ts, check the API docs or compare with working tools

Phase 4 — Fix & Verify

1. Fix the root cause
2. Run npm run typecheck && npm run lint
3. If the tool's behavior or params changed, update docs/TOOLS.md
4. Remove any temporary console.error debug lines

Common Issues Reference

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