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.
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 discloses that test vectors are 'served inline — the same fixtures the engine test suite runs', which is a behavioral detail about output. However, it does not explicitly state that the operation is read-only, safe, or has no side effects. Given the lack of annotations, the description covers some behavioral traits but not comprehensively.
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 sentence that front-loads the core purpose ('List redeal's algorithms...'). It packs relevant details (algorithm versions, test vectors, usage hint) without unnecessary words. Minor improvement could be splitting into two sentences for readability, but overall it is concise and well-structured.
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 tool has no parameters, no output schema, and no annotations, the description provides a reasonable overview of what the tool returns (list of algorithms with contracts and inline test vectors). However, it does not describe the format of the response (e.g., array, key structure, pagination) or any error conditions. For a simple listing tool, it is adequate but leaves some gaps.
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 has zero parameters with 100% coverage trivially. The description adds significant meaning beyond the schema by specifying what the list contains (algorithm names, input contracts, test vectors). With no parameters to document, the description effectively provides all semantic context for the tool's purpose and output.
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 verb 'List' and the resource 'redeal's algorithms', enumerating specific algorithms (split.v1, random.v1, shapley.v1, auction.v1). It distinguishes itself from sibling tools which are action-oriented (commit_input, create_deal, etc.) rather than listing-oriented.
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 includes the phrase 'Read this before creating a deal', which implies when to use the tool (before deal creation). However, it does not explicitly state when not to use it or mention alternatives among siblings. The guidance is present but minimal and implied.
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?
No annotations are provided, so the description carries full burden. It clearly explains the behavioral effect: the deal computes and fairness certificate auto-issues when last party reveals. It mentions hash verification requirement, making the tool's side effects transparent. Could be improved by noting whether reveals are reversible or idempotent.
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 sentences with zero waste. Each sentence serves a distinct purpose: what the tool does, the verification requirement, and the downstream side effect with reference to sibling. Ideal length and front-loading of key 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?
Despite no output schema and no annotations, the description ensures completeness by covering the tool's core action, its prerequisite (hash commitment), its side effect (auto-computation+certificate), and links to the certificate retrieval tool. The 5 parameters are all documented in the schema, and the description adds crucial semantic detail for the complex 'input' parameter.
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%, so baseline is 3. The description adds significant value by embedding protocol-specific format rules inside the 'input' parameter description (JSON structures for each algorithm version, valuation sum constraint). It also clarifies that 'salt' is optional for open-mode deals, which goes beyond the schema's generic type description.
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 clear verb 'Reveal' and specific resource 'committed input', explicitly stating the hash verification requirement. It distinguishes from siblings like 'commit_input' and 'get_certificate' by describing the timing and downstream effect.
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 usage context: when to use (must hash to earlier commitment, and after last reveal the certificate auto-issues). It references the alternative 'get_certificate' for fetching the certificate, but does not explicitly state when not to use it or exclude other siblings like 'commit_input'.
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. Dates show when Glama detected each change.
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_certificateClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Add one secure layer between your agents and this server.
Each tool has a clear, distinct role in the deal lifecycle: key creation, deal creation, algorithm listing, input validation, commitment computation, committing, revealing, entropy retrieval, certificate fetching, and certificate verification. No two tools appear to do the same thing.
All tool names follow a consistent verb_noun snake_case pattern (e.g., create_deal, get_certificate, verify_certificate). The verbs and nouns are descriptive and match the tool's function. There is no mixing of conventions.
With 11 tools, the set is well-scoped for the fairness deal domain. Each tool earns its place, covering onboarding, deal creation, input handling, execution, and verification without unnecessary redundancy.
The core lifecycle is covered: create key, create deal, inspect algorithms, validate inputs, compute commitments, commit, reveal, fetch entropy for random deals, retrieve certificates, and verify them. The main gap is a tool for counterparties to accept/join a deal using the invite token, but this may be handled outside the MCP server.