kernelCAD

Explain Failure

why_did_this_fail

Read-onlyIdempotent

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

Name	Required	Description
`code`	No
`file`	No	Hosted server: cannot read files from your machine — pass `code`, or `project:<slug>` for a saved project.
`feature_id`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 11, 2026

removedOutput schema / properties

Removed value: -{
-  "candidateReason": {
-    "description": "Why no candidate was derivable.",
-    "type": "string"
-  },
-  "candidateStatus": {
-    "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"
-  },
-  "candidates": {
-    "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"
-  },
-  "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"
-  },
-  "repairRegion": {
-    "additionalProperties": true,
-    "description": "Minimal editable line ranges for the failure: { file, ranges: [{ startLine, endLine, role, featureId?, paramName? }] }.",
-    "type": "object"
-  },
-  "targetDiagnosticId": {
-    "description": "Id of the diagnostic the repair plan targets; pass it to repair_script.",
-    "type": "string"
-  },
-  "trace": {
-    "description": "Every captured feature joined to its call site, AST node range, diagnostics, inputs and dependents.",
-    "items": {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    "type": "array"
-  }
-}

removedOutput schema / required
```
Removed value: -[
-  "ok"
-]
```

Changed1 schema field changedSep 28, 2026

addedInput schema / properties / file / description

Added value: +"Hosted server: cannot read files from your machine — pass `code`, or `project:<slug>` for a saved project."

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.1/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real value beyond them: traversal scope ('upstream chain'), result ordering (topological, requested feature last), and the fact that per-code hints are inline so no follow-up call is strictly needed. It omits edge behavior such as what happens with an invalid feature_id or an unbounded chain, which would be the remaining valuable detail.

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?

Front-loaded with the trigger, then traversal behavior, then output ordering, then the sibling pointer. Four compact sentences, each carrying distinct information with no padding.

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?

An output schema exists, so return values needn't be spelled out, and the description still usefully adds the ordering guarantee. For a three-optional-parameter read tool this is nearly sufficient, with the only real hole being the meaning of the code/feature_id selectors.

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 only 33% — just `file` is documented — yet the description only restates the parameter list as '{ file?, code?, feature_id? }' without explaining what `code` or `feature_id` mean or which one drives the trace. The file-hosting caveat is contributed by the schema itself, not the description.

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 and resource ('trace why a feature failed', 'walk the upstream chain of a failing feature') and distinguishes itself from lookup_diagnostics by positioning that sibling as the full catalogue versus this tool's targeted upstream trace. An agent can identify the right tool without opening the schema.

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

Usage Guidelines4/5

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

Gives a clear triggering condition ('use this when you need to trace why a feature failed') and names the alternative tool with the condition that selects it ('call lookup_diagnostics for the full catalogue'). It does not exclude nearby siblings like inspect or verify, so it falls short of full when-not guidance.

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

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.