io.github.JC7333/mandatia

Overview Schema Source Related Servers Discussions Admin

prepare_contest_signature

Returns the exact payload a principal must sign to contest a logged action, so you can sign it and submit the contest without writing anything.

Instructions

Return the exact bytes a principal must sign to contest a logged action.

Nothing is written. The principal signs payload (UTF-8 bytes; payload_b64url is the same bytes) with its Ed25519 key, then calls contest_action with the same arguments plus principal_signature and this signed_at.

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, as it will be recorded (1 to 500 characters). response_days: Days until respond_by (1 to 365), chosen by the operator. contested_by: The contesting principal. Default: the mandate's principal. signed_at: ISO 8601 timestamp with timezone. Default: now (UTC).

Returns: JSON string with keys: payload (str), payload_b64url, signed_at, contested_by. On error: {"error": "...", "code": "..."}.

Input Schema

Name	Required	Description	Default
`reason`	Yes
`action_id`	Yes
`signed_at`	No
`mandate_id`	Yes
`contested_by`	No
`response_days`	Yes

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.1Nov 7, 2026

TDQS

A4.6/5.0

Behavior4/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 well: 'Nothing is written' states the side-effect profile, defaults are given for contested_by and signed_at, and the error shape is disclosed. It omits who is authorized to invoke it and whether the returned bytes are deterministic for a given signed_at, which matters for a signing-prep helper.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The mutation-free guarantee and the sign-then-contest workflow are front-loaded, followed by a compact Args block and a Returns block. Every line adds information an agent needs; there is no restatement of the tool name or filler.

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 six-parameter signing-preparation tool this is complete: purpose, workflow, side effects, all parameter semantics with bounds and defaults, and return keys. The Returns section partially duplicates the existing output schema, but the added error shape justifies it.

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 does: every one of the six parameters is explained, including UUID typing for mandate_id and action_id, a 1 to 500 character bound on reason, a 1 to 365 day bound on response_days, the default principal for contested_by, and the ISO 8601 with timezone requirement for 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?

The first sentence names a specific verb and resource — returning the exact bytes to sign for contesting a logged action — and immediately distinguishes this from the sibling contest_action, which is the tool that actually performs the contest. An agent can tell the two apart without opening either 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?

The description lays out the full call sequence: prepare here, sign the payload with an Ed25519 key, then call contest_action with the same arguments plus principal_signature and the returned signed_at. That is explicit routing guidance rather than inference. It stops short of stating any exclusion or precondition for when this step is unnecessary.

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

Deploy Server