Skip to main content
Looks up rows in an agent-configured CSV by column match, exact or LLM-semantic. Display name “CSV Lookup”. Off by default — bind a CSV per configured tool. Prefer batch match_criteria / source_rows over one call per line item.

​
Authentication and enablement

Configured tool: upload/bind the CSV on the agent. No OAuth.

​
Inputs

  • file_name — which bound CSV.
  • match_criteria — [{column, values}]. Values in one criterion are OR; multiple criteria are AND for exact matching only — under llm, every value fans out as an independent semantic search (column names are ignored) and criteria are never ANDed. Columns by header, letter (A), or number (1).
  • return_columns — comma-separated names, or * (default).
  • matching_strategy — exact (fast) or llm (embeddings).
  • source_rows — for LLM matching on concatenated keys; pass per-row {column, value} pairs instead of hand-concatenating.
  • filter_criteria — LLM matching only. [{column, values}] exact-match row filters applied before semantic ranking: excluded rows can never be returned as a match or candidate. Use this — not a second match_criteria entry — to constrain LLM matches by a column value, e.g. [{"column": "CustomerType", "values": ["Ship-To"]}]. Columns must be CSV header names.
    • Repeated lookup values need a unique row column. LLM matching syncs the CSV into the matching service one product per distinct identity, and that identity defaults to the lookup column’s value. When many rows share it (a payment-method code such as AUTODRAFT repeated once per vendor), only one of them survives the sync and a filter_criteria on any other row fails with “no products found”. Set Unique Row Column (unique_key) when configuring matching for the CSV — an id or similar per-row header — so every row is synced and filterable. Leaving it blank keeps the old behaviour.
  • use_learned_rules — LLM matching only; admin-bound toggle, off by default. Appends the agent’s approved learned rules (from user corrections and feedback, csv_lookup_match operation type — or all rules when the agent has inject rules in all LLM calls on) to the matching prompt. Rules are appended to the prompt, never replace it, and a rules-fetch failure degrades to matching without rules. Requires the matching service to support additional_instructions; older service versions ignore it.
  • case_sensitive — exact match only; default false.

​
Output

Matched rows (and additional_candidates for LLM). The full CSV is not embedded — for a “pick any row” review UI, use review_form with a CSV option source.

​
Limits and side effects

  • LLM matching is slower/costlier; use exact when values are canonical.
  • Read-only against the bound CSV.

​
Expected errors

  • Unknown file_name, empty criteria (except LLM + source_rows), CSV still indexing.
  • filter_criteria with matching_strategy: exact (add another match_criteria entry instead), or a filter_criteria column that is not a header of the CSV.