deusproof-mcp

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true and openWorldHint=false, so the read-only nature is already signaled. The description adds behavioral nuance: it returns a 'single-use nonce' and the exact signing string, implying a one-time use and a purpose tied to record tier upgrades. It also explains the 'witnessed' vs 'signed' distinction and the founding seat incentive, which goes beyond the bare annotation. There is no contradiction with annotations.

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, although complex, sentence that conveys the purpose, condition, and output efficiently. It is front-loaded with context about witnessed records and the benefit of signing. There is no filler, but the density of information in one sentence makes it slightly less skimmable. Overall, it is concise and well-structured for the information it carries.

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?

With no output schema, the description explicitly mentions what is returned (nonce and signing string), which is helpful. It also explains the broader context of record tiers and the Genesis Council seat. However, it leaves the 'certificate_id' parameter unexplained, and it doesn't clarify the relationship with the claim_authorship sibling or what to do with the returned string. For a two-parameter tool, this is adequate but has clear 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?

Schema description coverage is 50%, with only 'did' having a description. The tool description does not explain 'certificate_id' at all, leaving it ambiguous. It does reinforce the meaning of 'did' by mentioning Ed25519 did:key, but it fails to compensate for the undocumented parameter. Since coverage is low, the description should have provided meaning for certificate_id; it does not, so this dimension is weak.

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 purpose: it returns a single-use nonce and the exact string to sign for upgrading a record to 'signed' tier. It uses a specific verb ('returns') and identifies the resource (a signing challenge for a record). It also distinguishes itself from siblings like claim_authorship by explaining this is the challenge-generation step, not the actual claim action.

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?

It gives clear context on when to use: 'If you have your own Ed25519 did:key', indicating a prerequisite. It implicitly suggests usage when you want to upgrade a 'witnessed' record to 'signed' tier. However, it does not explicitly mention alternatives or when not to use, nor does it contrast with the sibling claim_authorship tool; thus it lacks explicit exclusions but provides a solid usage context.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only say the tool is not read-only and not destructive. The description adds meaningful behavior: records are sealed on an append-only ledger, anchored to Bitcoin, return a verify URL, and can be upgraded from 'witnessed' to 'signed' via a challenge. This goes well beyond the structured annotation hints.

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 front-loaded with the core purpose and packs useful details (free, no account, ledger, Bitcoin, verify URL, witness/signed tiers). It is slightly wordy and includes the awkward phrase 'submitted over a URL we cannot hold your private key,' but every sentence contributes 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?

Given the moderate complexity, no output schema, and four parameters, the description explains the overall workflow, output (verify URL, challenge), and constraints well. Minor gaps remain around exact response structure and optionality of model/handle, but the tool is understandable enough to invoke safely.

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% and each parameter already has a clear description. The tool description adds some context—mentioning that the text is scored for authorship signal and timestamped—but it does not substantially reinterpret or enrich the parameter meanings.

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-resource pair ('Record what you made and when') and clearly distinguishes this tool from siblings like claim_authorship and notarize_hash by emphasizing the public append-only ledger, Bitcoin anchoring, authorship signal score, and permanent verify URL.

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 clear context for when this tool is appropriate: registering a creation with timestamp, authorship scoring, and public verifiability. It also states prerequisites/constraints ('Free, no account', private key not held). It does not explicitly name alternatives, so it does not reach 5.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

While annotations identify a write operation, the description goes further by explaining the actual mutation: it upgrades the record to 'signed', re-signs the provenance manifest, and may grant a founding seat. It also discloses an important refusal condition for records signed by another key. There is no annotation contradiction.

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 compact, front-loaded with the action, and every sentence delivers useful information: what to submit, what happens as a side effect, and when the operation is refused. It contains no fluff or 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?

The high-level workflow and side effects are communicated well, especially the provenance-manifest re-signature and founding-seat condition. However, with no output schema and five child children and multiple required parameters, the description could do a what the operation returns or clears about did/record identity. Still, the behavioral context is strong.

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 leaves 80% of properties undocumented, so the description must compensate. It links the username and nonce to 'signature' and 'authorship_challenge', but it does not explain did, certificate_id, nonce, or signature_b64 precisely. This is only marginal added meaning over the schema.

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 states a specific verb ('Submit') and a specific resource (the signature from authorship_challenge), then explains the resulting action: proving key ownership, upgrading the record to 'signed', re-signing the provenance manifest, and granting a founding seat. This clearly distinguishes the tool from its siblings by connecting it to authorship_challenge and the claimed record.

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 places usage after authorship_challenge: you use this tool when you have a signature from that challenge and want to claim authorship. It also explains that a record already signed by another key is refused. It does not explicitly name alternatives or exclusions, but the flow is clear enough for a 4.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, indicating safe read. The description adds that reading is free and open, and that voting needs a seat, which provides context beyond the annotation. It also clarifies the did parameter's effect (returns signing string), adding behavioral detail not 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 sentences, front-loaded with the main purpose, and each phrase adds value. It is concise with no fluff, though the phrase 'Pass your did:key and it also returns...' could be clearer about optionality.

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's simplicity (no required params, no output schema, no annotations beyond readOnly), the description covers the essential functionality and key behavioral traits. It could mention the output format of the signing string, but overall it is complete for a read-only 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?

Schema coverage is 0%, so the description must explain the parameter. It does, stating that passing the did:key returns the exact string to sign, which adds meaning beyond the bare schema. However, it doesn't clarify if the parameter is required for basic ballot reading, causing ambiguity. Baseline for low coverage is 3, and it meets that.

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 reads the current Genesis Council ballot, listing options, tally, and closing time, and optionally returns the signing string if a did is provided. It distinguishes itself from siblings like council_vote by focusing on reading not voting, though it doesn't explicitly state the distinction.

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?

It explicitly says reading is free and open to anyone, while voting requires a seat, giving clear context on who should use it. It doesn't mention alternatives like council_vote, but the context is sufficient to infer when to use this vs voting. The optional did parameter is implied for getting the signing string.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide only readOnly=false, openWorld=false, destructive=false, offering minimal behavioral detail. The description adds crucial transparency: votes must be signed with a specific Ed25519 key, seats are non-transferable, and the vote cannot be forged even by the platform. It also notes the one-vote-per-seat rule. This goes beyond annotations, though it does not cover error handling or state changes, so a 4 is appropriate.

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 long, each packed with essential information: the action, eligibility, signature requirement, and prerequisite. It front-loads the primary verb and avoids filler, making every word earn 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?

The tool has 3 required parameters with no schema descriptions and no output schema. The description covers the semantics of all parameters, states the prerequisite (council_ballot), explains the signature mechanism, and clarifies the non-transferable nature of seats. It provides all necessary context for an agent to invoke the 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?

Schema coverage is 0% (no descriptions for params). The description indirectly clarifies all three parameters: 'did' is the seat-holder's identity, 'choice' is the vote option, and 'signature_b64' is the base64 signature generated from the council_ballot string. While not explicitly mapping each parameter, the context provides enough inference to understand their roles, compensating for the lack of 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 clearly states the tool's action: 'Cast one vote on the open proposal.' It specifies the resource (open proposal) and verb (cast vote), and distinguishes itself from the sibling tool council_ballot by framing it as the actual voting action while council_ballot is the prerequisite. This is specific and 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 instructs to 'Call council_ballot first to get the exact string to sign,' providing a clear prerequisite and workflow. It also defines eligibility ('Only agents holding a founding seat may vote, one vote per seat') and implies that agents without a seat or without having called council_ballot should not use this tool. This is explicit usage guidance.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds meaningful behavior by describing the passport's contents: registered works, signed works, scores, and sovereign identity. It does not contradict the annotations and gives useful context about what the tool actually exposes.

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 front-loaded sentence of about 30 words. It communicates the main action, identifier forms, and result components without unnecessary filler or repetition of the title.

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 read-only tool with no output schema, the description covers the key details: what is fetched, by what identifier, and what the result contains. It does not mention error or not-found behavior, but that is a minor gap for such a lightweight lookup 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?

With zero schema description coverage for its single parameter, the description compensates by stating that the identifier can be a did:key or an handle. This adds useful semantic information beyond just the property name 'did_or_handle', although it could go further by showing exact formats or resolution behavior.

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 a specific action and resource: 'Fetch an agent's public passport' and clarifies the lookup key as 'did:key or handle'. It then lists the core contents returned, making the tool's purpose and scope distinct from the writing/certification sibling tools.

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 when to use the tool: when you need an agent's public record by DID or handle. It does not explicitly name alternatives or exclusions, but the read-only lookup intent is clear and enough to distinguish it from the other tools.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses important behavior: 'nothing is uploaded', the fingerprint is 'timestamped (RFC 3161), sealed on a public append-only ledger and anchored to Bitcoin', and it is 'Free, no account.' These details give the agent a clear picture of the tool's operation and effects, exceeding the minimal annotation information.

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 just a few sentences, front-loaded with the main action and key differentiator ('nothing is uploaded'). Every sentence contributes useful information—purpose, mechanism, ideal use case, cost, and limitation—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?

The description covers purpose, use case, behavior, and limitations comprehensively for a tool with no output schema. The only missing piece is what the caller should expect as a result (e.g., a certificate or receipt). Since there is no output schema, mentioning the return value would make it fully 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?

The input schema already explains all four parameters with full coverage, including a highly detailed description of output_hash (exact bytes, line ending issues). The tool description adds the general concept of 'send only its SHA-256' but no new parameter-specific semantics beyond what the schema already provides. 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 specific purpose: 'Prove content existed at a point in time WITHOUT revealing it: send only its SHA-256.' It uses a specific verb ('prove') and resource ('SHA-256 fingerprint'), distinguishes it from siblings by explaining it is not for authorship, and the title reinforces that nothing is uploaded.

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 clear when-to-use guidance: 'Ideal for private code, drafts or anything you must keep secret but want provable priority for.' It also explicitly states what it does not do ('Proves existence and time — not authorship'), which helps exclude it from authorship-related tasks. However, it does not name an alternative tool, so it lacks an explicit 'use X instead' pointer.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint=true annotation is reinforced by the description's 'Free, no account' and the non-revealing hash-check behavior. The description adds valuable context about limitations ('never who created something first in the world') and the privacy-preserving nature of output_hash, going beyond the annotation.

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?

Five sentences, front-loaded with the primary purpose, then usage context, parameter guidance, and access cost. No filler or redundant content, though it is slightly wordier than necessary in the 'if something close already exists...' clause.

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 workflow timing, the two search modes, access requirements, and a key limitation. There is no output schema, so a bit more detail on what the returned matches contain would improve completeness, but for a read-only search tool with strong parameter hints, this 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning for text (search by meaning) and output_hash (SHA-256 exact-content check without revealing it). This is useful disambiguation beyond the schema's brief descriptions, though limit is only covered by the schema.

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 checks whether anything similar exists on the public record and who recorded it there. It explicitly positions itself as a pre-publication/pre-registration check, distinguishing it from sibling tools that certify, notarize, or claim authorship.

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 'Use it BEFORE publishing or registering' and explains the two possible outcomes (existing match vs. checked-clear). It does not name specific sibling tools as alternatives for the registering step, but the before-context is clear and actionable.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare readOnlyHint=true, so the description doesn't need to repeat that. However, it adds value by specifying exactly what the tool returns (score, authorship tier, hashes, anchor state, ledger status), going beyond the bare annotation. It doesn't mention any side effects or prerequisites, but since it's a read operation and the annotation covers that, this is sufficient. The absence of any destructive language aligns with the readOnlyHint, so no contradiction.

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, both dense with information. The first sentence lists the key data points returned, and the second gives a clear use case. There is no fluff or redundancy, making it concise and well-structured. It earns a high score for efficiency, though not a 5 because it could potentially include more specific examples or formatting hints, but it is already quite tight.

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's simplicity (one parameter, no output schema, read-only annotation), the description covers all critical aspects: what it does, what it returns, and when to use it. However, it doesn't mention potential errors (e.g., what happens if the certificate id doesn't exist) or rate limits, but these are less critical for a read-only verification tool with a straightforward purpose. The absence of an output schema means the description partially compensates by listing the returned fields, which is good, but it could be slightly more explicit about the response format.

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 only one parameter, certificate_id, which is clearly named as an identifier. The schema description coverage is 0%, but with a single parameter that is self-explanatory from its name, the description doesn't need to add much. The description mentions 'by id' which matches the parameter, but it doesn't specify the format (e.g., UUID vs. string) beyond what the type string implies. Since this is a common identifier type, the baseline of 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 function: to check a DEUSPROOF certificate by id, listing the specific types of information returned (score, authorship tier, hashes, Bitcoin anchor state, ledger status). It distinguishes itself from sibling tools by specifically addressing certificate verification, whereas siblings like certify_creation or claim_authorship are for creating or claiming, making this the go-to for validation.

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 tells the agent when to use this tool: 'Use it to confirm a claim someone shows you.' It implies the context of verifying an existing certificate, which contrasts with sibling tools that create or manage certificates. It clearly directs the agent to use this when validation is needed, making it distinct from the creation-focused siblings.

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