Sign PDF

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

Annotations already flag this as destructive, non-read-only and idempotent, so the safety profile is covered. The description adds real value beyond them: the signing link stops working (external side effect for the recipient) and the cancel does not refund the monthly count (an irreversible quota consequence). It still doesn't say what happens to the request record or how it errors on an already-signed request, so not a 5.

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

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

Three short sentences, front-loaded with the action and eligibility, then the two consequences. Every sentence carries distinct information with zero 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?

No output schema exists, so the description carries return/behavior burden, and it does cover the key consequences an agent needs before calling. It is near-complete for a 2-param destructive tool, missing only the request_id semantics and post-cancel record state.

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

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

Schema description coverage is only 50%: request_token is documented in the schema, but request_id carries no description anywhere. The description adds no parameter meaning at all, so it fails to compensate for the undocumented 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?

Specific verb (cancel) plus resource (signature request) plus a precondition ("not signed yet") that no sibling tool covers — send_for_signature, get_signature_status, download_signed_pdf and find_signature_requests are all clearly distinct operations. An agent picking among the six siblings can select this one 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 description gives a clear eligibility condition ("a request that is not signed yet"), which implicitly excludes already-signed requests. It stops short of naming the alternative action for signed requests or explicitly stating when not to use it, so it is clear context without exclusions.

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 flag destructiveHint=true and idempotentHint=true, so safety is largely covered. The description adds genuinely new behavioral context that annotations cannot express: already-sent signature requests are unaffected, i.e. the delete is non-cascading. It does not state irreversibility or error behavior for an invalid ID, keeping it short of a 5.

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, destructive action front-loaded, with no filler. "Confirm with the user first" borders on restating the destructiveHint annotation, but it is short and actionable enough to earn 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 single-parameter delete with no output schema, the description covers the essential agent-facing facts: it destroys something, it is non-cascading, and confirmation is expected. Only the identity/format of template_id and failure behavior are left unaddressed.

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 there is one parameter, template_id, which the description never mentions. The name is fairly self-explanatory, but the description supplies no format, source, or constraint information to compensate for the empty 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 gives a specific verb and resource ("Delete a saved template"), which cleanly separates it from sibling reads and mutations like get_template, list_templates, and update_template. It stops short of explicitly naming those siblings as alternatives, so it is clear but not fully differentiated.

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 useful operational guideline, but it says nothing about when to delete versus archive/update, or what preconditions must hold. Usage is implied by the destructive verb rather than spelled out against 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 cover the safety profile (readOnly, non-destructive, closed-world), and the description adds real behavior beyond them: the status prerequisite, that the link is private, that a shell-command variant is included, and that Portant also emailed the PDF. It stops short of stating link lifetime/expiry or what happens if the status is not yet signed.

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 essential precondition is front-loaded and every sentence carries information (precondition, credential source, alternate credential, delivery note). The first sentence is dense and stacks three deliverables, which slightly hurts scannability.

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, and the description fills that gap by describing the return value (private open/download link with certificate page, plus a shell download command) and the fallback stored copy. Prerequisites and both credential paths are covered, so an agent has what it needs to call 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 coverage is only 50% (request_token has no schema description), so the description must compensate and does: it says request_token comes from send_for_signature and that request_id is the sign-in equivalent for an account-stored copy, matching the schema note on request_id. It does not say whether the two are mutually exclusive or which wins if both are passed.

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 ('get a private link ... download the signed PDF') and specifies what is returned (link plus signing certificate page plus a shell command). It is clearly distinguishable from get_signature_status (which only reports status) and find_signature_requests (which locates the request).

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 an explicit precondition ('After the status is "signed"'), names where the credential comes from ('Pass the request_token from send_for_signature'), and names the alternative path plus the sibling to use for it ('request_id ... find it with find_signature_requests'). Both routing conditions are spelled out.

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, destructiveHint=false and openWorldHint=false, and the description goes further: it discloses the 10-result cap, newest-first ordering, the returned fields, the no-filter behavior, and an authentication prerequisite ('Needs Portant connected with sign-in'). No output schema exists, so this return-shape detail is genuinely load-bearing.

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

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

Three tight sentences: search scope and trigger first, result shape and defaults second, next-step routing last. Front-loaded and 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 still supplies the return fields, result count, ordering, default behavior, and auth requirement, and it hands off to the correct follow-up tools. Nothing an agent needs to call this 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 coverage is 100%, so the matching rules (case-insensitive title fragment, exact email match) are already documented. The description still adds value by framing the parameters as combinable ('or both') and describing the zero-parameter behavior, which the schema cannot express.

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 (Find) and resource (the user's own signature requests) plus the two search axes (signer email, title fragment) and the scoping constraint 'own'. It is clearly distinguishable from get_signature_status or download_signed_pdf, which operate on an already-known request_id.

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 names the trigger condition ('when you do not have the request_id, for example in a new chat'), the no-filter fallback, and routes the agent onward to get_signature_status, cancel_signature_request, or download_signed_pdf once a match with stored: true is found.

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 readOnlyHint/destructiveHint/openWorldHint annotations it discloses non-obvious behavior: the call is invisible to the user ("It shows nothing to the user"), returns only fuzzy name matches with template_id, name and kind, defines the empty-result path, and states the auth prerequisite ("Needs Portant connected with sign-in").

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?

Purpose and the trigger example are front-loaded, and each subsequent sentence carries distinct information (invisibility, return shape, no-match path, follow-up chain, auth). The later sentences are densely chained with several actions, but nothing is filler.

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

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

For a single-parameter lookup with no output schema, the description covers the input derivation, the exact return fields, the empty-result case, the downstream tool chain, and the auth requirement. An agent has everything needed to call it correctly and act on 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, but the description adds a translation rule the schema lacks: derive the query from the user's phrasing ("query 'mutual NDA' when the user says 'send a mutual NDA to Sam'") and omit the signer's name. That directly guides parameter construction rather than restating 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?

States a specific verb+resource ("Search the user's saved templates by name") and scopes it to the agent's use case of finding a document to send. It is clearly distinguishable from siblings like list_templates and get_template, which list all or fetch one by id.

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?

Explicit sequencing: "Call it before you write a document to send," then "read a match with get_template and send it with send_for_signature," with an explicit no-match branch ("when it returns none, write the document and do not mention templates"). Alternatives and a concrete trigger utterance are both provided.

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 destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context beyond the annotations: a rate limit and the side effect that the user separately receives an email with the signed PDF, which prevents an agent from treating this call as the delivery mechanism.

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

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

Three short sentences, front-loaded with the action and the return states, with the rate limit and side-effect note trailing. The status enumeration is long but earns its place by substituting for a missing output schema; 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 no output schema, the description usefully enumerates the return statuses and covers the polling limit and the email side effect. The remaining gap is authentication context for request_id/request_token, which is only half-covered by the schema, but for a simple read-only status check this is close to complete.

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

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

Schema description coverage is only 50%: request_token is documented in the schema, but request_id has no description anywhere. The prose mentions no parameters at all, so it does not compensate for the undocumented half — the agent gets no help on what request_id should be or why both are listed with zero required fields.

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 and resource ('Check whether the signer has signed') and enumerates the possible outcome states, which sharply distinguishes it from siblings like find_signature_requests (listing) and send_for_signature (mutation). An agent can identify the tool's role 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?

It gives a polling constraint ('Do not check more than once a minute'), which is real usage guidance, but never states when to prefer this over find_signature_requests or cancel_signature_request, nor any prerequisite for calling it. Usage is implied (poll a single request) rather than contrasted with alternatives.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds genuine behavioral detail beyond them: the return varies sharply by template type, with Google Docs yielding a live link and PDFs yielding only name and field count. That return-shape disclosure is valuable given there is no output schema.

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

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

Three dense sentences, front-loaded with the primary action and followed by format-specific behavior; little waste. Slightly long sentences, but each carries actionable 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?

With no output schema, the description accepts the burden of describing returns and does so for all three template types. The remaining gap is how the caller acquires a valid template_id, which matters for a single-required-param 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 description coverage is 0% for the single required template_id, and the description never explains the identifier's form or where to obtain it (list_templates is not referenced). With low coverage the description is expected to compensate and it does not.

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

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

States a specific verb (get) and resource (saved markdown template) and even branches the purpose by template format: text for markdown, link for Google Doc, name+field count for PDF. An agent can distinguish this read tool from list_templates, update_template and delete_template directly from the description.

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 concrete downstream contexts — edit names/dates/terms before sending via document.markdown, or before update_template — and effectively warns that Google Doc/PDF templates are sent as-is rather than edited. No explicit negative case naming a sibling to avoid, 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?

Goes well beyond the annotations: it explains that the sandbox usually cannot reach Portant, describes the upload card UI behavior in Claude/ChatGPT, gives the exact curl PUT pattern with Content-Type and Authorization header, and specifies PDF-only with a Word-to-PDF conversion note. Annotations only say this is a non-read-only, non-destructive, non-idempotent call; the description supplies the real operational 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?

Front-loaded with the core action, then branches into the two invocation paths and the PDF constraint. Dense but nearly every sentence carries actionable detail; the curl example and card explanation are long but earn their place.

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

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

Complete for a zero-parameter tool with no output schema: it covers the trigger conditions, both upload mechanisms, the auth header requirement, the returned identifiers, and the follow-up tool. Nothing needed to invoke it correctly is missing.

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

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

Zero parameters, so the baseline is 4. The description adds value by naming the artifacts returned (upload_url for PUT, upload_id for the next call), which is useful even though no output schema exists.

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 ('Get a place to upload a PDF file') and immediately scopes it to PDFs, distinguishing it from text-handling siblings. The downstream link to send_for_signature makes its role in the workflow unambiguous.

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

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

Explicitly enumerates when to use it (file rather than text, sandbox-made PDF, user-supplied PDF, anything over 1 MB) and when not to (do not send base64 from the sandbox). It also names the alternative path (shell PUT via curl) and the required next step (pass upload_id to send_for_signature).

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: results are ordered newest first, each item carries a kind discriminator, and the call requires Portant connected with an active sign-in. Only minor gaps remain (no pagination/limit behavior), so it lands just below the top.

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 load-bearing: what is returned, when to use it and when to use the sibling, and the connection prerequisite. The most decision-relevant content (the output and the routing rule) is front-loaded with 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?

There is no output schema, so the description correctly compensates by enumerating the returned fields and their possible values, plus the auth prerequisite. For a zero-parameter read tool this is everything an agent needs to call it and interpret 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 there is nothing for the description to disambiguate and the baseline is 4. The description usefully notes there is no filtering surface, implicitly telling the agent that filtering is find_templates' job.

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 ('Show the user all their saved templates') and goes further by naming the return shape (template_id, name, kind with the enum values markdown/pdf/google_doc) and ordering (newest first). This is enough for an agent to distinguish it from get_template, find_templates and the mutation siblings without opening any 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?

Explicitly scopes usage ('Use it only when the user asks to see, open or manage their templates') with a concrete trigger phrase, and names the alternative with its selecting condition ('To check if a template fits a document the user wants to send, use find_templates instead'). Both the when and the when-not are present.

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 mark this as a non-readonly, non-idempotent, open-world write. The description adds context beyond those: it validates the document 'the way a send would', states plan gating (Plus and Scale), requires Portant connected with sign-in, rejects unfilled placeholders, and describes what gets saved (link vs. PDF vs. markdown) and what is returned (template_id). This is substantive behavioral disclosure.

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?

Purpose is front-loaded and every sentence carries operational detail (token syntax, plan gating, return value). It is dense and the long parenthetical about markdown/template_id runs on, but little is 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?

Despite no output schema and a nested document object, the description covers inputs, validation behavior, auth and plan prerequisites, and the return (template_id plus how to use it with send_for_signature). An agent has everything needed 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 coverage is 100%, so the baseline is 3. The description earns more by explaining token syntax ({{signature:signer}}, {{var:Customer company}}), how named fields map to document.values on each send, and how the same field tokens mirror send_for_signature. It adds real semantics beyond the schema, though the fields/positions object is left mostly to 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?

States a specific verb and resource ('Save a document as a template') and immediately distinguishes from send_for_signature by adding 'without sending it to anyone'. An agent can tell this apart from siblings like get_template, update_template, and send_for_signature without opening any 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 an explicit trigger ('when the user asks to save, upload or add a template') with a worked example, and routes the agent to related tools — get_upload_url for PDFs, get_template for template editing, send_for_signature for later sending. When-to-use and alternatives are both covered.

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 flag the mutation and open-world nature (destructiveHint true, openWorldHint true), but the description adds substantial behavior: Portant emails the signer a private link, nothing reaches the signer until Send is clicked, sequential signer emails, final signed PDF to everyone, request_id/request_token/next_step return values, and explicit limits (five signers, 5 MB, 50 pages, 14-day expiry). It also states the tool never signs for anyone.

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 and document input options are front-loaded, and nearly every sentence carries operational value (routing, limits, return values). It is dense and lacks paragraph breaks, making it harder to scan than an ideal definition, but there is little 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?

For a 16-parameter, nested, destructive, open-world tool with no output schema, the description supplies what is missing: workflow ordering, confirmation requirements, limits, return fields, and edge cases like review vs. sender_signs vs. no sign-in. Nothing critical to calling it correctly appears absent.

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 real meaning beyond the schema: it explains the three document input routes (markdown, PDF via upload_id/pdf_url/pdf_base64, Google Doc), how {{signature:signer}} placement works and that Portant adds a block by default, and the interplay between sender_signs, signer/signers, and review. It stops short of re-explaining every enum or nested field, which the schema already covers.

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 — get a document signed — and immediately scopes it: one person, or up to five in set order, optionally with the sender signing first. It also names the sibling save_template as the alternative when the user wants to keep a template without sending, so an agent can distinguish it without opening other schemas.

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

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

Explicitly says when to use review: true or sender_signs: true (when the user wants to check or sign first, call immediately, not after showing text), when not to (no review needed when sender_signs is true, or when Portant is connected without sign-in), and requires confirming signer names, emails, and order before a plain send. Alternatives and exclusions are named.

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 only give generic flags (destructive, non-idempotent, open-world). The description adds concrete behavioral facts beyond them: a hard cap of 3 reminders per request, a minimum one-hour gap since the last signer email, the required source of request_token, and the fact that link-delivery requests have no email to resend. That is exactly the context an agent needs before invoking a rate-limited, outward-facing send.

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 compact sentences, each carrying a distinct operational fact (what it does, precondition, rate limit, link-delivery caveat) with the core action front-loaded. 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 still covers the essentials for a side-effecting send: precondition, token provenance, rate limit, and the edge case where resending is impossible. Nothing critical for a 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 only 33%, but the description compensates for request_token by stating it comes from send_for_signature. The message parameter is already documented in the schema (plain text, 500 chars, links stripped). request_id remains undocumented in both places, so the description adds partial but not full meaning.

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 (email the signer again with the same private signing link) and scopes it to requests with status "pending". This clearly differentiates it from the sibling send_for_signature, which performs the initial send.

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 says to use it only when the user asks, states the precondition (status "pending", waiting for the signer), and routes the agent to a different action when delivery is "link" because no email was sent. When-to-use, when-not-to-use and the alternative path are all covered.

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 flag destructiveHint=true and idempotentHint=true, but the description adds substantive behavior beyond them: nothing is sent, the review/signing link stays stable, removed signers lose their fields, the added signature page is removed when empty, markdown placeholders are refused, the document is rebuilt on specific changes, and request_token is required. That is exactly the extra context an agent needs before invoking a destructive 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?

Purpose and the safety-critical 'nothing is sent, link stays the same' are front-loaded, and nearly every clause carries information. It is, however, a dense multi-clause block covering several concerns in sequence; light structuring into when-to-use / what-changes / signer-rules would improve scanability.

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 9-parameter, destructive, no-output-schema mutation, the description covers scope, safety outcomes, signer replacement semantics, per-format branching (markdown vs. placed-field PDF), field-placement rules, and the request_token requirement. An agent can invoke this correctly without further clarification.

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 78%, so the baseline is 3, but the description goes well beyond field definitions: signers is a whole-list replacement (1–5 people) matched by email, add_fields only applies to PDFs with pre-placed fields and defaults to one signature box on the last page, markdown requires the full text rewritten with signature markers, fields' index refers to numbering before this change, and allow_placeholders is only for user-confirmed brackets. These are semantic rules the schema cannot express.

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 and immediately enumerates the two request states it applies to (awaiting review vs. awaiting signer) plus the concrete attributes it can change: signers, order, title, note, markdown, and field placement. This is far more specific than the sibling tools (send_for_signature, cancel_signature_request, update_template) and lets an agent tell them apart 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?

It gives an explicit gating condition — 'Use it only when the user asks for the change, and confirm the new people with the user first' — which is real when-to-use guidance, and the 'before anyone gets it' framing implicitly excludes already-sent requests. It does not name a sibling alternative explicitly (e.g., use send_for_signature to dispatch), 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 flag destructive=true and idempotent=true, and the description adds genuinely new behavioral facts beyond them: the old version cannot be restored, the user should confirm first, in-flight requests are unaffected, PDF vs. Google Doc handling differs, and a Doc template reflects live Google Docs content. These are material consequences an agent could not infer from the annotation flags.

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?

Six sentences is long, but the three supported operations are front-loaded and nearly every sentence carries a distinct constraint (irreversibility, confirmation, in-flight requests, PDF limitation, Doc liveness). Only the example sentence could be trimmed without loss.

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

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

For a destructive mutation tool with no output schema, the description covers the safety profile, mode limitations, prerequisite read, and post-write side effects. An agent has everything needed to decide whether to call it and how to warn the user.

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 75% and already documents name, markdown, and google_doc_url. The description adds real semantics on top: markdown must be the whole new text using the same field tokens as send_for_signature, and the mode-specific mapping (rename vs. replace text vs. repoint Doc) clarifies when each parameter 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?

Opens with three specific verb+resource operations (rename a template, replace markdown text, repoint a Google Doc template), immediately distinguishing it from get_template, list_templates, and delete_template. The title alone would be ambiguous, but the description makes the scope of mutation 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?

Explicitly states when to use it ('only when the user asks to change the template itself') with a concrete NDA example, names the prerequisite read step (get_template), and gives exclusions: requests already sent do not change, PDF templates can only be renamed. This is textbook when/when-not/alternative guidance.

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