dev-error-explainers

Explain a developer error

explain_error

Read-onlyIdempotent

Diagnose raw developer error messages or logs offline and return documented causes with ranked fixes for CORS, ESM/CommonJS, npm, Next.js, and Postgres issues.

Instructions

Explain a concrete developer error message or log excerpt and return its documented cause and fix.

Call it when the user pastes (or you captured from a terminal/browser console) an actual error, for example:

Node.js ESM/CommonJS errors: ERR_REQUIRE_ESM, ERR_MODULE_NOT_FOUND, "Cannot use import statement outside a module", "require is not defined in ES module scope".
npm ERESOLVE / peer-dependency conflict logs from npm install.
Next.js next build / next dev output (module not found, heap out of memory, server/client component errors, prerender failures).
Browser CORS console errors ("has been blocked by CORS policy", preflight, Access-Control-Allow-Origin).
A postgres:// or postgresql:// connection string (DATABASE_URL, Supabase pooler/direct URLs) that fails to connect.
Postgres connection errors from Node.js apps: connect ECONNREFUSED / ETIMEDOUT on 5432, getaddrinfo ENOTFOUND, Prisma P1000/P1001/P1017, "password authentication failed", "no pg_hba.conf entry", "too many clients", self-signed certificate. Pass the raw text verbatim, including the stack trace and the "Node.js vX" footer when present; do not paraphrase it.

Returns a short human-readable diagnosis (cause, why, ranked fixes with code, official source links) plus the same result as structured JSON. If nothing is recognised it answers "No known error recognised — nothing guessed"; then rely on your own reasoning.

Fully offline and deterministic: no network, no LLM, same input gives the same output. Secrets it can recognise (URL passwords, Bearer/Basic tokens, JWTs, token/key query parameters) are masked in the output.

Input Schema

TableJSON Schema

Name	Required	Description
`error`	Yes	The raw error message or log excerpt, verbatim (max ~200 KB). Include the lines around the error: stack trace, npm log block, "Node.js vX" footer, or the full connection string.
`client`	No	Optional database client for connection-string advice (default prisma).
`node_version`	No	Optional Node.js version in use (e.g. "20.10.0"), used to tailor ESM/CommonJS advice. Usually detected from the error text itself.

Output Schema

TableJSON Schema

Name	Required	Description
`tool`	Yes	Always "dev-error-explainers".
`engine`	Yes	The code path that produced the diagnosis (src/contract.js).
`matched`	Yes	True when at least one explainer recognised the input.
`results`	Yes	One Diagnosis per finding, most severe first (docs/CONTRACT.md); empty when matched is false.
`version`	Yes	Package version that produced the result.
`redactions`	Yes	Number of values masked in the output.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 30, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/openWorld=false, but the description adds material context beyond them: fully offline and deterministic, secret masking in output (URL passwords, Bearer/Basic tokens, JWTs), the exact 'No known error recognised' fallback string, and the dual human-readable + JSON return.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose, invocation trigger, and return/fallback behavior are front-loaded; the error-family bullet list is long but each bullet maps to a real supported category. Slightly verbose, but every line is load-bearing for the agent's routing decision.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return details are not strictly required, yet the description still names the two return formats and the unrecognised-error fallback. Combined with the usage examples and behavioral notes, nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3; the description goes beyond it by instructing that the raw text be passed verbatim including stack trace and Node footer, and clarifies node_version is usually auto-detected. That adds behavioral guidance the schema does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('explain a concrete developer error message or log excerpt') and scopes the output ('documented cause and fix'). Even with no siblings, the first sentence pins the tool's domain precisely enough that an agent can distinguish it from generic reasoning.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to call it ('when the user pastes ... an actual error') and enumerates the concrete error families it handles (Node ESM, npm ERESOLVE, Next.js, CORS, Postgres/Prisma). It also defines the failure path: if nothing is recognised, rely on your own reasoning.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools

explain_errorA