Skip to main content
Glama

diff_reports

Compare two scans and report what a change introduced and what it resolved. Ask this rather than summarize_report when the question is whether a change made things worse: a project with inherited findings answers 'what is wrong' the same…

Instructions

Compare two scans and report what a change introduced and what it resolved. Ask this rather than summarize_report when the question is whether a change made things worse: a project with inherited findings answers 'what is wrong' the same way before and after, which says nothing about the change. Give failOnNew to learn whether a pull request gate would fail. A severity in failOnNew is compared with each new finding's rankedSeverity, not its severity.

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": {
      "basePath": "<basePath>",
      "headPath": "<headPath>"
    },
    "name": "diff_reports"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNomaximum new findings to return; defaults to 20
basePathYespath to the results.sarif from the base revision
headPathYespath to the results.sarif from the revision being proposed
failOnNewNoreport whether a new finding at or above this would fail a gate, in either vocabulary: a priority band (P1-P4), which folds in the component's declared exposure and criticality, or a severity (critical, high, medium, low), compared with each new finding's rankedSeverity

Output Schema

NameRequiredDescriptionDefault
newNo
noteNo
fixedNo
newCountYesfindings present in head and absent from base
wouldFailNotrue when a new finding meets failOnNew; only meaningful when failOnNew was given
fixedCountYesfindings present in base and absent from head
movedCountNofindings in both scans under a different component, as splitting or renaming a component reports them; neither new nor fixed, and no gate reads them
gateAppliedNothe threshold wouldFail was computed against

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.180.0
    • addedOutput schema / properties / fixed / items / properties / escalation / properties / cve
      Added value: +{
      +  "description": "the CVE the dataset matched, present where the finding's rule id names none",
      +  "type": "string"
      +}
    • addedOutput schema / properties / new / items / properties / escalation / properties / cve
      Added value: +{
      +  "description": "the CVE the dataset matched, present where the finding's rule id names none",
      +  "type": "string"
      +}
  2. Changed13 schema fields changedv0.166.3
    • changedInput schema / properties / failOnNew / description
      Previous value: -"report whether a new finding at or above this would fail a gate, in either vocabulary: a priority band (P1-P4), which folds in the component's declared exposure and criticality, or a severity (critical, high, medium, low)"New value: +"report whether a new finding at or above this would fail a gate, in either vocabulary: a priority band (P1-P4), which folds in the component's declared exposure and criticality, or a severity (critical, high, medium, low), compared with each new finding's rankedSeverity"
    • changedOutput schema / properties / fixed / items / properties / escalation / properties / from / description
      Previous value: -"the severity the scanner reported"New value: +"the severity before this signal raised it: the scanner's rating, held at severityFloor where that is present"
    • changedOutput schema / properties / fixed / items / properties / escalation / properties / to / description
      Previous value: -"the severity the finding was ranked at"New value: +"the severity this signal raised it to"
    • addedOutput schema / properties / fixed / items / properties / rankedSeverity
      Added value: +{
      +  "description": "the severity this finding was ranked at (critical, high, medium or low), after the control's minimum severity and every signal; the one the report prints and a severity gate such as --fail-on high or failOnNew judges",
      +  "type": "string"
      +}
    • changedOutput schema / properties / fixed / items / properties / severity / description
      Previous value: -"critical, high, medium or low"New value: +"the scanner's own rating (critical, high, medium or low), before the control's minimum severity or any signal moved it; a severity gate reads rankedSeverity, not this"
    • addedOutput schema / properties / fixed / items / properties / severityFloor
      Added value: +{
      +  "description": "the minimum severity this finding's control holds its findings at, present only where it raised the scanner's rating",
      +  "type": "string"
      +}
    • changedOutput schema / properties / fixed / items / required
      Previous value: -[
      -  "severity",
      -  "ruleId",
      -  "message"
      -]New value: +[
      +  "severity",
      +  "rankedSeverity",
      +  "ruleId",
      +  "message"
      +]
    • changedOutput schema / properties / new / items / properties / escalation / properties / from / description
      Previous value: -"the severity the scanner reported"New value: +"the severity before this signal raised it: the scanner's rating, held at severityFloor where that is present"
    • changedOutput schema / properties / new / items / properties / escalation / properties / to / description
      Previous value: -"the severity the finding was ranked at"New value: +"the severity this signal raised it to"
    • addedOutput schema / properties / new / items / properties / rankedSeverity
      Added value: +{
      +  "description": "the severity this finding was ranked at (critical, high, medium or low), after the control's minimum severity and every signal; the one the report prints and a severity gate such as --fail-on high or failOnNew judges",
      +  "type": "string"
      +}
    • changedOutput schema / properties / new / items / properties / severity / description
      Previous value: -"critical, high, medium or low"New value: +"the scanner's own rating (critical, high, medium or low), before the control's minimum severity or any signal moved it; a severity gate reads rankedSeverity, not this"
    • addedOutput schema / properties / new / items / properties / severityFloor
      Added value: +{
      +  "description": "the minimum severity this finding's control holds its findings at, present only where it raised the scanner's rating",
      +  "type": "string"
      +}
    • changedOutput schema / properties / new / items / required
      Previous value: -[
      -  "severity",
      -  "ruleId",
      -  "message"
      -]New value: +[
      +  "severity",
      +  "rankedSeverity",
      +  "ruleId",
      +  "message"
      +]
  3. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations, the description carries the burden and does well: it discloses the non-obvious semantic that a failOnNew severity is compared against each new finding's rankedSeverity rather than its raw severity, and explains why the diff framing matters. It does not state whether the tool is strictly read-only or whether it writes any artifacts, but the output schema covers return shape.

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?

Four tight sentences, front-loaded with the core comparison and immediately followed by the sibling routing rule and the failOnNew use case. Dense but every sentence contributes; the rankedSeverity caveat is the only part that partly duplicates the schema.

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?

Output schema exists, all four parameters are documented, and the subtle comparison semantics are called out. Complete enough to invoke correctly; only a brief note on read-only behavior or output shape would close the remaining gap.

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%, so the baseline is 3, but the description adds real meaning: failOnNew accepts either a priority band (P1-P4, folding in declared exposure and criticality) or a severity, and is meant to answer a gate question. That goes beyond the field-level schema text even though the rankedSeverity comparison is repeated there.

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 specific verb and resource ('compare two scans') plus the two-sided output ('what a change introduced and what it resolved'), which immediately separates it from summarize_report. An agent can identify the tool's job without opening the schema.

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 and the condition that selects it: use this rather than summarize_report when the question is whether a change made things worse, with a concrete reason (inherited findings make 'what is wrong' identical before and after). It also states when to pass failOnNew (to learn whether a PR gate would fail).

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