atlas2-mcp/resolve_scheme.md

Resolve Tool Communication Blueprint

This document describes the contract for the resolve tool – the format the tool accepts as input and the structure it returns as output.

Request

The request is a JSON object with the following top‑level keys:

Key	Type	Description
subject	string	The entity to resolve. Required
context	object	Optional context to narrow the search.
	realm	string
	provenance	string
	time	string
	language	string
constraints	object	Rules to apply while resolving.
	deterministic	boolean
	require_authority	boolean
	allowed_sources	array of strings
	max_candidates	integer
	min_confidence	number (0‑1)
hints	object	Guidance for the resolver
	expected_type	string
	preferred_id	string
	aliases	array of strings
debug	object	Toggle verbose information
	include_explanations	boolean
	include_candidates	boolean

Response

The tool replies with a JSON object containing:

Key	Type	Description
status	string	One of resolved, ambiguous, not_found, error
entity	object	The resolved entity when status === "resolved"
	id, label, type, description, source, uri, attributes
confidence	number (0‑1)
candidates	array of objects	When ambiguous; each has id, label, type, source, confidence
ambiguity	object	Details if status is ambiguous
	reason, dimension
resolution_path	array of steps
	phase, action, source, note
meta	object	Request ID, timestamp, duration in ms
error	object	If status is error; contains code and message

Example

{
  "status": "resolved",
  "entity": {"id": "Q123", "label": "Mozart", "type": "Person", "description": "A Viennese composer", "source": "Wikidata"},
  "confidence": 0.97,
  "candidates": [],
  "resolution_path": [...],
  "meta": {"request_id": "abc123", "timestamp": "2026‑04‑05T15:30:00Z", "duration_ms": 42}
}

Feel free to use this file as the reference for any implementation of the resolve tool.