Skip to main content
Glama

Diff two eCFR issue dates

diff_issues
Read-onlyIdempotent

Compares Title 38 citations between two eCFR issue dates to identify which provisions changed, were added, or removed.

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). Fetched from eCFR on demand: both dates' full-title XML is hashed per citation on the fly — there is no local index for a point-in-time diff; a short-lived in-memory memo may serve a document this process fetched moments ago, and concurrent readers of the same date share one fetch. 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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "from_date": "<from_date>",
      "to_date": "<to_date>"
    },
    "name": "diff_issues"
  }
}

Input Schema

NameRequiredDescriptionDefault
to_dateYeseCFR issue date, YYYY-MM-DD
from_dateYeseCFR issue date, YYYY-MM-DD

Output Schema

NameRequiredDescriptionDefault
addedYescitations added at the to-date — capped at 100
noticeYesthe 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
changedYescitations whose content changed — text or heading — capped at 100
removedYescitations removed by the to-date — capped at 100
truncatedYestrue when any citation list was cut at the 100-citation cap
toIssueDateYes
fromIssueDateYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.2.1

TDQS

A4.6/5.0
Behavior5/5

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

Goes well past the readOnly/idempotent annotations: discloses on-demand eCFR fetching, per-citation hashing of full-title XML, absence of a local index, an in-memory memo and shared fetch for concurrent readers, a 100-entry cap per list flagged by `truncated: true`, and pre-fetch rejection of identical or impossible dates. These are exactly the cost, caching, and truncation facts an agent needs before calling.

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?

The core operation is front-loaded in the first clause, and the remaining sentences carry distinct facts (alternative path, fetch/caching model, truncation, error cases). It is dense — the memo-and-concurrent-readers detail is marginal — but nothing is redundant enough to obscure the leading definition.

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?

For a two-parameter read tool with an output schema and safety annotations, the description covers the remaining burden: fetch cost, caching, truncation signaling, and error preconditions. An agent can call it correctly without further inference.

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 both parameters are documented as YYYY-MM-DD, so the baseline is 3; the description adds real semantics beyond the schema by stressing both are required with no default and by declaring that identical dates or impossible calendar dates error out before any fetch. The parenthetical restates the date format the schema already gives.

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

Purpose5/5

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

States a precise verb+resource+scope: 'Provision-level diff of Title 38 between two eCFR issue dates', and enumerates the three outcome classes (changed, added, removed). An agent immediately knows this is a between-two-dates comparison, not a single-section fetch.

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

Usage Guidelines4/5

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

Explicitly says both dates are required with 'no default-to' and routes the 'what changed since my index was built' case to `cfr-free diff <from>` locally, which is a genuine when-not clause. It stops short of contrasting with any in-suite sibling (e.g. redline), so guidance is contextual rather than fully comparative.

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