Mark: stamp files with a signed, timestamped provenance record. Hash locally; verify free.
Scored across 9 tools
Each tool maps to a distinct action in the provenance lifecycle: account creation, balance check, stamp purchase, proof creation/listing/revocation, verification, and two clearly paired escrow operations. The detailed descriptions reinforce the boundaries, so an agent can select tools without confusion.
Nearly all tools follow a clear snake_case verb_noun pattern (create_proof, get_balance, revoke_proof, verify_proof). The only outlier is `reveal`, which drops the noun but remains understandable in context.
Nine tools is a well-scoped set for a provenance-stamping service, covering the full workflow without excessive surface area. Each tool has a clear role, even the two future escrow placeholders.
Core lifecycle is covered: create account, buy stamps, check balance, create/list/revoke proofs, and verify hashes. Minor gaps exist—no tool to fetch a single proof by id and escrow grant/reveal are marked not yet available—but agents can work around these for the current hash-only domain.
Start a purchase of prepaid stamps for your key (requires API key). Returns url: a Stripe Checkout link that a PERSON must open and pay; you cannot pay it yourself. Show the link to your user, then poll get_balance. The stamps land on this key's account and never expire. Packs: 5 for $1.00, 10 for $1.50, 50 for $5.00, 100 for $8.00, 500 for $35.00, 1,000 for $65.00, 2,000 for $120.00 (bundle ids bundle_5, bundle_10, bundle_50, bundle_100, bundle_500, bundle_1000, bundle_2000).
| Name | Required | Description | Default |
|---|---|---|---|
| bundle | Yes | Which pack, e.g. bundle_5 for 5 stamps at $1 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond the annotations: the API-key requirement, the human-in-the-loop constraint that the agent cannot pay the Stripe link itself, the fact that stamps land on this key's account and never expire. These are exactly the behavioral traits an agent needs and cannot infer from openWorldHint/destructiveHint/idempotentHint.
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?
Front-loads purpose, then mechanism, then pricing in a single dense block with no filler sentences. The price list is long but each entry carries information absent from the schema, so it earns its place; structure is slightly run-on rather than perfectly scannable.
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 compensates by naming the return value (`url`) and its meaning, plus the post-purchase workflow. Nothing needed to invoke 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 coverage is 100% and the enum already lists the bundle ids, so the baseline is 3. The description adds real decision value by pairing every bundle id with its stamp count and price, which the schema does not fully do (it only prices bundle_5).
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 and resource ("Start a purchase of prepaid stamps for your key") plus the scope of the purchase, and is instantly distinguishable from siblings like get_balance or create_account. An agent knows exactly what this tool initiates.
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?
Gives clear next-step context: requires an API key, returns a Checkout URL that a human must open, and tells the agent to show the link to the user and then poll get_balance. It names a follow-up sibling (get_balance) but offers no explicit when-not-to-use condition, since no alternative purchase path exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Provision a persistent API key with no human, browser, or email in the loop. Call this once, store the returned secret (shown only this one time), and use it as the Authorization header on every later call: create_proof, list_proofs, revoke_proof, get_balance, buy_stamps (verify_proof needs no auth). The key owns its own creator id, with no identity attached. Free stamps: one per network, so check freeStamp in the result; when it is false, the key needs prepaid stamps (buy_stamps) or x402 payment before its first stamp. Rate-limited to 3 keys per network per day; for 3 free stamps a month or a human-owned account, direct a person to makemark.io/account instead.
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | Optional label to recognize this key later, e.g. the agent or project name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavior well beyond the annotations: the secret is shown only one time, the key owns its own creator id with no identity attached, and creation is rate-limited to 3 keys per network per day. The non-idempotent annotation is corroborated by 'call this once' and the one-time secret display, with 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 core action and the one-time secret warning are front-loaded, and each clause carries real information (auth header usage, free-stamp check, rate limit, human redirect). It is dense but long for a single-parameter tool, with the rate-limit and redirect details slightly crowding the primary instruction.
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 compensates by naming the two return fields that matter (secret and freeStamp) and how to act on each. Auth requirements, free-tier limits, and the fallback payment path are all covered, leaving nothing an agent needs missing before calling.
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?
Only one optional parameter, and schema coverage is 100%, so the schema already documents `label` as a recognizable name. The description adds useful semantics about result fields (secret, freeStamp) but nothing extra about the label itself beyond what the schema 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?
States a specific verb and resource ('Provision a persistent API key') and immediately scopes it as agent-self-service with no human, browser, or email. It also enumerates the sibling tools the resulting key unlocks, so an agent can place it correctly relative to buy_stamps, create_proof, and the rest without opening another schema.
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 says 'Call this once' and to store the returned secret, and it gives concrete branching advice: check freeStamp, and if false use buy_stamps or x402 before the first stamp. It also redirects the out-of-scope case (3 free stamps a month or a human-owned account) to makemark.io/account, which is an explicit when-not rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stamp content with a permanent provenance record. Pass the sha256 hash of the content (hash it locally; the content itself is never uploaded). Returns an instant signed receipt: attach its verifyUrl, byline, badgeEmbed, and qrUrl to the published artifact. The receipt's publisher field carries the account's verified identity (domain/handle) or null. If you have no key, call create_account, store its one-time secret, and retry this same call with Authorization: Bearer <secret> (its freeStamp says whether a free stamp comes with it). If the response is payment_required or quota_exhausted, call buy_stamps and give a person the returned checkout link (prepaid packs never expire: 5 for $1.00, 10 for $1.50, 50 for $5.00, 100 for $8.00, 500 for $35.00, 1,000 for $65.00, 2,000 for $120.00), poll get_balance until the stamps arrive, then retry. To pay per stamp instead, sign one advertised x402 requirement and send it as a PAYMENT-SIGNATURE HTTP header: tool arguments can't carry it, so either configure your MCP client to send that header or POST the same JSON to https://makemark.io/proof directly. An invalid_api_key error means the key is mistyped or revoked: create a new one. The optional disclosure fields (aiDisclosure, usageNote, location) only show on visibility: public stamps and are unsigned metadata, not part of the cryptographic proof. The stamp asserts provenance from a signer at a time, not authorship truth.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Optional human-readable title | |
| location | No | Optional, creator-opt-in only: where this was made | |
| usageNote | No | Optional usage/license line, e.g. "Free to share, with credit" | |
| visibility | No | Default private | |
| contentHash | Yes | sha256 hex of the exact content bytes (64 chars) | |
| contentType | No | MIME type, e.g. text/markdown | |
| aiDisclosure | No | Optional, honest disclosure of AI involvement. Shown on the public record card. | |
| canonicalSlug | No | Optional stable slug for a canonical latest-version pointer | |
| previousProofId | No | For a new version of already-stamped content: the prior proof id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark it idempotent and non-destructive but say nothing about the operational reality, which the description fills in richly: content is never uploaded (only a hash), the call returns a signed receipt with specific fields, and it discloses the error taxonomy (payment_required, quota_exhausted, invalid_api_key) plus the retry flow. It also honestly scopes the proof's meaning ('provenance from a signer at a time, not authorship truth') and clarifies that disclosure fields are unsigned metadata. 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 core action is front-loaded in the first sentence, followed by the return shape, then the fallback flows. It is long and dense, and the full price table is arguably more than the description needs, but nearly every sentence carries operational information an agent needs to succeed on first call.
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 carries the burden of explaining returns and does so (verifyUrl, byline, badgeEmbed, qrUrl, publisher). It also covers auth setup, payment paths, idempotency behavior, and the semantic limits of the proof, leaving little an agent would need to discover by trial.
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 genuine meaning beyond the schema: the disclosure fields (aiDisclosure, usageNote, location) only appear on visibility: public stamps and are unsigned, and the contentHash must be computed locally rather than uploading content. Most other parameters are left to the schema, which justifies a 4 rather than a 5.
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 and resource: 'Stamp content with a permanent provenance record.' This clearly distinguishes it from siblings like verify_proof, list_proofs, and revoke_proof, which each operate on existing proofs rather than creating one.
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 routes the agent to alternatives by condition: call create_account if you have no key, call buy_stamps on payment_required or quota_exhausted, poll get_balance until stamps arrive, and create a new key on invalid_api_key. This is exactly the kind of 'when to use vs. what to call next' guidance the dimension rewards.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Your key's stamp balance (requires API key): plan, included monthly stamps used and remaining, prepaid stamps (balance), whether a free stamp is still unused (lifetimeSampleAvailable), and recent pack purchases. Poll this after a person pays a buy_stamps link; credits usually arrive within seconds.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover read-only and non-open-world; the description adds an auth requirement (API key) and a behavioral latency cue that credits land within seconds of payment. It does not describe pagination or rate limits on the polling it recommends, but it clearly exceeds what the annotations provide.
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?
Purpose and auth requirement are front-loaded, and the second sentence delivers the operational guidance efficiently. The parenthetical field list is dense but each field name earns its place as return-value documentation, so nothing is wasted.
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 compensates by enumerating the returned fields, and it supplies the auth prerequisite and the polling-after-payment workflow. An agent has enough to call this correctly and interpret the result.
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 takes no parameters, so the baseline is 4. The description correctly implies a parameterless call scoped implicitly to the caller's own key.
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 resource — the caller's key stamp balance — and enumerates exactly what that balance comprises (plan, monthly stamps used/remaining, prepaid `balance`, free-stamp availability, recent purchases). It also names the sibling `buy_stamps` as the related action, so an agent can place it among the proof/stamp tools without opening a schema.
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?
Gives a concrete trigger: poll after a person pays a `buy_stamps` link, with the latency expectation that credits arrive within seconds. This is clear when-to-use context, though it does not state when not to call it or name any alternative read tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Grant a specific identity the ability to decrypt escrowed content. Only available for proofs created with content escrow opted in (not yet available — stamps are hash-only today). Returns a capability token the grantee uses with reveal.
| Name | Required | Description | Default |
|---|---|---|---|
| proofId | Yes | The proof to grant access to | |
| granteeId | Yes | Identity (did:web: or key fingerprint) to grant |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover openWorldHint and destructiveHint, so the description carries real weight here: it discloses the escrow prerequisite, the current unavailability, and that a capability token is produced for later use with reveal. That is substantive context beyond the annotations, though it says nothing about permissions, idempotency, or whether grants can be revoked.
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 short sentences, front-loaded with purpose followed by the precondition and the return value. The parenthetical about hash-only stamps is slightly awkward but earns its place as a critical caveat.
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 usefully explains the return value (a capability token consumed by reveal) and the prerequisite. For a two-parameter tool it is nearly complete; only the revocation/expiry behavior of the granted capability is unaddressed.
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 (proofId, granteeId) are already documented in the schema. The description adds no format, validation, or sourcing detail beyond that, so the baseline 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?
States a specific verb (grant), a specific resource (decrypt access to escrowed content), and a precise scope (a specific identity). It also names the value returned, which separates it cleanly from siblings like reveal and revoke_proof.
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?
Gives an explicit precondition — only proofs created with content escrow opted in — and warns the capability is not yet live ('stamps are hash-only today'), which is exactly the when-not guidance an agent needs. It stops short of naming an alternative for the hash-only case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List your recent stamps (requires API key).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results, default 20 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered by structured data. The description adds the API-key requirement, which is genuine extra context, but says nothing about ordering of 'recent' results, pagination, or default behavior beyond what the schema supplies.
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?
A single short sentence with the core action front-loaded and no wasted words. The trailing parenthetical is slightly awkward but does carry a real prerequisite, so nothing is padded.
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-only list tool with one fully documented optional param and annotations covering safety, the definition is nearly adequate. It still omits what 'recent' means, ordering, and how results are paged, and the stamps/proofs naming gap leaves residual ambiguity.
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?
There is a single optional parameter (limit) with 100% schema coverage describing its default of 20. The description contributes no additional parameter meaning, so the baseline of 3 applies when the schema does all the work.
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 verb (List) and a resource (your recent stamps), so the operation is identifiable. However, it renames 'proofs' as 'stamps', which is a terminology mismatch against the tool name and its siblings (create_proof, verify_proof, revoke_proof), and it does not differentiate this tool from those siblings.
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 only guidance is a parenthetical prerequisite ('requires API key'), which is a condition rather than a when-to-use rule. It never says when to call list_proofs versus verify_proof or reveal, nor any exclusion, leaving the agent to infer routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve escrowed content for a proof you have been granted access to. Only available for proofs created with content escrow opted in (not yet available — stamps are hash-only today). The service re-checks H(content) == stampedHash before returning.
| Name | Required | Description | Default |
|---|---|---|---|
| proofId | Yes | The proof whose content to reveal | |
| capabilityToken | Yes | Capability token from grant_access |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and a closed-world scope, but the description adds real behavioral content: the service re-verifies H(content) == stampedHash before returning, and the feature is currently inert because stamps are hash-only. That tells the agent why calls may fail, which annotations cannot convey.
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, front-loaded with the action, then the availability constraint, then the integrity guarantee. Every sentence carries distinct information with no 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 two-parameter read-only tool with no output schema, the description covers what is returned (escrowed content), the precondition, and the current unavailability. Only the shape of the returned content on success or hash-mismatch failure is left unstated.
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 both parameters are described there, including the note that capabilityToken comes from grant_access. The prose adds the escrow/verification context but no new syntax or format meaning for either parameter, 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?
States a specific verb (retrieve) and resource (escrowed content) scoped to a proof the caller has been granted access to. This clearly separates it from verify_proof (hash verification), grant_access (issuing the token), and list_proofs, so an agent can route without opening the schema.
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?
Gives an explicit precondition (must have been granted access via a capability token) and a hard availability gate (only works when content escrow was opted in; not yet available today). It does not name a fallback sibling for the case where escrow is absent, so it stops short of full when/when-not routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revoke a stamp you created (forward-only: anchored history stays verifiable, but the proof is marked revoked from now on). Requires API key.
| Name | Required | Description | Default |
|---|---|---|---|
| proofId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by explaining forward-only semantics: the anchored history remains verifiable while the proof is marked revoked going forward, and it discloses the API-key auth requirement. The annotations already declare destructiveHint=true, and the description is consistent with that rather than contradicting it.
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 short sentences with zero filler; the operation and its forward-only consequence are front-loaded, and the auth requirement is a brief trailing note.
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 mutation with no output schema, the description covers the essential behavior (what revocation does and does not destroy) plus auth. Remaining minor gaps are proofId provenance and failure behavior when the proof is not owned by the caller.
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% and the single proofId parameter is undocumented in the schema, so the description must compensate. It partially does by implying the ID refers to a proof the caller created, but gives no format, source, or example of a valid proofId.
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 (Revoke) and resource (a stamp you created), with the scope/ownership constraint attached. It is distinguishable from siblings like verify_proof or list_proofs, though it does not name an alternative explicitly.
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?
Usage is only implied by the precondition 'a stamp you created' – the agent can infer this acts on its own proofs and not others'. There is no explicit when-to-use, when-not-to-use, or routing to a sibling such as verify_proof for read-only checks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify content against all existing stamps. Pass a sha256 hash; matching is EXACT-BYTES-ONLY. Read the verdict fields: exact (these bytes are stamped), each proof's publisher (the verified identity: domain/handle + tier, or null meaning an unverified account, never trust a name that isn't in publisher), and conflict (2+ distinct signers claimed the same bytes; earliest anchored is listed first). A no-match on a re-encoded/screenshotted copy is EXPECTED and is not evidence of fakery: fetch the original and verify that. Free, no auth required.
| Name | Required | Description | Default |
|---|---|---|---|
| contentHash | Yes | sha256 hex of the content bytes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: states it is free with no auth required, defines the exact-byte matching semantics, and explains how to read the verdict fields including the trust rule for `publisher` (null = unverified account) and the meaning of `conflict`. With readOnlyHint/openWorldHint already declaring a safe closed-world read, this adds substantial operative context, though it doesn't cover edge cases like empty or malformed hash input.
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?
Front-loads purpose and the hashing rule, then the verdict-field guidance, then the falsification-of-no-match caveat. Dense but every clause carries operational weight; slightly long, with the field-by-field walkthrough bordering on verbose.
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?
There is no output schema, so the description correctly takes on the burden of explaining the return shape (`exact`, `publisher`, `conflict`) — including field ordering for conflicts. Combined with the matching rule and auth/rate context, an agent can invoke and interpret this tool fully.
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, but the description adds the critical constraint that matching is EXACT-BYTES-ONLY, which materially shapes what value of contentHash will succeed. It reinforces rather than replaces the schema's 'sha256 hex of the content bytes'.
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 (verify) and resource (content against existing stamps) and immediately pins down the matching rule (EXACT-BYTES-ONLY). Clearly distinguishable from siblings like create_proof and list_proofs, which create or enumerate rather than check a 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?
Explicitly covers when to use (pass a sha256 hash to check a stamp) and when-not to draw a negative conclusion (a no-match on a re-encoded/screenshotted copy is expected, so fetch the original instead). This routing guidance is exactly what an agent needs to avoid misinterpreting a failure.
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.
buy_stampsget_balancecreate_accountcreate_proof3 fields changedInput schema / properties / aiDisclosureAdded value: +{
+ "description": "Optional, honest disclosure of AI involvement. Shown on the public record card.",
+ "enum": [
+ "Not AI-generated",
+ "AI-assisted",
+ "Fully AI-generated"
+ ],
+ "type": "string"
+}Input schema / properties / locationAdded value: +{
+ "description": "Optional, creator-opt-in only: where this was made",
+ "type": "string"
+}Input schema / properties / usageNoteAdded value: +{
+ "description": "Optional usage/license line, e.g. \"Free to share, with credit\"",
+ "type": "string"
+}grant_accessrevealcreate_prooflist_proofsrevoke_proofverify_proofStamp or notarize data into a public witnessed transparency log. Proves timing, not truth.
Capture a web source, or seal a hash you hold, into a signed receipt anyone can verify offline.
Timestamp & verify evidence on-chain, free. Proofpack: a portable BEEF+BUMP proof bundle per txid.
Prove a web page or document existed on a date: public SHA-256 registry anchored in Bitcoin. Free.
Add one secure layer between your agents and this server.
