biz.dfch.SpecMgr

Overview Schema Source Related Servers Discussions Admin

Get the reference diagram of one document

get_reference_diagram

Generate a PlantUML diagram of a source document's reference neighbourhood, showing artifacts as nodes, references as edges, and highlighting cycles and unresolved targets.

Instructions

Render and return the deterministic PlantUML component diagram of one source document's reference neighbourhood (the frozen rulebook specmgr://reference-graph §2–§5): one node per artifact (label = the document title, truncated to SPECMGR_DIAGRAM_MAX_TITLE, default 40), a stereotype + colour per artifact type, nodes grouped into per-domain packages, one edge per unique reference ({src} --> {dst} : refers to, the referenced item carries the incoming arrow), every edge lying on a cycle (SCC-based) drawn with the red -[#red]-> arrow, and every reference whose target cannot be resolved on disk drawn as a top-level <<UNRESOLVED>> node. type is the source document's domain (one of adr, req, uc, tsk, qa, prb, gol, rsk, dec, sop, feat, vcr, sysrs) and id the source's own identifier; depth (1..5, default 1) is the forward BFS depth; reverse=True is additive (the forward expansion to depth plus the direct incoming references to the source, direct-only on the incoming side); include_feat=False drops every FEAT node except the explicitly requested source (then every edge touching a dropped node); title overrides the diagram title (default: the source's H1; sanitized but never truncated). Guard order: id (path-injection attempt or wrong format -- for type="feat" the full feat-NNN-slug only; a bare feat-NNN is rejected, use list_feat to discover the exact id) and depth are both a ValueError raised before any filesystem access; a missing source raises the source domain's own XNotFoundError; an existing-but-broken source returns the non-raising ParseFailureResult (error/path/id, the error text byte-identical to the domain's list_<d> failed-row error for the same file (ADR 9080b37c) for the 12 whole-body domains -- time-qualified by ADR 3982712a for feat; for adr (whose list_adr carries no failed row: broken ADRs are skipped), the leg-read AdrParseError's own text). Returns PlantUML source (not a specmgr document) -- run it through specmgr plantuml-check (CLI) or the validate_plantuml tool for a validation verdict.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`id`	Yes
`type`	Yes
`depth`	No
`title`	No
`reverse`	No
`include_feat`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.36.0Oct 17, 2026

TDQS

A4.7/5.0

Behavior5/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 thoroughly: it discloses the guard order (id/depth ValueError raised before any filesystem access), the exact error taxonomy (XNotFoundError, ParseFailureResult with byte-identical error text per ADR references), and the non-raising failure path. This is unusually rich behavioral disclosure.

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 purpose is front-loaded and every clause carries information, but the whole body is a single dense wall of text laced with ADR codes and specmgr:// URI jargon. Bullet-separating the per-parameter semantics would improve scannability without losing content.

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?

For a 6-parameter, no-annotation, complex rendering tool, this is complete: it covers purpose, all parameter semantics, error behavior, guard ordering, and the post-call validation step. With an output schema present, the return contract is adequately signaled by the explicit note that the result is PlantUML source.

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

Parameters5/5

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

Schema coverage is 0%, so the description must compensate, and it does: it defines type (the source's domain with all 13 enum values implied), id (the source's own identifier, with format constraints for feat), depth (1..5 forward BFS depth), reverse (additive forward + direct-only incoming), include_feat (drops FEAT nodes and touching edges), and title (overrides H1, sanitized, never truncated).

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 opens with a specific verb and resource: 'Render and return the deterministic PlantUML component diagram of one source document's reference neighbourhood'. The scope ('one source document') implicitly distinguishes it from the sibling get_reference_diagram_all, and the output type (PlantUML source, not a specmgr document) is stated explicitly.

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?

It gives clear operational guidance: use list_feat to discover the exact feat id, and run the result through validate_plantuml or specmgr plantuml-check for a verdict. It does not, however, explicitly state when to prefer this tool over sibling diagram tools such as get_reference_diagram_all, get_uc_diagram, or get_use_case_package_diagram.

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

Deploy Server