# 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 | e.g. *"music"*, *"geography"* |
| | `provenance` | string | Source of the query (e.g. user, system) |
| | `time` | string | ISO‑8601 timestamp |
| | `language` | string | BCP‑47 language tag |
| **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}
}
```

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