io.github.JC7333/mandatia

Overview Schema Source Related Servers Discussions Admin

issue_action_token

Issues a signed action token only when a valid mandate authorizes the requested action and amount; returns denial details when scope, limits, or mandate status fail.

Instructions

Issue a signed action token IF AND ONLY IF a valid mandate authorizes it.

This is the hard-stop: no valid mandate → no token → no action possible. When the mandate (or any mandate above it in a delegation chain) has a structured perimeter, the requested action_type must be allowed, must not be forbidden, and must respect the amount limit, at every level of the chain. A cumulative ceiling (period_max_amount over period_days) on any mandate of the chain caps the total amount of the tokens issued under it and every sub-mandate below it in the rolling window, this one included; an issued token counts whether it is used or not. Every parent mandate must also still be active and unexpired. Risk classes of the chain shorten the token's lifetime; the matched class names are sealed into the token as amr_risk_classes. When one of them sets registry_check, the token carries amr_registry_check: true, and the receiver must re-check it with check_action_token at the moment of acting. Returns a JSON string with either {token, jti, expires_at, key_id} on success, or {denied: true, reason: "...", mandate_id: "..."} on denial. Perimeter denials use reason "action_out_of_scope", with "detail" and "refused_by" (the mandate whose perimeter refused the action).

Args: mandate_id: UUID of the mandate the agent invokes. agent_id: Agent identifier, must match mandate.agent_id. action: Description of the action to be authorized. audience: Where the token will be presented (runtime/platform URL or id). action_metadata_json: Optional JSON-encoded dict of additional action metadata. lifetime_override_seconds: Optional shorter token lifetime. It can only shorten: the lifetime is never above settings.token_lifetime_seconds. Whatever is asked, the token expires no later than the mandate and every mandate above it in the delegation chain, and lives no longer than the shortest risk class (risk_classes) reaching action_type in any perimeter of the chain. action_type: Dotted action type checked against the mandate perimeter, e.g. "invoice.pay" or "agent.create". Required when the mandate (or a mandate above it) has a structured perimeter; sealed into the token as amr_action_type. Under a free-text mandate it is sealed but not checked (the token then carries no amr_perimeter_digest).

Returns: JSON string. Success keys: token, jti, expires_at, key_id. Denial keys: denied (true), reason, mandate_id.

Input Schema

Name	Required	Default
`action`	Yes
`agent_id`	Yes
`audience`	Yes
`mandate_id`	Yes
`action_type`	No
`action_metadata_json`	No	{}
`lifetime_override_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.7/5.0

Behavior5/5

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

No annotations exist, so the description carries the full behavioral burden and does so thoroughly: it discloses denial semantics and reason codes ('action_out_of_scope' with detail/refused_by), cumulative ceiling accounting ('an issued token counts whether it is used or not'), lifetime shortening across the chain, and claims sealed into the token (amr_risk_classes, amr_registry_check, amr_action_type, amr_perimeter_digest). These are non-obvious consequences an agent could not infer from the schema.

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?

The hard-stop rule is front-loaded and the dense policy prose is justified for a security-critical gate. However, the body already states the return shape ('Returns a JSON string with either {token, jti, ...} or {denied: true, ...}') and the trailing 'Returns:' block repeats it verbatim in substance, which is avoidable redundancy given an output schema exists.

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 high-stakes gated-issuance tool with 7 parameters and no annotations, the description covers prerequisites, chain-wide constraints, denial cases, and lifetime bounds. Return values are backed by an output schema, so the description is complete enough for an agent to call it correctly and to interpret refusals.

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 it documents every one of the seven parameters with meaning beyond the titles: agent_id must match mandate.agent_id, action_type is dotted and required only under a structured perimeter, and lifetime_override_seconds can only shorten with explicit chain and risk-class bounds. This is exactly the compensation the low-coverage case demands.

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 action token') plus the governing condition ('IF AND ONLY IF a valid mandate authorizes it'). It is clearly separable from siblings such as check_action_token (which re-verifies a token) and verify_mandate (which validates the mandate), so an agent can choose correctly 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 strong conditional context: no valid mandate means no token and no action, and the mandate chain must be active, unexpired, and within perimeter/amount limits. It also mandates a later call to check_action_token when amr_registry_check is set, which is genuine cross-tool routing. It stops short of explicitly naming alternatives for the issuance step itself, so not 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