Skip to main content
Glama

explain_match

Read-onlyIdempotent

Explains the match score between one expected and one observed record, returning signal weights for tuning scoring rules or reviewing match confidence.

Instructions

Explain the match score between one expected and one observed record.

Purpose: Scores a single transaction pair across reference, amount, date, and name signals, returning individual signal weights and an explanation even for pairs below threshold.

When to use:

  • When tuning scoring weights, tolerances, or debugging match decisions.

  • When explaining match confidence for human review or exception handling.

When NOT to use:

  • Scores one pair rather than an entire batch; use reconcile for multi-record batches.

  • Compares amounts directly rather than converting across currencies; use match_amounts_with_fx_drift with an explicit FX rate.

Behavioral transparency: Pure, deterministic, side-effect-free, read-only calculation without external dependencies.

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": {
      "expected": "<expected>",
      "observed": "<observed>"
    },
    "name": "explain_match"
  }
}

Input Schema

NameRequiredDescriptionDefault
optionsNoOptional tuning object: 'abs_tol'/'rel_tol' (amount tolerance), 'date_window_days', 'high_threshold', 'review_threshold', 'currency_strict', 'enable_one_to_many', 'max_combination'.
expectedYesOne expected record.
observedYesOne observed record.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.0.2

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is partly covered. The description still adds value by stating the calculation is pure, deterministic, and free of external dependencies, and by noting that individual signal weights are returned even for sub-threshold pairs — a behavioral detail not in the annotations.

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 labeled sections (Purpose / When to use / When NOT to use / Behavioral transparency) are front-loaded and easy to scan, with no filler sentences. The header scaffolding is slightly heavier than needed for a three-parameter tool, but each line carries substantive information.

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?

An output schema exists, so return-value detail is rightly omitted, and the description covers purpose, routing, and determinism for a single-pair diagnostic tool. The only minor gap is guidance on what shape the expected/observed records take, though the permissive additionalProperties schema suggests flexibility.

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 100% and the options object already enumerates its tuning keys ('abs_tol'/'rel_tol', 'date_window_days', 'high_threshold', etc.), so the schema carries most of the load. The description adds only the signal names (reference, amount, date, name) as orientation, without explaining how expected/observed records should be shaped.

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 opens with a specific verb and resource ('Explain the match score between one expected and one observed record') and the Purpose section clarifies it scores a single pair across reference, amount, date, and name signals. This is clearly distinguishable from the batch-oriented siblings.

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 cases (tuning weights/tolerances, debugging match decisions, human review) and explicit when-not-to-use exclusions naming the correct alternatives: 'use reconcile for multi-record batches' and 'use match_amounts_with_fx_drift with an explicit FX rate'. Both routing decisions are handed to the agent directly.

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