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

Annotations already declare destructiveHint=true, but the description adds concrete consequences the agent could not infer: signing links stop working, remaining signers are e-mailed, and the action cannot be undone. That is exactly the context needed to decide whether to proceed with an irreversible mutation.

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, each doing distinct work: what it does, what happens as a result, and the irreversibility warning. The critical caution is front-loaded at the point of decision.

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 destructive mutation with no output schema, the description covers side effects and irreversibility well, which is the high-risk part. The remaining gap is the undocumented required 'reason' parameter, which leaves the caller guessing at invocation specifics.

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 never mentions either parameter. The required 'reason' field in particular is unexplained — an agent gets no guidance on what it is for or how it is surfaced to recipients. Only 'the document' loosely implies 'id'.

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 and resource ('Cancels (voids) a document') plus the precondition ('still being signed'), which cleanly separates it from send_document, send_reminder, and create_signing_link among the siblings. An agent can identify the operation 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?

Gives a clear eligibility condition ('still being signed') and an explicit operational instruction ('confirm with the user first'). It stops short of naming a specific alternative for documents already completed, so it is not a full when/when-not routing statement.

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?

Adds behavior beyond the annotations: the one-hour expiry and the bearer-token security property ('whoever has it sign as that person'). The sharing warning is genuinely useful operational context. It stops short of stating single-use behavior or what happens after expiry.

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 with the core action and delivery mode front-loaded, followed by the security caveat. Every sentence earns its place and nothing is padded.

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 three parameters at 0% schema coverage and no output schema, the definition should clarify the document id, recipient id, and returnUrl semantics, and ideally what the response contains. The conceptual framing is good but the parameter-level gaps are significant for 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?

Schema description coverage is 0%, so the description must carry the burden, but it only loosely maps 'a person' to recipientId and never explains what 'id' is or what returnUrl does. The hint about opening in 'your own app' gestures at returnUrl but does not define 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?

States a specific verb and resource ('Creates a one-hour signing link') plus the delivery mode (EMBEDDED) that distinguishes it from email-oriented siblings like send_document and send_from_template. An agent can identify exactly what this tool produces 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?

Implies the use case ('to open in your own app or hand to that person'), which distinguishes embedded from outbound delivery at a conceptual level. However, no sibling tool is named and there is no explicit when-not guidance, leaving the agent to infer that this is the embedded alternative to send_document.

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 annotations present, the description still adds meaningful context: the document must be completed, the file is written locally, and the output includes the certificate of completion as a final page. Missing are behaviors that matter for a write-to-disk tool: whether an existing file is overwritten, and what error/result is returned for a non-completed document.

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

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

One front-loaded sentence with zero filler; the precondition and the notable output detail (certificate page) are packed in without wasted words.

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

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

For a two-parameter tool with no output schema, the description covers purpose, precondition, and output composition adequately. It would be complete at 5 with a note on file overwrite behavior or how failures (non-completed document) surface.

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 50% — saveTo is documented in the schema with an example path, while id has no schema description. The description partially compensates by implying id must reference a COMPLETED document, but adds no syntax or constraint detail for either parameter (e.g., file extension requirements, path resolution). Baseline 3 is appropriate.

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

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

States a specific verb (saves/downloads) and resource (the sealed signed PDF) plus what it contains (certificate of completion as last page), which lets an agent distinguish it from siblings like verify_pdf or get_document. It does not explicitly name a sibling, 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 capitalized 'COMPLETED document' gives an implied precondition for use, which is real guidance. However, no alternative is named (e.g., verify_pdf for validation, get_document for metadata) and no when-not-to-use case is stated beyond the completion requirement.

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 supply readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuine behavioral value by spelling out exactly what the response contains per recipient, including the decline reason and timing, which is more than the annotations convey.

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

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

One front-loaded sentence enumerating the returned fields with zero filler. Nothing is redundant or buried.

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 one-parameter read with no output schema, describing the response contents is exactly the right compensation, and it does so precisely. It could still mention a not-found or permission behavior, but nothing essential for correct invocation is missing.

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

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

Schema coverage is 0% and the single id parameter has no description, but its uuid format makes the identifier type evident from the schema. The phrase "one document" weakly ties id to a document identifier, yet the description never states whether it is the document UUID versus a signing-link token.

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 resource and scope ("Full status of one document") plus the exact contents returned: per-person opened/signed/declined state, decline reason, and timestamps. It is clearly a single-document read, implicitly distinguished from list_documents, but never names a sibling 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?

No when-to-use or when-not-to-use guidance is given. The phrase "one document" hints that this is the single-record counterpart to a list call, but an agent must infer that rather than being told how it differs from get_history or list_documents.

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 readOnlyHint annotation already establishes that this is a safe read operation, and the openWorldHint annotation covers external access. The description adds useful context beyond annotations by explaining that the history is hash-chained, includes per-step timestamps and IPs, and reports whether the chain is intact. It does not discuss pagination or error behavior, but the core behavioral disclosure is strong.

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 compact sentence that front-loads the key concept: hash-chained document history. Every clause contributes useful information about what the history contains and how integrity is reported.

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

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

For a read-only, single-parameter history lookup with no output schema, the description does well by enumerating the returned information: steps, time, actor, IP address, and chain integrity. It could further clarify error behavior or the meaning of the id parameter, but it is largely complete for the tool's complexity.

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 a single required 'id' parameter with 0% schema description coverage, so the schema itself does not explain what the parameter represents. The description's phrase 'history of a document' implicitly indicates that the id identifies a document, which is enough to interpret the sole parameter, but it adds no format or constraint details beyond that.

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 specifies that this tool retrieves a document's hash-chained history, including timestamps, actors, IPs, and chain integrity. This is a specific resource and return shape, though it does not explicitly distinguish itself from sibling tools such as get_document or verify_pdf.

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 an audit or compliance use case through its mention of hash chains and IP addresses, but it does not state when to use this tool versus alternatives like get_document or verify_pdf. No prerequisites or exclusions are given.

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 and openWorldHint=true, so the safety profile is covered. The description adds genuine value by naming the concrete payload fields (organisation identity, default language, sending limit), which is exactly what an agent needs to know before calling a zero-parameter read; it stops short of noting error behavior for an invalid key.

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

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

One sentence, front-loaded with the primary result and then the secondary fields, with zero filler. Nothing here could be removed without losing content.

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

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

There is no output schema, so the description carries the return-value burden, and it lists the three main pieces of information returned. It does not describe the full response shape (ids, plan details, limits structure), leaving a small gap for an agent that needs to parse 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?

The tool takes zero parameters, so the baseline is a 4 and there is nothing for the description to disambiguate. It also implicitly confirms the call is key-scoped rather than taking an organisation identifier.

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 and resource: it returns the organisation tied to the API key plus default language and sending limit. That cleanly distinguishes it from the document/send siblings, which none of them overlap with, though the phrasing 'Shows which PenlyDoc organisation the API key belongs to' is slightly indirect compared with a direct 'Returns the current organisation'.

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 rather than stated: an agent can infer this is a context/configuration lookup rather than a document operation, and no sibling is a plausible substitute. But there is no explicit 'use this when you need account identity, plan or limit info' guidance or mention of when it is unnecessary.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), so the bar is lower; the description does add useful behavior beyond that with the 'newest first' ordering and the note that signer info is attached. It says nothing about pagination behavior, the 25-item default or 200 ceiling, or whether filters combine (status AND externalRef), all of which matter for a list 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?

Two short sentences with zero padding. The core identity (what is listed, in what order, with what content) comes first and the filtering hint second, which is the right front-loading.

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

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

For a read-only, no-required-parameter list tool with no output schema, the description is close to complete: it identifies the collection, ordering, included signer data, and the two main filters. The remaining gap is pagination and limit semantics, which an agent calling a list endpoint would reasonably want spelled out.

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 whole burden, and it clarifies only two of three parameters: status and externalRef filtering. The limit parameter is never mentioned, and the description doesn't say whether the two filters are mutually exclusive or conjunctive, leaving real ambiguity.

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 and resource ('Lists documents sent for signature') and immediately distinguishes itself from list_templates and the single-document getters by naming what the collection contains. It also says what each entry carries ('who has signed'), so an agent knows the shape of the payload without opening a 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 second sentence implies when to reach for this tool ('Filter by status or by your externalRef'), which is useful context, but there is no statement of when not to use it, no pointer to siblings like get_document for a single record, and no guidance on paging a large result set.

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 and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context about the payload, notably the 'ready to send' readiness flag and the roles/data keys, but says nothing about ordering, volume, or scoping of the result set.

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 front-loaded sentence naming the resource first and then the fields. Every clause carries information 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 must carry the return-value burden, and it does by listing id, name, roles, data keys, and readiness. It stops short of describing ordering or whether the list is paginated, but for a zero-parameter read tool this is close to sufficient.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is no parameter semantics to explain. The description rightly spends its words on the return shape instead.

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 and resource ('Lists the organisation's templates') and enumerates the returned fields, so the agent knows exactly what it gets. It does not explicitly contrast with siblings such as list_documents or get_organisation, but the resource noun is unambiguous enough to avoid 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?

Usage is only implied: an agent can infer this is the discovery step before send_from_template, but the description never says when to call it or what alternative to use instead. No prerequisites or exclusions are 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?

Adds real behavior beyond annotations: send=true triggers immediate e-mails to recipients, the no-fields path defers placement to the console, and the result carries a link for that. It also warns to confirm with the user before sending. Annotations (openWorldHint, idempotentHint=false, destructiveHint=false) cover the safety profile, but the description doesn't address whether a created document can be cancelled/replaced or what rate/size constraints apply beyond the schema's maxItems.

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 upload-then-create action, then the two variants for placing signature boxes, then the send-vs-console decision. Four tight sentences, no preamble, no repetition of title or schema fields.

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

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

Given 10 parameters, nested recipient/field objects, 20% schema coverage, and no output schema, the description covers the core creation flow and the send/console fork but leaves recipient roles, routing/signing order, expiry, and message semantics entirely to the schema. Adequate to call the tool in the simple case, thin for the richer one.

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 20%, and the description compensates well for the highest-risk parameters: it explains that files are joined in order, that signature boxes come from {{sig:1}} tags or the fields argument, and that field coordinates use a top-left origin. However, it says nothing about recipients (role, routingOrder, delivery, language), signingOrder, message, expiresInDays, or externalRef, leaving much of a 10-parameter tool undocumented in both schema and description.

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+resource pair: uploads local files and creates a document for signature, with the accepted formats (PDF, PNG/JPEG page photos, joined in order) spelled out. This implicitly but clearly separates it from send_from_template and send_draft, which reuse existing content rather than uploading new files.

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?

Explicitly branches on conditions: send=true e-mails recipients right away (with an instruction to confirm with the user first), and when no {{sig}} tags or fields exist, use send=false and let the user place boxes in the console. Both the when and the when-not are stated with concrete 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?

Annotations already declare openWorldHint=true, idempotentHint=false and destructiveHint=false. The description adds the important out-of-band effect that e-mails go out to signers and that user confirmation is required, which is context the annotations don't convey. It could go further by saying the send cannot be undone/re-called.

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

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

Two short sentences, front-loaded with the action and effect, with the confirmation requirement as the second. 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 one-parameter mutation tool without an output schema, the description covers what happens and the safety gate reasonably well. It is still incomplete on the only parameter and on the consequence of sending (irreversibility, recipient set semantics).

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% for the single required parameter, so the description needed to explain it and doesn't. Nothing says whether "id" is the draft's UUID or which draft it refers to, and no format or source for obtaining it is given.

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 and resource ("Sends a DRAFT document") and adds the concrete effect (PenlyDoc e-mails the first people to sign). The DRAFT qualifier implicitly distinguishes it from send_document, though the sibling is never named.

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?

"Confirm with the user first" gives a clear precondition for invoking the tool. It stops short of explicitly contrasting with send_document or describing when to use a draft versus a live document, so no exclusions/alternatives are 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?

Beyond the annotations it discloses the real external side effect (immediate e-mail to recipients with delivery EMAIL), the safe draft mode, and the retry contract via externalRef/idempotencyKey. That is meaningful added context for an openWorldHint=true tool. Minor tension: the description promises safe retry while idempotentHint=false, which is explainable (idempotency is caller-supplied, not automatic) but could be spelled out more crisply.

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?

Four tight sentences, front-loaded with what the tool creates, followed by the send=true/send=false branch and then the retry note. No filler or repetition of the schema, though the final idempotency sentence is the least essential of the four.

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 an 8-parameter nested tool with no output schema, the definition covers the create-and-send flow, the draft path, the confirmation requirement, and retry semantics. The main remaining gap is that it never says what comes back (document id? status?) nor points at list_templates for obtaining templateId and role keys, forcing the agent to infer both.

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 only 50% schema coverage, the description compensates well: it explains that roles maps one person per role key, that data supplies values for template data keys, and that delivery EMAIL gates the e-mail behavior. externalRef and idempotencyKey also get purpose-level meaning. title, message, and language remain undocumented in prose, keeping it off a 5.

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

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

The opening clause gives a concrete verb and resource ('Creates a document from a template') plus the shape of the two main inputs (one person per role, values for data keys). It is clear against most siblings, though it never explicitly distinguishes itself from send_document or send_draft, which an agent could plausibly confuse for the same outcome.

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 explicit branching guidance: send=true e-mails recipients with delivery EMAIL, send=false produces a console-reviewable draft, and it adds the precondition 'confirm the people and values with the user first' before sending. What is missing is routing against sibling alternatives such as send_draft or send_document when a document already exists.

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 declare openWorldHint, non-idempotent, non-destructive, but the description adds the crucial behavioral facts: an email is dispatched immediately, it goes to every current signer, and it requires user confirmation. That exceeds what the annotations convey. It still omits failure behavior (what happens if nobody is pending).

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

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

Two short sentences, action first, constraint second. Every clause earns its place with no repetition of structured data.

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 one-parameter tool with annotations, but gaps remain: what happens when no signer is pending, whether repeat sends are blocked (annotations say non-idempotent), and confirmation of what the id refers to. No output schema exists to cover the return 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?

Schema description coverage is 0%, so the description must carry the parameter burden. 'This document' implies the single 'id' parameter is a document identifier, but the description never states that explicitly or notes it is a UUID, leaving that to the schema's format field.

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 and resource ('E-mails a reminder... on this document') and scopes it to 'everyone whose turn it is', which separates it from send_document and send_from_template. It does not explicitly name a sibling, but the action is distinct enough that an agent can route correctly.

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?

'Confirm with the user first' is a real usage constraint, and 'whose turn it is' implies the precondition. However, no alternatives are named and nothing says when NOT to use it (e.g., when no one is waiting or a reminder was already sent).

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 and openWorldHint, so the safety profile is covered; the description adds genuinely useful context beyond that — nothing is stored and no API key is required, which matters for a tool that reads a local file. It stops short of describing output format, but the enumerated checks partly cover that.

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 front-loaded sentence with a colon-delimited list of what is checked, followed by two short constraint clauses. Every clause adds information; 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?

For a one-parameter read-only tool with no output schema, the description covers the operation, the input nature (local path), and the key results (seal status, timestamp, signer). What an agent needs to invoke it correctly is present, though the shape of the return value is only sketched.

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?

One parameter with 100% schema description coverage, so the schema already documents that 'file' is a local path. The description reinforces that the target is a local signed PDF but adds no format or path-syntax detail beyond the schema, making the baseline 3 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?

States a specific verb ('Checks') and resource ('local signed PDF') and enumerates the exact questions answered: seal integrity, sealing time, signer identity. This clearly distinguishes it from siblings like download_signed_pdf or get_document.

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?

'Works for any PDF' and 'No API key needed' imply broad applicability and low setup friction, but the description never says when to reach for this versus siblings (e.g., after download_signed_pdf, or instead of get_document). Usage is implied rather than directed.

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