Skip to main content
Glama

build-explain_diagnostic

Decode Exeris tooling errors, warnings, or notes by pasting diagnostic text verbatim; returns the meaning, underlying rule, and the action to take.

Instructions

Decode an error, warning or note exeris-tooling printed — an annotation-processor message, a codegen plugin goal failure or warning, a capability-graph or cap-tier Wall refusal, a missing runtime driver, a code-generation pipeline or CodegenMain line, or an exeris-initializr error. Paste the diagnostic text verbatim; returns what it means, the rule behind it, and what to do. Looks each diagnostic up by its stable EXT- identifier (ADR-095), which exeris-tooling prints from 0.9.0, and falls back to message text only for output that carries none. An identifier with no catalogue entry is named back as a catalogue gap, and a diagnostic it does not recognise is reported as not in the catalogue — never as not being an Exeris problem.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "text": "<text>"
    },
    "name": "build-explain_diagnostic"
  }
}

Input Schema

NameRequiredDescriptionDefault
textYesThe diagnostic, pasted verbatim. A whole build log is fine — every recognised diagnostic in it is returned.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.9.0

TDQS

A4.1/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does so well: it discloses the lookup key (stable EXT- identifier per ADR-095, printed from 0.9.0), the fallback to message-text matching for older output that lacks an identifier, and the two failure semantics — unknown identifier reported as a catalogue gap, unrecognised text reported as not-in-catalogue. It does not cover cost, truncation on very large logs, or whether the call is read-only, so it is not exhaustive.

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?

Front-loaded with the verb and purpose, then the long enumeration of diagnostic classes, then behaviour. The list of diagnostic categories is long but genuinely discriminating; the closing clause about never reporting something as not-an-Exeris-problem is a bit of editorial flourish but still carries semantic weight.

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?

For a single-string-input decoding tool with no output schema and no annotations, the description tells the agent what it returns (meaning, governing rule, remediation), how matching works, and how misses are reported. That is close to complete; only volume/limits on pasted logs and the precise shape of the response remain unspecified.

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

Parameters3/5

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

With one parameter at 100% schema coverage, the baseline is 3. The description's note about pasting verbatim and that whole build logs are acceptable largely restates the schema's own wording ("A whole build log is fine — every recognised diagnostic in it is returned"), adding little new meaning about format, size limits, or parsing behaviour.

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?

Opens with a specific verb and resource ("Decode an error, warning or note exeris-tooling printed") and then enumerates the concrete diagnostic classes it covers — annotation-processor messages, codegen plugin goal failures, wall refusals, missing runtime drivers, CodegenMain lines, initializr errors. That enumeration makes it clearly distinct from siblings like docs-search or docs-get_adr, which retrieve documents rather than interpret build output.

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 clear triggering context — use it when you have diagnostic text, and paste it verbatim, with the explicit allowance that a whole build log is acceptable. It does not state any exclusion or name an alternative for related needs (e.g. fetching the underlying ADR via docs-get_adr), so it stops short of full when/when-not guidance.

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