Skip to main content
Glama
sebastienrousseau

pain001-mcp

by sebastienrousseau
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Get example corpus provenance

get_corpus_provenance
Read-onlyIdempotent

Retrieves a corpus file's provenance sidecar to show its sources, evidence confidence, validation-ladder results, edition changes, and SHA-256, helping assess how far to trust the file.

Instructions

Return the provenance sidecar of one example file.

Use this to know how far to trust a file: the sources it was derived
from, the confidence of the evidence (``verified``, ``derived`` or
``assumed``), the validation ladder result per rung, what the builder
renamed or dropped to fit the edition, and the file's SHA-256.

Delegates to :func:`pain001.corpus.provenance`.

Args:
    scenario_id: The scenario.
    version: The message type.
    variant: The overlay id of a bank variant, else ``None``.

Returns:
    The parsed sidecar as a dict, or ``{"error": ...}`` when there is
    no such file or no corpus.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
variantNoAn overlay id for the bank variant; omit for the generic file.
versionYesThe message type, e.g. 'pain.001.001.09'.
scenario_idYesThe market scenario (from list_corpus_files).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.0.67

TDQS

A4.1/5.0
Behavior4/5

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

With readOnlyHint/idempotentHint already covering safety, the description adds real behavioral value: the confidence vocabulary (verified/derived/assumed), the per-rung validation ladder, renames/drops applied by the builder, and an explicit failure mode returning {"error": ...} when no file or corpus exists. It lacks any note on cost, pagination or caching, keeping it below the top mark.

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 one-line purpose followed by usage rationale, then Args/Returns. The Args section is somewhat redundant given the fully documented schema, but nothing is bloated and structure aids 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?

No output schema exists, so the Returns block (parsed dict or error dict) legitimately fills a gap, and annotations cover the safety profile. An agent has enough to call it correctly, though the upstream delegation to pain001.corpus.provenance adds little for the caller.

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%, so the baseline is 3. The Args block largely restates the schema ('The scenario', 'The message type') and only marginally enriches it by noting variant is the bank-variant overlay id or None.

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 ('return the provenance sidecar of one example file') and implicitly contrasts with the sibling get_corpus_file / list_corpus_files by scoping to provenance metadata only. An agent can distinguish this from the file-fetching 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 Guidelines4/5

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

'Use this to know how far to trust a file' gives a clear motivating context for when to reach for the tool. It does not explicitly name the alternative sibling (get_corpus_file) or state exclusions, so it stops short of a 5.

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

Deploy Server

Other Tools