Vigil — an outside witness for AI agents

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

Annotations already signal mutation and non-idempotency (readOnlyHint=false, idempotentHint=false). The description adds meaningful behavioral nuance: the digest is sent to external OpenTimestamps calendars and 'submission is not verified Bitcoin confirmation,' warning that calling this does not guarantee a confirmed result. This goes beyond what annotations alone 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?

Two compact sentences carry all the necessary information: the first identifies the action and scheduling context, the second exposes the main limitation. There is no filler, repetition, or redundant restatement of schema fields.

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 triggering action with one optional deprecated parameter, the description covers the purpose, scheduling, external effect, and the confidence caveat. The only notable gap is that no output schema exists and the description doesn't state what the call returns, such as a receipt or status.

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 only parameter, vigil_key, is fully documented in the schema with deprecation and authentication guidance, so the description doesn't need to repeat it. Since schema description coverage is 100%, the baseline of 3 is appropriate; the description adds no parameter-level detail but none is necessary.

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 precise action—anchoring the current chain head to OpenTimestamps on demand—rather than a vague verb. The parenthetical clearly distinguishes it from the automatic periodic anchoring, so an agent can tell exactly what this tool uniquely does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the trigger condition: use this when an anchor is needed before the next automatic anchor, which happens every few hours regardless. It doesn't explicitly name sibling tools or exclusion cases, but the scheduling context makes the when-to-use decision reasonably clear.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value beyond that by disclosing that submissions are pending rather than independently confirmed and that no key is needed, which meaningfully shapes expectations.

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 deliver the resource, the pending/unverified caveat, and the authentication requirement with no wasted words. The most important identifying information is front-loaded in the first sentence.

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 zero-parameter, read-only, idempotent tool, the description is nearly complete: it states what data is exposed, its reliability caveat, and its auth requirement. It would be slightly stronger if it explicitly said that it returns a list or collection, but the plural name and public-scope phrasing largely cover that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the schema's description coverage is effectively complete, so there is no parameter burden for the description to carry. A baseline of 4 is appropriate because no additional parameter explanation is needed.

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 the resource ('public timestamp submissions to OpenTimestamps calendars') and one key property ('pending, not an independently verified Bitcoin confirmation'), but it never states the actual action, such as 'list' or 'retrieve'. The plural name vigil_anchors hints at a collection operation, yet that is left to inference rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides useful context: the operation is public and 'no key is required,' and the data is unverified. However, it does not explicitly say when to choose this tool over siblings like vigil_anchor or vigil_verify_receipt, nor does it state when not to use it.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a concrete behavioral constraint with 'Max 1000 per call,' though it does not state what happens when the limit is exceeded (error vs truncation).

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 no filler. The verb and object are front-loaded, and the constraint 'Max 1000 per call' is placed in its own terse sentence that earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, safe, optional-range read operation with fully documented parameters and non-destructive annotations, the description is nearly complete. It is missing only explicit return-shape or error behavior and a named pointer to sibling tools for single-receipt reads.

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 already have clear defaults and meanings, so the baseline is 3. The description adds value by introducing the range limit, which gives additional semantic weight to from_serial and to_serial as a bounded interval.

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 distinct resource ('a range of receipts'), and a clear purpose ('audit chain continuity'). This range-based scope differentiates it from sibling tools like vigil_get_receipt, which implies a single receipt.

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: when auditing chain continuity over a receipt range. The 1000-per-call max is a useful boundary, but it does not explicitly name alternatives or when-not-to-use conditions, so it falls short of a 5.

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

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

Annotations already mark the tool as destructive, but the description adds valuable specifics: deleting the configuration, stopping future alerts, and no restoration of the previous timer. This goes beyond the structured annotations without contradicting them.

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 no filler. The action is stated first, then the destructive consequences are front-loaded, and every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple delete operation with a fully documented two-parameter schema, the description covers the critical consequences an agent must know: configuration loss, stopped alerts, and irreversibility. The idempotent annotation further covers repeated calls, so nothing essential 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%, and the schema documents both parameters well, including the deprecated vigil_key guidance. The description adds no parameter-level detail, so 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 opens with a specific verb and resource ('Remove a watchdog') and immediately clarifies the destructive scope: deletes configuration and stops future alerts. This clearly distinguishes it from siblings like vigil_set_watchdog and vigil_watchdog_status.

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 usage context by warning that the operation is destructive, stops alerts, and has no undo. It does not explicitly name alternatives or state when-not-to-use, but the warning strongly implies caution and makes the tool's purpose unambiguous.

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 mark the tool read-only and idempotent. The description adds the key behavioral fact that no auth is needed and all receipts are accessible, which is not present in the annotations and is important for an agent to know before calling.

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 convey the action, the lookup key, and the access model with no filler. The essential operation is front-loaded.

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 single-parameter, read-only lookup, the description is nearly complete: it specifies the input, the access policy, and the object class. No output schema exists, so a brief note about the returned receipt object could add value, but the tool is simple enough that 'fetch a receipt' is likely 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 schema already documents 'serial' as 'The receipt serial number.' The description merely says 'by serial number,' adding no additional format, constraints, or nuance beyond 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 names a specific action ('Fetch') and resource ('a receipt'), keyed by serial number. This distinguishes it from siblings like vigil_verify_receipt and vigil_journal_get without needing to open 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?

The 'Public — anyone can read any receipt' sentence gives clear context about access and when no authorization is required. It doesn't explicitly compare to alternatives, but the verb and resource are unique enough among siblings that the intended use is clear.

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 destructive/non-read-only behavior, but the description adds real behavioral context: the gateway verifies offline and fail-closed, free tier caps active leases, this is security-sensitive, the account key should be kept out of the controlled agent, and the lim string is enforced only by the customer's gateway. It stops short of disclosing what happens if another lease already exists.

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?

Six sentences, with the core action front-loaded and every sentence contributing a distinct fact. The structure is good, though the caveats (free tier, security note, account key, lim enforcement) are a little list-like and could be organized more tightly.

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 sensitive mutating tool there is solid behavioral coverage: offline fail-closed verification, security warnings, and free-tier limits. Yet with no output schema and no return-type mention, an agent cannot confidently know that the call returns a signed lease to hand to the gateway—what the caller receives or how to route it is left implicit.

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 raises that by adding semantic value beyond the schema: it explains that lim enforcement is entirely the customer's gateway's job, and points to the short-lived nature of ttl. It does not need to repeat param definitions since the schema already has them.

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 specific verb ('grant'), resource ('Ed25519-signed LEASE'), and intent ('authorizing an agent to perform an action until it expires'), and it positions itself as the guard on money/data-moving actions. This makes it easy to distinguish from the sibling lease tools (verify, renew, revoke, enumerate).

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 implies the usage context—registering the lease before a customer gateway lets the action through—and notes the free-tier one-lease limit. However, it never explicitly contrasts the tool with vigorsh like vigil_renew_lease or vigil_revoke_lease, nor states when not to use it beyond the security warning.

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 mark the operation as non-read-only and destructive, and the description adds meaningful behavioral detail: it 'Resets the deadline and delivery state, potentially suppressing an overdue alert or rearming delivery.' This explains the real side effects beyond just 'reset,' which is helpful context for an agent deciding whether calling it could change alerting behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded, starting with the memorable 'Still alive.' followed immediately by the core action. Every sentence earns its place: one defines the action, one provides usage frequency, and one explains the behavioral consequences.

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 two straightforward parameters, one required, and a clear keepalive use case, the description covers the action, cadence, and side effects. It does not describe a return value, but there is no output schema and the important operational behavior is already disclosed. The only minor gap is that it does not explicitly explain what happens if the interval is missed, though 'suppressing an overdue alert' implies it.

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 covers both parameters fully: 'name' is described as the watchdog name with length constraints, and 'vigil_key' is documented as a deprecated credential with clear guidance to omit it when using the Authorization header. The description adds no parameter-specific meaning, so the schema-description coverage 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 uses a specific verb and resource: 'Reset a watchdog's timer.' The phrase 'Still alive.' and the repeated reset semantics make the tool's purpose unmistakable and distinguish it from siblings like vigil_set_watchdog or vigil_delete_watchdog, which create or remove watchdogs rather than refresh them.

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 to call the tool: 'Call this at least once per interval.' It also hints at the consequence of failing to call it by mentioning 'suppressing an overdue alert.' It does not explicitly name alternatives or state when not to use it, but the intended keepalive pattern is clear.

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, idempotentHint, and destructiveHint false, covering safety traits. The description adds one behavioral detail: 'No key required'—an access/authentication trait not captured in annotations. It does not describe output format, error behavior, or rate limits, but for a simple info tool with annotations, this is acceptable yet not highly informative.

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, well-structured sentence that front-loads the primary purpose ('Service description') before enumerating specifics. It contains no redundant words and effectively communicates the tool's scope and the key usage note about authentication.

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 zero-parameter, read-only info tool with no output schema, the description is sufficient. It states what the tool returns (pubkey, chain head, free-tier limits) and the critical access requirement (no key). Nothing an agent needs to correctly invoke and interpret this tool 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?

The tool has zero parameters, so the schema trivially covers 100%. The description is not required to explain parameters but instead clarifies the output contents, which is appropriate. It adds value by enumerating the pieces of service information returned, fulfilling the baseline for a parameterless tool.

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 resource (service info) and lists the specific contents: Ed25519 pubkey, chain head, free-tier limits. It distinguishes itself from siblings by noting 'No key required,' which implies an unauthenticated info endpoint. However, it lacks an explicit verb like 'returns' and does not directly contrast with related tools such as vigil_chain or vigil_pricing.

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 'No key required' provides a clear usage condition—this tool can be called without authentication, unlike many siblings that likely require keys. However, it does not explicitly state when to prefer this over alternative tools like vigil_chain or vigil_pricing, nor does it mention exclusions or scenarios where this should not be used.

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 include destructiveHint=true and idempotentHint=true. The description adds valuable context by specifying that it removes stored bytes and that there is no undo through the API, which goes beyond the annotations and helps the agent understand the irreversible nature of the operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences. It leads with the action, then provides the critical warning. Every word earns its place; no filler or repetition.

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 delete operation with one required parameter and clear destructive annotations, the description covers the essential behavior. It doesn't mention return values or side effects beyond data removal, which is acceptable given the low complexity and absence of an output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%—both slug and vigil_key are fully documented in the schema, including the deprecation note. The description adds no extra parameter-specific guidance, but since the schema handles it fully, 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 verb ('Delete'), the resource ('journal slot'), and the destructive consequence ('removes stored bytes with no undo'). It unambiguously distinguishes itself from sibling journal tools like get/put/list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

While it does not explicitly name alternative tools or exclusion conditions, the destructive warning and the action verb clearly imply the intended scenario (permanent deletion). It lacks explicit routing to alternatives but the context is strong enough for an agent to select it appropriately.

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, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: the return value is base64-encoded and must be decrypted client-side. This is exactly the kind of beyond-annotations disclosure that helps an agent handle the response correctly.

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, zero filler. The core action is front-loaded, and the critical return-format note is included without bloat.

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-by-slug tool with full schema coverage and safety annotations, the description is nearly complete. It could mention that the slug must exist or what happens on a miss, but the schema's pattern and the read-only annotations cover most of what an agent needs.

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 both parameters. The description adds the fact that the blob is base64 and client-decrypted, which relates to the return value rather than the parameters. Baseline 3 is appropriate since the schema carries the parameter documentation 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 ('Fetch') and resource ('journal blob by slug'), and the sibling list includes vigil_journal_list and vigil_journal_put, so the agent can distinguish this as the read-by-slug operation. It doesn't explicitly contrast with siblings, but the verb+resource is clear enough.

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 implies usage: call this when you need a journal blob by slug. It doesn't explicitly say when not to use it or mention alternatives like vigil_journal_list for enumeration. The sibling list provides context, but the description itself gives no routing 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds scoping to the caller's own journal and lists the return fields, but does not mention pagination, ordering, or behavior on empty results. With annotations covering the safety profile, this is adequate but not rich.

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 with no filler. The parenthetical field list earns its place because there is no output schema to document the return shape elsewhere.

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 zero-required-parameter, read-only list operation, the description provides the essential return fields and scoping. It lacks explicit pagination or ordering caveats, but these are minor for a simple slot listing, especially since the only parameter is thoroughly documented in the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, including a detailed deprecation note for vigil_key. The description itself does not need to add parameter semantics; the schema already carries that burden, 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?

The description uses a specific verb ('List'), identifies the resource ('your journal slots'), and names the returned fields (slug, size, last-updated). It is readily distinguishable from sibling operations like vigil_journal_get, vigil_journal_put, and vigil_journal_delete because it is explicitly a plural listing operation.

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 implies usage by saying 'List' but gives no explicit when-to-use guidance or alternatives. An agent must infer that individual journal slot operations belong to vigil_journal_get/put/delete; the description does not state exclusions or conditions.

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 destructiveHint=true, but the description adds valuable specifics: previous bytes are replaced with no version history or undo, the server stores exactly the supplied bytes, and client-side encryption is the caller's responsibility. This goes beyond the annotation and helps the agent anticipate real consequences.

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 tight sentences front-load the core action and overwrite behavior, then cover encryption expectations, size limits, and destructiveness. Every sentence earns its place with no filler or repetition.

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 write tool with no output schema, the description adequately covers the destructive nature, storage limits, encoding requirement, and encryption responsibility. It does not describe the response format, but that is not essential for correct invocation. Minor ambiguity remains between the 64KB stated limit and the schema's 100000-character base64 maxLength, but this does not block usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents slug, data_base64, and vigil_key fully. The description reinforces the base64 requirement and the opaque-blob semantics, but adds little meaning beyond the schema, so 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 opens with a specific verb and resource: 'Store an opaque blob under a slug (overwrites).' It clearly identifies the write operation and the key behavioral feature (overwriting), which differentiates it from sibling journal operations like vigil_journal_get and vigil_journal_delete without needing to inspect schemas.

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 implies appropriate use for storing client-side encrypted blobs and explicitly warns about the free tier limits and base64 encoding requirements. However, it does not name alternatives or state when not to use this tool, leaving the differentiation from sibling tools implicit rather than explicit.

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, idempotentHint, and destructiveHint false, covering the safety profile. The description adds that the call is scoped to the caller's own leases ('your') and that the output includes lease states, which is useful context beyond the annotations. 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?

One sentence, front-loaded with the action and object. Zero waste. Very concise.

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 listing tool with no required parameters and a deprecated optional credential, the description is sufficient. It conveys the scope and output content ('states'), and annotations cover safety. Could mention pagination or sorting, but not critical for a basic list.

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 single parameter vigil_key is deprecated and has a detailed schema description explaining to prefer the Authorization header. The tool description adds nothing about parameters, but with 100% schema description coverage and no required parameters, the schema carries the burden. Baseline is 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb 'List' and resource 'leases' with a meaningful qualifier 'your' and 'states' to indicate output content. Clearly distinguishes from sibling tools like vigil_lease_status, which likely targets a single lease.

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?

No explicit guidance on when to use this tool vs alternatives like vigil_lease_status or vigil_verify_lease. The phrase 'List your leases' implies a bulk listing operation, but no exclusions or alternatives are mentioned.

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 cover readOnly, idempotent, and non-destructive hints. The description adds the crucial auth requirement ('No key required') and the 'public' nature, which are valuable behavioral details beyond what annotations provide. No contradictions 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?

One sentence, front-loaded with the core purpose, and every phrase adds value (status values, polling use, auth requirement). No wasted words.

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 status-check tool with one parameter and no output schema, the description implies the return is the status value. It lacks explicit error handling or response format details, but given the simplicity and annotations, it is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% – the single parameter lease_id is fully described as returned by vigil_grant_lease. The description adds no extra parameter detail, but since the schema handles it, the 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 a specific verb ('public status') and resource ('lease'), enumerates possible values (active/expired/revoked), and identifies its polling purpose. It distinguishes from siblings like vigil_verify_lease by emphasizing 'public' and 'No key required', making its role 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?

It explicitly says 'What a gateway polls for revocation', giving a concrete use case. While it doesn't name alternatives or exclusions, the context is clear enough for an agent to infer when to use it versus other lease-related tools (e.g., verifying or granting).

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 are sparse (readOnlyHint=false, destructiveHint=false, etc.), so the description carries the full burden. It discloses the irreversible publication of digest, label, and account handle in a public chain, states no deletion tool exists, explains the timestamp is a signed assertion of Vigil's clock, and clarifies the proof limits. This is exactly the kind of behavioral context that annotations don't 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?

The description is compact and information-dense. Every sentence earns its place: the first explains the core operation and output, the second explains chain ordering and timestamp semantics, the third covers rate limits, the fourth covers irreversibility, and the fifth clarifies proof limits. No filler or repetition of schema details.

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, the description provides a thorough account of what the receipt contains (Ed25519-signed, timestamped, hash-chained, serial-numbered). It covers the key operational constraints: rate limit, irreversibility, public exposure, and proof limitations. An agent has enough information to decide whether to call this tool and what to expect.

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 schema already documents all three parameters. The description adds value by explaining the subject_sha256 format (64 hex chars) and the public nature of the label, which reinforces the schema's warning. It also clarifies that vigil_key is deprecated and not a scoped agent token, which is useful beyond the schema. The description doesn't add much about the output, but the parameters are well covered.

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 ('Notarize work'), the exact input (sha256 hex digest), and the full output (Ed25519-signed, timestamped, hash-chained, serial-numbered receipt). It also distinguishes itself from verification tools by noting it proves signed-data integrity, not action/claim truth. This is clearly differentiated from siblings like vigil_verify_receipt and vigil_verify_source.

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 to use the tool: to notarize a digest and get a signed receipt. It explicitly states the free tier limit (10/day) and warns about irreversibility, which helps an agent decide whether to call it. It doesn't explicitly name alternative tools for verification, but the closing sentence implies the distinction from verification tools. The irreversibility warning effectively serves as a 'when not to use' signal.

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 read-only, idempotent, and non-destructive behavior. The description adds the auth requirement ('No key required'), which is a behavioral trait not covered by annotations. This is exactly the kind of contextual value the rubric rewards.

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 no redundancy. The resource is front-loaded, and the auth note is separated into its own sentence. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only endpoint with no output schema, the description covers the resource content ('plans and per-tier limits') and auth requirements. It does not describe the exact output format, but that is not essential for an agent to successfully invoke the 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?

This tool has zero parameters, and the description correctly implies no inputs are needed. With 0 params, the baseline is 4; there is no parameter information the description would need to add.

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 the resource ('the plans and per-tier limits') and gives concrete detail (free, dev, pro), making it clear this returns pricing/plan data. It lacks an explicit verb like 'get', but the noun phrase is unambiguous and distinct from all 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 'No key required' note gives a clear usage signal: this endpoint is accessible without authentication, unlike many siblings. However, it does not explicitly state when to choose this tool over alternatives or when not to use it; the usage context is implied rather than stated.

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?

Goes far beyond the annotations: the key is shown once, is the only identity, is persistent, grants full account control, and must not be placed in a model transcript. The irreversible, no-recovery nature is explicitly disclosed.

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 and front-loads the most critical fact: the key is shown once. There is mild redundancy between 'only identity' and 'persistent identity', but every sentence carries operational weight.

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 a single parameter and no output schema, the description supplies all essential usage context: what is returned, that it is displayed once, how to store and protect it, and what the key represents. Nothing critical 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%, so the baseline is 3. The description adds no meaning about the handle parameter beyond the schema's format-only description, although the parameter name and example make its purpose reasonably inferable.

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 (create) and a concrete resource (a bearer key), making the tool's registration/identity-creation role clear. It does not explicitly contrast itself with sibling tools like vigil_revoke_key or vigil_anchor, so it misses the highest score.

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 implies this is the entry point ('No email, no account', free tier) and gives strong post-creation instructions. However, it never states when to choose this tool over alternatives or when not to use it.

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 mark this as mutating and destructive; the description adds useful context by noting it 'extends authority and refreshes the offline recheck window,' is security-sensitive, and requires keeping renewal credentials outside the controlled agent. 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?

Three tightly written sentences with the core action front-loaded. Each sentence adds a distinct operational or security fact, and there is no filler or repetition of schema content.

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 sufficiently covers the call's purpose, operational role, and security implications while the schema carries parameter details. It mentions the result in terms of 'a fresh signed token and new expiry,' though it could more explicitly route the agent to status- or revoke-related siblings.

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%, and the schema thoroughly documents lease_id and ttl_s including bounds, plus the deprecated vigil_key. The description adds no parameter-level detail beyond the schema, 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 opens with a specific verb and resource: 'Extend a lease with a fresh signed token and new expiry.' It also distinguishes the operation from stopping, revoking, or granting by explaining that renewal is how a healthy agent keeps acting.

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 situational guidance: 'Renewing is how a healthy agent keeps acting; stop renewing (or revoke) and it lapses.' This tells the agent when renewal is appropriate, though it does not explicitly name sibling alternatives such as vigil_grant_lease or vigil_lease_status.

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 goes well beyond the annotations. While annotations already declare destructiveHint=true and idempotentHint=true, the description adds critical behavioral context: the revocation is immediate ('stops authenticating immediately'), irreversible, cascades to leases and watchdogs, and has specific data-access consequences (private journal access lost, public receipts remain). It also clarifies a non-effect (does not cancel Stripe subscription). This is exemplary disclosure for a destructive operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded. The first sentence states the core action. The second sentence delivers the most critical warning (immediate, irreversible). The remaining sentences efficiently enumerate consequences and exclusions. Every sentence earns its place; there is no redundancy except the intentional repetition of 'Irreversible' for emphasis, which is acceptable given the stakes.

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 destructive, irreversible tool with no output schema, the description is remarkably complete. It tells the agent what happens immediately, what is permanently lost, what remains, and what is not affected. The only minor gap is the lack of an explicit statement about the return value, but for a void-like destructive action this is not critical. The annotations (destructiveHint, idempotentHint) plus the description cover all decision-relevant 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 100%, so the schema already documents the single optional vigil_key parameter thoroughly, including its deprecation and the preferred Bearer header alternative. The description adds value by clarifying the scope ('your own key') and the irreversible consequences, which helps an agent understand what the parameter-less call actually does. However, the description doesn't explicitly map the parameter to the behavior, so it doesn't quite earn 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?

The description opens with a specific verb and resource: 'Revoke your own key.' It immediately distinguishes this from sibling tools like vigil_revoke_lease and vigil_delete_watchdog by naming the exact object being revoked (the key) and the scope ('your own'). The subsequent consequences (stopping authentication, revoking leases, deleting watchdogs) further disambiguate it from related revocation 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 states when to use this tool: when you want to revoke your own key. It also provides an explicit exclusion: 'It does not cancel a Stripe subscription,' which helps an agent avoid a common confusion. However, it doesn't explicitly name alternative tools for related operations (e.g., vigil_revoke_lease for revoking a lease without deleting the key), so it falls just short of a 5.

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

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

Despite annotations already marking destructiveHint=true and idempotentHint=true, the description adds significant behavioral context: revocation is not instantaneous, the timing of enforcement, irreversibility for this lease ID, inability to renew, and that already admitted actions are not undone. This goes well beyond the annotations and gives the agent a clear picture of consequences.

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 concise, with four sentences focused on the core action and its key consequences. The critical warning about irreversibility is front-loaded, and every sentence contributes value without redundancy. It avoids unnecessary fluff while covering essential edge cases.

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 complexity (a destructive, irreversible operation) and that there is no output schema, the description covers the most important aspects: timing, irreversibility, and scope of impact. It does not describe the return value or any prerequisites, but those are less critical given the annotations and the simple parameter set. It is nearly complete for the agent's needs.

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 already describes both parameters (lease_id and the deprecated vigil_key) with coverage at 100%. The description does not add any parameter-specific meaning beyond what the schema provides. It merely references 'lease ID' without new details, so the baseline of 3 for high schema coverage 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 opens with a clear verb and resource: 'Revoke a lease.' It immediately distinguishes itself from siblings like vigil_grant_lease, vigil_renew_lease, and vigil_verify_lease by focusing solely on revocation. The subsequent details (timing, irreversibility) further solidify its unique purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides strong operational context, explaining when revocation takes effect (at recheck_by_ms or earlier) and that it is irreversible. However, it does not explicitly name alternatives or state when NOT to use this tool. The guidance is implied (use for revoking) rather than explicit about exclusions, but it is clear enough for an agent to infer the right use case.

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 (destructiveHint, etc.), the description reveals concrete behavioral details: a missed heartbeat triggers a signed 'absence' payload, retries failed delivery, caps at five attempts per armed interval, and overwriting resets timer/delivery state. These are non-obvious and not present in the schema, adding substantial value.

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 information-dense and front-loaded with the core purpose. It has some redundancy—the missed-heartbeat action is described twice ('Miss one and Vigil attempts...' and 'A missed heartbeat sends...'), and the retry cap is stated once but the second sentence partially repeats the trigger. It could be tightened without losing meaning, but overall it's efficient.

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 mutation tool with no output schema and five parameters, the description covers the essential workflow, limits, overwrite semantics, and delivery failure behavior. It does not mention what the tool returns (e.g., a receipt ID), but siblings like vigil_get_receipt suggest a return value might be expected; the description omits that. However, given the annotations and schema, the description is largely complete for invoking 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?

The input schema covers all parameters with descriptions (100% coverage). The tool description adds a little context, e.g., the webhook is 'signed' and 'capped at five attempts', and the message is 'supplied' on a missed heartbeat, but these are more about behavior than parameter meaning. The schema already defines constraints like interval range and URL pattern, so the description adds only marginal semantic value beyond 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 verb 'Arm' and the resource 'dead-man switch', then explains the mechanism: register interval + webhook, then call vigil_heartbeat. It distinguishes itself from siblings like vigil_heartbeat (sends heartbeats) and vigil_delete_watchdog (removes) by describing its setup/overwrite behavior.

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 instructs to call vigil_heartbeat before each interval, which guides the workflow. It also notes the overwrite behavior, implying this tool is used for both creation and reconfiguration. However, it does not explicitly mention alternatives like vigil_watchdog_status for checking state, so it stops short of full when-to-use vs when-not-to-use guidance.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful context that authentication is required and that the usage window is today. However, 'Requires your key' is ambiguous given the schema's deprecated optional vigil_key and preferred Bearer header, and no return or error behavior is disclosed.

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 no filler. The main result details are front-loaded, and the auth note is a single necessary additional sentence.

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 read-only tool with zero required parameters and no output schema, the description provides the high-level return contents and the auth expectation. It omits output shape and exact auth mechanism, but the schema covers the auth-header path, and the tool is simple enough that this is nearly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the deprecated vigil_key parameter and the preferred auth-header behavior. The description adds no real parameter-level detail, and 'Requires your key' could even be misread as requiring the deprecated argument.

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 identifies what the tool exposes: the current tier, its limits, and today's usage. It lacks an explicit verb like 'retrieves' and does not explicitly differentiate itself from siblings such as vigil_info or vigil_pricing, so it stops short of a top score.

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 usage context is implied: call this when you need your current tier, limits, or daily usage. However, there is no explicit when-to-use guidance, no mention of alternatives, and 'Requires your key' reads more as an auth prerequisite than as 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?

Annotations already mark the tool read-only, idempotent, and non-destructive; the description adds valuable behavioral context: offline execution, fail-closed semantics, expiration and recheck_by_ms constraints, and the explicit lack of live revocation or policy enforcement. No contradiction exists between description and 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 front-loaded with purpose and key behavior, but it repeats the same limitation list twice: once in the second sentence and again in the final sentence. The redundancy makes it less concise than it could be, though it remains structured and readable.

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 two simple parameters, the rich annotations, and the explicit success condition of allow=true, the description provides enough context to invoke the tool correctly. It could be more complete by stating the exact failure/error response shape, especially since there is no output schema, but this is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with lease and pubkey_hex already well documented, including the warning to never copy the key from the lease. The description reinforces the independently pinned key concept but adds little semantic value beyond the schema, so the baseline score 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 names a specific verb and resource: an offline, fail-closed check of a lease token against a pinned Ed25519 public key. It clearly distinguishes this from receipt verification and gateway policy checks, and states the exact success condition.

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 states what this tool is for and what it must not be used for, explicitly listing missing checks such as live revocation, agent identity, action, amount, and gateway policy. It does not name specific sibling tools as alternatives, but the context of mandatory gateway checks provides clear usage boundaries.

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 cover read-only, idempotent, and non-destructive. The description adds meaningful behavior: 'Read-only and local to Vigil' and the exact failure modes that produce valid=false (tampering, forgery, wrong signer, malformed input). This goes beyond the annotations and clarifies outcome semantics.

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 carry everything: verification target, key requirement, failure behavior, and read-only locality. Every sentence earns its place and the critical security constraint is front-loaded.

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 verification tool, the description covers invocation-wise preconditions, failure semantics, and behavior. The only minor omission is an explicit description of the success return (valid=true), though this is strongly implied by the false-case enumeration. No output schema exists, so the description carries the return contract reasonably well.

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 already provides 100% coverage with detailed parameter descriptions, including the 'independently pinned' and 'never copy it from the receipt' guidance. The description's mention of the key requirement is redundant. No additional meaning is added beyond what the schema already documents, so a 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 states exactly what the tool does: verify a receipt's hash and Ed25519 signature against a pinned public key. It names the resource ('receipt') and the operation ('verify') with enough specificity to distinguish it from sibling tools like vigil_verify_lease and vigil_verify_source.

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 usage context: the key must be mandatory, independently pinned, and must not come from the receipt being checked. It does not explicitly name alternatives or exclusions, but the domain-specific wording makes it obvious this is for verifying receipts rather than leases or sources.

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=true, idempotentHint=false), the description discloses the exact financial consequence ('settlement spends USDC irreversibly'), absence of refunds, the non-idempotency nuance (same args alone are not enough; need idempotency-key metadata and original payment proof), and the epistemic limit ('Does not establish absolute truth'). This aligns with and substantially extends the annotation signals.

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 and front-loaded: purpose first, then risk, then retry behavior. Every clause adds safety-critical information, though the final idempotency sentence is dense and could be structured a bit more clearly.

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 an output schema and annotations, the description handles the high-level purpose, safety, and retry behavior well. It falls short on completeness because the parameter semantics are almost entirely absent, and 'price and payment requirements' are referenced without pointing to a concrete source (e.g., vigil_pricing) or explaining how max_price_usd/max_age_seconds affect the call.

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 0%, and the description provides almost no mapping to the three parameters: it never explains `source_url`, `claim`, or the `options` object (max_price_usd, max_age_seconds). The only indirect link is 'price and payment requirements' hinting at cost, but that is insufficient to compensate for undocumented parameters.

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 'Paid source-local verification with exact evidence and signed receipt', which names a concrete action (verify a source), a distinguishing paid/source-local scope, and a deliverable (signed receipt). It does not fully unpack what 'source-local' means or compare against verify_receipt/verify_lease, but it is far from tautological.

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 text implies usage context with 'source-local' and 'Does not establish absolute truth', and it gives a clear precondition ('Read price and payment requirements before authorizing') plus retry guidance. However, it never states when to choose this tool over sibling verification tools or when not to use it, so selection guidance is only implicit.

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 establish that this is read-only, idempotent, and non-destructive. The description adds concrete behavioral detail by naming what the call exposes (interval, last beat, overdue, fired, exhausted), which goes beyond the annotation information and helps the agent understand the response.

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?

One dense, front-loaded sentence states the operation and the key state fields with no filler. Every word contributes to the agent's understanding.

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 low-complexity read-only status lookup with fully documented parameters and safety annotations, the description is nearly complete. The only minor gap is the lack of error semantics for an unknown watchdog name, but the listed state fields give a solid picture of what to expect.

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%, and the schema already explains the deprecated vigil_key and its preferred replacement. The description adds no parameter-level guidance, so the schema carries the semantic burden; 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 uses a specific verb ('Read') and identifies the resource ('a watchdog's state') while enumerating the exact state fields returned (interval, last beat, overdue, fired, exhausted). This is clearly distinct from siblings like vigil_set_watchdog or vigil_heartbeat.

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 intended use is implied by 'Read a watchdog's state' and the readOnlyHint. However, the description does not explicitly state when not to use it or point to alternatives, so an agent must infer the right choice from the verb and sibling names.

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