These parameters and conventions apply to all V2 MCP tools.

Workflow Sessions

All tools accept an optional workflow_id parameter (UUID format).

{
  workflow_id: "550e8400-e29b-41d4-a716-446655440000"
}

Use it to:

• Group related calls — Tools called with the same workflow_id are linked for analytics and debugging
• Deterministic results — The same workflow_id returns consistent results across repeated calls
• Correlate feedback — Pass workflow_id to submit_feedback to link feedback to a specific session

Generate a UUID at the start of a workflow and pass it to every tool call in that session.

Export Formats

Three tools support large result exports: entity_resolve, entity_enrich, and entity_find.

The format parameter controls how results are returned:

Export URLs are valid for 1 hour. Use an export format for result sets larger than 100,000 records — inline responses are capped at a sample size.

// Inline sample (default)
await entity_resolve({ identifiers: [...] });

// Full export as JSONL
await entity_resolve({ identifiers: [...], format: "jsonl" });
// Returns: { export: { url: "https://...", format: "jsonl", rows: 1240000, size_bytes: 89432104, expires_at: "2025-01-16T13:00:00Z", resource_uri: "workflow://..." } }

CSV Column Mapping (lookup_columns)

entity_resolve and resolve_and_enrich_rows both accept a CSV via csv_resource_uri. When you do, you must tell the resolver which columns hold which identifier types. That mapping is the lookup_columns object — a single shape shared across V2 resolution tools so the same caller code works for both.

lookup_columns: {
  email?:    { names: string[]; hash_type?: "plaintext" | "md5" | "sha1" | "sha256" },
  phone?:    { names: string[]; hash_type?: "plaintext" | "md5" | "sha1" | "sha256" },
  address?:  { names: string[] },
  name?:     { names: string[] },
  linkedin?: { names: string[] },
  domain?:   { names: string[] }
}

At least one sub-key with a non-empty names array is required. Each sub-key is independent — provide only the identifier types your CSV has columns for.

Per-identifier rules:

Multi-column addresses — Most CRM exports (Shopify, HubSpot, Salesforce, BigCommerce) split an address across several columns. List them under address.names in street-first order so the per-row concatenation matches libpostal's canonical form:

address1, address2?, city?, region?, postcode, country?

The server joins the row's cell values with ", " in listed order before parsing. Ordering matters for match quality, not just parse success — a wrong-order list (e.g. [city, postcode, address1]) often still parses but the components map to the wrong slots, depressing match rates without raising address_parse_low_yield.

address_parse_low_yield warning — When more than 50% of address values fail libpostal parsing, the response includes a warnings[] entry with code address_parse_low_yield. This typically signals a column-ordering mistake or single-column inputs that contain only fragments without a postcode. The warning fires only on severe failures; verify column order whenever the match rate is below expectation, even when no warning is present.

Migration note — V2 originally exposed flat email_columns / phone_columns / address_columns / name_columns / linkedin_columns parameters. Those keys are now rejected with a per-key error pointing at the lookup_columns.<key> replacement. There is no compatibility shim — update callers to the nested shape.

Tracing

Every tool response includes a tool_trace_id field — a unique identifier for that specific tool invocation.

{
  "tool_trace_id": "trc_01j8x...",
  ...
}

Include this ID in support requests. It lets the Watt team look up the exact execution, inputs, and outputs for debugging.