io.github.JC7333/mandatia

Overview Schema Source Related Servers Discussions Admin

check_action_token

Re-check an action token with the issuing registry before acting to confirm its signature, mandate, and delegation chain remain valid and are not revoked or expired.

Instructions

Re-check an action token with the registry at the moment of acting.

For the receiver of an agent's action, typically before an irreversible one (a payment, a sent document, a signed order), and always when the token carries amr_registry_check: true. The signature only proves the action was authorized when the token was issued; this check also says whether it still is now.

Checks, in order: header (EdDSA only, key of this registry), signature, iss, aud, exp, nbf; the token is one this registry issued (its jti, mandate, action hash and audience match the issued_tokens record); the action hash, if you give one; the token's age, if you set a maximum; then the mandate is still active, not revoked, not expired and held by the token's agent, and so is every mandate above it in the delegation chain. Read only: the database is opened read-only, nothing is written, and the answer is not signed. Call the registry over your own channel: never accept a check result relayed by the agent whose token it is.

Args: token: The compact JWS returned by issue_action_token. audience: Who you are; must equal the token's aud. expected_action_hash: Optional SHA-256 (64 lowercase hex) of the canonical action you are about to perform; must equal amr_action_hash. max_token_age_seconds: Optional stricter bound you set as receiver (1 to 86400): refuse a token issued more than this many seconds ago. It can only tighten the check; a token past its exp is refused whatever you set.

Returns: JSON string. Valid: {valid: true, reason: "ok", jti, mandate_id, agent_id, action_type (if sealed), registry_check_required, expires_at, checked_at}. Refused: {valid: false, reason, detail?, jti?, mandate_id?, refused_by?, checked_at}. Reasons: invalid_input, malformed, wrong_algorithm, key_mismatch, bad_signature, wrong_issuer, wrong_audience, token_expired, token_not_yet_valid, missing_claim, registry_unavailable, unknown_token, token_record_mismatch, action_mismatch, token_too_old, mandate_not_found, agent_mismatch, mandate_status_, mandate_status_revoked, mandate_expired, parent_mandate_, parent_mandate_revoked, parent_mandate_expired, parent_mandate_not_found, delegation_chain_too_deep, internal_error.

Input Schema

Name	Required	Description	Default
`token`	Yes
`audience`	Yes
`expected_action_hash`	No
`max_token_age_seconds`	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 supplied, the description carries the full burden and does: it enumerates the check sequence (header algorithm, signature, iss/aud/exp/nbf, issued_tokens record, action hash, age, mandate and full delegation chain), declares read-only database access, notes the response is unsigned, and warns about out-of-band channel trust.

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 trigger, then layered detail; the sectioning (checks / Args / Returns) is easy to scan. The long enumeration of refusal reason strings is partly redundant given an output schema exists, which keeps it from a 5.

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?

For a security-critical verification tool with four parameters and an output schema, the description supplies everything an agent needs: purpose, prerequisites (amr_registry_check), check ordering, refusal semantics, and channel-trust guidance. Nothing material 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 coverage is 0%, yet the description documents all four parameters beyond the schema: token is the compact JWS from issue_action_token, audience must equal the token's aud, expected_action_hash is a 64-char lowercase hex SHA-256 matching amr_action_hash, and max_token_age_seconds is bounded 1–86400 and can only tighten the check.

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?

Opens with a specific verb and resource plus a timing qualifier: 'Re-check an action token with the registry at the moment of acting.' This clearly separates it from issue_action_token (issuance) and verify_mandate (mandate-level verification) in the sibling list.

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?

States exactly when to call it — before an irreversible action (payment, sent document, signed order) and always when amr_registry_check is true — and explains the gap it fills versus signature-only verification. It also gives a negative instruction about never trusting a relayed result from the agent whose token it is.

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

Deploy Server