Skip to main content
Glama

verify_narration

Read-onlyIdempotent

Audit an assistant draft reply clause-by-clause against in-memory tool receipts to flag fabricated action claims before sending; pass an empty receipts list when no tools ran.

Instructions

Audit an assistant draft reply clause-by-clause against in-memory turn receipts to flag fabricated tool-action claims, unlike verify_receipt_log and inspect_receipt which read on-disk JSONL logs. Call before sending a tool-using reply (pass receipts=[] when zero tools ran to reject any claimed side effects); do not use for RAG citation checking (use corroborate_sources) or log-file cryptography. Runs offline with zero network calls: ungrounded claims return is_valid=false with character offsets and retry_prompt rather than raising an error, whereas malformed receipt objects return isError=true.

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": {
      "narration": "<narration>",
      "receipts": "<receipts>"
    },
    "name": "verify_narration"
  }
}

Input Schema

NameRequiredDescriptionDefault
receiptsYesTool execution receipts for the current turn (ToolReceipt objects or AER-1 dicts; pass [] if zero tools ran).
narrationYesAssistant reply text to audit for ungrounded tool claims.
user_promptNoOptional user prompt for conversational context.

Output Schema

NameRequiredDescriptionDefault
deviceYesInference device used for supervision (e.g. CPU).
is_validYesTrue when every action claim is backed by a receipt.
latency_msYesWall-clock supervision latency in milliseconds.
retry_promptYesCorrective repair instruction when is_valid is false, else ''.
unsupported_spansYesCharacter-level spans for each ungrounded action claim.
unsupported_claimsYesVerbatim assistant clauses lacking receipt support.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.1.2
    • changedInput schema / properties / receipts / description
      Previous value: -"Tool execution receipts for the current turn (ToolReceipt objects with tool, ok, executed, args, output; pass [] if zero tools ran)."New value: +"Tool execution receipts for the current turn (ToolReceipt objects or AER-1 dicts; pass [] if zero tools ran)."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "device": {
      +      "description": "Inference device used for supervision (e.g. CPU).",
      +      "type": "string"
      +    },
      +    "is_valid": {
      +      "description": "True when every action claim is backed by a receipt.",
      +      "type": "boolean"
      +    },
      +    "latency_ms": {
      +      "description": "Wall-clock supervision latency in milliseconds.",
      +      "type": "number"
      +    },
      +    "retry_prompt": {
      +      "description": "Corrective repair instruction when is_valid is false, else ''.",
      +      "type": "string"
      +    },
      +    "unsupported_claims": {
      +      "description": "Verbatim assistant clauses lacking receipt support.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "unsupported_spans": {
      +      "description": "Character-level spans for each ungrounded action claim.",
      +      "items": {
      +        "properties": {
      +          "claimed_family": {
      +            "description": "Inferred action category of the claim.",
      +            "type": "string"
      +          },
      +          "end_char": {
      +            "description": "Zero-based exclusive end character offset.",
      +            "type": "integer"
      +          },
      +          "start_char": {
      +            "description": "Zero-based start character offset in narration.",
      +            "type": "integer"
      +          },
      +          "text": {
      +            "description": "Matched ungrounded clause text.",
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "text",
      +          "start_char",
      +          "end_char",
      +          "claimed_family"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "required": [
      +    "is_valid",
      +    "device",
      +    "latency_ms",
      +    "unsupported_claims",
      +    "unsupported_spans",
      +    "retry_prompt"
      +  ],
      +  "type": "object"
      +}
  2. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations cover the safety profile (readOnly, non-destructive, idempotent, closed-world), but the description adds real behavioral detail beyond them: zero network calls, ungrounded claims return is_valid=false with character offsets and retry_prompt instead of raising, while malformed receipts return isError=true. That failure-mode distinction is exactly what an agent needs and is nowhere 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?

Front-loaded with purpose and sibling differentiation, then usage, then exclusions, then behavior — a sensible order with no filler. The sentences are dense and stack multiple clauses in parentheses, which costs a little readability but nothing is redundant.

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

Completeness5/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 values need not be re-explained, and the description still covers the one thing the schema cannot: the difference between an invalid-narration result and an isError response. With rich annotations and full parameter coverage, nothing an agent needs to invoke this correctly is missing.

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 meaning the schema does not: receipts=[] is a deliberate signal that zero tools ran, used to reject any claimed side effects. That is a genuine semantic beyond the field's own description.

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 — audit an assistant draft reply clause-by-clause against in-memory turn receipts — and immediately contrasts with verify_receipt_log and inspect_receipt, which read on-disk JSONL logs. An agent can distinguish this from its siblings without opening any 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?

Explicit timing ("Call before sending a tool-using reply"), an edge-case instruction (pass receipts=[] when zero tools ran to reject claimed side effects), and named exclusions routing RAG citation checking to corroborate_sources and log cryptography elsewhere. When-to-use, when-not, and alternatives are all present.

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