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.
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.