Skip to main content
Glama

GAIP Witness Agent

by io.github.tjcgraham-rgb
OverviewDiscussionsAdmin

Did the service deliver?

witness_delivery
Read-onlyIdempotent

Use this when asked whether a service delivered what was agreed ("did the supplier deliver?"). Pass the terms_id from witness_register_terms and mode PUBLIC_REPLAY (GAIP fetches it) or BUYER_SUBMITTED. Returns PASS / FAIL / UNKNOWN per check, what changed since last time, and a receipt. Free, read-only, no account; inputs must be public and non-personal.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
bodyNoBUYER_SUBMITTED: the response body you received (max 32 KiB).
modeYesPUBLIC_REPLAY: GAIP fetches the public URL itself. BUYER_SUBMITTED: check a response you pass in.
terms_idYesThe terms_id returned when the terms were registered.
syntheticNoOptional: true marks a test call.
episode_idNoOptional: your own id to group related calls.
body_sha256NoBUYER_SUBMITTED: SHA-256 of the body, instead of the body.
http_statusNoBUYER_SUBMITTED: the HTTP status you received.
content_typeNoBUYER_SUBMITTED: the Content-Type you received.
research_consentNoOptional, default false. true lets this delivery check be counted, never named, in GAIP's monthly aggregate research figures.
continuity_handleNoOptional: the continuity_handle from an earlier GAIP result; links this call to your earlier ones.
data_classificationNoPUBLIC (default) or NON_PERSONAL_PUBLIC. Never send personal data.PUBLIC
independent_operator_idNoOptional: your operator id (recorded as a claim, not verified).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / research_consent
      Added value: +{
+  "default": false,
+  "description": "Optional, default false. true lets this delivery check be counted, never named, in GAIP's monthly aggregate research figures.",
+  "type": "boolean"
+}
  2. Changed11 schema fields changed
    • addedInput schema / properties / body / description
      Added value: +"BUYER_SUBMITTED: the response body you received (max 32 KiB)."
    • addedInput schema / properties / body_sha256 / description
      Added value: +"BUYER_SUBMITTED: SHA-256 of the body, instead of the body."
    • addedInput schema / properties / content_type / description
      Added value: +"BUYER_SUBMITTED: the Content-Type you received."
    • addedInput schema / properties / continuity_handle / description
      Added value: +"Optional: the continuity_handle from an earlier GAIP result; links this call to your earlier ones."
    • addedInput schema / properties / data_classification / description
      Added value: +"PUBLIC (default) or NON_PERSONAL_PUBLIC. Never send personal data."
    • addedInput schema / properties / episode_id / description
      Added value: +"Optional: your own id to group related calls."
    • addedInput schema / properties / http_status / description
      Added value: +"BUYER_SUBMITTED: the HTTP status you received."
    • addedInput schema / properties / independent_operator_id / description
      Added value: +"Optional: your operator id (recorded as a claim, not verified)."
    • addedInput schema / properties / mode / description
      Added value: +"PUBLIC_REPLAY: GAIP fetches the public URL itself. BUYER_SUBMITTED: check a response you pass in."
    • addedInput schema / properties / synthetic / description
      Added value: +"Optional: true marks a test call."
    • addedInput schema / properties / terms_id / description
      Added value: +"The terms_id returned when the terms were registered."
  3. Changed3 schema fields changed
    • addedInput schema / examples
      Added value: +[
+  {
+    "mode": "PUBLIC_REPLAY",
+    "terms_id": "<terms_id from witness_register_terms>"
+  }
+]
    • addedInput schema / properties / data_classification / default
      Added value: +"PUBLIC"
    • changedInput schema / required
      Previous value: -[
-  "data_classification",
-  "terms_id",
-  "mode"
-]New value: +[
+  "terms_id",
+  "mode"
+]
  4. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds real context beyond them: free, no account, inputs must be public and non-personal, and the shape of the result (PASS/FAIL/UNKNOWN per check, deltas since last time, a receipt). No output schema exists, so disclosing the return contents is genuinely valuable here.

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 the use case, then mode guidance, then the result summary and constraints; every clause earns its place. The embedded quoted question and stacked parenthetical slightly crowd the prose but do not waste space.

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?

For a 12-parameter tool with a nested object and no output schema, the description covers the essentials: trigger, mode choice, terms_id provenance, return shape, and privacy constraints. The optional continuity/consent/classification parameters rely on the 100%-covered schema, which is acceptable.

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. The description goes beyond the schema by stating where terms_id comes from (witness_register_terms) and clarifying the two modes' semantics, though the optional fields (continuity_handle, research_consent, data_classification, episode_id) are left entirely to the 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?

States a specific verb and resource: check whether a service delivered what was agreed, with the trigger question quoted back. It also names the sibling witness_register_terms as the source of terms_id, so the agent can tell it apart from the registration tool without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear triggering condition ('when asked whether a service delivered what was agreed') and explains which mode to pick (PUBLIC_REPLAY vs BUYER_SUBMITTED) plus the public/non-personal input constraint. It does not explicitly rule out or route to other verification siblings such as gaip_verify_supplier_claims or verify_gaip_receipt, so it stops short of full when-not guidance.

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

All GAIP Witness Agent toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources