entity.resolve

Phase 0 stub

Resolve a canonical entity identity from a name, email, phone, or handle.

CategoryEntity
JSON-RPCtools/call
EndpointPOST /mcp
Sourcepackages/mcp-tools/src/tools/entity-resolve.ts

Description

Resolves a query string to a canonical entity in the knowledge graph. Default entity type is `person` (the dogfood implementation); ADR-0018 makes entity type pluggable so the same primitive serves accounts, repos, transactions, products, etc.

Input schema

FieldTypeRequiredDescription
querystringyesEntity name, email, phone, or handle to resolve.
hintstringnoOptional resolution hint (e.g. entity type).

Output shape

typescript
{
  ok: boolean;
  entity?: { id: string; canonical_name: string; kind: string };
  error?: string;
  message?: string;
}

Example call

JSON-RPC tools/call request body (omit the JSON-RPC envelope when using an SDK; the SDK adds it for you):

jsontools/call params
{
  "name": "entity.resolve",
  "arguments": { "query": "sarah@acme.com" }
}

Example response

Tool results are always wrapped as content[0].text with a stringified JSON body. The shape below is what you get back from JSON.parse(result.content[0].text):

jsonparsed result body
{
  "ok": false,
  "error": "feature_not_available",
  "message": "Entity resolve requires consolidation pipeline. Use entity.lookup for now."
}

Errors this tool can return

CodeMeaning
invalid_argumentsTool input failed Zod validation.
unauthorizedMissing or invalid bearer token.
feature_not_availableThe tool is registered but the underlying capability is not wired in this build.

See the full error catalog for resolution steps on each code, plus the standard transport-layer responses (401, 429).

Notes