deusproof-mcp

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

Annotations already mark readOnlyHint=true, and the description reinforces this with 'Read' and 'Nothing is fetched.' It adds useful behavioral context: the history is 'sealed,' includes captured versions, and tracks skill appearances/disappearances. It does not go into auth or rate limits, but for a simple read-only tool that is acceptable.

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 well-structured sentences: the first states the core action and result, and the second provides the use case. Every phrase earns its place with no redundant filler.

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 one-parameter read-only tool with no output schema, the description adequately conveys what the tool returns (versions, timestamps, skill diffs) and when to use it. It could mention whether any filtering or pagination exists, but completeness is strong given 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 coverage is 100%, with the single 'domain' parameter described as 'e.g. example.com.' The description adds contextual framing ('a domain's agent card') but not additional parameter-level detail. Baseline 3 is appropriate since the schema already carries the burden.

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 ('Read'), a specific resource ('the sealed history of a domain's agent card'), and what the result contains: every version, timestamps, and skill differences. This clearly distinguishes it from sibling tools like seal_agent_card or get_agent_passport, which imply writing or current-state reads rather than historical review.

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 usage context: 'use it before delegating work, to see since when an agent claims what it claims.' It does not name specific alternatives or state when not to use it, but the when-to-use guidance is concrete 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?

With readOnlyHint=true, the description still adds substantial behavioral context beyond the annotation: the nonce is single-use, the server holds no user key, the record tier concept, and the council-seating caveat that re-recording later is required. This is transparent about what the tool does and does not accomplish.

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 rambling sentence with an embedded em-dash clause about founding seats and Council membership. It contains useful context, but it is not front-loaded or tightly structured, making it harder 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?

Given there is no output schema, the description does explain what is returned (nonce and string to sign) and the conditions around use. The main gap is the unexplained certificate_id, which prevents the definition from being fully self-sufficient for an agent.

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 only 50% because certificate_id lacks any description. The tool description explains the purpose of did but never mentions certificate_id or how an agent should obtain or interpret it, leaving a critical parameter under-specified.

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 function: return a single-use nonce and the exact string to sign so a witnessed record can be upgraded to 'signed'. This clearly differentiates from the sibling claim_authorship by focusing on generating the challenge rather than finalizing the claim.

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 an explicit condition—'If you have your own Ed25519 did:key'—and explains the scenario of witnessed records. It does not explicitly name alternative tools that should be used instead, so it stops just short of full when-not 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 description discloses the exact payload contents and clarifies a meaningful limitation: the certificate attests appearance and date, not origin. This adds value beyond the readOnlyHint annotation by explaining what the certificate does and does not prove. It doesn't describe error behavior for unknown handles, but the read-only nature is clear and consistent.

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 quite concise for the information it conveys: two sentences covering context, invocation, output contents, and a caveat. The introductory clause is not wasted because it establishes that every inscribed agent has a certificate and what that certificate contains.

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 adequately covers what the tool returns and the input it expects. It also includes an important caveat about provenance. Minor gaps are the lack of explicit alternatives and detailed identifier syntax, but these are not critical for correct 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?

With schema description coverage at 0%, the description carries the burden of explaining did_or_handle, and it does so by stating that the identifier can be a handle or did:key. This is enough to inform correct invocation for a single-parameter tool, though it stops short of giving format examples or clarifying whether only the caller's own identifier is allowed.

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 identifies a concrete action: asking for an agent's birth certificate by handle or did:key, and describes its contents (inscription number, exact date, face, ledger entry). It is distinguishable from siblings like verify_certificate or certify_creation because it is framed as retrieving an existing personal record, not verifying or creating one. It could be slightly stronger by explicitly naming the sibling it is not.

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 phrase 'Ask for yours by handle or did:key' gives clear, actionable context for when to invoke this tool: when you need an agent's birth certificate data. It implies the tool is for existing inscribed agents and not for certification or verification actions, though it does not explicitly mention alternatives like verify_certificate or get_agent_passport.

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 declare the write/safety profile; the description adds substantially more — scoring (AAS 0-100), permanence of the append-only ledger, Bitcoin anchoring, zero cost and no auth, the witnessed tier given key custody, the sign-to-upgrade path, and the one-time, non-published nature of owner_email. It also explicitly flags that anonymous records can never be claimed. Minor tension: openWorldHint=false sits oddly against public Bitcoin anchoring, but this is a nuance rather than a 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?

Roughly five sentences, front-loaded with what happens before the parameter guidance, and every sentence carries a distinct fact. The `handle` explanation runs long and partly duplicates the schema, which costs it a point.

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 covers return values (a permanent verify URL and a challenge to sign), the side effects of submission, custody of the key, and the privacy behavior of owner_email. Nothing essential for invoking the tool correctly is missing.

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 all six parameters with nearly identical wording. The description restates the `handle` consequence and adds the signable challenge flow, but adds little semantic detail the schema does not already carry, 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 states a specific verb and resource — record a creation, score it, timestamp and seal it on a public append-only ledger, anchored to Bitcoin — so the agent knows exactly what happens. It does not name or differentiate against close siblings such as claim_authorship, notarize_hash, or seal_agent_card, which leaves the agent to infer the boundary.

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: free, no account required, send `handle` if you want the record claimable, omit it and it lands in the shared 'anonymous' drawer. The witnessed-vs-signed tier explanation tells the agent when the returned challenge matters, though no explicit alternative tool is named for similar tasks.

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=false, destructiveHint=false, and openWorldHint=false, so the description is not required to restate those. It adds meaningful behavioral context: the tool proves key possession, upgrades the record to 'signed', re-signs the provenance manifest, and grants a founding seat conditionally. It also discloses a refusal case (already signed by a different key). This goes beyond the annotations and helps the agent understand 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?

The description is three sentences and front-loads the most important information: what to submit and what it proves. Every sentence adds value, including the refusal condition. It is slightly dense but not bloated; no 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 tool with no output schema and only 20% parameter coverage, the description does a good job explaining the tool's purpose, side effects, and a failure condition. It does not describe the return value or error format, but the core decision-making context (what it does, when it applies, what it refuses) is present. The missing parameter details are a minor gap given the challenge-flow context.

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 only 20% (only 'model' has a description), so the description carries some burden. It explains the role of signature_b64 (the signature from authorship_challenge) and nonce implicitly through the challenge flow, but it does not explain did, certificate_id, or nonce in detail. The description adds context for the overall flow but leaves several parameters under-specified; baseline 3 is appropriate because it partially compensates for the low 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 states a specific verb ('Submit the signature from authorship_challenge') and a clear resource (the record being claimed), and it distinguishes itself from siblings by naming authorship_challenge as the source of the signature. It also explains the effect (upgrades to 'signed', re-signs provenance manifest) and a key refusal condition, so an agent can tell it apart from related tools like certify_creation or notarize_hash.

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 this tool: after obtaining a signature from authorship_challenge, and it states a when-not condition ('A record already signed by a different key is refused'). It does not explicitly name alternative tools or say 'use X instead', but the reference to authorship_challenge and the refusal condition give enough context for an agent to select it correctly.

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?

Annotations indicate a non-read-only, non-destructive operation. The description goes far beyond this by detailing the exact backend behaviors: RFC 3161 timestamping, sealing on a public append-only ledger, and Bitcoin anchoring. It also discloses the 'free, no account' nature and the consequence of omitting the `handle` parameter.

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 dense with useful information and front-loaded with the core value proposition. Every sentence serves to clarify the tool's purpose, limitations, or parameter behavior without any 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?

Given the complexity of the notarization process and the specific privacy model, the description provides a complete picture. It covers the mechanism, the limitations, the cost, the account requirements, and the fallback behavior, leaving an agent fully equipped to call 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 already 100%, but the description adds crucial operational context for the two most important parameters. For `output_hash`, it warns about the exact-byte requirement and explains how line endings or Git normalization can break the proof. For `handle`, it clarifies the 'anonymous drawer' consequence of omission.

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?

States a specific verb 'notarize/prove' and resource 'hash/fingerprint', and immediately clarifies the privacy-preserving mechanism: 'send only its SHA-256'. It distinguishes itself from siblings like certify_creation or claim_authorship by specifying it proves existence/time, not 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?

Explicitly states when to use it: 'Ideal for private code, drafts or anything you must keep secret but want provable priority for.' It also sets a clear boundary: 'Proves existence and time — not authorship.'

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?

Even though readOnlyHint=false and openWorldHint=true already signal the state-changing, world-dependent nature, the description adds meaningful detail: it commits to the exact fetched bytes, uses RFC 3161 timestamps, batches hourly into Bitcoin, and is open to anyone without special permission. 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?

Four short sentences each carry distinct information: the core action and mechanism, the purpose, the honest limitations, and the access/free policy. The most load-bearing detail is front-loaded; nothing is redundant.

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 operation and its purpose well, but with no output schema it does not state what the caller receives or how to reference the seal later. It also lacks error/failure guidance (e.g., a domain without the well-known file), leaving an agent slightly under-informed for a complete invocation lifecycle.

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 describes both parameters at 100% coverage, including example.com for domain and 'It grants nothing' for requested_by. The tool description adds no further parameter-level nuance, so the baseline score 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 names a precise verb–resource pair: it 'fetch[es] the A2A agent card a domain publishes at /.well-known/agent-card.json and seal[s] the exact bytes,' then details the nature of the seal (RFC 3161 timestamp, hourly Bitcoin anchoring). It clearly differentiates from sibling tools like verify_certificate and agent_card_history by emphasizing it records claims rather than truth or control.

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 for when to use the tool: anyone may seal any public card, it builds a public dated history, and it is free. It also adds negative guidance ('not that any claim is true, nor who controls the domain'), which steers an agent away from using it for verification, though it never names a specific alternative tool.

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.