Tools for agents: One-to-one keyed record join

Pair JSON records by exact string IDs with duplicate-key validation and explicit unmatched rows.

Connect with MCP

{
  "mcpServers": {
    "super-agent-tools": {
      "url": "https://app.getsupers.com/sites/agent-record-join/mcp"
    }
  }
}

Streamable HTTP · No API key · Stateless

Use this URL in any client supporting remote Streamable HTTP MCP. Calls return structured JSON; inputs are processed without persistence.

Call `join_records_by_key`

Keys name top-level fields, not JSON Pointer paths. Every row must contain its specified key as a string; numbers, null and missing keys fail explicitly. Empty string key values are allowed. Matching is case-sensitive and preserves whitespace, Unicode and leading zeros without normalization or coercion. Duplicate key values on either side fail the entire call with both row indices, even if those keys would be unmatched. Matched pairs retain separate left/right objects so colliding field names never overwrite data. Matched and left_only follow left input order; right_only follows right input order. All indices are zero-based positions in the respective original arrays. Empty arrays are allowed. This is a one-to-one full reconciliation, not a many-to-many SQL join, fuzzy matcher or mutation of the input records.

Input and output schemas

{
  "name": "join_records_by_key",
  "title": "One-to-one keyed record join",
  "description": "Pair records by exact string key values; return matched pairs and both unmatched sets. Reject missing, non-string or duplicate keys before producing any result.",
  "inputSchema": {
    "$defs": {
      "JsonValue": {}
    },
    "properties": {
      "left": {
        "items": {
          "additionalProperties": {
            "$ref": "#/$defs/JsonValue"
          },
          "type": "object"
        },
        "title": "Left",
        "type": "array"
      },
      "right": {
        "items": {
          "additionalProperties": {
            "$ref": "#/$defs/JsonValue"
          },
          "type": "object"
        },
        "title": "Right",
        "type": "array"
      },
      "left_key": {
        "title": "Left Key",
        "type": "string"
      },
      "right_key": {
        "title": "Right Key",
        "type": "string"
      }
    },
    "required": [
      "left",
      "right",
      "left_key",
      "right_key"
    ],
    "title": "join_records_by_keyArguments",
    "type": "object"
  },
  "outputSchema": {
    "additionalProperties": true,
    "title": "join_records_by_keyDictOutput",
    "type": "object"
  },
  "icons": null,
  "annotations": {
    "title": null,
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "meta": null,
  "execution": null
}

Structured result

Run the example to see the actual result.

HTTP alternative

POST https://app.getsupers.com/sites/agent-record-join/call
Content-Type: application/json

{
  "left": [
    {
      "id": "a",
      "task": "build"
    },
    {
      "id": "b",
      "task": "review"
    }
  ],
  "right": [
    {
      "task_id": "b",
      "status": "done"
    },
    {
      "task_id": "c",
      "status": "queued"
    }
  ],
  "left_key": "id",
  "right_key": "task_id"
}

The HTTP and MCP interfaces execute the same implementation. Validation errors are returned explicitly. See the tool notes above for its supported inputs and behavior.

One-to-one record reconciliation without overwriting

Your browser does not support video.

Read the explanation

The documented left records have keys a and b; the right records have b and c. Exact matching therefore pairs b once, leaving a left-only and c right-only. At eighty pixels per matched or unmatched row the bars span eighty and one hundred sixty. The pair retains distinct left and right objects so their field names cannot overwrite each other. This is full one-to-one reconciliation, not a many-to-many join or fuzzy match. The offline page lets us edit the JSON but cannot load its shared app script, and no HTTP or MCP call is made. These are contract consequences rather than an actual API result. Two rows with unique string keys are allowed by the documented input contract. Two rows with the same key reject the whole call, even if that key has no partner in the other array. Both input-count bars span one hundred sixty at eighty pixels per row, demonstrating that the same row count can have a different validation outcome. The error includes the two row indices rather than silently choosing one or multiplying matches. Empty string key values are permitted, but numbers, null, and missing keys are rejected. No type coercion or mutation of original records is intended. Consider one record on each side. String zero one does not match string one, giving zero matches, while string one matches the identical string one, giving one. At one hundred twenty pixels per match the bars span zero and one hundred twenty. Matching is case-sensitive and preserves whitespace and Unicode without normalization. Matched and left-only outputs follow left input order, and right-only follows right input order. Indices refer to zero-based original positions. The tool does not interpret keys as JSON Pointer paths or infer identity from a similar spelling, and actual production execution remains unverified here.

One-to-One Record Join & Reconciliation Mechanics

How does the tool reconcile two JSON arrays by key, and what prevents data collisions or ambiguous matches?

This tool performs strict one-to-one keyed reconciliation between two lists of JSON objects. Instead of flattening or merging records into a single dictionary where matching keys might overwrite each other, it validates that each record contains its designated key field as a string and rejects duplicates on either side. Matching pairs preserve their respective intact left and right objects along with their zero-based input indices.

The operation strictly enforces one-to-one uniqueness: duplicate keys anywhere within the left or right lists fail the entire call immediately. Keys must reside at the root level of each object (nested JSON Pointer paths are not supported), and keys must be strings without type coercion or whitespace trimming.

Try a worked example

Submitting the default JSON payload pairs left record index 1 ('id': 'b') with right record index 0 ('task_id': 'b') under 'matched'. The leftover item from left ('id': 'a') is emitted in 'left_only' at index 0, and the unmatched right item ('task_id': 'c') is emitted in 'right_only' at index 1, yielding counts of 1 matched, 1 left_only, and 1 right_only.

Key Validation & Collision Avoidance

Before performing any join comparisons, the service indexes each list. Every object must possess the named key field as an explicit string value. Missing key attributes, numerical IDs, null values, or duplicate keys within the same dataset cause a runtime ValueError that identifies the offending row index.