agent-notary

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

The description discloses key behavioral traits: idempotency per (committer, nonce), hash format (sha256(salt || sha256(content))), deadline format (ISO-8601), and context purpose. With no annotations provided, the description fully bears the burden of disclosure and does so thoroughly.

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 superfluous content. The first sentence states the core purpose, the second provides essential technical details. It is front-loaded and 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?

The description covers all necessary aspects: purpose, parameter formats (hash, deadline), context role, and idempotency. The presence of an output schema reduces the need to describe return values. Overall, it is complete for an agent to correctly invoke this 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?

Despite 0% schema description coverage, the description adds critical meaning: explains the commit_hash derivation, ISO-8601 deadline, context linking to escrow/job, and the idempotency key (committer, nonce). This compensates for the missing parameter descriptions in the schema.

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

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

The description clearly states the tool's purpose: 'Commit to a deliverable BEFORE handover.' It specifies the verb (commit) and resource (deliverable), and distinguishes itself from siblings like 'reveal' and 'verify' by focusing on the pre-handover commitment step.

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 before handover, providing temporal context. However, it does not explicitly contrast with siblings or state when not to use this tool. The sibling names help infer alternatives, but the description lacks direct 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?

Description adds behavioral context (salt/digest hidden pre-reveal) beyond the parameter schema. However, no annotations exist, and the description does not disclose other behaviors like error cases or post-reveal differences.

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?

Single sentence, concise and front-loaded, but omits important details that would improve usefulness without adding much length.

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?

Despite having an output schema, the description lacks details on response structure, post-reveal behavior, or error conditions. Insufficient for a status-checking tool with pre/post reveal states.

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 has 0% description coverage and the tool description does not describe the commitment_id parameter beyond its role in the overall operation. No format or source guidance provided.

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?

Description clearly indicates retrieving a commitment's current record and distinguishes pre-reveal state, but could be more explicit about it being a read operation among siblings like commit and reveal.

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 versus siblings like list_commitments or verify. Only implicit through the pre-reveal mention.

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 exist, and the description does not elaborate on what 'capabilities' or 'input contract' entails, nor any behavioral aspects like side effects or data access.

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?

Extremely concise at 4 words, front-loaded, 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?

While the output schema exists to explain return values, the description lacks context about what the agent is and the nature of capabilities; more detail would improve completeness.

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?

No parameters in the schema, so the description need not add parameter details; baseline score 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 'Return capabilities and input contract' clearly states the tool's function of returning an agent's capabilities and input contract, which is specific and distinct from sibling tools like commit or verify.

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 on when to use this tool compared to alternatives; no context provided for appropriate scenarios or prerequisites.

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 full burden. It states 'list' which implies a read operation, but does not explicitly confirm read-only behavior, side effects, auth requirements, or rate limits. Minimal disclosure beyond the 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 a single sentence, 10 words, front-loaded with verb and resource. No unnecessary 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 list tool with one optional parameter, the description is adequate. However, it lacks mention of pagination, ordering, or output format (though output schema exists). Could be more complete with default behavior.

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

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

The schema has 0% description coverage, but the description adds the enum values (PENDING, REVEALED, EXPIRED) for the 'state' parameter, which is helpful. However, it does not clarify the default behavior when state is null (presumably no filter).

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 'list' and resource 'commitments', and specifies optional filtering by state. It distinguishes itself from sibling tools like 'commit' or 'reveal' by focusing on listing.

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 for listing commitments with optional state filtering, but does not provide explicit when-to-use or when-not-to-use guidance relative to siblings like 'commitment_status' or 'verify'.

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. It discloses strict verification ('one bit of drift fails'), timeout behavior ('late reveals expire'), and output purpose ('delivery_proof for escrow release'). It does not mention idempotency or side effects beyond expiration, but the behavioral traits are 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 three sentences long, front-loaded with the action and resource, and each sentence adds essential information. There is no redundancy or 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?

Given the presence of an output schema (likely describing the return value) and the description's coverage of usage, behavior, and expiry, the tool is mostly complete. However, the lack of parameter descriptions is a notable gap, and the description could better leverage the 0% schema coverage to compensate.

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%, yet the description only alludes to 'digest + salt' without individually describing the three parameters (salt, commitment_id, content_digest). The 'commitment_id' parameter is not explained, leaving ambiguity. The description fails to add sufficient meaning beyond the schema's parameter names.

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 action ('reveal'), the resource ('committed content's digest + salt'), and the context ('after handover'). It also distinguishes from sibling tools like 'commit' and 'verify' by mentioning escrow release and verification against commitment.

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 specifies when to use the tool ('after handover') and notes that late reveals expire the commitment, implying time sensitivity. However, it does not explicitly state when not to use it or list alternative tools for different scenarios, though the context from siblings provides some implicit 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, the description carries full burden for behavioral disclosure. It adds the optional digest check, but fails to mention whether this is a read operation, side effects, or what happens on failure. The output schema is not described.

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 wasted words, front-loading the main action. Every sentence adds value.

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

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

For a simple tool with 2 parameters and an output schema, the description covers the core purpose but omits return value details and usage guidance. It is minimally adequate.

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. It maps 'commitment_id' to the resource and 'content_digest' to the optional check against received content, adding meaning beyond parameter names. However, it lacks specifics like format or constraints.

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 action (verify) and the resource (a revealed commitment), and distinguishes it from sibling tools like 'commit' and 'reveal' by specifying it is an independent verification after reveal.

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 on when to use this tool versus alternatives such as 'commit' or 'commitment_status'. The description does not mention context or prerequisites.

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