Response envelope

Every public resolver returns one ToolResponse. The CLI and MCP adapter serialize it to JSON; Python callers receive the Pydantic model.

Top-level fields

Field	Type	Meaning
edition	string	Concrete edition queried.
tool	string	Underlying resolver name, without the MCP dicom_ prefix.
input	object of string values	Normalized public input record for the query.
status	enum	ok, not_found, or validation_error.
result	object or null	Tool-specific result, candidate set, or structured message.
classification	object	Normativity, evidence level, and machine decidability.
parse_confidence	object	Conservative level, source, and optional notes.
refs	array	Edition-aware StandardRef records.
warnings	array of strings	Ambiguity, parser, unsupported-case, or bounded-heuristic notes.
notice	string or null	Optional notice field reserved by the public model.
trace	object	Query id, UTC resolution time, and optional source-manifest digest.

Null fields are normally omitted from CLI and MCP JSON serialization.

Status

ok

A result was constructed. Read warnings and confidence before treating it as a unique normative answer.

not_found

No matching parsed fact was found. result contains a structured message. This does not establish that the concept is absent from every part or every edition.

validation_error

The input failed deterministic validation, such as a malformed tag, UID, or VR code. Correct the input before broadening the search.

Classification

{
  "normativity": "normative",
  "evidence_level": "parsed_registry",
  "machine_decidability": "decidable"
}

Normativity values

Value	Meaning
normative	Parsed normative structure is being returned.
explanatory	Retrieved or bounded explanatory content.
derived	Result derived from stored facts.
heuristic	Bounded non-normative heuristic.
unsupported	No supported fact was established.

Evidence-level values

Value	Typical source
parsed_registry	PS3.6 data-element or UID registry.
parsed_table	IOD, module, value-term, VR, media, web, or content-mapping table.
parsed_cross_reference	SOP/IOD or Transfer Syntax enrichment and contextual graph resolution.
retrieved_text	Standard text search, retrieval, or encoding explanation.
external_comparison	Evaluation or comparison material outside normal parsed lookup.

Machine-decidability values

Value	Meaning
decidable	The supported query can be resolved mechanically from parsed facts.
partially_decidable	A bounded result is possible but context or prose can remain unresolved.
not_decidable	The fact cannot be decided mechanically by the current surface.
not_applicable	Decidability does not apply to this outcome or explanatory retrieval.

Successful text tools are explanatory, use retrieved_text, and mark machine decidability not applicable. Contextual attribute resolution is partially decidable.

Non-ok responses use unsupported normativity and not-applicable machine decidability while retaining the tool’s primary evidence-level category.

Parse confidence

{
  "level": "high",
  "source": "parsed_registry"
}

Level	Typical interpretation
high	Successful structured result without warnings.
medium	Contextual result, warning-bearing result, or a not-found lookup.
low	Retrieved text or bounded textual explanation.
unknown	Input validation failed before a fact was assessed.

notes can explain why confidence was reduced.

Parse confidence is not a probability and does not replace classification.

Standard references

Each refs entry can contain:

Field	Meaning
part	DICOM part label such as PS3.6.
section	Section identifier or number when available.
table	Table identifier when available.
anchor	Stable DocBook or HTML anchor when available.
official_url	Generated official link when available.
edition	Concrete edition for the reference.

A combined result can contain several references. Preserve all of them.

Trace

{
  "query_id": "generated-uuid",
  "resolved_at": "2026-01-01T00:00:00Z",
  "source_manifest_sha256": "manifest-digest"
}

• query_id is generated per response.
• resolved_at is an aware UTC timestamp.
• source_manifest_sha256 is included when the queried database exposes the corresponding build metadata.

Tool-specific result highlights

Resolver family	Representative result fields
Data element	tag, name, keyword, vr, vm, retired
UID	uid_value, uid_name, uid_keyword, uid_type, part, retired
VR	vr, name, class, length, padding, repertoire, binary/text fields
Transfer Syntax	UID identity, explicit-VR, endian, encapsulation, compression, retirement, notes
DICOMweb	name, resource category, HTTP method, route, constraints, status codes, media references
Media type	media type, service context, transfer-syntax constraints, directions
SR template	TID, name, extensibility, ordered rows
Context group	CID, name, extensibility, version, ordered rows
Code meaning	value, scheme, version, meaning, context groups
Graph/context	matched entities, relationship/use rows, candidates, effective type, explanation
Text	query or source location, bounded excerpt or matches

Use typed fields rather than parsing prose inside a result.

Schematic synthetic-fixture response

{
  "edition": "2026b",
  "tool": "lookup_data_element",
  "input": {
    "tag_or_keyword": "Modality"
  },
  "status": "ok",
  "result": {
    "tag": "(0008,0060)",
    "name": "Modality",
    "keyword": "Modality",
    "vr": "CS",
    "vm": "1",
    "retired": false
  },
  "classification": {
    "normativity": "normative",
    "evidence_level": "parsed_registry",
    "machine_decidability": "decidable"
  },
  "parse_confidence": {
    "level": "high",
    "source": "parsed_registry"
  },
  "refs": [
    {
      "part": "PS3.6",
      "edition": "2026b"
    }
  ],
  "warnings": [],
  "trace": {
    "query_id": "generated-uuid",
    "resolved_at": "generated-utc-timestamp",
    "source_manifest_sha256": "local-manifest-digest"
  }
}

Exact section, table, anchor, URL, timestamps, and digest depend on the local build.