cfr-free

Overview Schema Source Related Servers Discussions Admin

Diff two eCFR issue dates

diff_issues

Read-onlyIdempotent

Compare two eCFR issue dates at provision level for Title 38 to identify which citations changed, were added, or were removed between from_date and to_date.

Instructions

Provision-level diff of Title 38 between two eCFR issue dates: which citations changed, which were added, and which were removed between from_date and to_date (both YYYY-MM-DD, both required — this tool has no default-to; for "what changed since my index was built" run cfr-free diff <from> locally, which resolves to from the index issue date). Stateless: both dates' full-title XML is fetched from eCFR and hashed per citation on the fly — no local index needed, no cache. Each citation list is capped at 100 entries; truncated: true means at least one list was cut. Identical dates or an impossible calendar date (e.g. month 13) are rejected as errors before any fetch.

Input Schema

Name	Required	Description	Default
`to_date`	Yes	eCFR issue date, YYYY-MM-DD
`from_date`	Yes	eCFR issue date, YYYY-MM-DD

Output Schema

Name	Required	Description
`added`	Yes	citations added at the to-date — capped at 100
`notice`	Yes	the limit on what the two dates mean: eCFR serves the revision in force on the requested date and does not report which issue date that is, so the dates are selectors and not a stamp of the revision served
`changed`	Yes	citations whose content changed — text or heading — capped at 100
`removed`	Yes	citations removed by the to-date — capped at 100
`truncated`	Yes	true when any citation list was cut at the 100-citation cap
`toIssueDate`	Yes
`fromIssueDate`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.2.1Oct 29, 2026

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover readOnly/idempotent/non-destructive, but the description adds genuinely new behavioral facts: stateless operation, full-title XML fetched from eCFR and hashed per citation, no cache or local index, and a 100-entry cap per list surfaced via `truncated: true`. The error-before-fetch behavior for invalid dates is also disclosed. Only gap is no indication of latency/cost implications of fetching two full-title XML documents.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose and the changed/added/removed triad, then alternative routing, then behavior, then error cases — a sensible order. The parenthetical about the local CLI is long and dense, but it carries real routing value rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, yet the description still flags the one return-value detail an agent must act on (`truncated: true` meaning a list was cut) plus the 100-entry cap. Combined with stated statelessness, fetch behavior, and error preconditions, nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and already documents both params as YYYY-MM-DD, so the baseline is 3; the description adds real value by stressing both are required with no default-to and that identical or impossible dates are rejected pre-fetch. It does not elaborate on the directional semantics beyond the names `from_date`/`to_date`.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Provision-level diff of Title 38 between two eCFR issue dates') and enumerates the three output categories (changed, added, removed). It clearly separates itself from the local CLI `cfr-free diff`, but never mentions the sibling tool `redline`, so an agent must infer how this differs from that overlapping diff tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the alternative workflow: 'for "what changed since my index was built" run `cfr-free diff <from>` locally, which resolves `to` from the index issue date.' It also states the precondition that both dates are required and that there is no default-to, plus the rejection conditions (identical dates, impossible calendar dates).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server