Join two spreadsheets
join_spreadsheetsUse this when the user wants to merge, match or VLOOKUP two spreadsheets on a shared ID column: "vlookup two spreadsheets", "merge two excel files by customer ID", "match orders to customers", "why are some rows not matching", "find which IDs are missing from the other file". Attach both files (CSV, TSV or .xlsx; or one workbook with two sheets) or paste both tables. Left join by default (all left rows kept); inner and full joins are available. Auto-detects the key column and explains why (override with left_key/right_key, or give a composite key). Key clean-ups are applied in order and each is counted: spaces, case, look-alike characters, Excel number formats (12345.0, 1.2345E+05), separators, leading zeros (C00123 = C123), letter prefix used by one file only; turn any off with skip_normalizations. Reports unmatched rows on both sides with a likely reason and closest key, duplicate keys with fan-out counts, and returns an Excel workbook (Merged, Unmatched left, Unmatched right, Duplicates, Summary) plus a merged CSV. Does not do mail merge (letters, labels, emails), does not compare two versions of one file cell by cell, and does not edit the original files.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "join_spreadsheets"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| left_key | No | Key column name(s) in the left file; leave out to auto-detect. Use a list for a composite key, e.g. "customer_id" or ["First Name","Last Name"]. | |
| join_type | No | left (default, like VLOOKUP): keep every left row and add matching right columns. inner: only rows found in both. full: everything from both files, matched where possible. Example: left. | |
| left_file | No | The main file whose rows you keep (CSV, TSV or .xlsx), e.g. orders.csv. A workbook with two sheets can be passed alone: sheet 1 is joined to sheet 2. | |
| right_key | No | Key column name(s) in the right file; leave out to auto-detect. Use a list for a composite key, e.g. "Customer ID" or ["First Name","Last Name"]. | |
| duplicates | No | When a key appears more than once in the right file: all (default) keeps every match and warns about the extra rows; first keeps only the first match, like VLOOKUP. Example: first. | |
| left_sheet | No | Sheet name in the left workbook, e.g. Orders. Default: the first sheet with data. | |
| left_table | No | Only when no file is attached: the left (main) table pasted as CSV or tab-separated text with a header row, e.g. "order_id,customer_id,amount\nSO-1,C123,40.00". | |
| right_file | No | The lookup file whose columns are added (CSV, TSV or .xlsx), e.g. customers.xlsx. | |
| right_sheet | No | Sheet name in the right workbook, e.g. Customers. Default: the first sheet with data (or the second sheet when both tables are in one workbook). | |
| right_table | No | Only when no file is attached: the right (lookup) table pasted as CSV or tab-separated text with a header row, e.g. "customer_id,name\nC00123,Acme Supply". | |
| left_header_row | No | Only if the headings were detected wrongly: the row number of the left file's header (counting non-blank rows in a CSV, sheet rows in Excel), e.g. 4. | |
| right_header_row | No | Only if the headings were detected wrongly: the row number of the right file's header, e.g. 3. | |
| skip_normalizations | No | Key clean-ups to turn OFF when IDs that differ only that way are really different, e.g. ["case"] for case-sensitive IDs or ["zeros"] when 0123 and 123 are different codes. Options: trim, case, unicode, excel, separators, zeros, prefix. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| left | Yes | ||
| note | Yes | ||
| match | Yes | ||
| right | Yes | ||
| excluded | Yes | ||
| warnings | Yes | ||
| downloads | Yes | ||
| join_type | Yes | ||
| duplicates | Yes | ||
| key_choice | Yes | ||
| turned_off | Yes | ||
| prefix_rule | Yes | ||
| normalizations | Yes | ||
| unmatched_preview | Yes | ||
| unmatched_reasons | Yes | ||
| would_match_if_on | Yes |