Skip to main content
Glama

sp_compare_revisions

Read-only

Compare two saved snapshots of the same designation using a paginated literal text diff to spot changed requirements.

Instructions

Paginated literal text diff of two saved snapshots of the same designation. This is not an official amendment or a legal assessment of changed requirements.

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": {
      "left_snapshot_id": "<left_snapshot_id>",
      "right_snapshot_id": "<right_snapshot_id>"
    },
    "name": "sp_compare_revisions"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNo
offsetNo
left_snapshot_idYes
right_snapshot_idYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already establish the safe read-only, closed-world, non-destructive profile, so the description adds genuine value beyond them: it discloses that the diff is literal text (not semantic or clause-aware) and that results are paginated. The explicit disclaimer that this is not an official amendment or legal assessment is a useful behavioral limit. Remaining gaps are minor: nothing about ordering, limits, or behavior on mismatched or invalid snapshot IDs.

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?

Two short sentences, front-loaded with the core operation before the caveat. Both sentences earn their place, though the disclaimer could be tightened into a clause of the first sentence rather than a standalone line, and the stray line break adds no structure.

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

Completeness3/5

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

For a simple read-only tool with no output schema, the definition covers the essentials: what is compared, that output is literal text, and that it is paginated. However, an agent still lacks information about what a paginated diff response looks like in shape (per-line changes vs. whole blocks) and about the numeric bounds of limit/offset, leaving it underspecified for a four-parameter tool.

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

Parameters3/5

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

Schema description coverage is 0%, so the description must carry parameter meaning. It partially does: "two saved snapshots of the same designation" implies the meaning and constraint of left_snapshot_id and right_snapshot_id, and "paginated" signals limit/offset. But it gives no formats, ID shapes, default values, or maximum limits, so the semantics of the four parameters remain thin relative to a 0% coverage schema.

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?

The description names a specific verb and resource: a "paginated literal text diff of two saved snapshots of the same designation." It also constrains scope with "of the same designation," so an agent knows exactly what inputs the tool expects. No sibling tool among the listed names performs a comparison, so no disambiguation is required.

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 phrase "two saved snapshots of the same designation," which tells the agent the precondition for calling it, and the second sentence rules out treating the output as a legal amendment analysis. However, there is no explicit "use this when…" statement, no mention of when to prefer this over reading both documents individually, and no guidance on what to do if the snapshots are not from the same designation.

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