# 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 | Resolution realm, e.g. `internal`, `external`, `news`, `music`, `geography` |
| | `provenance` | string | Source of the query (e.g. user, system) |
| | `time` | string | ISO‑8601 timestamp |
| | `language` | string | BCP‑47 language tag |
| **strategy** | object | Controls how the resolver should behave. |
| | `mode` | string | One of `quick`, `ranked`, `llm_select`, `interactive`, `hybrid` |
| | `use_embeddings` | boolean | Use embedding similarity while ranking candidates |
| | `auto_accept_threshold` | number (0-1) | Confidence threshold for auto-resolving; useful for `ranked`/`hybrid` |
| | `interactive_below_threshold` | boolean | Return candidates instead of auto-picking when confidence is low |
| | `use_llm_fallback` | boolean | Allow a cheap LLM pass when symbolic ranking is inconclusive |
| **constraints** | object | Rules to apply while resolving. |
| | `deterministic` | boolean | If true, the tool must always return the same result |
| | `require_authority` | boolean | Require a trusted source |
| | `allowed_sources` | array of strings |
| | `max_candidates` | integer | Default 5 |
| | `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
```json
{
  "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.