Vigil — an outside witness for AI agents

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

With no annotations, the description carries the burden of explaining behavior. It discloses that this is a proactive, likely mutating operation and that the chain is anchored automatically anyway. However, it does not mention potential costs, authentication requirements, failure modes, or what the tool returns.

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 concise sentence with no filler. The 'PRO:' prefix immediately signals access tier, and the core purpose plus the automatic-anchor context are front-loaded efficiently.

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 tool with one optional parameter, the description covers the action and the key usage context. However, the absence of an output schema and annotations means the agent is left without information about the response format, side effects, or any costs associated with this PRO feature, so the description is not fully complete.

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

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

Schema description coverage is 100%, so the only parameter, vigil_key, is already fully documented in the schema. The tool description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'anchor the current chain head to OpenTimestamps on demand.' It also distinguishes itself from the automatic anchoring process and, implicitly, from sibling tools like vigil_anchors or vigil_notarize by focusing on immediate, on-demand anchoring.

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 'on demand' combined with 'the chain is auto-anchored every few hours regardless' clearly indicates when an agent should call this tool: when an immediate anchor is needed instead of waiting for the periodic automatic anchor. It does not explicitly name an alternative tool, but the context 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?

With no annotations, the description carries the full burden. It does disclose two important behaviors: submissions are pending rather than verified Bitcoin confirmations, and no key is required. It doesn't state whether the operation is read-only, whether it has side effects, or what happens on failure. That's useful but incomplete; the pending-status caveat is valuable and prevents an agent from over-trusting results.

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-status caveat, and the auth requirement. No filler or repetition. The first sentence is a noun fragment rather than a clear verb clause, losing some efficiency but not much.

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 tool with no output schema, the description should say what a call returns or does. It strongly implies that the return is the set of public timestamp submissions, but it never explicitly states the operation or output shape. The caveats are helpful, but the lack of an explicit verb leaves the tool's behavior under-specified, though the low complexity mitigates the risk.

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 is a bare object, so there are no parameter semantics to document. The description doesn't attempt to invent parameters. Its 'No key required' line is auth context, not parameter info. This meets the baseline for zero-parameter tools.

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 a key attribute ('pending, not an independently verified Bitcoin confirmation'), but never states the action (e.g., list, fetch, monitor). Without a verb, the tool's operation is inferred from the plural name and zero-parameter schema rather than explicitly described. It also doesn't distinguish itself from `vigil_anchor` or `vigil_notarize` beyond the 'public' and 'no key' qualifiers.

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 provides an implied use case: public, keyless access to pending timestamp submissions. The 'No key required' line is a relevant access condition. However, there are no explicit when-to-use vs when-not-to-use instructions, no mention of alternatives such as `vigil_anchor`, and no guidance on whether this replaces or supplements other vigil tools.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose the read-only nature and the 'Max 1000 per call' cap, both genuinely useful. But it does not say what happens when the range exceeds 1000, how gaps in the chain are surfaced, or what the response contains.

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 sentences totalling 14 words, with the verb and resource front-loaded and the constraint placed at the end. Every word earns its place; nothing is redundant.

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

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

Adequate for a two-optional-parameter read tool, but with no output schema and no annotations, the description should hint at what the agent receives back (e.g., gap list, verification status, raw receipts). The 1000-cap also raises a pagination question that is not answered.

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 baseline is 3 and the schema already documents both parameters and their defaults. The description adds one useful constraint, the 1000-cap on range size, but does not clarify inclusivity of endpoints or ordering behavior.

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

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

States a specific verb ('Read'), resource ('a range of receipts'), and the audit purpose ('chain continuity'). The range-scope distinguishes it from siblings vigil_get_receipt (single receipt) and vigil_verify_receipt (verification), though no sibling is named explicitly and the distinction is implied 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 phrase 'to audit chain continuity' implies when this tool should be selected, and 'Max 1000 per call' hints at call-sizing. However, no alternatives are named and no when-not-to-use conditions are given, which is a real gap given the 25 sibling tools the agent must route among.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. The verb 'Remove' implies destructive intent, but the description does not disclose whether deletion is permanent, whether it can fail, what happens to associated data, or what permissions are required.

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 extremely short and front-loaded with the main action, which is structurally clean. However, it is under-specified: a single six-word sentence does not provide enough useful context for a destructive operation.

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 deletion tool with no annotations, no output schema, and an undocumented required parameter, this description is incomplete. An agent would not know what happens after removal, whether the operation is reversible, or how the name parameter should be supplied.

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

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

Schema description coverage is only 50%, with the required parameter 'name' having no description in either the schema or the tool description. The description does not clarify that 'name' identifies which watchdog to remove, nor does it address the vigil_key parameter's role or alternatives.

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 ('Remove') and a clear resource ('a watchdog'), and the action is distinct from sibling tools like vigil_set_watchdog and vigil_watchdog_status. However, it does not define what a watchdog is or explicitly contrast itself with related tools, leaving slight ambiguity.

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 no guidance on when to use this tool versus alternatives such as vigil_set_watchdog or vigil_watchdog_status. No prerequisites, consequences, or exclusion conditions 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?

With no annotations, the description carries the behavioral disclosure burden. It usefully states that the operation is publicly readable by anyone, which is important authorization context. However, it does not mention behavior on missing serial numbers, response format, or any other edge-case behavior beyond the basic fetch 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 exceptionally concise: two short sentences, with the core action front-loaded and the access note as useful supporting context. 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 simple one-parameter fetch tool with no output schema, the description is largely complete. It identifies the resource, the lookup key, and the public access model. It could mention what a receipt represents or what happens when no receipt matches, but the low complexity keeps this from being a significant 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?

The schema already fully describes the single parameter with 100% coverage. The description adds only 'by serial number,' which reinforces the parameter but does not provide extra meaning 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 a specific verb ('Fetch') and resource ('a receipt'), and identifies the key parameter ('serial number'). It does not explicitly differentiate from the sibling vigil_verify_receipt, which could plausibly be confused, so it stops short of a 5.

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 supplies access context ('Public — anyone can read any receipt') but provides no guidance about when to use this tool versus alternatives like vigil_verify_receipt or vigil_journal_get. There are no explicit conditions or exclusions to guide tool selection.

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

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

With no annotations provided, the description carries the behavioral burden and does well: it discloses the lease is short-lived, Ed25519-signed, verified offline, fail-closed, and limited to 1 active lease on the free tier. It does not describe the return value or failure/error behavior, but the core behavioral profile is clearly conveyed.

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 deliver the core behavior, the verification model, the operational boundary, and the free-tier limit. Every sentence earns its place, and the most important information 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?

Given the 5-parameter schema and 100% parameter coverage, the description provides a strong overall picture: what the lease is, how it is verified, what actions it guards, and a hard free-tier constraint. The main gap is that no output schema exists and the description does not explicitly state what the function returns or what happens when the free-tier limit is exceeded.

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 each parameter already has a meaningful description with constraints. The tool description adds context about lease semantics but does not add parameter-level meaning 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 names a specific verb ('Grant'), a specific resource ('short-lived, Ed25519-signed LEASE'), and the exact purpose: authorizing an agent to perform an action until expiry. It also distinguishes this tool from siblings like vigil_renew_lease and vigil_revoke_lease by focusing on the initial granting act and calling it 'the guard on a money/data-moving action.'

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

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

The description gives clear context: this is the guard for authorizing money/data-moving actions, with offline fail-closed verification by a customer-run gateway. It implies when to use it but does not explicitly contrast it with sibling tools such as renew, revoke, or verify, so no exclusion or alternative guidance is 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?

With no annotations to carry the safety/behavior burden, the description does disclose the main side effect: the call resets the watchdog timer. It doesn't cover authentication requirements, error behavior, or consequences of an expired/missing watchdog, but for a simple keep-alive action the key behavior is present.

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 core action and the invocation frequency are both stated in two short sentences. The opening 'Still alive.' is somewhat decorative, which prevents a full 5, but it doesn't bloat the definition.

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 two-parameter tool with no output schema and no nested objects, the description covers the main purpose and operational frequency. It falls short by not explicitly explaining the 'name' parameter or the relationship to watchdog setup, though these can be loosely inferred from the resource word 'watchdog.'

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 required 'name' parameter has no schema description, and the tool description only indirectly implies it is the watchdog identifier. The optional 'vigil_key' parameter is already well documented in the schema, so the description adds only marginal parameter meaning rather than fully compensating for the gap.

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

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

The description identifies a specific action—'Reset a watchdog's timer'—on a concrete resource, which is enough to distinguish it from sibling tools like vigil_set_watchdog, vigil_watchdog_status, or vigil_delete_watchdog. The 'Still alive.' framing reinforces the liveness/heartbeat semantics without obscuring the 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 phrase 'Call this at least once per interval' gives an explicit timing requirement for using the tool. However, it doesn't mention alternative tools or when not to use it, and it doesn't state a prerequisite such as the watchdog needing to exist or be set up first.

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?

No annotations are provided, so the description carries the behavioral transparency burden. It discloses the auth requirement and the main data returned: service description, Ed25519 signing pubkey, chain head, and free-tier limits. It does not mention output format, freshness, or error behavior, but for a simple info tool the disclosed details are meaningful and non-obvious.

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 one compact sentence that front-loads the core subject and then lists the concrete returned items. The final 'No key required' is a valuable addition with no wasted words. Every element 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 parameterless info endpoint, the description names the key pieces of information an agent would expect: service description, verification pubkey, chain head, and free-tier limits. It also covers the access requirement. A minor gap is the lack of response format or error details, but the tool is simple enough that this does not prevent correct invocation.

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

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

The input schema has zero parameters, so the baseline is 4. The description adds a relevant input-related detail by stating that no key is required, which helps an agent determine what credentials or inputs are needed. There are no parameters to document beyond this.

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 the tool's resource: it exposes service metadata including the Ed25519 pubkey, current chain head, and free-tier limits. It lacks an explicit verb like 'get' or 'return', but the content is specific enough that an agent can understand what the tool does. It does not explicitly distinguish it from sibling tools, but the listed items are unique enough to avoid obvious confusion.

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 says 'No key required,' which is a clear and useful usage signal for when the tool can be called without authentication. It gives practical context about the tool's accessibility, though it does not explicitly name alternative tools or exclusion conditions. For a general info endpoint, this is sufficient 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the destructive nature of the operation but does not mention permanence, side effects, authentication requirements, or what happens if the slug does not exist.

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 short sentence with no redundant wording. It is front-loaded and efficient, though it leans toward under-specification rather than structured completeness.

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 operation with no annotations and no output schema, the description is too thin. It omits important context such as authentication via bearer header, reversibility, and result expectations, leaving an agent under-informed.

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

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

Schema description coverage is only 50%, with the required 'slug' parameter undocumented in the schema. The description does not clarify how the slug identifies the journal slot or whether the optional vigil_key affects behavior, so it fails to compensate for the schema gap.

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 ('Delete') and a resource ('journal slot'), which clearly states the core operation. It also differentiates from sibling tools like vigil_journal_get, vigil_journal_list, and vigil_journal_put, though the term 'slot' could be more precise.

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 guidance is given about when to use this tool versus alternatives. There is no mention of prerequisites, deletion semantics, or what distinguishes deleting a journal slot from other journal operations.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does add useful behavior beyond simple 'fetch' by stating that the response is base64 and that decryption must happen client-side. However, it omits other behavioral context such as authentication requirements, error behavior, or what happens when the slug does not exist, so it is not fully transparent.

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. It communicates the core action and the key return behavior efficiently, and every part 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 fetch tool with two parameters and no output schema, the description is usable but incomplete. It states the return format but does not explain slug semantics, authentication expectations, or error cases. The missing details are not fatal, but an agent would benefit from more guidance to invoke this correctly in all contexts.

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 documents vigil_key but leaves slug undocumented, and the description only restates that the journal is fetched 'by slug' without adding meaning about slug format, constraints, or relationship to other journal operations. With schema description coverage at 50%, the description should compensate more for the undocumented slug parameter but does not.

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

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

The description states a specific verb and resource: 'Fetch a journal blob by slug.' The slug parameter is identified as the retrieval key, which clearly differentiates this from siblings like vigil_journal_list, vigil_journal_put, and vigil_journal_delete. An agent can tell what the tool does 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?

The description gives no guidance on when to use this tool versus alternatives such as vigil_journal_list or vigil_journal_put. It implies use when you have a slug and want the journal blob, but it does not surface exclusions or alternative selection criteria. This is minimal and leaves the agent to infer usage context.

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

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

With no annotations, the description carries the behavioral disclosure burden. It accurately implies a read-only listing operation and scopes results to 'your' journal slots, but it doesn't detail authentication expectations, pagination, ordering, or any side effects. The behavior is simple enough that this is acceptable but not fully 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 concise sentence that front-loads the action, resource, and output fields. It contains no fluff or redundant phrasing.

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 low complexity, one optional parameter, and no output schema, the description provides the essential usage and return shape information. It could mention auth or ordering, but the input schema already covers the credential behavior, making the tool 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 description coverage is 100% for the single optional vigil_key parameter, and the schema itself provides detailed guidance about using the Authorization header instead. The description adds no extra parameter meaning, which is fine because the schema already covers it.

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 the specific verb 'List' with a clear resource, 'journal slots', and enumerates the returned fields: slug, size, last-updated. This makes it immediately distinguishable from sibling tools like vigil_journal_put and vigil_journal_delete.

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 indicates when to use the tool: when an agent needs to list journal slots rather than fetch, create, or delete a specific slot. It doesn't explicitly name alternatives like vigil_journal_get, but the usage context is clear from the objective phrasing.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so well. It explicitly warns that the server stores exactly the bytes supplied and cannot enforce client encryption, discloses that writes overwrite existing content, and exposes free-tier slot and size limits. This is unusually transparent for a mutation tool.

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 core action, the overwrite consequence, the client-side encryption requirement, the base64 encoding requirement, and resource limits. Every sentence carries distinct information and 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?

For a simple write tool with no output schema, the description covers the essential calling requirements: what to store, how to encode it, what security caveat applies, and what quota limits exist. It omits explicit return-value behavior, but the core invocation is well-specified and the schema supplies the remaining parameter and auth-header guidance.

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 slug, data_base64, and vigil_key. The description still adds meaningful semantic context by emphasizing that data_base64 must contain already-encrypted bytes, that the blob is opaque to the server, and that the free tier imposes a 64KB per-slot ceiling, which an agent needs to know before invoking.

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 the specific action 'Store an opaque blob under a slug' with the resource being a journal entry addressed by slug. The parenthetical '(overwrites)' adds a key behavioral differentiator, and the use of 'opaque blob' clearly distinguishes this write-oriented tool from siblings like vigil_journal_get, vigil_journal_delete, and vigil_journal_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?

The description gives clear operational guidance: encrypt client-side, send exactly the supplied bytes, and base64-encode the data. It does not explicitly name alternative tools or state when not to use this one, but the context is sufficiently clear that an agent can infer the write-intent versus sibling read/delete/list operations.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. 'List your leases and their states' implies a read operation, but it does not explicitly state that it is read-only or disclose pagination, response structure, ordering, or whether all leases are returned regardless of state.

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 one focused sentence with a clear verb and object, no filler, and no repetition of structured schema information. It is efficient and 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 simple tool with no required parameters and no output schema, the description names the result (leases and states) but omits potentially useful context like pagination, definitions of the lease states, and how to choose this tool among many lease-related siblings. It is minimally adequate but not complete for navigation.

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 is fully documented in the schema, including its legacy nature and the preferred Bearer header alternative, giving 100% schema description coverage. The description itself adds no parameter-level detail, which matches the baseline for high coverage.

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

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

The description identifies a specific verb ('List') and resource ('your leases') and notes the output focus ('their states'). It is clear, but it does not explicitly distinguish this from sibling tools like vigil_lease_status or vigil_verify_lease, which also concern leases.

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 guidance is provided about when to use this tool versus alternatives such as vigil_lease_status, vigil_renew_lease, or vigil_verify_lease. The description simply states the listing action without specifying contexts, exclusions, or preferred alternatives.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It usefully reveals that the tool is public, requires no authentication key, and returns lease lifecycle states. However, it does not disclose behavior for invalid or unknown lease IDs, data freshness, or whether any side effects occur, which leaves some ambiguity for a tool with zero annotation coverage.

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 short sentences with no filler. It front-loads the primary purpose, then adds the key usage context and authentication note. Every sentence earns its place.

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

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

For a simple one-parameter status tool with no output schema, the description covers the core purpose, possible statuses, the intended consumer, and the absence of auth requirements. It is slightly thin on what exactly the response looks like and how errors are handled, but the essential information an agent needs to invoke it correctly is present.

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%, so the description must compensate for documenting the lease_id parameter. It implies that the lease_id identifies the lease whose status is checked, and 'No key required' helps clarify that lease_id is not an API key. But the description never explicitly mentions lease_id, its format, or how to obtain a valid lease ID, leaving the parameter under-explained.

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 the tool as a status check for a lease, enumerating the possible states (active / expired / revoked) and the polling use case. It does not explicitly name or contrast itself with siblings like vigil_verify_lease or vigil_leases, but the 'public status' framing gives it a distinct identity.

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 clear usage context: this is what a gateway polls for revocation, which tells an agent when to choose this tool. It also states that no key is required, a useful prerequisite. It does not explicitly mention alternatives or when not to use it, but the context is sufficiently 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?

With no annotations provided, the description fully discloses the behavioral profile: it is a POST that returns a receipt with specific cryptographic properties, describes the trust model (chain position over timestamps), and states the free-tier rate limit. This goes well beyond the input schema and gives an agent a clear picture of side effects and guarantees.

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 crafted sentences: the first states the core operation and output, the second clarifies a subtle trust-model point, the third gives the rate limit. No filler, no repetition of schema prose, and key information 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?

With no output schema, the description explains the receipt's key attributes (signed, stamped, hash-chained, serial-numbered) sufficiently. It also covers the rate limit and the public-chain semantics. It doesn't describe the exact response envelope or potential errors, but for a notarization action the essential context is present.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description only reinforces the sha256 format already stated in the schema and adds no new information about label or vigil_key. It meets the baseline for high coverage but does not add extra semantic value.

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 operation ('Notarize work'), the input (sha256 of anything), and the output (signed, hash-chained receipt). It clearly distinguishes this from sibling tools like vigil_verify_receipt and vigil_get_receipt by focusing on the creation of a notarization record.

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

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

The description clearly implies when to use this tool: when you need a notarized proof-of-existence for a hash. It gives useful context ('the proof of when is the position in the public chain') and rate-limit info, but it does not explicitly name alternatives or state when-not-to-use.

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

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

With no annotations present, the description carries the full behavioral disclosure burden. It conveys that this is a public lookup requiring no key, which meaningfully hints at a safe read-only operation. It does not describe response formatting, but the expected behavior is simple and adequately conveyed.

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 short sentences with no filler. The main subject (plans and per-tier limits) is front-loaded, and the practical auth detail is appended efficiently.

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 informational tool with no output schema, the description is largely complete: it states what is returned and that no key is required. A more explicit statement of the return format would improve it slightly, but nothing essential for invoking it 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?

The tool accepts zero parameters, and the empty input schema fully documents that. The description adds useful context about what information is returned, so no 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 clearly identifies the resource as pricing plans and per-tier limits, naming the specific tiers (free, dev, pro). It lacks an explicit verb like 'retrieves' or 'lists,' but the intent is unambiguous and distinct from the sibling tools.

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

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

The description provides clear context for when this tool is relevant: when a user needs plan information or tier limits. The note 'No key required' adds practical usage guidance by indicating authentication is not a prerequisite, though it does not explicitly contrast this tool with alternatives.

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

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

With no annotations provided, the description carries the full behavioral burden, and it does so exceptionally well. It discloses that the bearer key is shown exactly once, must be stored, is the sole identity, and that there is no email/account recovery mechanism. It also states the free-tier starting state, giving the agent important operational context beyond the simple 'create' action.

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 extremely concise and front-loaded with the core action, then each short sentence adds valuable behavioral detail. There is no filler, and the urgent 'shown ONCE — store it' instruction is placed immediately after the main verb.

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 one parameter and no output schema, the description covers the essential operational context: why to call it, what it returns, and important caveats about storage and account recovery. It does not detail the response format or field names, but given the tool's simplicity, the missing pieces are minor rather than critical.

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

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

The input schema already provides 100% coverage of the single parameter, including format constraints for 'handle'. The tool description does not add extra semantic meaning about how 'handle' relates to the generated key, so a baseline score of 3 is appropriate because the schema does the heavy lifting.

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 the specific verb-resource pair 'Create a key' and immediately clarifies the resource's role as an identity ('your only identity'). It distinguishes this tool from the sibling set by focusing on registration and key issuance, and the one-time display rule makes the purpose unmistakable.

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: use this tool when you need a new bearer key/identity, and it emphasizes there is no email or account recovery, implying this is the entry point for onboarding. It does not explicitly name alternatives, but for a register tool the context is strong enough that an agent would not confuse it with a lease, watchdog, or revocation tool.

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

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

With no annotations, the description carries the full burden. It discloses the core effect (fresh signed token, new expiry) and the lapse-on-stop behavior. However, it omits important behavioral details such as authentication expectations, idempotency, failure modes, or what becomes invalidated.

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 tight sentences, front-loaded with the action and effect. The lifecycle analogy adds context without bloat. Every sentence earns its place.

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

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

For a mutation tool with no annotations, no output schema, and minimally described parameters, the description is too thin. An agent still lacks ttl_s semantics, authentication guidance, expected response, and how renewal interacts with revocation.

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 33%, and the only documented parameter is vigil_key. The description vaguely maps 'new expiry' to ttl_s and 'a lease' to lease_id, but it does not explain ttl_s units, allowed ranges, or lease_id format, leaving the agent to guess.

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 ('Extend') and resource ('a lease') and clarifies the mechanism: a fresh signed token and new expiry. It clearly distinguishes renewal from granting or revoking, though it does not explicitly name a sibling tool.

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 second sentence gives lifecycle context: renewing is how a healthy agent keeps acting, and stopping renewal or revoking lapses the lease. This implies when to use the tool but does not explicitly compare it to vigil_grant_lease or vigil_revoke_lease.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by stating two important consequences: authentication stops immediately and the action is irreversible. It does not mention authentication requirements or what happens to dependent artifacts, but the key behavioral traits are covered.

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 short sentences with no filler or redundancy. Key facts are front-loaded ('Revoke your own key') followed immediately by the most important 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?

For a simple one-parameter tool with no output schema, the description covers the essential information: what is revoked, how quickly it takes effect, and that it cannot be undone. It could additionally clarify the authentication requirement, but the schema's parameter description already addresses the legacy credential versus Bearer header choice.

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 one parameter is already well documented in the schema. The description adds no additional parameter semantics beyond what the schema provides, which matches the baseline for high schema coverage.

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

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

The description states a specific action ('Revoke') and a specific resource ('your own key'), which clearly identifies what the tool does. 'Your own' disambiguates it from sibling tools like vigil_revoke_lease or vigil_delete_watchdog, so an agent can distinguish it without inspecting other 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 clearly implies when to use the tool: when the caller needs to revoke their own API key. It does not explicitly name alternatives or state when-not-to-use, but the self-scoped wording gives enough context to avoid confusion with lease or watchdog revocation.

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

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

With no annotations, the description carries the full disclosure burden and adds valuable, non-obvious behavior: revocation is not instantaneous and old offline tokens remain valid until recheck_by_ms (at most 30 seconds). This gives the agent correct expectations about timing and eventual enforcement.

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 concise sentences with no filler. The main action is front-loaded, followed by two relevant caveats that each earn their place.

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

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

The description explains important timing behavior but omits any indication of return value, success/failure semantics, or prerequisites such as authorization. For a mutating tool with no output schema and no annotations, this leaves a moderate 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 coverage is only 50% because lease_id has no schema description. The tool description does not explain lease_id beyond the obvious 'revoke a lease' implication, and it adds nothing about vigil_key beyond what the schema already 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?

The description uses a specific verb and resource ('Revoke a lease') and clearly states the operation's purpose. It doesn't explicitly contrast with sibling tools like vigil_grant_lease or vigil_renew_lease, but the action is 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?

No explicit guidance on when to choose this tool over siblings or what conditions require revocation. The description focuses on post-revocation behavior rather than selecting this tool vs alternatives.

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

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

With no annotations provided, the description carries the full burden and discloses important behavior: a missed heartbeat causes exactly one signed 'absence' POST to the webhook, and the free tier allows one watchdog. It does not mention auth requirements, idempotency, or response details, but the core behavioral contract is clear.

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 the action and followed by the operational consequence. 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 tool with no output schema and no annotations, the description adequately covers the lifecycle, the trigger condition, and the free-tier limit. It leaves out return-value and error semantics, but those are minor for a straightforward watchdog-creation operation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds workflow context for interval_s and webhook_url but does not need to explain each parameter further.

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 specific verbs ('Arm', 'Register') and defines the exact artifact: a dead-man switch with an interval and webhook, plus the required follow-up call to vigil_heartbeat. This clearly differentiates it from sibling heartbeat, status, and deletion 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?

It gives a clear usage sequence: register interval and webhook first, then call vigil_heartbeat before each interval elapses. It does not explicitly say when not to use this tool versus alternatives, but the intended workflow is evident.

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

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

With no annotations, the description must carry the behavioral burden. It implies a read-only lookup and mentions key requirements, but it does not explicitly confirm there are no side effects, nor does it describe response format, error behavior, or how usage limits are calculated.

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 short, focused sentences. The main return content is front-loaded, and the authentication note is kept separate, making it easy for an agent to parse quickly with 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?

The tool is simple with only one optional parameter and no output schema, so the description covers the core purpose and credential requirement. However, it omits any detail about response structure, what 'limits' means in practice, and how to distinguish this from other vigils info tools, leaving some gaps for an agent.

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

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

The input schema fully describes the vigil_key parameter, including the preferred Authorization header alternative, so the description adds little. 'Requires your key' is consistent with schema semantics but does not enhance parameter understanding beyond what the schema already provides.

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 what the tool reports: current tier, limits, and today's usage. It is specific enough to distinguish it from most sibling tools, though it lacks an explicit verb like 'retrieve' or 'get' and could still be confused with vigil_info.

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 a prerequisite ('Requires your key') but provides no guidance on when to choose this tool over alternatives such as vigil_info or vigil_pricing, and does not mention exclusions or preferred contexts.

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

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

With no annotations, the description carries the full transparency burden. It does this well by disclosing offline behavior, fail-closed semantics, default pubkey behavior, the exact allow condition, and the need to poll status for revocation. It stops short of describing failure modes, error responses, or behavior for malformed tokens, but the core decision logic is transparent.

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, each carrying distinct value: the mode and posture of the check, the precise allow condition, and the follow-up action. The description is front-loaded with the most important qualifiers ('Offline, FAIL-CLOSED') and contains no filler.

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

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

For a two-parameter offline verification tool, the description gives an agent nearly everything needed to invoke it correctly: required input, optional override with default, result semantics, and a follow-up safety step. The main gap is the lack of an output schema or explicit description of the response shape beyond 'allow=true', and edge-case behavior for invalid signatures is only implicit in 'FAIL-CLOSED'.

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

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

Schema description coverage is only 50%, so the description meaningfully compensates by explaining that the check is 'against a pinned pubkey (defaults to this server's key)' — this gives real semantic content to pubkey_hex and clarifies it is optional. The lease parameter is already documented as 'A full lease token from vigil_grant_lease' in the schema, and the description reinforces its role.

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 ('check of a lease token'), a clear resource, and sharp constraints ('Offline, FAIL-CLOSED', 'allow=true only if the signature verifies and the lease has not expired'). It also sets itself apart from status-style endpoints by noting the gateway should poll status for revocation, making the verification tool's niche clear.

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 conveys when to use this tool: for offline, fail-closed lease checks that never rely on network state. It also gives a usage boundary by stating that revocation must be confirmed by polling status. However, it does not explicitly name alternative sibling tools such as vigil_lease_status or specify when not to use this tool beyond the revocation caveat.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses the cryptographic verification behavior, the self-attestation path, the self_attested=true flag, and the limitation that self-attestation is only a convenience. It does not describe return/error behavior on invalid signatures, but the disclosed caveats go well beyond the schema.

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

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

Two sentences with no filler. The first sentence states the core action and trust requirement; the second provides the critical optional-parameter caveat. Information is 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 tool with a nested object, no output schema, and no annotations, the description is largely complete: it defines the operation, the required input, the optional parameter's semantics, and the credibility caveat. The main missing piece is the exact return shape or error behavior on failed verification, which an output schema would normally cover.

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 meaningful semantics beyond the schema by explaining key provenance for pubkey_hex, the out-of-band confirmation requirement, and the behavioral consequence of omission. It also clarifies that receipt should be a full object returned by vigil_notarize or vigil_get_receipt.

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: 'Verify a receipt's hash and Ed25519 signature against a pubkey you trust.' This clearly identifies the tool's function and distinguishes it from sibling verification tools like vigil_verify_lease and vigil_verify_source by focusing specifically on receipts.

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

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

The description gives explicit guidance for when to supply pubkey_hex versus when it can be omitted, including the source of the trusted key ('from vigil_info, confirmed out-of-band') and a warning that self-attestation is 'not independent proof.' It does not explicitly exclude alternative tools, but it provides strong contextual 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?

Beyond annotations, the description discloses the paid financial side effect, the promise of 'exact evidence and signed receipt', and the epistemic limitation 'Does not establish absolute truth'. It also documents idempotent retry behavior with payment proof, which is consistent with and extends the idempotentHint=true annotation. No contradiction with annotations 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?

The description is three short sentences with no filler. The core action and purpose are front-loaded, followed by the critical caveat and the essential operational retry instruction. Every sentence earns its place.

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

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

For a paid tool with an output schema, the description covers the most critical operational context: pricing, payment proof, idempotent retry, and the limitation regarding absolute truth. It lacks explicit sibling routing and parameter mapping, but the presence of an output schema and the tool's focused purpose keep this from being a serious omission.

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 does not mention source_url, claim, options, max_price_usd, or max_age_seconds by name or meaning. The only oblique hint is 'price', which gestures at cost but does not explain how to use max_price_usd or how the options affect verification behavior.

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

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

The description clearly defines the action as 'source-local verification' with 'exact evidence and signed receipt', which names the resource and expected outcome. It also adds the important caveat that it 'does not establish absolute truth', giving the tool a distinct epistemic role. It does not explicitly name sibling tools, but 'source-local' separates it from lease/receipt verification 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 description gives explicit preconditions: 'Read price and payment requirements before authorizing' and instructs to retry with the same vigil/idempotency-key metadata and payment proof. This provides clear operational context. It stops short of explicitly stating when to prefer this tool over siblings like vigil_verify_lease or vigil_verify_receipt.

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

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

With no annotations, the description carries the burden of conveying side effects. 'Read' clearly signals a non-mutating inspection, and the listed fields tell the agent what state information will be exposed. It does not detail authentication or error behavior, but that is partially addressed by the vigil_key parameter description in the schema.

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

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

The description is a single front-loaded sentence with no filler. It leads with the operation ('Read a watchdog's state') and then lists the useful state components, earning its place with every word.

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 operation, listing the state fields is helpful, especially since there is no output schema. However, the description does not explain how the required name parameter maps to a watchdog, how errors are signaled, or what distinguishes this from closely named status/info siblings. Some additional routing or error context would make it fully complete.

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

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

Schema description coverage is only 50%, and the required 'name' parameter has no schema description. The tool description never states that the watchdog is identified by name, leaving the agent to infer it from 'a watchdog's state.' This does not meaningfully compensate for the undocumented required parameter.

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' with a clear resource, 'a watchdog's state,' and enumerates the key state dimensions (interval, last beat, overdue, fired, exhausted). This distinguishes it well from sibling tools like vigil_heartbeat, which sends a beat, or vigil_set_watchdog, which creates 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?

The description implies usage: call this tool when you need a watchdog's current state. However, it does not explicitly state when to prefer this over related tools such as vigil_info, vigil_lease_status, or vigil_get_receipt, nor does it mention any exclusions or preconditions.

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