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

Beyond the sparse annotations, the description discloses that the approval is hash-bound, witnessed at its own time, written to the attestations sidecar, and does not modify the receipt. It also explains the ephemeral-key path yielding present_unverified versus the vouched present_verified path with identityProofRef. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and every sentence earns its place: usage context, behavioral guarantees, binding mechanism, and identity constraints. There is no filler or restatement of the tool name.

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 9-parameter complexity and no output schema, the description covers the critical operational caveats: witness-mode matching, distinct approver, sidecar write, ephemeral vs enrolled key behavior, and the receiptUrl alternative. An agent has enough context to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the crucial cross-parameter constraint that the approver MUST be distinct from the recording agent and links approverPrivateKeyPem to the present_unverified vs present_verified distinction. This is extra meaning beyond the individual schema descriptions.

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: attach an independently-witnessed APPROVAL to an already-finalized receipt without modifying it. It also frames this as a deferred satellite and mentions hash-binding, which clearly distinguishes it from in-session approval or finalization 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?

It explicitly says to use this when a reviewer signs off after the receipt was sealed, e.g. one model approves work another model recorded. It gives important conditions like distinct approver and matching witness mode, but it does not explicitly name an alternative for in-session approvals, so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond them: the composed 'allowed' gating (startable AND mandate AND recording gate), the precise false-conditions for startable (managed mode, no usable parameters, non-bundled action, missing V1 params), the false-conditions for recordSchemaValid, and the $param/$allowlist resolution of the evidence schema. There is no contradiction with the annotations — 'never records anything' aligns with readOnlyHint=true.

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

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

The core purpose is front-loaded in a strong first clause, and no content is wasted. However, the body is one dense run-on sentence with deeply nested parentheticals (the startable clause alone chains four false-conditions inside em-dashes), which makes it hard for an agent to parse quickly. The structure does not match the information density.

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 six output flags and no output schema, the description carries the return-value burden well: it names and explains allowed, transition validity, parameter-binding errors, resolved evidence schema, startable, and recordable. The only notable gap is that 'the mandate' is referenced in the allowed composition without ever being defined or sourced, leaving one gate 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 coverage is 100%, setting a baseline of 3, but the description meaningfully enriches parameter meaning: it explains that params are bound against the template's parameters block, that evidence is validated against the resolved evidence schema (evidenceValid), that priorActionTypes drives the transition check (including the empty-array START case), and that mode determines startability for remote binding. This goes beyond the schema's per-parameter text.

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 opening clause 'Pre-flight a single action against a workflow template BEFORE recording it' gives a specific verb, resource, and temporal scope, and the final clause 'advisory and never records anything' explicitly distinguishes it from the recording siblings. The tool's job — a pre-record validation gate — is 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 it before recording to surface violations up front rather than in the finalized receipt's conformance report, and 'never records anything' tells the agent this is not the recording path. However, it never explicitly names the alternative (e.g., use sequesign_record_action when you intend to persist) or states when NOT to use it beyond implication.

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 discloses important behavioral details beyond the annotations: the confirmation does not modify the sealed receipt, it is hash-bound to the receipt and action, it is independently witnessed, and it is written to the attestations sidecar. It also clearly explains the ephemeral-key vs. enrolled-key identity behavior (present_unverified vs. present_verified), which is valuable execution context.

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 focused sentences: the core action, the when-to-use condition, and the behavioral/identity consequences. It is front-loaded with the primary purpose and every sentence contributes new, non-redundant information.

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 8 parameters and complex domain, the description is remarkably complete. It covers the core operation, the temporal constraint, the sidecar write, the hash binding, and the two identity modes. There is no output schema, but the description provides enough behavioral context for an agent to invoke the tool correctly and understand what the operation produces.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description goes beyond this for key parameters: it explains the counterpartyPrivateKeyPem omission/minting behavior, the role of identityProofRef in vouching, and the receiptUrl's purpose for showing registered identity on a stored receipt. This adds meaningful semantic value beyond the schema.

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

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

The description opens with a specific verb and resource: 'Attach an independently-witnessed COUNTERPARTY confirmation to an already-finalized receipt'. This clearly distinguishes the tool from the sibling record_counterparty_attestation by emphasizing deferred action on a sealed receipt, and it is further reinforced by the title's 'deferred counterparty satellite'.

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 context for use: 'Use this when a counterparty ... confirms an action after the receipt was sealed.' This is a clear trigger condition. However, it does not explicitly name alternatives or state when not to use the tool, especially relative to the closely related sibling sequesign_record_counterparty_attestation.

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 convey the read/write and destructive profile, but the description adds meaningful behavior beyond that: finalize closes and removes the session from memory, and it produces a package directory plus verification summary. It does not mention irreversibility or failure behavior, but the added context is useful and does not conflict with the annotations.

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

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

Two sentences carry all the essential information: the primary action, the lifecycle side effect, and the return contents. The description is front-loaded with the main behavior and contains no filler or redundant restatement of the title.

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

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

For a single-parameter tool with no output schema, the description covers the critical return information: package directory, managed-mode receipt URL, and verification summary. A minor gap is that the shape of the 'verification summary' is unspecified, but the definition is still sufficiently complete for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100% for the single parameter, so the baseline is 3. The description reinforces that the sessionId is closed after finalize but adds no new format, validation, or source details. There is also a mild inconsistency in the schema, which calls the value 'receiptId' while the parameter is named 'sessionId,' and the description does not resolve 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 opens with a specific verb ('Seal') and object ('the session into a verifiable receipt package'), making it clear this is the finalization step rather than a read/verification-only action. It also includes 'run the SDK's own verification' and describes the post-finalize closure, which helps distinguish it from general verify tools. However, it does not explicitly contrast itself with sequesign_verify, so full sibling differentiation is missing.

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 sentence 'After finalize the sessionId is closed (removed from memory)' clearly establishes this as the terminal step in the session lifecycle, implying the agent should call it only after all recording/approval actions are complete. This gives clear context but no explicit exclusions or alternatives, so it falls short of a top score.

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

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

Annotations already mark the tool as read-only and idempotent, and the description adds valuable non-obvious behavior: session_ready depends on the mode argument, falls back to the server default, and is direct-only for registry templates. It also clarifies that templates may be bundled or fetched from a configured registry.

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 dense but every sentence earns its place: what is fetched, what is returned, how session_ready behaves, and when to use it. The main action is front-loaded and there is 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?

With no output schema, the description compensates by listing all returned fields and explaining the tricky session_ready semantics. An agent can call this tool knowing exactly what to expect and why it matters for downstream decisions.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds some context about template provenance and mode-dependent session_ready, but it largely reinforces rather than extends the schema's parameter semantics.

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: fetching one workflow template by profile_id. It enumerates the exact return fields, which distinguishes it clearly from list_templates (list vs. single item) and check_action (inspect rules vs. validate an 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?

It explicitly states when to use the tool: before starting a profile_constrained session or before sequesign_check_action. It does not explicitly name alternatives or state when-not-to-use it, so it stops just short of full routing guidance.

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

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

Annotations already mark it read-only/idempotent, and the description adds genuinely useful behavior: entry details differ between bundled and registry sources, details_available indicates remote manifest-level entries, and the curation tier is explicitly 'NOT a security control.' It also discloses the SEQUESIGN_TEMPLATE_REGISTRY_URL dependency.

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 dense paragraph, but every clause carries information – no filler or repetition. It front-loads the core purpose and then layers detail logically, though it could be more scannable with bulleted lists.

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

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

With no output schema, the description compensates by enumerating every field an entry contains, distinguishing bundled vs remote entries, and connecting profile_id to sequesign_start_session. It also specifies the optional filter and the environment-variable prerequisite, making the tool callable without additional lookups.

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 fully documents the optional tier parameter with an enum, so the baseline is 3. The description adds meaningful nuance by calling the tier 'discovery metadata, NOT a security control' and by confirming the filter is optional, which helps the agent treat it as a soft filter rather than a security boundary.

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 action and resource – 'List the Sequesign workflow templates (profiles) available for profile_constrained sessions' – and clearly distinguishes bundled from registry templates. It also names the sibling tool sequesign_get_template for remote detail, so an agent can tell this list operation apart from related 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 explicitly says to call sequesign_get_template when a remote template's full detail is needed, and notes that profile_id should be passed to sequesign_start_session, which frames list_templates as the discovery step. Although it doesn't state 'when not to use' broadly, the contrast with get_template is explicit enough.

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 indicate a non-read-only, non-idempotent write operation. The description adds meaningful behavioral context beyond that: the action is appended to the session chain, evidence is hashed and signed, and an actionId is returned. This clarifies the side effects and the role of the evidence without contradicting the annotations.

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

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

The description is two sentences with no fluff. It front-loads the core operation first, then explains the key parameter's role and the return value's downstream use. 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 tool with six parameters, two required, and no output schema, the description covers the essential operation, the purpose of evidence, and the return value. The schema supplies parameter details and defaults. The main omission is explicit error or precondition information, but nothing suggests that is critical for a well-formed session.

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 every parameter. The description adds some useful framing around 'evidence' being a structured record of what the agent did or observed and notes that the return value is an actionId, but it does not materially extend the per-parameter semantics already present 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 states a specific verb and resource: 'Append a signed action to the session's chain.' This clearly identifies what the tool does and distinguishes it from sibling tools like record_approval or record_counterparty_attestation by focusing on a generic recorded action rather than an approval or attestation.

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 when the tool should be used: when the agent has performed or observed something that should be recorded as a signed action. It also gives downstream guidance by explaining how to use the returned actionId. However, it does not explicitly contrast this tool with alternatives such as record_approval or record_counterparty_attestation, so routing among siblings 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.

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

Beyond the annotations, the description discloses important behavior: omitting approverPrivateKeyPem mints an ephemeral key and results in a present_unverified approval leg, while supplying an enrolled key plus identityProofRef produces a vouched present_verified approval. This is substantive and not inferable from the schema or annotations.

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

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

Two sentences with no wasted words. The core purpose and prerequisite come first, followed by the key behavioral conditional about ephemeral keys and verification state. 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 7-parameter tool with full schema coverage, the description covers the critical prerequisite, verification states, and key-handling behavior. It could be slightly more complete by naming sibling tools for routing and mentioning return expectations, but nothing essential to calling the tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful cross-parameter semantics by explaining the consequence of omitting approverPrivateKeyPem and the role of identityProofRef in achieving a verified approval, which is more than the individual property descriptions convey.

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 precise verb and scope: 'Attach a signed approval for an action already recorded in this session.' This clearly differentiates it from receipt- or session-level operations and tells an agent exactly what resource it acts on.

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 and a hard prerequisite: the action being approved must already be recorded. It also gives a realistic use case (human or independent agent reviewer signing off). It does not explicitly name sibling alternatives like sequesign_approve_receipt, so exclusion guidance is missing.

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

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

Annotations are all false, so the description carries the behavioral burden. It discloses that content binding is SDK-derived from the attested action and cannot be pointed at unseen content, and it explains ephemeral key vs. enrolled key behavior for present_unverified vs. present_verified attestations. No contradiction with annotations.

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

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

Three purposeful sentences with no filler. The main operation is front-loaded, followed by the key integrity constraint and mode-selection guidance. 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 six-parameter write tool with no output schema, the description covers the essential selection and invocation knowledge: what it does, the binding constraint, and the key-mode decision. It does not state the return value or explicitly contrast with related sibling tools, but these are not severe gaps.

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

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

Schema coverage is 100% and each parameter already has descriptive schema text. The description adds cross-parameter meaning by explaining that attestedActionId is cryptographically bound, not freely selectable, and by linking counterpartyPrivateKeyPem plus identityProofRef to the vouched attestation mode.

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: 'Attach a counterparty's signed confirmation of an action already recorded in this session', with a concrete example. It is semantically distinct from sibling tools like record_approval or countersign_receipt, though it does not name those alternatives explicitly.

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

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

It gives clear context for when to use the tool: when a counterparty confirms an action that was already recorded in the current session. It also describes two usage modes based on whether counterpartyPrivateKeyPem is supplied, but it does not explicitly say when not to use it or compare it with sibling 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?

Annotations already establish non-read-only, non-idempotent, non-destructive behavior. The description adds meaningful context beyond that: each session maps to 'one signed action chain,' the sessionId doubles as the receiptId, and providing policyContext raises verification to L3_POLICY_BOUND. No contradiction with the annotations — readOnlyHint=false aligns with 'Open a new session.'

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 earning its place: the first names the action, the second the return value, the third the one high-value optional parameter. The parenthetical '(one signed action chain)' compresses a key behavioral constraint into minimal space. Fully front-loaded with the core action in the opening phrase.

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 7 parameters, nested objects, and no output schema, the description covers the most critical gap by naming the return value (sessionId/receiptId). Combined with the schema's exceptionally rich parameter descriptions (template binding, transport modes, verification levels), an agent has enough to call this correctly. Slightly incomplete in that it doesn't note each call opens a fresh chain (relevant given idempotentHint=false), but the surrounding schema context mitigates this.

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 richly documents all 7 parameters including the mode enum, profile template binding, and pre-flight guidance via sequesign_list_templates/check_action. The description's only parameter note — that policyContext binds the receipt to a policy reaching L3_POLICY_BOUND — largely restates the schema's own policyContext description, adding no new 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 verb+resource: 'Open a new receipt-recording session (one signed action chain).' This clearly distinguishes it from all ten siblings, which operate on an existing session (record_action, approve_receipt, finalize, verify, etc.). The clarification that it returns the sessionId used by the other tools further anchors its unique role as the session initializer.

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?

'Returns a sessionId (the receiptId) used by the other tools' gives clear workflow-position context: this is the entry point that must precede record/approve/finalize operations. Sibling names make the sequence inferable. However, it does not explicitly state when not to use it (e.g., if a session already exists) or name alternatives, stopping short of the full 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavioral context beyond them: the trust-anchor model (embedded vs supplied vs auto-fetched keys), precise best-effort fallback semantics ("witness → self; registration → leg not promoted"), the SEQUESIGN_API_KEY auth requirement for receiptUrl, and the surprising constraint that receiptUrl still requires packageDirectory. No contradiction with annotations.

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

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

The description front-loads its purpose and uses numbered modes that make a complex 4-mode tool scannable. It is dense and heavily parenthetical, but every clause carries operational meaning; the length is justified by the tool's complexity.

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 high-complexity tool with 5 interacting parameters and no output schema, the description covers all modes, auth needs, fallback behavior, and required parameter combinations. The only gap is that return value shape and error conditions are never described, though the description hints at outputs ("surfacing external trust", "noted in the result").

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

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

Schema coverage is 100%, so the baseline is 3; the description adds genuine value by explaining cross-parameter interactions the per-property schema cannot: override semantics ("Explicit trustedWitnessKeysJson / trustedRegistrationKeysJson override the matching fetch"), mode exclusivity (fetchAnchors ignored with receiptUrl), and the packageDirectory dependency of receiptUrl.

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?

"Verify a sealed Sequesign receipt" is a specific verb+resource statement that immediately conveys the tool's function. The four enumerated modes further clarify scope, and the verification purpose is clearly distinct from the sibling tools that record actions, approve/countersign, or finalize 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 when-to-use guidance for each mode: default self-check for offline integrity, trusted JSON params for third-party checks, fetchAnchors for auto-fetching, and receiptUrl for the broker-stored authoritative copy. It also notes exclusions ("Local verify only (ignored with receiptUrl)" and "Default false = fully offline self-check"), though it never names sibling alternatives explicitly.

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