io.github.JC7333/mandatia

Overview Schema Source Related Servers Discussions Admin

issue_mandate_attestation

Issue a signed attestation proving a mandate is active and unexpired so an agent can share it for offline third-party verification without registry calls.

Instructions

Issue a signed attestation of a mandate, for the agent to show a third party.

The receiver (a seller, a hospital, an insurer) verifies it offline with the registry's public key (see get_registry_public_key and amr.verify_attestation), without an account and without calling the registry. It states that the mandate exists, who granted it, the agent, the scope and structured perimeter, the expiry, the principal's own signature when there is one, and that the mandate and every mandate above it were active when the attestation was issued.

Issued only if the mandate is active and unexpired, belongs to agent_id, every parent mandate is active and unexpired, and no principal signature in the chain is invalid or stripped. The attestation expires at the earliest of: now plus the lifetime (at most settings.attestation_lifetime_seconds), the mandate's expiry, any parent's expiry. A revocation made after issuance reaches an offline receiver only when the attestation expires: ask for a fresh one for each important act.

Args: mandate_id: UUID of the mandate to attest. agent_id: Agent identifier, must match mandate.agent_id. audience: Optional receiver the attestation is addressed to (e.g. "seller:acme"). The receiver must then name this audience when verifying. lifetime_seconds: Optional shorter lifetime. It can shorten, never extend, the configured maximum. include_principal_payload: For a principal-signed mandate, also include the principal's signature and the exact bytes it signed, so the receiver can re-check it without trusting the registry. Off by default: those bytes contain the mandate metadata, which is then disclosed to the receiver.

Returns: JSON string. Success keys: attestation (compact JWS), jti, issued_at, expires_at, key_id, issuer. Denial keys: denied (true), reason, mandate_id, and refused_by for a problem higher in the delegation chain.

Input Schema

Name	Required	Description	Default
`agent_id`	Yes
`audience`	No
`mandate_id`	Yes
`lifetime_seconds`	No
`include_principal_payload`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.1Nov 7, 2026

TDQS

A4.9/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so: it states the issuance preconditions (mandate active and unexpired, belongs to agent_id, all parents active, no invalid/stripped principal signature), the expiry computation as the minimum of three bounds, and the critical revocation-visibility limitation for an offline receiver. It also discloses the privacy cost of include_principal_payload.

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 purpose sentence, then constraints, then an Args/Returns block, so scanning is easy and every section is useful. It runs long and repeats the 'active and unexpired' condition across two paragraphs, which is a minor redundancy rather than wasted space.

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?

The Returns block summarizes both success keys (attestation JWS, jti, issued_at, expires_at, key_id, issuer) and denial keys including refused_by, even though an output schema exists, and the behavioral preconditions and expiry rules are all present. Nothing an agent needs to call this correctly or interpret a denial is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate and does: it defines mandate_id and agent_id with the matching constraint, audience as an addressed receiver that must be named at verification, lifetime_seconds as shorten-only and never extending the configured maximum, and include_principal_payload's exact contents and default-off disclosure tradeoff.

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 ('Issue a signed attestation of a mandate') and immediately names its purpose ('for the agent to show a third party'), which cleanly separates it from siblings like verify_mandate, get_proof, or issue_action_token. The agent knows exactly what artifact it gets back.

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?

Explicitly frames the use case (offline verification by a seller, hospital, insurer, without an account or registry call), points to the receiver-side path (get_registry_public_key and amr.verify_attestation), and gives an operational rule: request a fresh attestation for each important act. No exclusions are left to inference.

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

Deploy Server