Skip to main content
Glama

Compare two editions

diff
Read-onlyIdempotent

What changed in a code table or document between two editions: each code added, removed or changed and each changed section, rated editorial, additive or breaking, with who rated it.

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": {
      "subject": "<subject>"
    },
    "name": "diff"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoThe newer edition's date. The newest when absent.
codeNoOne code of the table.
fromNoThe older edition's date. The edition before `to` when absent.
limitNoAt most this many changes; 50 when absent.
subjectYesA code table, such as stc, ptr or extra-services, or a document, such as pub-199 or impb-spec.
severityNoOnly changes rated this.

Output Schema

NameRequiredDescriptionDefault
toYes
fromNo
totalYes
countsYes
changesYes
subjectYes
editionsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedOutput schema / properties / changes / items / properties / carried
      Added value: +{
      +  "additionalProperties": true,
      +  "properties": {
      +    "by": {
      +      "type": "string"
      +    },
      +    "from": {
      +      "type": "string"
      +    },
      +    "on": {
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "from",
      +    "by"
      +  ],
      +  "type": "object"
      +}
  2. Changed1 schema field changed
    • changedOutput schema / properties / changes / items / properties / ratedBy / enum
      Previous value: -[
      -  "rule",
      -  "model",
      -  "pending"
      -]New value: +[
      +  "rule",
      +  "person",
      +  "model",
      +  "pending"
      +]
  3. First observed

TDQS

A4/5.0
Behavior4/5

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

Annotations already establish this as a safe, idempotent, closed-world read, so the description's job is mostly to disclose the shape and meaning of results — which it does by stating that each change is rated editorial/additive/breaking and attributed to a rater. It stops short of mentioning truncation behavior or ordering of returned changes.

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?

A single front-loaded sentence with a colon-delimited enumeration; dense but every clause carries information. Slightly heavy as one continuous sentence, but no padding or repetition.

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

Completeness4/5

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

With six parameters (one required), rich annotations, and an output schema, the description covers purpose, scope, and the meaning of the rating vocabulary, which is what an agent needs to select and call it. Missing only guidance on defaults/limits and when the diff would be empty or truncated.

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

Parameters5/5

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

Schema coverage is already 100% (every parameter, including defaults for to/from/limit, is documented). The description still adds genuine meaning by explaining the tri-level severity taxonomy (editorial, additive, breaking) that the severity filter selects on and by clarifying that results span both code-level and section-level changes.

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?

The description names a specific operation (comparing two editions of a code table or document) and enumerates exactly what it returns: codes added/removed/changed and changed sections with ratings. That distinguishes it clearly from siblings like lookup, decode, and search, though the verb 'diff/compare' is only implied by the phrasing 'What changed'.

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

Usage Guidelines3/5

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

Usage is implied by the subject matter — you use this to compare two editions — but the description never says when to choose it over read_source or search_documents, nor any prerequisite such as needing both editions to exist. No explicit exclusions or alternatives are offered.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources