Issue Diagnosis Guide

When to use check_issue

Use check_issue when you’re already committed to a tool and hitting a specific problem. This isn’t for tool discovery — it’s for troubleshooting. Typical scenarios:

• Unexpected errors or degraded performance in production
• Configuration problems you can’t resolve from docs alone
• Compatibility issues when combining tools
• Hitting known limitations you weren’t aware of

Step 1: Describe the issue

Call check_issue with the tool name and a clear description of what’s going wrong. The more detail you provide, the better the diagnosis.

{
  "tool_name": "prisma",
  "issue_description": "Getting timeout errors on complex joins with PostgreSQL"
}

Step 2: Interpret the response

ToolPilot matches your issue description against known problems in the graph and returns diagnostic results with confidence scores. Here’s what a typical response looks like:

{
  "tool": "prisma",
  "matched_issues": [
    {
      "title": "Connection pool exhaustion on complex queries",
      "confidence": 0.89,
      "description": "Deeply nested includes generate multiple sequential queries that hold connections open, exhausting the default pool size of 5.",
      "solutions": [
        "Increase connection pool size: set `connection_limit` in the datasource URL to 20+",
        "Use `relationLoadStrategy: 'join'` (Prisma 5.8+) to reduce query count",
        "Break deeply nested includes into separate queries with explicit selects"
      ]
    },
    {
      "title": "Missing database indexes on join columns",
      "confidence": 0.62,
      "description": "Complex joins without proper indexes cause full table scans, leading to timeouts under load.",
      "solutions": [
        "Add composite indexes via @@index in your Prisma schema",
        "Run `EXPLAIN ANALYZE` to identify missing indexes"
      ]
    }
  ],
  "alternatives": [
    {
      "name": "drizzle",
      "reason": "Generates optimized SQL with explicit joins — avoids the N+1 pattern that causes Prisma timeouts",
      "health_tier": "healthy"
    }
  ]
}

Reading confidence scores

• 0.80 – 1.0 — High confidence. The issue is well-documented and the solutions are proven. Start here.
• 0.50 – 0.79 — Moderate confidence. The issue is a likely match but may not be exact. Worth investigating.
• Below 0.50 — Low confidence. This is a loose match — useful as a starting point but verify against your specific setup.

Step 3: Try the suggested solutions

Work through the solutions in order of the confidence score. In our Prisma example, the highest-confidence fix is to increase the connection pool size:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
  // Increase pool size from default 5 to handle complex queries
  relationMode = "prisma"
}

// Also consider adding: ?connection_limit=20&pool_timeout=30
// to your DATABASE_URL environment variable

If the first solution resolves the issue, great — remember to report_outcome so ToolPilot knows this fix worked. If it doesn’t, move to the next suggested solution.

Step 4: Consider alternatives when needed

Sometimes the issue isn’t a bug — it’s a fundamental limitation. If your Prisma queries are inherently complex and you’re spending more time working around the ORM than writing SQL, the alternatives section becomes especially relevant.

In our example, ToolPilot suggests Drizzle as an alternative because it generates explicit joins rather than sequential queries — addressing the root cause rather than patching the symptom.

Full example: Prisma timeout diagnosis

Let’s put it all together. You’re building an analytics dashboard and your Prisma queries with nested includes are timing out under load.

1. Diagnose — Call check_issue with the tool name and error details.
2. Read results — The top match (89% confidence) identifies connection pool exhaustion.
3. Apply fix — Bump connection_limit to 20 and add relationLoadStrategy: 'join'.
4. Verify — Timeouts stop. Query performance is acceptable.
5. Report — Call report_outcome with "outcome": "success" so the graph records this solution as effective.

If the fix hadn’t worked, you’d report "outcome": "failure" and evaluate the Drizzle alternative — especially if the root cause is Prisma’s query generation pattern rather than a configuration gap.

Recap

The diagnosis flow is: check_issue → read matched issues and confidence scores → apply solutions in order → consider alternatives if the problem is fundamental → report_outcome. Detailed issue descriptions dramatically improve diagnostic accuracy.