Neutral fairness computation for agents: two or more parties submit sealed inputs, a published deterministic algorithm runs (fair division, verifiable random selection, Shapley shares), and every party receives an identical signed certificate anyone can re-run and verify for free.
Scored across 12 tools
The tools map cleanly to distinct lifecycle steps: create, validate, commit, reveal, fetch state, and verify. The only real ambiguity is among get_certificate, get_public_certificate, and verify_certificate, but their descriptions clarify deal-based retrieval, id-based retrieval, and verification.
All tool names follow a predictable snake_case verb-first pattern like create_, get_, commit_, reveal_, and verify_. compute_commitment_tool is slightly awkward compared to compute_commitment, but it does not break the overall naming style.
With 12 tools, the set is well-scoped for the server's purpose: onboarding, algorithm discovery, deal creation, sealed commitment and reveal, entropy finalization, and certificate verification. Each tool earns its place without significant redundancy.
The core fairness-deal lifecycle is well covered, including validation before commitment and certificate verification after completion. Minor gaps like no list-deals or cancel-deal operation exist, but VOID expiration and get_deal provide workarounds.
Commit your sealed input as a hash (sealed mode). Nobody — including redeal — can see your input until all parties have committed. After the last commitment the deal opens for reveals immediately.
| Name | Required | Description | Default |
|---|---|---|---|
| deal_id | Yes | The deal id (d_...). | |
| commitment | Yes | "sha256:" + hex of sha256(JCS(your input JSON) ++ your salt bytes). Compute it locally; the server sees only this hash until everyone has committed. | |
| invite_token | Yes | The invite token for YOUR party, from create_deal's response. | |
| idempotency_key | No | Optional: retries with the same key + same arguments replay the original response. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the privacy guarantee ('Nobody — including redeal — can see your input until all parties have committed') and the temporal behavior (reveals open immediately after last commitment). It does not mention failure modes or revert behavior, but the idempotency_key parameter is covered in 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences that are front-loaded with the core action. Every sentence provides meaningful context without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the core workflow and privacy behavior well, and the schema covers parameters. However, there is no output schema, and the description does not mention what the tool returns (e.g., a receipt or confirmation), which is a minor gap for a state-changing protocol step.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter well documented (e.g., commitment format described in detail). The tool description itself adds no additional parameter semantics beyond what is already in the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Commit your sealed input as a hash (sealed mode)' with a specific verb and resource. It also distinguishes the tool from siblings by explaining the sealing behavior ('Nobody — including redeal — can see your input until all parties have committed') and the subsequent reveal timing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when this tool is used: during the commitment phase before reveals. 'After the last commitment the deal opens for reveals immediately' implies the sequencing relative to other tools like compute_commitment_tool and reveal_input. However, it does not explicitly name alternatives or provide 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute a commitment string for (input, salt): sha256(JCS(input) ++ salt_bytes), prefixed 'sha256:'. Convenience only — the rule is public and you can compute it yourself.
| Name | Required | Description | Default |
|---|---|---|---|
| salt | Yes | Your hex salt (even length, e.g. 32+ random bytes hex-encoded). Keep it secret until reveal. | |
| input | Yes | Your algorithm input (any JSON value). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels: it discloses the exact algorithm, output format ('prefixed 'sha256:''), and states the rule is public. It also notes it's a pure convenience wrapper with no hidden side effects, making behavior fully transparent for a deterministic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste. The formula is front-loaded, and the 'Convenience only' note adds essential context without repetition. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a pure function with two parameters, the description is complete. It provides the algorithm, input types, output format, and context on when to use it. No output schema exists, but the formula fully specifies the return value. Sibling tools don't create ambiguity that requires more detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for both parameters (100% coverage). The description adds meaning by explaining how each parameter is used in the formula: input is canonicalized via JCS and salt is converted to bytes. This goes beyond the schema's simple definitions and clarifies processing semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool computes a commitment string via a concrete formula ('sha256(JCS(input) ++ salt_bytes), prefixed 'sha256:''). This specific verb+resource definition distinguishes it from siblings like commit_input, which likely performs a different action, and the phrase 'Convenience only' further clarifies its scoped role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Convenience only — the rule is public and you can compute it yourself,' which tells the agent this tool is optional and a manual alternative exists. However, it does not explicitly name any alternative tools (e.g., commit_input) or contrast with them, so the guidance is clear but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a fairness deal. You are party 0 (initiator). Returns a deal id and one invite token per party — give each counterparty their own token. Sealed mode: everyone commits a hash, then reveals; certificate is issued automatically when the deal computes or goes VOID.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | "sealed" (default, commit/reveal) or "open" (single round trip, low stakes). | |
| api_key | Yes | Your redeal API key (get one free with create_key — no signup form). | |
| algorithm | Yes | Algorithm id from list_algorithms: "split.v1" (fixed 1,000-point budget) | "random.v1" | "shapley.v1" | "auction.v1". | |
| retention | No | "standard" (inputs retained encrypted) or "purge" (destroyed 7 days after certification). | |
| supersedes | No | Optional: certificate id (c_<16 hex>) this deal's certificate replaces (re-draw after VOID etc.). | |
| terms_hash | No | Optional: "sha256:<hex>" of the deal's terms (echoed into the certificate; we never see the terms). | |
| visibility | No | Optional: "public" (default — anyone can fetch the certificate at its id) or "parties" (only you and your invite-token holders). Certificates never contain inputs, only the outcome; choose "parties" when the outcome itself is sensitive. | |
| external_ref | No | Optional: your own identifier for this deal, e.g. "campaign-4821" (echoed into the certificate). | |
| party_labels | Yes | One label per party, e.g. ["alice", "bob"] — or objects {"label", "weight"?, "statement_hash"?} (weight defaults to 1; statement_hash is "sha256:<hex>" of a declaration you want bound into the certificate). Party 0 is you (the initiator). Labels go on the public certificate permanently: use nicknames, never real names or emails. | |
| commit_deadline | Yes | Commit deadline as unix seconds UTC. Missed → deal EXPIRES (no certificate). | |
| idempotency_key | No | Optional: retries with the same key + same arguments replay the original response. | |
| reveal_deadline | Yes | Reveal deadline as unix seconds UTC (after commit_deadline). Missed → deal goes VOID and a non-participation certificate names whoever didn't reveal. | |
| algorithm_params | No | Algorithm-specific params from list_algorithms. split.v1: {"items": [...]}; random.v1: {"drand_round": N}; shapley.v1: {"coalition_values": {...}}; auction.v1: {"item": "...", "unit": "GBP", "reserve": N}. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool returns deal ids and tokens, explains sealed mode behavior (commit/reveal), and notes automatic certificate issuance on compute or VOID. It does not detail costs or side effects, but it provides sufficient behavioral context for the core operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core purpose. Every sentence adds value: purpose, output, and mode workflow. It is appropriately sized for the complexity, avoiding redundancy with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex 13-parameter tool and no output schema, the description covers the essential workflow: creation, tokens, sealed mode, and automatic certificate. It does not repeat parameter details (handled by schema) and provides enough context for an agent to understand the tool's role in the broader process. Minor gaps like prerequisites (API key) are covered in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with detailed parameter descriptions, so the baseline is 3. The description adds minimal per-parameter meaning beyond the schema, only briefly mentioning sealed mode tied to the mode parameter. It does not elaborate on param formats or inter-relations, leaving the schema to do the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Create a fairness deal' with specific details about parties, tokens, and mode. It clearly distinguishes this as the deal-creation tool among siblings like commit_input and get_deal, with a specific verb+resource and a clear outline of expected actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does and the workflow (create deal, then commit/reveal), but it does not explicitly mention when not to use it or alternatives. It lacks explicit 'when to use' versus 'when to use another tool' guidance, but the purpose is clear enough that usage is inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a free redeal API key. No signup, no email — this is the entire onboarding. The key is shown once; store it. Use it as api_key in create_deal.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses a critical trait: the key is shown exactly once, so it must be stored. It also notes there is no signup/email, conveying simplicity. It does not mention expiration or regeneration, but enough context is given for a free key tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, with the first sentence stating the primary action. Each subsequent sentence adds essential information (key shown once, how to use it) without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with no output schema, the description is remarkably complete. It covers purpose, the onboarding context, a crucial warning (store the key), and integration with create_deal. Nothing critical is missing for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema provides full coverage by default. The description adds no parameter details (none exist) but clarifies that the key is displayed once and used as api_key in create_deal, which explains the output semantics without needing to discuss inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool obtains a free API key with the specific phrase 'Get a free redeal API key.' It distinguishes itself from sibling tools by framing this as the entire onboarding step, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use this tool: it is the entire onboarding process, with no signup or email required. It also tells how to apply the result ('Use it as api_key in create_deal'), providing clear context relative to the sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the signed fairness certificate for a finished deal (state CERTIFIED). Includes the labelled signature (es256 or ed25519) and transparency-log inclusion proof. Verify it with verify_certificate.
| Name | Required | Description | Default |
|---|---|---|---|
| deal_id | Yes | The deal id (d_...). | |
| credential | Yes | Your API key (initiator) or any party's invite token for this deal. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It clearly indicates a read operation ('Fetch'), specifies the required state precondition, and describes the returned contents (signature and proof). It does not mention error conditions or side effects, but 'Fetch' strongly implies non-mutating behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action, and includes relevant details (certificate contents, verification pointer) without any unnecessary fluff. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 params, fully described in schema), and the description covers the output contents and precondition. It lacks details about error cases or authentication specifics, but for a straightforward fetch operation, the context is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage for both parameters ('deal_id' and 'credential'). The description does not add extra context about parameter usage beyond what the schema provides, so the baseline of 3 is appropriate for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and clearly identifies the resource ('signed fairness certificate') with a condition ('for a finished deal (state CERTIFIED)'). It distinguishes itself from the sibling tool 'verify_certificate' by mentioning that verification is done separately, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use the tool (for deals in state CERTIFIED) and points to an alternative for verification ('Verify it with verify_certificate'). This gives clear context, though it does not explicitly mention when not to use other deal-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a deal's public state: protocol state (OPEN/COMMITTING/REVEALING/CERTIFIED/VOID/EXPIRED), who has committed/revealed, deadlines, result, and certificate_id once issued. Inputs of other parties are never exposed.
| Name | Required | Description | Default |
|---|---|---|---|
| deal_id | Yes | The deal id (d_...). | |
| credential | Yes | Your API key (initiator) or any party's invite token for this deal. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a key behavioral trait: 'Inputs of other parties are never exposed' and implies read-only behavior via 'Read'. It lacks explicit statements about side effects or error cases, but the privacy guarantee adds strong context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, and every phrase contributes (state list, privacy note). There is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with only 2 parameters and no output schema, the description fully covers what is returned (state, participants, deadlines, result, certificate_id) and includes a privacy guarantee. It is sufficiently complete for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific meaning beyond the schema (deal_id, credential); it focuses on output content rather than parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Read a deal's public state', using a specific verb and resource. It enumerates the concrete data returned (protocol state, who committed/revealed, deadlines, result, certificate_id), clearly distinguishing it from mutating sibling tools like commit_input and reveal_input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for reading a deal's public state, providing context for when to use it. However, it does not explicitly mention alternatives or exclusions, e.g., when to prefer get_certificate over get_deal, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finish a random.v1 deal once every party has revealed: redeal fetches the deal's pre-declared drand round from the public League of Entropy beacon (fixed at creation, publicly cross-checkable), computes the draw, and issues the certificate. Call this after the last reveal_input; the deal rests in REVEALING until you do. Idempotent — safe to retry.
| Name | Required | Description | Default |
|---|---|---|---|
| deal_id | Yes | The deal id (d_...). | |
| credential | Yes | Your API key (initiator) or any party's invite token for this deal. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: sourcing from the public League of Entropy beacon, the state transition from REVEALING to finalized, and idempotency. This goes beyond a simple 'finishes the deal' by explaining underlying mechanics and side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three focused sentences, each contributing unique value: purpose/process, usage timing, and idempotency. Front-loaded with the primary action, no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-param tool with no output schema, the description covers the essential context: what it does, when to invoke it, the state change, and retry safety. The workflow relationship with reveal_input is clear, making the tool's role in the overall process complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already well-documented in the schema. The description does not add significant parameter-specific semantics, only implicit context (e.g., 'after the last reveal_input' relates to deal_id). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's role: 'Finish a random.v1 deal' and details the exact process (fetching drand round, computing draw, issuing certificate). It distinguishes itself from sibling tools like reveal_input and get_certificate by explicitly tying its execution to post-reveal finalization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'Call this after the last reveal_input' and explains the deal remains in REVEALING until called. The idempotency note ('safe to retry') also gives practical usage direction. The context of prerequisites and state transition is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a certificate's full JSON (outcome included) by id. Works for public deals (the default). Parties-only deals and unknown ids both return NOT_FOUND. To re-verify the computation itself, use verify_certificate (checks) or the CLI re-runner with the parties' inputs.
| Name | Required | Description | Default |
|---|---|---|---|
| cert_id | Yes | The certificate id (c_...). Verification is free and always will be. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses error behavior (parties-only and unknown ids return NOT_FOUND) and scope (works for public deals). It also notes verification is free and always will be, adding useful context beyond a simple fetch.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the purpose, then cover error cases and alternatives. No irrelevant details or repetition, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple one-parameter tool with no output schema, the description covers purpose, scope, error handling, and alternatives. It sufficiently explains the return format ('full JSON') and constraints, making it complete for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with cert_id already described. The tool description adds only trivial 'by id' context and doesn't provide additional semantics beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a certificate's full JSON (outcome included) by id, specifying it works for public deals. It differentiates from siblings by explicitly contrasting with verify_certificate for re-verification and mentioning parties-only deals return NOT_FOUND.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: use for public deals, and when to use verify_certificate or CLI re-runner instead for re-verification. It also implies not to use for parties-only deals due to NOT_FOUND, providing clear when/when-not context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List redeal's algorithms (split.v1 fixed-budget fair division, random.v1 verifiable random selection, shapley.v1 Shapley shares, auction.v1 sealed-bid second-price auctions) with their input contracts and the published test vectors (served inline — the same fixtures the engine test suite runs). Read this before creating a deal.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains what the tool lists (algorithms, input contracts, test vectors) and notes the test vectors are served inline and are the same fixtures the engine test suite runs. This gives useful behavioral context. A small gap is not explicitly stating it is read-only, but that is implied by 'list'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence that front-loads the purpose ('List redeal's algorithms') and then provides specific details in a parenthetical list. Every piece of information is useful; there is no redundancy or wasted words. The usage guidance is appended naturally.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description fully explains what is returned: the algorithms with their input contracts and test vectors. It also gives a usage hint. There is no missing information needed for an agent to understand and use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%. The description does not need to add parameter information, and the baseline for zero-parameter tools is 4. The description does not detract from parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it lists redeal's algorithms and enumerates them by name (split.v1, random.v1, shapley.v1, auction.v1) along with a brief explanation of each. This clearly distinguishes the tool from sibling tools like create_deal or commit_input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description ends with explicit guidance 'Read this before creating a deal', indicating the tool should be used early in the workflow. While it doesn't list when not to use it or alternatives, the context is clear enough for an agent to understand its role.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reveal your committed input. It must hash to your earlier commitment. When the last party reveals, the deal computes and the fairness certificate is issued automatically — fetch it with get_certificate.
| Name | Required | Description | Default |
|---|---|---|---|
| salt | No | Your hex salt from commitment time. Omit (or empty) for open-mode deals. | |
| input | Yes | Your algorithm input exactly as committed (any JSON value). split.v1: {"valuations": {...}} — your valuations must sum to exactly 1000; random.v1: {"nonce": "<hex>"}; shapley.v1: {"accept": true|false}; auction.v1: {"bid": <integer>}. | |
| deal_id | Yes | The deal id (d_...). | |
| invite_token | Yes | The invite token for YOUR party, from create_deal's response. | |
| idempotency_key | No | Optional: retries with the same key + same arguments replay the original response. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that input validation occurs ('must hash to your earlier commitment'), that the action triggers automatic computation and certificate issuance if last party, and that the certificate is fetched separately. However, it omits side effects (e.g., does reveal lock the input?), error behavior (hash mismatch?), and whether the tool is read-only or mutating. The idempotency_key parameter is not referenced in the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: three sentences that front-load the action, add a constraint, and provide follow-up guidance. Every sentence earns its place—no wasted words. Perfectly sized for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic flow (commit → reveal → certificate) and references a sibling tool for the next step. However, it does not describe the return value of the tool itself, error conditions, or what happens if the party is not the last to reveal. Given the absence of an output schema, more detail on the response would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The tool description does not add parameter-level information beyond what the schema already provides (the algorithm-specific input formats are documented in the schema's input property description). The description only adds general behavioral context, not per-parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Reveal your committed input.' It distinguishes itself from sibling tools like commit_input (which commits) and get_certificate (which fetches the resulting certificate) by describing the trigger: 'When the last party reveals, the deal computes and the fairness certificate is issued automatically.' The verb 'Reveal' plus resource 'committed input' is specific and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use the tool: after commitment (input must hash to earlier commitment) and before fetching the certificate. It explicitly points to a sibling tool ('fetch it with get_certificate') for the follow-up action. However, it does not explicitly state when NOT to use the tool or list alternatives; the flow is implied rather than enumerated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate your algorithm input against the deal's contract BEFORE you commit. A commitment binds the exact input bytes — a contract-violating input (e.g. split.v1 valuations not summing to exactly 1000) can never be corrected afterwards and the deal will VOID at the reveal deadline. Always validate first, then compute_commitment_tool, then commit_input. Read-only: nothing is stored or changed.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | The algorithm input you plan to commit (e.g. {"valuations": {"<item_id>": <points>}} for split.v1 — every party's valuations must sum to exactly 1000). Validated against the deal's algorithm and declared params; nothing is stored. | |
| deal_id | Yes | The deal id (d_...). | |
| invite_token | Yes | The invite token for YOUR party, from create_deal's response. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses the tool's behavioral trait: 'Read-only: nothing is stored or changed.' It also warns of the consequence of using the tool incorrectly (deal VOID at reveal deadline). There is no contradiction with any structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose, and every sentence serves a distinct role (purpose, consequence, ordering, behavioral note). No redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity, 3 required parameters, no output schema, and no annotations, the description covers purpose, usage, behavioral traits, and parameter context. The only minor gap is the absence of any information about the return value (e.g., success/failure/errors), but the tool's role as a validation gate is sufficiently clear for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter. The description adds value beyond the schema by providing a concrete example of the 'input' format and its constraint, and by reiterating the read-only nature for all parameters. This is a meaningful addition, raising it above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: 'Validate your algorithm input against the deal's contract BEFORE you commit.' It uses a specific verb ('validate') and resource ('algorithm input against the deal's contract'), and distinguishes it from sibling tools like 'commit_input' by positioning it as a prerequisite step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use the tool: 'Always validate first, then compute_commitment_tool, then commit_input.' It also explains why (contract-violating input voids the deal) and gives an example of what constitutes a violation (valuations not summing to 1000), making the decision to use this tool unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a redeal certificate by id: signature check (current or published legacy key) + transparency-log inclusion check, reported per check. Free, no credential required, always.
| Name | Required | Description | Default |
|---|---|---|---|
| cert_id | Yes | The certificate id (c_...). Verification is free and always will be. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behaviors: the two specific checks performed (signature and transparency-log), that results are 'reported per check', and that operation is free and credential-less. This adequately conveys the non-destructive, read-only nature of the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly packed sentence that front-loads the purpose and includes relevant details (checks, cost, credential requirement). Every clause adds value, and it is concise enough to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description covers purpose, procedure, and operational constraints. It hints at output granularity ('reported per check') but does not specify the return format, which is a minor gap. Overall, it is sufficiently complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds context about the certificate id being a redeal certificate, but doesn't add meaning beyond the schema's parameter description ('The certificate id (c_...)'). The tool description itself does not elaborate on the parameter format beyond what schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Verify a redeal certificate by id' with specific actions: 'signature check (current or published legacy key) + transparency-log inclusion check'. This distinguishes it from sibling tools like get_certificate or validate_input by focusing on verification checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While no explicit alternatives are named, the description provides clear context by stating it is 'Free, no credential required, always', implying it can be used freely for any certificate verification. This gives a sense of when to use it without external prerequisites, though it does not explicitly rule out other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
create_deal1 field changedInput schema / properties / visibilityAdded value: +{
+ "description": "Optional: \"public\" (default — anyone can fetch the certificate at its id) or \"parties\" (only you and your invite-token holders). Certificates never contain inputs, only the outcome; choose \"parties\" when the outcome itself is sensitive.",
+ "type": [
+ "string",
+ "null"
+ ]
+}get_public_certificatecreate_deal7 fields changedInput schema / properties / algorithm / descriptionPrevious value: -"Algorithm id from list_algorithms: \"split.v2\" (recommended — fixed 1,000-point budget) | \"random.v1\" | \"shapley.v1\" | \"auction.v1\". (\"split.v1\" is retired 2026-08-17 — closed to new deals; existing certificates verify forever.)"New value: +"Algorithm id from list_algorithms: \"split.v1\" (fixed 1,000-point budget) | \"random.v1\" | \"shapley.v1\" | \"auction.v1\"."Input schema / properties / algorithm_params / descriptionPrevious value: -"Algorithm-specific params from list_algorithms. split.v2: {\"items\": [...]}; random.v1: {\"drand_round\": N}; shapley.v1: {\"coalition_values\": {...}}; auction.v1: {\"item\": \"...\", \"unit\": \"GBP\", \"reserve\": N}."New value: +"Algorithm-specific params from list_algorithms. split.v1: {\"items\": [...]}; random.v1: {\"drand_round\": N}; shapley.v1: {\"coalition_values\": {...}}; auction.v1: {\"item\": \"...\", \"unit\": \"GBP\", \"reserve\": N}."Input schema / properties / external_refAdded value: +{
+ "description": "Optional: your own identifier for this deal, e.g. \"campaign-4821\" (echoed into the certificate).",
+ "type": [
+ "string",
+ "null"
+ ]
+}Input schema / properties / party_labels / descriptionPrevious value: -"One label per party, e.g. [\"alice\", \"bob\"]. Party 0 is you (the initiator). Labels go on the public certificate permanently: use nicknames, never real names or emails."New value: +"One label per party, e.g. [\"alice\", \"bob\"] — or objects {\"label\", \"weight\"?, \"statement_hash\"?} (weight defaults to 1; statement_hash is \"sha256:<hex>\" of a declaration you want bound into the certificate). Party 0 is you (the initiator). Labels go on the public certificate permanently: use nicknames, never real names or emails."Input schema / properties / party_labels / itemsPrevious value: -{
- "type": "string"
-}New value: +trueInput schema / properties / supersedesAdded value: +{
+ "description": "Optional: certificate id (c_<16 hex>) this deal's certificate replaces (re-draw after VOID etc.).",
+ "type": [
+ "string",
+ "null"
+ ]
+}Input schema / properties / terms_hashAdded value: +{
+ "description": "Optional: \"sha256:<hex>\" of the deal's terms (echoed into the certificate; we never see the terms).",
+ "type": [
+ "string",
+ "null"
+ ]
+}reveal_input1 field changedInput schema / properties / input / descriptionPrevious value: -"Your algorithm input exactly as committed (any JSON value). split.v2: {\"valuations\": {...}} — your valuations must sum to exactly 1000; random.v1: {\"nonce\": \"<hex>\"}; shapley.v1: {\"accept\": true|false}; auction.v1: {\"bid\": <integer>}."New value: +"Your algorithm input exactly as committed (any JSON value). split.v1: {\"valuations\": {...}} — your valuations must sum to exactly 1000; random.v1: {\"nonce\": \"<hex>\"}; shapley.v1: {\"accept\": true|false}; auction.v1: {\"bid\": <integer>}."validate_input1 field changedInput schema / properties / input / descriptionPrevious value: -"The algorithm input you plan to commit (e.g. {\"valuations\": {\"<item_id>\": <points>}} for split.v2 — every party's valuations must sum to exactly 1000). Validated against the deal's algorithm and declared params; nothing is stored."New value: +"The algorithm input you plan to commit (e.g. {\"valuations\": {\"<item_id>\": <points>}} for split.v1 — every party's valuations must sum to exactly 1000). Validated against the deal's algorithm and declared params; nothing is stored."create_deal2 fields changedInput schema / properties / algorithm / descriptionPrevious value: -"Algorithm id from list_algorithms: \"split.v2\" (recommended — fixed 1,000-point budget) | \"split.v1\" | \"random.v1\" | \"shapley.v1\"."New value: +"Algorithm id from list_algorithms: \"split.v2\" (recommended — fixed 1,000-point budget) | \"random.v1\" | \"shapley.v1\" | \"auction.v1\". (\"split.v1\" is retired 2026-08-17 — closed to new deals; existing certificates verify forever.)"Input schema / properties / algorithm_params / descriptionPrevious value: -"Algorithm-specific params from list_algorithms. split.v1/split.v2: {\"items\": [...]}; random.v1: {\"drand_round\": N}; shapley.v1: {\"coalition_values\": {...}}."New value: +"Algorithm-specific params from list_algorithms. split.v2: {\"items\": [...]}; random.v1: {\"drand_round\": N}; shapley.v1: {\"coalition_values\": {...}}; auction.v1: {\"item\": \"...\", \"unit\": \"GBP\", \"reserve\": N}."reveal_input1 field changedInput schema / properties / input / descriptionPrevious value: -"Your algorithm input exactly as committed (any JSON value). split.v1: {\"valuations\": {...}}; split.v2: same, but your valuations must sum to exactly 1000; random.v1: {\"nonce\": \"<hex>\"}; shapley.v1: {\"accept\": true|false}."New value: +"Your algorithm input exactly as committed (any JSON value). split.v2: {\"valuations\": {...}} — your valuations must sum to exactly 1000; random.v1: {\"nonce\": \"<hex>\"}; shapley.v1: {\"accept\": true|false}; auction.v1: {\"bid\": <integer>}."create_deal1 field changedInput schema / properties / party_labels / descriptionPrevious value: -"One label per party, e.g. [\"alice\", \"bob\"]. Party 0 is you (the initiator)."New value: +"One label per party, e.g. [\"alice\", \"bob\"]. Party 0 is you (the initiator). Labels go on the public certificate permanently: use nicknames, never real names or emails."commit_inputcompute_commitment_toolcreate_dealcreate_keyget_certificateget_dealget_entropylist_algorithmsreveal_inputvalidate_inputverify_certificate
Add one secure layer between your agents and this server.