Compare two versions of a JSON row list: what was added, removed or changed, field by field.
Scored across 2 tools
The tools serve clearly different purposes: diff_rows does the actual diffing, while list_capabilities returns documentation about diff_rows. Minor overlap in that list_capabilities lacks an explicit verb_object pattern, but no confusion in practice.
Both names use snake_case and start with a verb ('diff', 'list'), so the convention is mostly consistent. The lack of a uniform action prefix is a small deviation.
Only two tools for a dataset diff server. While they cover the core operation and its metadata, the surface feels thin and could benefit from tools for validation or batch operations.
Covers the primary diff operation well, including a dry-run-style capabilities check. However, there are notable gaps: no tool to fetch or prepare rows, no pagination or large-diff handling, and no output export.
Compares two versions of the same list of JSON rows (a before and an after snapshot, such as yesterday's and today's price list, product feed or CRM export) and returns one row per difference: status added, removed or changed, the key, the old and new values, and changedFields naming exactly which fields moved. Set keyFields to the field(s) that identify a row (sku, id, email); without it rows match on full content and an edited row shows as removed plus added. Comparison is exact: "19.99" (text) and 19.99 (a number) differ, as do "Blue" and "blue " and null and a missing field; nested objects compare by value. Put always-changing fields such as timestamps in ignoreFields. The summary counts added, removed, changed and unchanged rows and warns about duplicate keys, rows missing a key, and field names found in no row. oldRows and newRows together are limited per call (list_capabilities gives the number); larger calls are refused with a message saying how to split them.
| Name | Required | Description | Default |
|---|---|---|---|
| newRows | Yes | The after snapshot: a JSON array of row objects, the same kind of rows as oldRows. At least one row. | |
| oldRows | Yes | The before snapshot: a JSON array of row objects. At least one row. Keys may differ between rows. | |
| keyFields | No | Field name(s) that uniquely identify a row on both sides, for example ["sku"] or ["country","sku"]. Strongly recommended: without it a changed row is reported as one removed row plus one added row. | |
| ignoreFields | No | Optional. Fields never compared, for example ["scrapedAt","lastChecked"], so a timestamp alone does not mark a row changed. | |
| compareFields | No | Optional. Only these fields decide whether a matched row changed. Default: every field on either row. | |
| includeUnchanged | No | Optional, default false. Set true to also return matched rows with no difference (status "unchanged"). They are always counted in the summary. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers: exact comparison semantics ("19.99" vs 19.99, "Blue" vs "blue ", null vs missing field, nested objects compared by value), the meaning of duplicate/missing-key warnings, and a hard per-call row limit on oldRows+newRows with refusal messages telling the caller how to split. This is unusually rich behavioral disclosure.
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?
Purpose and return shape are front-loaded, and nearly every clause adds operational detail (comparison rules, warnings, cap). It is a long single block rather than segmented, which slightly hurts scanability, but little is wasted.
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?
No output schema exists, and the description compensates fully by describing the returned rows, the summary counters, and the warning categories, plus the failure mode at the row cap. Nothing needed to call it correctly 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains the consequence of omitting keyFields (removed+added instead of changed), the role of ignoreFields in suppressing timestamp-only changes, and the combined row cap across the two required arrays.
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?
States a precise verb and resource: compares two versions of a JSON row list and returns one row per difference, with the returned shape (status, key, old/new values, changedFields) enumerated. It is unambiguously distinguishable from the only sibling, list_capabilities, which it also correctly references as the source of the row cap.
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?
Gives clear conditional guidance on each optional parameter: set keyFields to identify rows, otherwise rows match on full content and an edited row appears as removed plus added; put always-changing fields in ignoreFields; compareFields decides change detection. It does not state explicit when-not-to-use conditions or route to alternatives beyond list_capabilities, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the exact matching and comparison rules diff_rows uses, the shape and order of its output rows, and the maximum rows per call. Call this first if you are unsure how values are compared. 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, the description carries the full burden, and it discloses key traits: that it is free, processes no data (read-only, no side effects), and that it reveals ordering and limits for diff_rows. It does not describe output format beyond high-level content, but for a metadata/introspection tool the disclosure is strong.
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-loaded with what it returns, followed by the when-to-call guidance and a closing note on cost. Zero filler.
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?
Covers what is returned, when to call it, and that it is cheap/read-only – sufficient for an agent to decide whether to invoke it. The only minor gap is the absence of output schema, but the description enumerates the content well enough.
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?
Zero parameters, so baseline is 4. Nothing to document and no schema gaps to compensate for.
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?
States a specific verb (Returns) and enumerates exactly what resource is returned: matching/comparison rules, output row shape and order, max rows per call. It also names the sibling diff_rows whose behavior it describes, distinguishing itself clearly.
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?
Explicitly says 'Call this first if you are unsure how values are compared' – a precise when-to-use condition tied to the single sibling tool. No ambiguity about its role relative to diff_rows.
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.
diff_rowslist_capabilitiesJoin two lists of JSON rows on a key, like SQL or VLOOKUP: left, inner, full, anti joins, union.
Compare two JSON files deeply, ignoring order, to surface every difference. Get a clear, structure…
Compare two JSON files deeply without worrying about key or array order. Detect missing, extra, an…
Compare two JSON files deeply, regardless of order. Get a detailed difference report highlighting…