Skip to main content
Glama

Verify a Claim About a Change

verify_claim
Read-onlyIdempotent

Verify claims about code changes by diffing baseline and changed sessions. Returns confirmed, refuted, or indeterminate for 'no_new_api' or 'symbol_removed_unused' claims.

Instructions

Verify a structured claim about a change by diffing two analyzed sessions (baseline → changed). Supported claim types (MVP): 'no_new_api' (no types/methods were ADDED AND no method signatures changed) and 'symbol_removed_unused' (the named symbol was removed AND had no usages in the baseline's static fan-in graph). Returns a verdict of confirmed / refuted / indeterminate with a reason + evidence. NOTE THE SCOPE OF 'no_new_api': it is about ADDITIONS and SIGNATURE CHANGES, so a REMOVAL does not refute it - a change set that only deletes public API is legitimately 'confirmed'. Removals are therefore never silent: the reason states the boundary and every removal the same diff records is listed as evidence, prefixed '-'. For the removal question ask verify_claim(symbol_removed_unused), or diff_public_contract (outside the default profile's pool). Conservative in BOTH directions: what the diff cannot prove is never falsely confirmed - and never falsely refuted either, because 'was not removed' is a claim about the change that is only made once the string resolves to something this diff could report on. A name that resolves to nothing, a property/field/event/enum member (the diff models types and methods only), and the simple name of a removed type the diff had to render by its FULL name because it is ambiguous, each return 'indeterminate' naming that cause - not a confident 'was not removed'. A removed method whose only baseline callers called an interface or abstract member it implemented (find_usages' viaContract) is 'indeterminate' too: such a call ran its body only when the instance was of its type, and the reason says whether that credit was exact. Unsupported claim types return indeterminate.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
symbolNoThe symbol name the claim is about (required for symbol_removed_unused) - a bare name or the qualified Type.Member form, the same strings find_usages / impact_of_change / find_tests_for resolve. A removed type whose simple name is ambiguous solution-wide is recorded under its FULL name; pass that full name for it. A namespace-qualified TYPE name is accepted here even when nothing was removed - this tool resolves it against the baseline's declared type identities, which the fan-in tools (simple name only) do not, and the answer then names the simple name to carry on with. A dotted name no namespace declares stays unresolved rather than falling back to whatever type carries its last segment.
claimTypeYesClaim type: 'no_new_api' or 'symbol_removed_unused'.
changedSessionIdYesThe changed session_id (after the change).
baselineSessionIdYesThe baseline session_id (before the change).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior4/5

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

The annotations declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description goes further by detailing indeterminate conditions (unresolved symbols, non-type/method members, viaContract ambiguity) and the conservative-verdict policy, which is valuable behavioral context. It could specify output format details, but the return shape is described.

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

Conciseness3/5

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

The description is dense and front-loads the core purpose, but it is lengthy and includes detailed edge-case explanations that could be moved to a separate doc. The structure is logical but not optimally concise for quick scanning.

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?

Given no output schema and complex domain logic, the description covers return values (verdict + reason + evidence), supported claim types, indeterminate causes, and conservative reasoning. It is nearly complete, though it could mention session ID requirements more explicitly.

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 description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying what 'symbol' accepts (bare or qualified name, full name for ambiguous removed types) and the exact resolution semantics relative to sibling tools. This exceeds the schema's own documentation.

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 states a specific verb+resource ('Verify a structured claim about a change by diffing two analyzed sessions') and enumerates the two supported claim types with precise semantics. It clearly distinguishes its scope (additions/signature changes) from sibling tools like verify_claim(symbol_removed_unused) and diff_public_contract.

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?

Explicit when-to-use guidance is given: supported claim types are listed with their meanings, and the tool routes to alternatives for the removal question ('For the removal question ask verify_claim(symbol_removed_unused), or diff_public_contract'). It also states the boundary of 'no_new_api' to prevent misapplication.

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