agent-notary

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

The description adds real behavioral content — the hash construction, deadline format, and escrow linkage — which the annotations do not cover. But it asserts 'Idempotent per (committer, nonce)' while annotations set idempotentHint=false, so the agent receives conflicting signals about retry safety. It also does not say what happens when a deadline passes or whether a commit can be superseded.

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 critical timing constraint is front-loaded, and the remaining clauses are dense but purposeful, each mapping to a different parameter or behavior. The semicolon-chained style is terse to the point of being cryptic in places, but 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?

An output schema exists, so not explaining return values is acceptable, and the description covers the hashing and escrow aspects of a fairly specialized tool. It still leaves gaps around failure modes, whether a commit is revocable, and the identity/authorization implied by 'committer', which matter for a mutation tool.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, and it largely does: commit_hash is defined by an explicit formula with output length, deadline is constrained to ISO-8601, context is tied to the escrow/job, and nonce is implied as the idempotency key. Only 'committer' is left unexplained, which keeps it below a 5.

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

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

Uses a specific verb ('Commit') on a specific resource ('a deliverable') and adds a timing condition ('BEFORE handover'). It does not explicitly distinguish itself from siblings like commitment_status, list_commitments, or reveal, so it falls 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 phrase 'BEFORE handover' gives one sequencing rule, which implies usage context. However, there is no guidance on when to prefer this over the related tools (verify, commitment_status, seal_outcome_receipt) or what preconditions must hold before calling it.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context that salt and digest remain hidden before reveal, but does not explain authentication needs, error behavior, or what 'current' includes beyond the hidden fields.

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 redundant wording. Every phrase, including the pre-reveal caveat, adds some distinguishing detail.

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

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

For a simple read-only lookup with an output schema and rich annotations, the description is adequate but not complete. It does not clarify the relationship to sibling commitment tools or the meaning of commitment_id, both of which an agent would need to select the tool confidently.

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

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

There is one required parameter, commitment_id, with 0% schema description coverage, and the description does not define its expected format or meaning beyond the obvious name. The description therefore fails to compensate for the missing schema documentation.

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 phrase 'Current record for a commitment' identifies the resource and scope, but omits an explicit verb and does not distinguish this from siblings such as get_orc_commitment or list_commitments. The parenthetical clarifies the pre-reveal state, yet the core purpose remains only implied rather than stated as a concrete 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?

There is no guidance on when to call this tool versus get_orc_commitment, list_commitments, or reveal. The description gives no conditions, exclusions, or prerequisites, leaving the agent to infer usage from the tool name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world behavior, so the safety profile is covered. The description adds that the response covers capabilities and the input contract, but does not discuss auth, limits, or return shape, though an output schema 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 one front-loaded sentence with no filler. For a zero-argument introspection tool, this is appropriately minimal.

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?

Low complexity, zero parameters, rich annotations, and an output schema mean little description is needed. It states the return content, though it could do more to signal when an agent should call it instead of the operational sibling tools.

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

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

The tool has zero parameters, so there are no parameter semantics to document. The baseline score of 4 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 gives a specific verb ('Return') and resources ('capabilities and input contract'), making the introspection role clear. It does not explicitly contrast with the sibling green-certificate tools, so it stops short of full sibling differentiation.

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?

There is no explicit when-to-use guidance, no prerequisites, and no named alternative; the introspection purpose is only implied by the description and tool name. An agent must infer that this is the discovery or service-description call.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that by disclosing the result fields (digest, issuer, profile, attestation, registered_at) and the NotFound outcome, which tells the agent how to handle a miss.

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

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

Two compact clauses with no filler, and the core question is front-loaded before the return details. The phrasing "Registry lookup:" is slightly jargon-heavy but still 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?

With a rich annotation set and an output schema, the description need not explain return structure, yet it still summarizes the result fields and NotFound case. The remaining gap is the meaning and expected format of the sole required parameter, plus any note on notary context or access requirements.

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 single parameter "commitment" carries no description or format in the schema. The description does not compensate: it never explains what form the commitment takes, how it is derived, or whether it is an ID versus a hash, leaving the required argument underspecified.

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 ("Registry lookup") and frames the exact question answered: whether an ORC commitment is sealed by this notary. It also names the returned fields and the NotFound outcome, which distinguishes it from siblings like list_commitments or commitment_status, though it never explicitly contrasts them.

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

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

Usage is implied by the framing question ("is this ORC commitment sealed by this notary?"), so an agent can infer this is a point lookup for a single commitment. There is no explicit when-to-use vs when-not guidance and no mention of the sibling tools such as commitment_status, verify, or list_commitments.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds only the optional state filter and does not disclose ordering, pagination, or default behavior beyond the word 'optionally.'

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?

It is one short, front-loaded sentence that states the purpose and filter values with no redundant wording.

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 annotations and an output schema covering safety and return shape, the main remaining gaps are disambiguation from sibling tools and explicit default behavior when state is omitted. It is adequate for a simple list operation but 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 0%, and the schema itself lacks an enum for state. The description compensates by naming the allowed values PENDING|REVEALED|EXPIRED and noting that state is optional, though it does not explicitly say that null or omission means all 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: 'List commitments.' This clearly distinguishes it from get_orc_commitment, but it does not explicitly contrast with siblings such as commitment_status.

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

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

It states that state filtering is optional, which implies usage for both filtered and unfiltered listing. However, it gives no explicit guidance on when to use this tool versus siblings or when not to use it.

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

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

The description adds meaningful behavior beyond the annotations: verification fails on one bit of drift, a delivery_proof is returned for escrow release, and late reveals expire the commitment. These are important operational traits not conveyed by readOnlyHint=false, destructiveHint=false, or idempotentHint=false. It does not discuss permission or authentication requirements.

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 tight sentences with no wasted wording. The core action is front-loaded, followed immediately by verification behavior and the delivery_proof outcome.

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 non-readonly commitment operation, the description covers the key workflow, failure condition, and expiry behavior, and an output schema exists for return details. However, with all three parameters undocumented in the schema, the definition leaves parameter-level semantics largely unexplained.

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 carries the full burden for three required parameters. It conceptually maps commitment_id, salt, and content_digest through phrases like 'commitment' and 'digest + salt', but it gives no format, source, or validation details for any 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 states a specific verb and resource: reveal the committed content's digest and salt after handover. It is clearly distinct from a generic reveal, and the commitment context separates it from most sibling tools. It does not explicitly contrast with verify or commitment_status, so it stops short of full sibling differentiation.

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

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

It gives clear timing guidance: use after handover, and late reveals expire the commitment. That tells the agent the operational window and the consequence of missing it. It does not name an alternative tool or explicitly state when not to use this one.

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

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

The description adds real behavioral context beyond the annotations: the notary attests integrity and time but not correctness, only digests are stored (no floats in output), and verification works at two levels (offline L1, registry L2). The annotations already cover safety hints, so this is a genuine supplement. It does not mention that the call is non-idempotent, i.e. whether re-sealing the same output yields a new receipt, which is the one meaningful behavioral gap.

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

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

Front-loaded with the core action and the return value, followed by the important trust-boundary caveat ('integrity and time, not correctness') and a spec pointer. Every sentence carries information; the only slightly awkward element is the trailing file-path reference, which assumes the agent can read local docs.

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?

An output schema exists, so return-value shape need not be described, and the L1/L2 verification model and trust boundary are well covered. However, for a tool with five parameters, nested objects, and no schema descriptions, the complete absence of parameter guidance leaves the definition short of what an agent needs to invoke it correctly.

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

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

Schema description coverage is 0% across five parameters, three of them free-form nested objects ('output', 'subject', 'bindings') and one an array of strings ('excludes'). The description explains none of them: not what 'profile' selects, not what belongs in 'bindings' versus 'subject', not what 'excludes' removes from the digest. For a tool whose core semantics live in these objects, this is a substantial omission.

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

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

The description names a specific verb+resource pair: sealing an agent output as an "Outcome Receipt (ORC v0.1)" and registering its commitment. It distinguishes this from the notary's other operations implicitly by describing the receipt/registry duality. It falls short of 5 because the distinction from the sibling 'commit' tool (which also sounds like it registers commitments) is never made explicit.

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

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

Usage is implied: you call this to seal an output and produce a verifiable receipt. But there is no explicit when-to-use versus 'commit', 'verify', or 'reveal', and no stated prerequisites or exclusions. The agent must infer the routing from the sibling names alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds the meaningful trait that verification is 'independent' — i.e. a local cryptographic check rather than a trusted lookup — and that the digest comparison is optional; only minor gaps remain (e.g. what a mismatch implies).

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

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

A single tight sentence with the core action front-loaded and the optional behaviour placed after the semicolon. Every clause adds information; nothing is redundant with the title or schema.

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

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

For a two-parameter read-only tool with rich annotations and an output schema, the description covers the action, the precondition, and the optional parameter's role. Missing only identifier/format details, which is a small gap given the output schema removes any need to explain return values.

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

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

With 0% schema description coverage, the description carries the full burden, and it only partially does so: it explains content_digest as the digest of the received content and marks it optional, but says nothing about commitment_id syntax or the expected digest format (hex/base64/algorithm). That is a meaningful but incomplete compensation for the undocumented 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?

Names a specific verb+resource pair ('verify a revealed commitment') and clarifies that digest comparison is an optional add-on. The word 'revealed' implicitly ties it to the reveal sibling, but no sibling is named explicitly for contrast (e.g. commitment_status or get_orc_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 phrase 'revealed commitment' implies a precondition (you must have revealed it first) and 'optionally check it against the digest of content you received' indicates when to supply the second parameter. There is no explicit statement of when to prefer this over commitment_status, get_orc_commitment, or list_commitments, so routing is left to inference.

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