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
strategy	object	Controls how the resolver should behave.
	mode	string
	use_embeddings	boolean
	auto_accept_threshold	number (0-1)
	interactive_below_threshold	boolean
	use_llm_fallback	boolean
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}
}

Suggested mode semantics

• quick: current fast path, take the top remote candidate.
• ranked: fetch several candidates, score them with explicit heuristics, then choose or return ambiguity.
• llm_select: fetch several candidates and let a cheap model choose.
• interactive: always return candidate choices to the client.
• hybrid: symbolic ranking first, then LLM fallback if needed.
• use_embeddings: when true, rank by lexical + embedding similarity.

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