---
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

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

| 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