kernelcad

Explain Failure

why_did_this_fail

Read-only

Use this when you need to trace why a feature failed. Walk the upstream chain of a failing feature. Returns the diagnostics of the requested feature plus the diagnostics of every upstream feature in topological order (the requested feature is the last entry). Per-code hints are inline on every diagnostic — call lookup_diagnostics for the full catalogue. Pass { file?, code?, feature_id? }.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`code`	No
`file`	No
`feature_id`	No

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	Yes
`chain`	No	Upstream feature diagnostics in topological order; requested feature last.
`error`	No
`trace`	No	Every captured feature joined to its call site, AST node range, diagnostics, inputs and dependents.
`errorCode`	No
`candidates`	No	Ordered concrete fixes, each with an AST-anchored patch, a predicted effect, and the geometry it was derived from.
`feature_id`	No
`repairRegion`	No	Minimal editable line ranges for the failure: { file, ranges: [{ startLine, endLine, role, featureId?, paramName? }] }.
`candidateReason`	No	Why no candidate was derivable.
`candidateStatus`	No	'no-automatic-candidate' means the region is the whole answer — no mechanical fix exists for that diagnostic kind.
`targetDiagnosticId`	No	Id of the diagnostic the repair plan targets; pass it to repair_script.

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedSep 21, 2026

addedOutput schema / properties / candidateReason

Added value: +{
+  "description": "Why no candidate was derivable.",
+  "type": "string"
+}

addedOutput schema / properties / candidateStatus

Added value: +{
+  "description": "'no-automatic-candidate' means the region is the whole answer — no mechanical fix exists for that diagnostic kind.",
+  "enum": [
+    "candidates",
+    "no-automatic-candidate"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / candidates

Added value: +{
+  "description": "Ordered concrete fixes, each with an AST-anchored patch, a predicted effect, and the geometry it was derived from.",
+  "items": {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / repairRegion

Added value: +{
+  "additionalProperties": true,
+  "description": "Minimal editable line ranges for the failure: { file, ranges: [{ startLine, endLine, role, featureId?, paramName? }] }.",
+  "type": "object"
+}

addedOutput schema / properties / targetDiagnosticId

Added value: +{
+  "description": "Id of the diagnostic the repair plan targets; pass it to repair_script.",
+  "type": "string"
+}

addedOutput schema / properties / trace

Added value: +{
+  "description": "Every captured feature joined to its call site, AST node range, diagnostics, inputs and dependents.",
+  "items": {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  "type": "array"
+}

Changed1 schema field changedJun 15, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "chain": {
+      "description": "Upstream feature diagnostics in topological order; requested feature last.",
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "error": {
+      "type": "string"
+    },
+    "errorCode": {
+      "type": "string"
+    },
+    "feature_id": {
+      "type": "string"
+    },
+    "ok": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "ok"
+  ],
+  "type": "object"
+}

First observedMay 25, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations already indicate a read-only, non-destructive operation, and the description adds valuable behavioral detail: the requested feature's diagnostics plus all upstream diagnostics are returned in topological order, with the requested feature last. It also discloses the inline per-code hint behavior and references lookup_diagnostics for the full catalogue.

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

Conciseness5/5

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

The description is compact and front-loaded, opening with use-case guidance before explaining behavior and output. Every sentence adds relevant operational detail, with no filler or repetition of the schema.

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

Completeness4/5

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

The description covers the core call flow, return ordering, and relationship to lookup_diagnostics, while the output schema covers return structure and annotations cover safety. The main gap is parameter semantics: with three undocumented optional parameters, the agent still lacks enough information to know how to uniquely identify the failing feature or whether any parameter is required.

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

Parameters2/5

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

Schema coverage is 0%, so the description must explain what file, code, and feature_id mean. It merely restates the parameter names with optional markers, adding no semantic meaning or guidance on how to choose or combine them. The agent is left to guess what 'code' or 'file' refers to in the context of failure tracing.

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?

The description clearly identifies the tool's job: tracing why a feature failed by walking its upstream chain. It names the specific resource (failing feature) and the output (diagnostics in topological order), distinguishing it from generic query/inspect tools.

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?

Starts with an explicit 'Use this when you need to trace why a feature failed', giving immediate selection guidance. It also directs the agent to lookup_diagnostics when a full catalogue of hints is needed, clarifying how this tool relates to a sibling.

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

All kernelcad tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.