io.github.JC7333/mandatia

Overview Schema Source Related Servers Discussions Admin

contest_action

Records a principal's dispute against an already logged action in a dated, hash-chained journal, including the reason and an operator response deadline.

Instructions

Record that a principal contests an action an agent already performed.

Use it when an act logged with log_action was not wanted: the registry keeps a dated, chained record that the act was disputed, and when, so silence is not the only trace. One contest per action; it cannot be withdrawn or edited.

The contesting principal is the mandate's principal (default) or the principal of any mandate above it in the delegation chain. If that principal has a registered key, the contest must carry its signature: build the bytes with prepare_contest_signature, sign them, pass principal_signature and signed_at. With AMR_REQUIRE_PRINCIPAL_SIGNATURE, every contest must be signed.

response_days sets respond_by = contested_at + response_days. It is the operator's own deadline (for example the delay its counsel gives before keeping or using what was ordered could be read as ratifying it): AMR computes no legal deadline and asserts none. list_action_contests reminds it.

A contest does not undo the action, does not revoke the mandate (call revoke_mandate for that) and changes no hash already recorded.

Args: mandate_id: UUID of the mandate the action was logged under. action_id: action_id returned by log_action. reason: Why the act is contested (1 to 500 characters). Example: "order placed above the agreed quantity" response_days: Days until respond_by, 1 to 365. Example: 14 contested_by: The contesting principal. Default: the mandate's principal. principal_signature: Base64url Ed25519 signature of the contest payload. signed_at: The signed_at placed in the payload (ISO 8601 with timezone).

Returns: JSON string with keys: status ("contested"), mandate_id, action_id, action_chain_hash, contested_by, reason, response_days, contested_at, reminder ({respond_by, days_left, deadline_passed}), principal_signature ({key_id, signed_at} or null), chain_hash. On error: {"error": "...", "code": "..."} with code invalid_input, mandate_not_found, action_not_found, contester_not_in_chain, action_already_contested or a principal signature code.

Input Schema

Name	Required	Description	Default
`reason`	Yes
`action_id`	Yes
`signed_at`	No
`mandate_id`	Yes
`contested_by`	No
`response_days`	Yes
`principal_signature`	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 discloses immutability (one contest per action, cannot be withdrawn or edited), the signature requirement tied to the contester's registered key and the AMR_REQUIRE_PRINCIPAL_SIGNATURE setting, and that no legal deadline is asserted. It also clarifies side-effect boundaries, noting that no already-recorded hash changes.

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?

Long but front-loaded and sectioned (behavior, then Args, then Returns); nearly every sentence carries operational information. The Returns block partially restates what the existing output schema already provides, which is the main redundancy.

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-complexity mutation with signature gating, multi-step prerequisites, and immutability, the description covers preconditions, failure codes, defaults, and follow-up tools. An agent could call this correctly and route signing through prepare_contest_signature without consulting anything else.

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 all seven parameters: mandate_id and action_id provenance, reason length bounds (1-500) with an example, response_days range (1-365) and its computed effect on respond_by, the contested_by default, and the payload linkage between principal_signature and signed_at.

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: records that a principal contests an action already performed, scoped to an act logged with log_action. It explicitly differentiates from siblings, noting that revoke_mandate is the revocation path and list_action_contests is the reminder surface.

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?

Gives an explicit triggering condition (use when an act logged with log_action was not wanted) and names alternatives with their purposes (revoke_mandate for revocation, prepare_contest_signature for signing, list_action_contests for follow-up). It also states the exclusions: does not undo the action, does not revoke the mandate.

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

Deploy Server