Join two lists of JSON rows on a key, like SQL or VLOOKUP: left, inner, full, anti joins, union.
Scored across 2 tools
join_rows performs data joins and list_capabilities retrieves server metadata; their purposes are completely distinct with no overlap. An agent can easily select the right tool based on the task.
Both tool names follow a consistent verb_noun pattern (join_rows, list_capabilities) using snake_case. This predictable convention makes the set easy to scan and understand.
The server is narrowly scoped to dataset joining, so 2 tools is not unreasonable. The single join_rows tool efficiently covers all join types and options, with list_capabilities as a necessary discovery companion, though the set is slightly thin compared to typical multi-tool servers.
join_rows supports all standard join types (left, inner, full, leftAnti, rightAnti, union) plus key matching, conflict strategies, and fan-out modes, leaving few gaps. Minor operations like previewing or validating data without joining are absent, but the core domain is well covered.
Joins two lists of JSON rows on a shared key, like a SQL join or a spreadsheet VLOOKUP, and returns the combined rows plus a summary: how many rows matched on each side, match rates, and warnings for duplicate keys, rows missing the key and key fields that exist on no row. Use it to enrich a list with fields from a lookup table (left join), keep only the overlap (inner), combine two sources into one table (full), find rows in one list that are missing from the other (leftAnti or rightAnti), or stack two same-shape lists (union). Keys match case-insensitively with whitespace trimmed by default, and the key can have a different name on each side (email on the left, contact_email on the right). Input and output rows are capped per call; a many-to-many join that would exceed the output cap is refused with the predicted row count, never truncated. Call list_capabilities for the exact limits.
| Name | Required | Description | Default |
|---|---|---|---|
| joinType | No | Which rows to keep. left (default): every left row, enriched where a match exists. inner: matched rows only. right: every right row. full: everything from both sides. leftAnti: left rows with no match on the right. rightAnti: right rows with no match on the left. union: stack both lists, no key needed. | |
| leftRows | Yes | The LEFT table: the main rows you want to keep or enrich. Each row is a JSON object; keys may differ between rows. | |
| rightRows | Yes | The RIGHT table: the lookup rows to pull matching fields from. Each row is a JSON object. | |
| keyMatching | No | normalized (default): case-insensitive, trimmed, repeated spaces collapsed, 123 matches "123". exact: values must be identical. | |
| rightFields | No | Only copy these fields from the matching right row, like choosing VLOOKUP return columns. Leave out to copy every right field. | |
| leftKeyFields | No | The field name(s) on the left rows to match on, for example ["email"], or ["firstName","lastName"] for a composite key. Required for every joinType except union. | |
| rightKeyFields | No | The matching field name(s) on the right rows, in the same order as leftKeyFields, for example ["contact_email"]. Leave out when the right rows use the same names as the left. | |
| includeJoinInfo | No | On by default: every row gets _joinStatus ("matched", "left_only", "right_only") and _matchCount. Set false for rows with only your own fields. | |
| multipleMatches | No | When one key matches several right rows. all (default): one output row per matching pair, like SQL. first: only the first matching right row, like VLOOKUP, so each left row appears once. | |
| onFieldConflict | No | When a right field has the same name as a left field. prefixRight (default): keep both, the right one renamed with rightFieldPrefix. keepLeft: ignore the right value. keepRight: overwrite the left value. | |
| rightFieldPrefix | No | Prefix for conflicting right fields when onFieldConflict is prefixRight. Default "right_", so price becomes right_price. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and meets it: default normalized matching semantics (case-insensitive, trimmed, space-collapsed, numeric coercion), duplicate/missing-key warnings, a returned match-rate summary, and a hard cap behavior where oversized many-to-many joins are refused with a predicted row count rather than truncated. These are non-obvious failure and return characteristics an agent cannot infer from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense paragraphs: purpose first, then usage scenarios, then matching semantics, caps, and a pointer to list_capabilities. No filler sentences; every clause carries operational information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter, no-annotation, no-output-schema tool, the definition covers the return shape (combined rows plus match counts, rates, and warnings) and the cap/refusal behavior. Nothing critical for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and each parameter (including four enums) is already fully documented in the schema, so the baseline is 3. The description adds some context — that keys may have different names per side and that keys can be composite — but largely restates matching behavior already covered by keyMatching and the key-field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Joins two lists of JSON rows on a shared key') and grounds it with familiar analogues (SQL join, VLOOKUP). It also names the only sibling tool, list_capabilities, for limits, so the agent can route between the two without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It enumerates concrete scenarios mapping to each join mode: enrich from a lookup table (left), keep only overlap (inner), combine sources (full), find missing rows (leftAnti/rightAnti), and stack same-shape lists (union). Explicit when-to-use guidance with named alternatives, which is exactly what the dimension asks for.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns every join type, key matching mode, conflict strategy and fan-out mode this server supports, the fields it adds to each row, and the input and output row limits per call. Free, processes no data.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden and usefully declares that the tool is free and processes no data, indicating no side effects or cost. It stops short of explicitly stating read-only status or output format, but for a zero-parameter capabilities listing this is largely sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences front-load the return content and then add the cost/behavior note. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations, so the description must convey what an agent can expect. It thoroughly enumerates the categories of returned information (modes, fields, limits) and clarifies that the call is free and data-free, making it complete for a discovery tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, and the schema is an empty object. The description correctly does not discuss parameters; the baseline for a parameterless tool is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Returns') and enumerates exactly what is returned: join types, key matching modes, conflict strategies, fan-out modes, added fields, and row limits. This makes it immediately distinguishable from the sibling 'join_rows', which performs joins rather than describing capabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Free, processes no data' implies a safe discovery call, but there is no explicit statement of when to use this versus 'join_rows' (e.g., 'call this before joining to learn supported modes'). The usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
join_rowslist_capabilitiesCompare two versions of a JSON row list: what was added, removed or changed, field by field.
GROUP BY and pivot tables for JSON rows: 11 functions, date buckets, top N, totals, messy numbers.
Clean, filter and reshape JSON rows in one call: 26 transforms, 25 filters, sort, dedupe, limit.
Dedupe, flatten and clean messy JSON rows (emails, phones, URLs, HTML) in one call, as JSON or CSV.