Formify — AI Assisted E-Signing

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

The description discloses key behavioral traits beyond the annotations: it explicitly states that the document is sent for electronic signature, that identity verification happens on Formify's signing page (not via this API), and that no image/document data passes through for ID scan. It also clarifies that only the signature method is selected, not the verification itself. These details add significant value over the annotations (readOnlyHint=false, destructiveHint=true) and help the agent understand side effects and privacy implications.

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 long (~250 words) but appropriately so for a tool with 12 parameters and complex nested objects. It is front-loaded with the core action and then cascades into conditions and user-interaction steps. While somewhat verbose, every sentence conveys necessary guidance, and the structure (core action → prerequisites → user questions → preview workflow) is logical. Slightly more concise would be ideal, but given the complexity, a 4 is justified.

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

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

The description covers prerequisites, alternatives, user interaction requirements, and behavioral side effects thoroughly. The main gap is the absence of any mention of the tool's return value (e.g., document ID or URL) and potential error conditions. Since there is no output schema, the agent must infer what the tool returns. While not critical for calling correctly, this omission prevents full completeness for a tool of this 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?

The input schema has 100% coverage, with extensive per-parameter descriptions (e.g., the field value rules, coordinate calculations, signatureType capability requirements). The description adds minimal parameter semantics beyond stating the templateId/fileId exclusivity and advising to strip file extensions from names. Since the schema already documents every parameter in depth, the description's added value is limited, warranting the baseline score of 3.

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

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

The description clearly states the action: 'Create a document and send it for electronic signature.' It explicitly distinguishes from siblings by noting the template/file exclusivity and referencing create_draft as an alternative when a preview is desired. The verb and resource are specific, making it immediately clear what this tool does versus create_draft, create_link, or create_template.

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 provides explicit usage guidance: when to use templateId vs fileId, mandatory preliminary calls (get_template, get_template_fields, get_file_fields), and a detailed list of questions the agent must ask the user before calling. It also explains when to use create_draft and send_draft instead of create_document, and when to recommend a preview. This is comprehensive, actionable, and leaves no ambiguity about when to use this tool versus 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?

Beyond the minimal annotations (readOnly=false, destructive=false), the description discloses deferred validation ('Full validation occurs only when send_draft is called'), non-mutating template behavior ('The template itself is never affected'), and that the draft name will become visible to signees. These are behavioral traits an agent cannot infer from annotations alone.

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 long but front-loaded with the core purpose and then structured into source rule, template preview, validation timing, naming, and a preview workflow. It remains focused, though the PREVIEW USE CASE paragraph partially recaps workflow steps already stated earlier, so it is not maximally tight.

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 12-parameter tool with nested objects and no output schema, the description covers the central workflow, error condition, preview path, and naming rules. The only notable gap is the absence of any statement about the return value (e.g., draft ID), which would matter more given there is no output schema.

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 the schema already documents the mutual-exclusivity rule, per-parameter optionality while drafting, and coordinate systems. The description adds a small amount on top — the cross-parameter 'EXACTLY ONE source' rule, the get_file_fields ordering prerequisite, and naming guidance — so it slightly exceeds the high-coverage baseline.

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 ('Create a draft document') and the qualifier 'without sending invitations' immediately distinguishes it from send_draft. It also references the two source parameters (fileId/templateId) and the preview workflow, leaving no ambiguity about what create_draft is for.

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 explicitly says drafts are 'the recommended way to preview an uploaded document before sending' and gives the full chain — build config here, get_draft_file_url to preview, update_draft if needed, then send_draft. It also states the exact-one-source rule and that validation is deferred to send_draft, which tells the agent when to use this tool and what belongs to 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?

Beyond the annotations (readOnlyHint: false, destructiveHint: true), the description discloses the crediting/billing model, that the link is live immediately, that Formify sends no invitations, error behavior (402/403), and the requirement for a capability. This gives the agent essential knowledge beyond the structured 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 long but information-dense, with critical warnings in ALL CAPS and a structured progression: purpose, immediate consequence, cost, prerequisites, then pre-call questions. There is minor redundancy between 'ALWAYS confirm with the user' and 'BEFORE calling, ask the user,' but the overall structure is effective.

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 complex, costly, no-output-schema tool, the description is remarkably complete: it covers the input prerequisite (upload_file), capability checks, user-confirmation steps, credit costs, error codes, and even the output hint ('share the returned linkUrl yourself'). 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?

The schema already documents all parameters (100% coverage), so the baseline is 3. The description adds extra meaning by clarifying that signeeDetails describes signature slots, not people, and that signatureBox is required for existing-page placement because there is no template to inherit coordinates from. This goes beyond the schema, so a 4 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?

The description opens with a specific verb and resource: 'Create a reusable public signing link from a PDF already uploaded with upload_file.' It clearly distinguishes this from sibling create_* tools by emphasizing public, recipient-less, reusable links and the upload_file prerequisite.

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 pre-call requirements: ALWAYS confirm with the user, ask about language, AI assistant (only if get_account_capabilities confirms aiAssistant), and confirmation of billing. It also states the capability requirement (publicLinksCreate) and clarifies when not to use this in recipient-based flows ('there are no recipients, so no email, phone, delivery method or signing order').

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 declare readOnlyHint false and destructiveHint false; the description adds meaningful behavioral context beyond that: it requires a capability, models signeeDetails as roles rather than specific people, and clarifies that no fields inside signeeDetails are required. It does not describe the return value or side effects on the original PDF, but the added preconditions and domain behavior are genuinely useful.

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 compact and front-loaded: first the purpose, then the workflow relationship, then the critical role-versus-person caveat, then the capability requirement. Every sentence carries useful information and there is no filler or redundant repetition of schema 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?

For a tool with no output schema and meaningful complexity, the description covers the key preconditions (uploaded PDF, templates capability), the conceptual model, and the relationship to create_document. It could explicitly state what the response contains, such as the new template identifier, but the information needed to invoke the tool correctly is essentially 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 100%, so the baseline is 3. The description adds conceptual value on top of the schema by explaining that fullName is normally a label like 'Buyer', that contact details are optional unless the same person signs every time, and that nothing inside signeeDetails is required. This complements the already-detailed schema property 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 action and resource: creating a reusable template from an already-uploaded PDF. It also differentiates the tool from siblings by explaining that templates bundle a document with signature fields so create_document later only needs recipients. This leaves no ambiguity about what create_template does or how it fits into the workflow.

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 precondition: the templates capability is required and get_account_capabilities should be checked first. It also explains the role-versus-person model and when contact details should be omitted. It does not explicitly state when to use create_document instead of create_template, but the downstream relationship is clear enough to infer the correct usage.

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

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

The description adds significant behavioral context beyond annotations: deletion is permanent and irreversible, the associated file is also deleted, and only certain document statuses are eligible. Combined with the annotations' destructiveHint=truearen't, these details give an agent a clear picture of side effects and prerequisites.

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 concise, front-loaded sentences cover action, constraints, and required procedure without repetition. No filler content; every sentence adds operational value.

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

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

For a simple destructive tool with one required parameter sesami, the description covers purpose, side effects (file deletion), preconditions (status), and workflow (get_document first, user confirmation). It does not mention error cases or permissions, but given the low complexity and rich annotations, the operational picture is sufficiently 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?

The schema already fully describes the single documentId parameter with 100% coverageikuha. The description adds indirect context by saying to call get_document first, but it doesn't explain how documentId is validated, formatted, or whether it could be a list. It stays at the baseline for parameter understanding.

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: 'Permanently delete a document.' It also clarifies what is deleted ('the associated file') and the irreversible nature, making the tool's exact purpose unambiguous even without seeing the tool name.

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?

Provides explicit when-to-use conditions: only documents with status 'completed' or 'revoked' can be deleted. It also specifies a required workflow: call get_document first and ask the user for confirmation. It does not explicitly name sibling tools like delete_draft or revoke_document as alternatives, but the workflow guidance is clear and actionable.

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 destructiveHint=true and readOnlyHint=false, so the description doesn't contradict them. It adds valuable context: 'Permanently delete' reinforces irreversibility, 'associated draft data' clarifies the scope, and 'both active and expired drafts' specifies allowed inputs. The description complements the annotations without redundancy.

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 action and scope are front-loaded, followed by the critical usage guideline. Highly efficient and easy to parse.

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

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

The tool has one parameter and no output schema, so the description covers the essential aspects: what it deletes, scope (active/expired), prerequisite (get_draft), and irreversibility. It could mention error handling or return values, but given the simplicity and annotation coverage, it is adequately 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?

The schema covers draftId with 100% coverage, describing it as 'Unique identifier of the draft to delete'. The description doesn't add meaning beyond what the schema provides, so the baseline of 3 applies. It reinforces the draft context but doesn't introduce new parameter details.

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 ('delete') and resource ('draft'), and clarifies it covers both active and expired drafts. Clearly distinguishes from sibling delete tools (delete_document, delete_file, delete_webhook) by specifying 'draft' and its associated data.

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?

Provides explicit usage instructions: always call get_draft first, show a summary, and ask for confirmation. This establishes the proper workflow and implies deletion is a user-initiated action after review. However, it does not explicitly state when not to use this tool versus alternatives, though the draft-specific context is clear.

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 destructiveHint=true and idempotentHint=true. The description adds a meaningful precondition: deletion is not permitted when the file is attached to a document in created or awaiting_signatures status. This goes beyond the structured hints and helps an agent predict failure conditions.

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 front-load the operation and immediately state the critical constraint. No filler or redundant restatement of the schema.

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

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

For a simple single-parameter deletion tool, the description plus annotations cover destructiveness, idempotencyholmes? wait annotations include idempotentHint true, destructive true. It includes the only important precondition. It doesn't specify permanence or failure behavior, but the schema/annotations carry the rest. Minor gap around what happens if the condition is violated.

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%; fileId is described in the schema. The description only restates that the file was previously uploaded, adding no deeper semantic detail about the 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?

The description clearly states the operation ('Delete a previously uploaded file') and identifies the resource (file), distinguishing it from sibling document/draft/webhook deletion tools. The status constraint adds specificity without ambiguity.

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 explicitly provides a usage condition: do not delete files attached to active documents, listing the statuses that make a document active. This is clear context for when deletion is disallowed, though it doesn't explicitly name an alternative tool for other resources.

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 carry destructiveHint=true, readOnlyHint=false, and idempotentHint=true, but the description adds substantial context beyond them: exactly what gets destroyed (PDFs, thumbnails, AI assistant data), what survives ('Documents the link already produced are NOT deleted'), irreversibility, the ordering dependency, and the 409 error condition. Nothing contradicts 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?

Every sentence carries an operational fact and the highest-stakes information (PERMANENTLY, scope of destruction) is front-loaded with caps for emphasis. It is slightly dense as a wall of text with parenthetical asides, and the rationale sentence partially restates the 409 scenario, keeping it just below a perfect 5.

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 destructive tool with no output schema, it covers prerequisites, error behavior, exclusions, and permission boundaries thoroughly. It does not describe the success response after deletion, a minor gap given no output schema exists (re-deletion idempotency is already conveyed by the idempotentHint annotation).

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% — linkId is already documented as 'Unique identifier of the public link to delete.' The description adds behavioral context around the link but no parameter-specific format or meaning beyond the schema, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource — 'PERMANENTLY deletes a public link' — and defines its scope ('and everything only it was using: its generated PDFs, thumbnails and any AI assistant data'). It distinguishes from siblings both by resource type (link vs document/draft/file/template) and by naming disable_link as the non-destructive counterpart.

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 explicit when/when-not guidance: 'Call disable_link, then this; deleting a live link returns 409,' plus the confirmation requirement ('always confirm with the user first') and the permission boundary ('Owner only — note that disabling is not'). An agent knows exactly the prerequisite, ordering, failure mode, and alternative tool.

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 annotation already flags destructiveHint and readOnlyHint, but the description adds critical behavior beyond that: permanent deletion, confirmation requirement, cascading file deletion only for files the template exclusively used, and preservation of documents and PDFs still in use. This fully discloses the destructive footprint.

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 compact yet information-dense, with the most critical fact (permanent deletion) at the start. Every sentence adds value: irreversibility, confirmation requirement, ownership, and non-destructive edge cases.

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 single-parameter tool, this is complete. It covers cancellation semantics, permission level, irreversible consequences, and what is and is not affected. No output schema exists, but none is needed for a tool whose job is simply to delete.

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 templateId parameter, so the schema already documents the parameter. The description references naming the template during confirmation but does not add API-level parameter semantics beyond what the schema provides, matching the baseline for full coverage.

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 ('deletes'), resource ('template'), and scope ('files only it was using'), making it easy to distinguish from sibling tools like delete_document or delete_file. The permanence is front-loaded, so an agent immediately understands what this tool does.

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 operational guidance: confirm with the user first, name the template, and note that this is owner-only. It does not explicitly name sibling alternatives, but the tool's purpose and preconditions make when to use it clear.

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?

Even though annotations indicate destructive and idempotent behavior, the description adds a meaningful operational consequence: event delivery stops immediately. This helps the agent understand the real-world effect of the call. 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 two short, front-loaded sentences with no filler, repeated information, or schema duplication. It covers action and consequence concisely.

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, the description plus schema is sufficient to know what to pass and what happens. It could have mentioned that the webhook ID can be found via list_webhooks, but this is not necessary 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?

The only parameter, webhookId, is fully described in the schema (type string, required, description 'Unique identifier of the webhook to delete'). The tool description adds no additional parameter semantics, so it does not exceed the baseline set by 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 uses a specific verb ('Delete') and a specific resource ('a registered webhook'), and the added consequence 'Event delivery stops immediately' makes the tool's purpose unmistakable and differentiates it from sibling delete tools like delete_document or delete_file.

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 provides clear context for when to use the tool: remove an existing webhook and immediately halt event delivery. It doesn't explicitly mention alternative operations or edge cases, but for a single-purpose delete tool the usage context is unambiguous.

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 goes far beyond the annotations (destructiveHint=true, idempotentHint=true) by detailing permanence and no-undo, the impact on documents and in-progress signers, billing consequences (no refund, billed instance release), and the prerequisite relationship with delete_link. It contradicts nothing in the annotations; the idempotent hint aligns with 'cannot be undone' because repeated calls have no additional effect.

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?

Each sentence delivers high-value information: permanent destruction, effect on documents/signers, billing, confirmation requirement, and relationship to delete_link. Although the description is longer than average, there is no fluff and it is front-loaded with the core purpose and permanence warning, making it efficient for agent consumption.

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 only one parameter, no output schema, and rich annotations, the description covers all essential operational aspects: permanence, document access, signer interruption, billing, prerequisite ordering, permissions, and confirmation. Nothing an agent needs to decide whether and how to invoke the tool 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?

The schema covers linkId with a clear description ('Unique identifier of the public link to disable'), so the parameter meaning is fully provided by the schema. The description adds no extra semantic detail about this parameter, which is acceptable given the 100% schema coverage; 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?

The description opens with the specific verb-resource pair 'Switches a public link off PERMANENTLY', clearly distinguishing it from siblings like update_link (which implies reversible changes) and delete_link (the subsequent deletion step). It also names duplicate_link as the only way to get a new link, reinforcing its unique role.

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 the tool is the 'REQUIRED FIRST STEP before delete_link', provides a mandatory confirmation guideline ('Always confirm with the user first, naming the link'), and clarifies that anyone with account access may use it. This gives an agent both the when-to-use and how-to-use context, and distinguishes it from the other destruction tool.

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 state readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description carries the burden of side-effect disclosure. It clearly explains that the source is untouched, nothing is sent, signature progress is not copied, payment requirements are carried over, and charges only occur when the draft is sent. These details go well beyond the annotations and prevent major misuses.

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?

Although longer than typical descriptions, every sentence earns its place by conveying operation, side effects, return value, workflow, billing behavior, signature progress, and exclusions. It is front-loaded with the core purpose and avoids vague filler, making the length justified and useful.

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 stating that the return value is draftId, not documentId. It covers the full scope of copied configuration, what is not copied, billing implications, workflow next steps, and the draft-duplication exclusion, giving an agent enough context 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?

The input schema covers all three parameters with descriptions (100% coverage), so the baseline is 3. The description adds useful context that documentId refers to a sent document and that the output is a draft, but it does not materially deepen parameter-level semantics beyond what the schema already provides.

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 the operation explicitly: copying a sent document's configuration into a NEW DRAFT, listing exactly which aspects are copied. It also distinguishes itself from duplicate_draft by explicitly stating that drafts cannot be duplicated with this tool, and clarifies that it returns draftId rather than documentId.

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 provides explicit when-to-use context and workflow guidance: review the copy, adjust with update_draft, then send with send_draft. It also gives a clear exclusion and alternative: 'A draft cannot be duplicated with this tool — use duplicate_draft.'

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 provide no safety hints (all false), so the description carries the burden of disclosure. It adds key behavioral facts: the original is untouched, no sending occurs until send_draft is called, and payment requirements carry over. This goes beyond what annotations state.

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 serving a distinct purpose: the core action, the recommended use case, and cost/side-effect notes. The most important information is front-loaded, with no redundancy or 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 simple tool with 3 parameters and no output schema, the description covers the main effect and side effects well. However, it does not state what the function returns (e.g., the new draft's ID or object), which is important for an agent to reference the copy afterward. This gap is notable given no output schema to fill it.

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 all parameters (name, userId, draftId) are documented in the schema. The description adds no parameter-specific semantics beyond the schema, so it meets the baseline but does not enhance 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 states a specific action and resource: 'Copy a draft into a new draft, leaving the original untouched.' This clearly distinguishes it from sibling duplicate tools for other resources (document, link, template) by naming the resource type 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?

The description provides a use case ('Useful for building several similar documents from one prepared starting point') but does not explicitly state when not to use it or contrast it with alternatives like create_draft or duplicate_document. Guidance is present but limited.

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 declare destructiveHint=true and readOnlyHint=false, but the description adds significant context beyond that: the action costs credits, is billed exactly like create_link, allocates its own instance, and charges pro rata for the rest of the period. It also discloses that the source link is untouched and keeps working, plus error conditions (402/403), which is valuable behavioral context an agent needs before calling.

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: purpose, source-link safety, credit cost, user-confirmation requirement, error codes, and the disabled-link revival use case. Important warnings are front-loaded and capitalized, making critical constraints hard to miss. It is longer than average, but the content justifies the length.

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

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

For a two-parameter tool with no nested objects and full schema coverage, the description covers all essential operational context: cost implications, irreversibility implications for disabled links, user confirmation, and failure modes. It does not describe the return value, but the tool's behavior and constraints are sufficiently complete for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description does not add parameter-specific detail beyond the schema, but it reinforces the purpose of name by noting the copy defaults to the source's name and leaves two links with the same name. This is baseline-appropriate given complete schema coverage.

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: 'Create a new public link' with the same configuration as an existing one. It clearly differentiates from siblings like create_link by framing this as a copy of an existing link, and it explicitly notes the copy gets its own URL while the source remains untouched. An agent can confidently distinguish this from disable_link, update_link, and create_link.

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 states clear usage context: duplicate an existing public link, and notably, it is the way to revive a disabled link because disabling cannot be undone. It also gives an explicit behavioral requirement: ALWAYS confirm with the user before calling. It does not explicitly name create_link as the alternative for brand-new links, but the distinction is strongly implied throughout.

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 say the operation is not read-only and not destructive; the description adds meaningful behavioral context: the original is untouched, the copy belongs to the duplicator, and template duplication is free. It does not mention return values or side effects, but it enriches the sparse annotations without contradicting them.

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 earning its place: the core operation, ownership semantics and use case, and a pricing distinction from a sibling behavior. The key verb and object are front-loaded; 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?

For a simple two-parameter action with no output schema, the description covers what the tool does, the key behavioral nuances, and a relevant alternative. It could add what the caller should expect back (e.g. the new template's ID), but the action is simple enough that the current description is nearly 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?

Schema description coverage is 100%, so the schema already names and explains both parameters, including the caveat that name defaults to the source's name. The description itself does not add parameter-level detail, but it does not need to given the schema's coverage.

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: 'Copy a template, leaving the original untouched.' It clearly distinguishes this from duplicate_document, duplicate_draft, and duplicate_link by focusing on templates and even notes that duplicating a public link behaves differently.

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 concrete usage context: it is the way to make a copy and the way to take a private copy of a colleague-shared template. It also hints at an alternative by contrasting template duplication with public-link duplication, though it does not explicitly say 'use duplicate_link instead for public links.'

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

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

The description adds valuable behavior beyond annotations by explaining the semantics of returned fields (signatureBankId, signatureIdScan, signatureFaceLiveness) and disclosing that no identity data passes through the API. This privacy/security context is not present in the annotations and helps set correct expectations.

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, front-loaded with the main purpose, and the second sentence adds a crucial caveat. There is no redundant or filler content; 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?

Given zero parameters, annotations for safety, and no output schema, the description is nearly complete: it states what the tool returns, gives examples, and highlights a non-obvious caveat about signature flags. The only minor gap is not specifying the response format, but that is not essential for such a simple capability check.

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

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

The tool has zero parameters and an empty schema, so there is nothing to clarify at the parameter level. The description instead clarifies response semantics (capability flags), which is the only useful extra context. A baseline of 4 is appropriate for a no-parameter tool.

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 ('Check') and resource ('account capabilities'), and gives concrete examples (BankID, templates, AI assistant). It also clarifies the meaning of the signature-method flags, which distinguishes this tool from other account-related getters in the sibling list.

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 clearly indicates this is for checking enabled features and importantly explains that the signature flags only indicate selectable methods, not actual verification. It implicitly tells an agent that identity verification is not done through this API, providing a clear boundary, though it does not name alternative tools explicitly.

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 read-only/idempotent safety. The description adds beyond annotations: the result includes pending invitations and returns a userId per user, giving the agent useful behavioral expectations for a parameterless list call.

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 crisp sentences. The core action and inclusion criteria are front-loaded, followed by a single high-value usage pointer. No filler or redundancy.

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 zero-parameter read tool, the description covers what is returned, the scope (all users including pending invitations), and one important downstream use. It is missing nothing critical for an agent 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?

The tool has zero parameters, so the baseline is 4. The description adds no parameter detail (none needed) but does hint at how the returned userId will be consumed elsewhere, which is mildly useful.

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?

Clear verb+resource: 'List all users on the account, including pending invitations.' It precisely describes scope but does not explicitly contrast with sibling tools like get_current_user, 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?

Provides a concrete use context: the returned userId can be used in create_document for ownership assignment. It does not explicitly state when not to use this tool or mention alternatives, but the guidance given is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds minimal behavioral context beyond 'get information,' but for a simple read-only operation with no parameters, this is acceptable. 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 a single, clear sentence with no wasted words. It is appropriately sized for a simple, parameterless read operation.

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 zero-parameter, read-only tool with annotations covering safety and idempotency, the description is nearly complete. It doesn't specify the exact fields returned, but no output schema exists and the tool's purpose is simple enough that an agent can infer the return value will contain user details.

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

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

The tool has zero parameters, so the schema provides no parameter semantics to clarify. The description correctly indicates no inputs are needed, which is sufficient. Baseline 4 for zero-parameter tools 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?

The description clearly states the tool's function: retrieving information about the currently authenticated user. It uses a specific verb ('Get') and resource ('current user'), and while it doesn't explicitly differentiate from siblings, its unique focus on the authenticated user distinguishes it from other get_* 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?

The description implies usage context—when you need details about the authenticated user—but does not explicitly state when to use this tool versus alternatives. There are no exclusions or alternative tool mentions, but the zero-parameter design makes the intended use fairly obvious.

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 goes well beyond the readOnly/idempotent annotations by enumerating the full document status enum and describing signeeDetails fields, including the important signatureStatus naming distinction and cooldown semantics. It also explains field values precisely, which is valuable without an 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?

The purpose is front-loaded in the first sentence, and the subsequent detail is dense but relevant. Enum values and field paths are clearly formatted, and the nested cooldown explanations earn their place because there is no output schema to document them.

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?

Without an output schema, the description carries the full burden of explaining the response contract. It covers all status values, signeeDetails fields, signatureStatus values, and cooldown semantics, which is sufficient for an agent to call and interpret 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%, and the sole parameter documentId is adequately described in the schema as 'Unique identifier of the document.' The description does not add parameter-specific semantics, but none are necessary given the complete schema coverage.

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

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

The description uses a specific verb ('Get') and resource ('specific document'), and specifies that it returns 'detailed status and metadata' plus 'per-signee signing status.' This distinguishes it from siblings like get_document_fields, get_draft, and list_documents without ambiguity.

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

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

There is no explicit guidance on when to use this tool versus the many sibling tools, nor any mention of prerequisites or exclusions. The usage context must be inferred entirely from the verb and the return description.

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 read-only, idempotent, non-destructive behavior. The description adds valuable context beyond those annotations: field type semantics, the readOnly meaning, and the value format rule (string vs array). 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?

Front-loaded with the core purpose, then each subsequent sentence adds necessary operational detail: field structure, usage ordering, alternative tool, and a critical value-format rule. 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 well by enumerating returned field properties and their meanings, plus the value format caveat. This is complete enough for an agent to invoke the tool and interpret its 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 only parameter, documentId, is fully covered by the schema description ('Unique identifier of the document'), so the 100% schema coverage gives a baseline of 3. The tool description adds no extra parameter detail, but none is needed.

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 'Retrieve all form field definitions in a document' uses a specific verb and object, and immediately distinguishes itself from sibling get_document_field_values by noting this tool returns field definitions, not filled values.

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 to call this before set_document_field_values, and points to get_document_field_values for already-filled values. This gives the agent clear selection and sequencing 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the behavioral detail that it works on documents in any status, which is not present in the annotations. This is useful context beyond what the structured fields provide. 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 three short sentences with no redundant information. The core purpose is front-loaded, followed by the status note and the sibling distinction. Every sentence earns its place, making it easy for an agent to quickly parse the essential 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?

For a simple read-only tool with one parameter and no output schema, this description is complete. It covers the purpose, status flexibility, and sibling differentiation. Annotations already handle the safety profile, and the return format is implicitly understood from the purpose (current field values). Nothing essential is missing for an agent to call this 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?

The schema describes the single parameter documentId with 'Unique identifier of the document', providing 100% coverage. The description adds no additional parameter semantics, but since the schema fully covers the parameter, the baseline score of 3 applies. The description doesn't need to repeat what the schema already states.

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

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

The description clearly states the verb 'retrieve' and the resource 'current values of all form fields in a document'. It explicitly differentiates from the sibling tool get_document_fields by noting that for field definitions and types, that tool should be used instead. This unambiguous purpose makes the tool easy to distinguish from its 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?

The description provides explicit guidance on when to use this tool: when you need current field values, and it works on documents in any status. It also explicitly names the alternative tool (get_document_fields) and the condition under which it should be used instead ('for field definitions and types'). This leaves no ambiguity about tool selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile well. The description adds value beyond annotations by enumerating what data the draft details include and by disclosing the prerequisite relationship to mutation tools. No contradiction with annotations; the description adds meaningful context on top of a strong annotation baseline.

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 zero filler. The purpose and content scope are front-loaded in the first sentence, and the sequencing instruction follows in the second. It's appropriately sized for the tool's simplicity, though the enumeration is slightly long-winded.

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

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

For a simple read tool with one parameter, strong annotations covering safety, and no output schema, the description is nearly complete. It discloses the returned content and the usage prerequisite. The only minor gap is no explicit statement about what a not-found draftId returns, but this is acceptable given the tool's simplicity.

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% with a single parameter (draftId) fully documented in the schema, so the baseline is 3. The description doesn't add parameter-specific detail beyond the schema, but none is needed for a single well-documented ID parameter. The description's content enumeration indirectly explains what the ID resolves to, which is adequate.

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

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

The description uses a specific verb ('Get') with a clear resource ('draft details') and enumerates the exact content returned: saved signee details, signature placements, form field values, invitation settings, and AI assistant configuration. This specific enumeration clearly distinguishes it from sibling tools like get_draft_file, get_draft_file_url, and list_drafts.

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 gives explicit when-to-use guidance: 'Always call this before update_draft, send_draft, or delete_draft.' This is strong sequencing instruction. It doesn't state explicit exclusions (e.g., 'for a list of drafts use list_drafts'), but the enumeration of content plus the mutation-prerequisite guidance provides clear context for selecting this tool.

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 readOnly/idempotent, and the description adds substantial behavioral detail: output encoding (base64 PDF), associated metadata, rendering scope only for fields with valid coordinates, exclusion of invalid fields from the PDF, draft-status/expiry constraints, and Bearer-token authentication. 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 compact and every sentence earns its place: output format, sibling routing, rendering edge case, and prerequisites/auth. It is front-loaded and gives the agent the most decision-relevant information first.

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?

Even with no output schema, the description fully explains return values (base64 PDF, filename, size), rendering edge cases, usage conditions, and authentication. The single required parameter is fully documented, and the sibling-routing guidance is explicit, making the description sufficient 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 coverage is 100% and the only parameter, draftId, is already clearly described in the schema as 'Unique identifier of the draft to preview'. The description does not add syntax, format, or parameter-specific nuances beyond this; its added text is about the draft/resource behavior, not the 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?

Clearly states the tool returns a PDF preview with signature fields rendered at their configured coordinates, as an embedded resource plus filename and size metadata. It also explicitly contrasts with get_draft_file_url, making the purpose and distinction 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?

Explicitly says when to use this tool (when the MCP client can render PDFs inline) and when to use get_draft_file_url instead (when only clickable links are supported). It also establishes prerequisites—draft must still be status draft and must not be expired—so an agent can pre-check validity before invoking.

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?

Discloses important behavior beyond annotations: the URL is short-lived, one-time-use, expires after 10 minutes, is consumed on download, requires no Authorization header, and only works while the draft is still in draft status and not expired. It also explains that fields without valid coordinates are omitted from the rendered PDF but remain in draft data. This adds substantial operational context beyond the readOnlyHint annotation.

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 detailed but every sentence contributes distinct useful information: purpose, return payload, auth requirement, usage guidance, workflow integration, rendering caveat, and constraints. It is front-loaded with the core purpose and then provides necessary operational context without redundancy.

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 fully covers return values, expiry behavior, authentication, prerequisites, and sibling differentiation. The mention of the typical preview flow also makes the tool's role in a larger process clear and sufficiently 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 coverage is 100%, so the draftId parameter is already fully described in the schema. The description adds contextual constraints such as draft status and expiry but does not add new parameter-level semantics. Baseline 3 is appropriate given complete schema coverage.

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 short-lived, one-time-use download URL for a PDF preview of the draft.' It clearly distinguishes itself from get_draft_file by describing the URL-based output and the condition under which each tool is appropriate.

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 this tool ('when the MCP client should hand the user a clickable link') and when to prefer an alternative ('If the client can render PDFs inline, prefer get_draft_file'). It also provides a typical preview flow with related tools, leaving no ambiguity about placement in a workflow.

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 read-only and non-mutating behavior. The description adds a useful value-format caveat for later pre-filling, but does not disclose any additional behavioral traits of this operation beyond what the annotations imply.

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, purposeful sentences. The core action and timing are front-loaded, and the value-format warning is compact and relevant.

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 simple read-only nature and the lack of an output schema, it communicates what is returned ('all form fields') and why the agent should use it. It does not spell out the exact return structure, but the purpose is clear.

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 already explains fileId as the uploaded file identifier. The description reinforces that it refers to an uploaded PDF, but does not add substantial meaning beyond the input 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?

Clearly states the action ('Retrieve all form fields'), the resource ('a PDF file'), and the stage in the workflow ('before creating a document from it'). This distinguishes it from related field/pre-fill operations.

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 tells the agent when to call this function: after upload_file and before document creation. It could name alternatives or conditions where it should not be used, but the workflow context is solid.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds crucial behavior: linkUrl is null while processing, and it explains the status values (active, disabled, processing) in context. Slight gap: no mention of possible errors or rate limits, but the added context is valuable.

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 efficient, front-loading the purpose, listing key fields in the first sentence, then adding contextual details. Every sentence earns its place; the guidance about update_link is placed at the end, which is fine as it's a usage note.

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

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

For a simple read operation with one parameter, the description provides comprehensive information: the return fields, the status vocabulary, the null behavior of linkUrl, and the relationship to update_link. No output schema exists, so this description fully compensates, making the tool easy to call 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?

The schema covers 100% of the single parameter (linkId) with a clear description, so the schema does the heavy lifting. The description doesn't need to add more; 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?

The description clearly states the tool retrieves a public link's full configuration, enumerating specific fields (name, language, status, signature slots, linkUrl). This precisely defines the resource and scope, distinguishing it from siblings like get_document or get_template.

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 instructs to ALWAYS call this tool before update_link, providing a clear when-to-use directive. It also contrasts the link's status vocabulary with documents, preventing misuse.

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 readOnly/idempotent annotations, the description discloses critical semantics: the values are the starting point every signer sees, not anyone's answers, because a public link has no single set of answers. This prevents a common misinterpretation and clarifies what the tool does not return.

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 definition, then adds essential differentiators and routing. Each sentence earns its place; the length is justified by the conceptual pitfalls it prevents.

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

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

With a single fully-documented parameter and no output schema, the description provides everything needed: what the tool returns, what it does not return, how it differs from siblings, and how to get actual signer-entered values. No critical calling context 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?

The only parameter, linkId, is already fully described in the schema as the unique identifier of the public link, so schema coverage is 100%. The description adds contextual meaning about public links but no additional parameter-level details, so the baseline of 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?

The description uses a specific verb ('List') and resource ('PDF form fields (AcroForm) in a public link's document'), and clearly distinguishes itself from signature slots by pointing to get_link's signeeDetails. This makes the tool's purpose unmistakable even among many sibling 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 contrasts with get_link's signeeDetails and gives a concrete alternative workflow for reading individual signer answers: take a documentId from list_link_documents and call get_document_field_values. It also states there is no tool for setting field values on a link, preventing futile searches.

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 substantial behavior beyond annotations: links are verification-locked, a one-time code is sent to the recipient's contact on file, recipients with both email and phone appear as two entries, recipients with no contact method are omitted, and calling generates and persists links on first use. Annotations provide idempotentHint and non-read-only status, and the description aligns with them while adding rich operational detail.

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 long but every section earns its place: purpose, security model, response shape, edge cases, and state-changing behavior. It is front-loaded with the core purpose and then covers essential caveats in a structured, readable way. Nothing feels 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?

Given the tool uses only one parameter, has no output schema, and involves complex security behavior, the description is remarkably complete. It explains response fields, verification flow, duplicate entries for dual-contact recipients, omitted recipients, idempotency, and the sent-versus-draft restriction, leaving no critical gap 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?

The schema already provides 100% coverage for the single documentId parameter. The description adds meaningful semantic constraint by specifying the document must be sent, not a draft, which goes beyond the schema's generic 'Unique identifier of the document' and helps the agent validate inputs before calling.

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 first sentence states a specific verb, resource, and scope: 'Get unique, self-distributable signing links for a document — one per recipient.' It clearly distinguishes this from generic link tools by emphasizing per-recipient, verification-locked links and manual distribution, which separates it from siblings like get_link or list_links.

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 the tool: 'Use this for signees created with disableInvitationMessage: true' or 'whenever the user wants to distribute a signing link themselves.' It also gives when-not guidance ('Only works on a sent document, not a draft') and names related alternatives like update_signee and revoking/resending the document for unrecoverable cases.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavior beyond that: the URL expires after 10 minutes and the document must be complete/signed by all parties. This gives agents actionable expectations without contradicting 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 short sentences with no filler. It front-loads the core purpose and adds only the important operational detail (10-minute validity), making it easy for an agent to parse quickly.

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

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

For a simple one-parameter read-only tool with strong annotations, the description is complete: it names the exact precondition, the resource, and the expiry behavior. An agent has all the information 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?

With 100% schema coverage for the single parameter, the schema already describes documentId fully. The description does not add new parameter-level semantics beyond confirming the document is completed, so the baseline of 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?

The description clearly states a specific verb and resource ('get a download URL') and narrows it with a precise condition ('completed signed by all parties document'). It also adds the URL validity window, which helps distinguish this from other fetch/list 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?

The description clearly implies when to use the tool: only for documents that are fully signed and completed. It does not explicitly name alternatives or exclusions, but the phrase 'completed (signed by all parties)' provides a clear contextual condition that guides selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by specifying the exact return content and mandating a follow-up call, which is behavioral context beyond annotations. No contradictions exist.

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 redundant phrasing. The purpose and return list are front-loaded, and the critical next-step instruction follows directly. Every word earns its place.

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

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

With only one parameter and no output schema, the description covers the return payload and the mandatory next step, which is sufficient for correct invocation. It doesn't mention error conditions or response formatting, but these are minor given the tool's simplicity and the read-only annotations.

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 single parameter templateId with a clear description ('Unique identifier of the template'), giving 100% coverage. The tool description adds no additional parameter-level meaning, so it relies on the schema as the baseline.

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

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

The description clearly states the verb and resource ('Get details for a specific template') and enumerates the returned fields (name, number of signees, and each signee's signature settings). This distinguishes it from siblings like list_templates and get_template_fields, which have different scopes.

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 usage guidance: 'Always call get_template_fields immediately after this — before collecting signer details or creating the document.' This tells the agent when and in what sequence to use this tool, effectively routing it to the correct sibling.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond this by detailing the field structure (name, label, type, editable, readOnly, options), explaining the decision to pre-fill, and the value formatting rules (string vs array, omit empty strings). This adds substantial behavioral context that annotations do not cover.

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 critical usage instruction ('Always call this immediately after get_template'), then systematically explains the field properties, the conditional action, and the value format rule. Every sentence adds essential information without redundancy, making it well-structured and efficient.

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

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

Given there is no output schema, the description fully explains the return structure (field attributes) and how to interpret it for subsequent actions. It covers the workflow (pre-fill decision), value format rules, and edge cases (omit empty strings). Nothing an agent needs to call and use 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?

The schema already documents the only parameter templateId with a description ('Unique identifier of the template'), achieving 100% coverage. The description does not add new semantic details about the parameter itself, though it implies the templateId comes from get_template. Since schema coverage is high, the baseline of 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?

The description clearly states the tool reveals whether a template has pre-fillable form fields, with a specific verb ('reveals') and resource ('template fields'). It is implicitly distinguished from sibling tools like get_document_fields and get_file_fields by the context of 'template' and the instruction to call it after get_template, so an agent can select it 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?

The description explicitly says 'Always call this immediately after get_template — before collecting signer details', giving a precise timing and workflow context. It also provides conditional guidance on asking the user about pre-filling when editable fields exist, and states the value format rule for different field types, which is essential for correct invocation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds critical pagination behavior: follow nextOffset until null, and never stop at a short page. This goes beyond the annotations and is essential for correct iteration.

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 concise sentences: the first states the purpose and scope; the second delivers a crucial pagination warning. No fluff, front-loaded with the primary action, and 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 list tool with no output schema, the description covers the essential behavior: scope and pagination protocol. It does not detail the response structure, but the pagination semantics imply nextOffset is in the response. The absence of an explicit output description is a minor gap, but overall the agent has enough 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 100% with descriptions for both limit and offset. The description adds context on how to use offset (pass nextOffset from the previous response) and clarifies when pagination ends (when nextOffset is null), enhancing the schema's basic parameter 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 clearly states the verb 'List' and the resource 'documents', with a specific scope ('created by the user or shared within the account'). This differentiates it from sibling tools like list_drafts, list_links, and list_templates, which target other resource types.

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

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

The description implies usage for listing documents but does not explicitly compare with alternatives such as list_drafts or list_links. It provides scope ('user or shared within the account') but no direct when-to-use vs. when-not-to-use guidance, leaving the agent to infer from the resource name.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the pagination contract (nextOffset until null), the fact that short pages are intentional and must not be treated as the end, and the default user scoping behavior. It doesn't describe the response shape, but with no output schema and a read-only list operation, the pagination behavior is the most important behavioral disclosure and it is present.

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 compact and front-loaded: the core action ('List draft documents with pagination') comes first, followed by a one-sentence definition of drafts, a routing pointer to get_draft, and a clearly marked PAGINATION section. Every sentence earns its place, and the critical pagination warning is highlighted with a label.

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 list tool with 100% schema coverage and annotations covering safety, the description is nearly complete. It covers the core action, the draft concept, the sibling to use for inspection, and the pagination contract. The only minor gap is that it doesn't describe the response envelope (e.g., that the response contains drafts and nextOffset), but the pagination instructions strongly imply it, and the schema documents the offset parameter. This is a minor gap, not a blocking 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 description coverage is 100%, so the schema already documents all three parameters (limit, offset, userId) with descriptions. The description adds the pagination protocol ('follow nextOffset until it is null') and the short-page warning, which complements the offset parameter description. However, it doesn't add meaning beyond what the schema provides for limit and userId. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('List draft documents') and clearly distinguishes drafts from sent documents by defining them as 'saved document configurations that have not been sent for signing yet.' This differentiates list_drafts from siblings like list_documents and list_templates without needing to inspect 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?

The description explicitly tells the agent when to use this tool versus alternatives: 'Use get_draft to inspect a draft before updating, sending, or deleting it.' It also provides a clear pagination protocol with an explicit stopping condition ('follow nextOffset until it is null') and a warning about short pages, which is exactly the kind of usage guidance an agent needs.

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 readOnlyHint, idempotentHint, and destructiveHint=false, so the description's burden is to add semantics beyond those flags. It does: only completed submissions are returned, abandoned submissions are excluded, and short pages are intentionally not the end of the list. This is exactly the non-obvious behavior an agent needs.

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?

Every sentence earns its place: scope, differentiation, output usage, exclusion behavior, and pagination caveat are all present without fluff. The most important scoping information is front-loaded, and structural markers like 'PAGINATION' make it easy to parse.

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 list tool with three well-documented parameters and no output schema, this definition is complete. It names related tools for consuming the documentId, explains the exclusion case, and fully specifies the pagination contract. Nothing needed for an agent to select and call 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?

The input schema already has 100% coverage with descriptions for all three parameters, so the baseline is 3. The description adds meaningful value by explaining how to use offset/nextOffset ('follow nextOffset until it is null') and warning against stopping at a short page, which directly improves correct invocation of the pagination parameters.

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 ('list') and a precise resource ('completed documents a public link has produced'), and immediately differentiates itself from list_documents, which covers documents sent to named recipients. An agent can clearly tell this tool from its siblings without opening 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?

It explicitly explains when to use this tool (for public-link submissions) and what it is not (not part of list_documents). It also gives actionable routing guidance: each documentId can be passed to get_document, get_signed_document_url, and get_document_field_values. Pagination behavior is fully specified.

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 call read-only and idempotent, and the description adds substantial behavior beyond that: public links are reusable signing links producing a separate document per signer, results should be presented as names/status with IDs hidden, the capability is required, and pagination must continue via nextOffset until null, including on short pages. 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?

Every sentence earns its place: scope, conceptual definition, output presentation, capability requirement, and pagination caveat. The most important disambiguation is front-loaded in the first sentence, and the pagination warning is clearly delimited.

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 list operation with only two well-documented parameters, the description covers scope, output format, capability prerequisite, and pagination semantics. Since there is no output schema, the description still conveys the essential return shape (link names and status) and the nextOffset mechanism, giving an agent everything needed 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 100%, so the input schema already documents limit and offset fully, including defaults and the meaning of nextOffset. The description reinforces the pagination contract but does not add new parameter meaning beyond what the schema provides, matching the baseline for high coverage.

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 ('List the public links you own plus the ones shared with the account'), and clearly distinguishes public links from per-recipient links by naming get_recipient_links as the source of the latter. This makes the tool's scope unambiguous even among many sibling list 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?

Explicitly tells when to use this tool (public links, owned/shared) and when not to (per-recipient links of already-sent documents), naming get_recipient_links as the alternative. It also states the prerequisite publicLinks capability, so an agent can verify availability before calling.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the presentation rule (hide IDs/metadata from the user) and the critical pagination behavior (short pages are not necessarily the last; follow nextOffset until null). This is exactly the kind of non-obvious behavior an agent needs to know.

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 states the core action and presentation rule, the second gives the pagination rule, and the third explains the non-obvious short-page behavior. The most important operational guidance is front-loaded.

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 list tool with 100% schema coverage and no output schema, the description covers the essential behavior: what to list, how to present it, and how to paginate. The only minor gap is that it doesn't describe the response shape, but since there is no output schema and the tool is simple, the description is nearly 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 100%, so the schema already documents both parameters (limit and offset) with descriptions including defaults and the nextOffset instruction. The description reinforces the pagination semantics but does not add meaning beyond what the schema provides. 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?

The description states a specific verb and resource ('List all available signing templates') and adds a clear presentation directive (show only names, hide IDs/metadata). It is easily distinguished from siblings like list_documents or list_drafts by the resource named in the first sentence.

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 for when to use the tool: when listing all available signing templates. It does not explicitly name alternatives or exclusions, but the sibling list makes the resource distinction clear, and the pagination guidance is strong. A small deduction for not explicitly saying 'use get_template for a single template's details'.

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 idempotentHint=true, covering the safety profile. The description adds the 'for this account' scope, which is useful but does not disclose any additional behavioral traits such as return format, pagination, or error handling. It adds minimal value beyond 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 a single concise sentence with no filler. It front-loads the action and scope, making it immediately clear and efficient.

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

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

With no output schema, the description carries the burden of explaining return values, but it only states 'list all registered webhooks' without describing the structure or contents of the returned list. It does not mention potential empty results or any error conditions. For a trivial list tool this is adequate but not fully complete.

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

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

There are zero parameters, so the schema fully covers parameter semantics. The description adds no parameter information, but with no parameters, the baseline is 4. It does not need to compensate for any gaps.

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 'list' and a clear resource 'webhooks' with an account scope, distinguishing it from sibling tools like register_webhook, delete_webhook, and rotate_webhook_secret. It is not a tautology and clearly identifies the 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?

The description provides no guidance on when to use this tool versus alternatives. It does not mention any conditions, exclusions, or references to sibling webhook tools. For a simple list operation the usage might be obvious, but the description itself offers no explicit or implied routing.

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=false and destructiveHint=false, so the description doesn't need to restate safety. The description adds valuable behavioral context: original files are kept, order matters, and a new fileId is returned. This goes beyond the schema and annotations, though it doesn't mention potential failure modes (e.g., unsupported file types) or rate limits.

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 action, the return value, and the critical ordering constraint. No fluff, no repetition of schema details. The most important behavioral note (order matters) is front-loaded in the final sentence.

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 2 parameters, 100% schema coverage, and no output schema, the description is nearly complete. It covers the input, the output (new fileId), the side effect (originals kept), and the ordering semantics. The only minor gap is that it doesn't describe the format of the returned fileId or any error conditions, but those are not essential 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 100%, so the baseline is 3. The description adds meaning beyond the schema by explicitly stating that the first fileId appears first (topmost pages) and that order matters, reinforcing the array semantics. It also clarifies that 'name' should include the extension, which is already in the schema but reinforced. This is a modest but real addition.

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 ('Merge'), a resource ('previously uploaded PDF files'), and a concrete outcome ('into a single file'). It also distinguishes itself from siblings by specifying the input type (PDF files) and the result (a new fileId), which is not ambiguous with create_document or upload_file.

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 clearly implies when to use this tool: when merging 2–8 previously uploaded PDFs. It does not explicitly name alternatives or exclusions, but the context (sibling tools like upload_file, create_document) and the explicit 'previously uploaded' phrasing provide clear usage context. A small gap: it doesn't say 'use upload_file first if files aren't uploaded yet,' but that is reasonably implied.

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 safe, non-destructive operation (readOnlyHint=false, destructiveHint=false). The description adds that registration creates a webhook that receives document event notifications via HTTP POST, which is useful context. It does not disclose delivery guarantees, verification handshakes, or what the response contains, but the annotations lower the burden.

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, well-structured sentence states the action, object, purpose, and delivery mechanism 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 simple create operation, the description plus schema and annotations cover the essentials. However, there is no output schema and the description omits practical invocation details such as URL validation expectations, auth implications, or what is returned after registration. This is adequate but not rich.

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 a clear description. The tool description does not add meaning beyond the schema, so the baseline of 3 applies.

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

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

The description names a specific verb ('Register'), a resource ('new webhook'), and the exact purpose ('receive real-time document event notifications via HTTP POST'). It is clearly distinct from lifecycle siblings like delete_webhook, list_webhooks, and rotate_webhook_secret.

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 context for when to use the tool: creating a webhook to receive real-time event notifications over HTTP POST. It does not explicitly name alternatives such as listing or rotating existing webhooks, but the intended use case is reasonably clear and no exclusion criteria are needed for a creation endpoint.

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 convey that it is not read-only (readOnlyHint=false); the description carries the full burden and delivers richly. It discloses that the staged entry holds no bytes until curl completes, the 10-minute URL expiry, the single-pending-upload-per-user rule, the exact refusal behavior (repeating pending uploadId and curl command), and how to diagnose sandbox blocking (network/DNS/allowlist errors). This is well beyond what annotations provide.

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 long, but every sentence earns its place given the complex two-step protocol, fallback path, and error-handling rules. CAPS markers (CRITICAL, ONE AT A TIME) highlight the highest-stakes guidance, and the flow is mostly chronological. It is dense rather than padded, though a bit monolithic in structure.

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 correctly explains what is returned (presigned URL, curlCommand, uploadId) and covers the full lifecycle: request, execute curl, wait for HTTP 200, call upload_file, one-at-a-time constraint, refusal handling, and fallback to direct upload. Nothing an agent needs to execute 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 coverage is 100% and there is only one parameter (fileName), so the schema already fully documents it. The description reinforces that the file is a PDF and ties the parameter to the attachment context, but it does not add meaningful new semantics beyond what the schema states. 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?

The description states a specific verb and resource ('Stage an upload for a PDF... Returns a presigned upload URL plus a ready-made curlCommand'), which clearly distinguishes it from the sibling upload_file. The scoping to shell-capable clients and the explicit mention of the two-step flow make the purpose 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?

Extremely explicit: it names the exact condition for use (can execute shell commands but cannot pass the file to a tool), the when-not path (skip and call upload_file with fileReference/url/file), the required follow-up order (run curl, wait for HTTP 200, call upload_file with uploadId), and the one-at-a-time constraint. No inference is required.

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 openly states that revoking is 'irreversible', which meaningfully supplements the annotations (destructiveHint=true, idempotentHint=true). It also discloses the conditional behavior based on signing status and mandates a confirmation step before invocation, giving the agent important behavioral context beyond the basic mutation flag.

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 compact, front-loaded with the core action and condition, and every sentence adds value. The prerequisite workflow is stated efficiently without unnecessary elaboration.

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 destructive action with no output schema, the description covers the essential operational context: applicability condition, required pre-call, confirmation step, and irreversibility. Nothing critical is missing for an agent to invoke this 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?

The input schema fully documents the only parameter (documentId), so the description does not need to add parameter-level detail. Baseline of 3 applies because the parameter is already well-defined and there is no ambiguity about what the caller must provide.

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

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

The description uses a specific verb ('Revoke') and names the exact resource type ('a document that has been sent for signing'), which clearly distinguishes it from generic deletion or creation tools. It also embeds a key scoping condition ('only possible if not yet fully signed'), making the tool's purpose unambiguous among siblings like delete_document and send_draft.

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: only for documents already sent for signing and only if not fully signed. It also prescribes a required prerequisite workflow ('Always call get_document first... then show the user a summary and ask for confirmation'), which is concrete and actionable for an agent.

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 destructiveHint=true, and the description adds value by specifying the consequence: the old secret is invalidated and verification logic must be updated. This goes beyond the annotation by explaining the operational impact.

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 zero waste. The core action and return value are stated first, followed by a critical operational instruction. Efficient and front-loaded.

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

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

For a simple one-parameter tool with no output schema, the description covers the action, the return value, and the essential post-action. Annotations cover the destructive nature, and no further information is needed 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 coverage is 100% for the single parameter webhookId, and the description does not add any additional semantic detail beyond the schema's 'Unique identifier of the webhook'. Baseline 3 is appropriate as the schema carries the full burden.

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 ('rotate'), resource ('webhook'), and the exact attribute ('HMAC signing secret'). It also mentions the return value and a required post-action, clearly distinguishing it from sibling tools like register_webhook or delete_webhook.

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 explicitly instructs the user to update verification logic immediately after rotating, which implies the old secret becomes invalid. It does not explicitly state when to use this tool versus alternatives, but the context (sibling tools) makes it the only rotation option, and the instruction is clear.

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 destructive, and the description adds valuable behavior: validation failure leaves the draft unsent, and confirmation is required before sending. This goes beyond the annotation's simple destructive hint.

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 primary action, then gives concise but essential preconditions and failure behavior. Every sentence earns its place without unnecessary 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?

The description covers the key context for a destructive action: prerequisites, confirmation requirement, and failure behavior. It does not describe the success return value, but the absence of an output schema makes this less critical.

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 for the single parameter draftId is 100%, with the schema already describing it as the unique identifier of the draft. The description adds no additional parameter-level meaning, so the baseline of 3 applies.

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

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

The description clearly states the action ('Convert a draft into a live document and send invitations') with a specific verb and resource. This distinguishes it from sibling tools like create_draft, update_draft, and send_reminder.

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 preconditions: call get_draft first, verify signees and coordinates, show a summary, and ask for confirmation. It does not explicitly name exclusions or alternatives, but the context for when to use the tool is clear.

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 (readOnlyHint false, destructiveHint true, openWorldHint true), the description discloses rate limiting (max 2 per 60 minutes, returns 429), the 403 response on wrong document status, and the meaning of signeeDetails[].reminders.reminderCooldown. This is detailed operational behavior that annotations do not provide.

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 information-dense but every sentence earns its place: main action, mandatory pre-call, two precise conditions, user-confirmation requirement, rate limit, and cooldown handling. It is structured with numbered conditions and code identifiers for clarity, and it front-loads the most important operational step ('Always call get_document first') immediately after the main action.

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 write tool with two parameters and no output schema, the description covers all essential context: preconditions, parameter sourcing, failure modes (403, 429), cooldown semantics, and user-interaction expectations. Nothing an agent needs to call this tool correctly appears to be 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?

The input schema already covers both parameters with 100% description coverage, so the baseline is 3. The description adds substantial meaning beyond the schema by explaining that signeeIds must be filtered to only awaiting_signature signees and that documentId must reference a document in awaiting_signatures status. This goes beyond the schema's 'Unique identifier of the document' and 'Signee IDs to remind', earning a 4 rather than a 3.

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 ('Send'), a resource ('signing reminder to one or more signees'), and the condition 'who have not yet signed.' It clearly distinguishes this tool from siblings like send_draft and update_signee, making its unique role obvious.

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 instructs 'Always call get_document first' and states the two preconditions (document status must be awaiting_signatures, signees must have signatureStatus awaiting_signature). It also provides a rule for user interaction ('Show who will be reminded and ask for confirmation') and a retry guideline with cooldown checking, leaving no ambiguity about when and how to invoke the tool.

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 write and destructive nature (readOnlyHint=false, destructiveHint=true) and idempotency (idempotentHint=true). The description adds valuable behavioral context not in annotations: the tool only works before signing and only on editable fields, clarifying when an operation will fail. It does not detail the mutation semantics (e.g., whether existing values are overwritten), but annotations lower the burden.

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 filler: the primary purpose is first, followed by the usage condition, the preferred alternative, and the key limitation. Every sentence adds distinct value.

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

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

The description covers purpose, usage timing, alternative tool, and an important precondition. The schema fully documents parameter semantics. For a 2-parameter write tool with no output schema, this is nearly complete; the only minor gap is not stating what the response indicates about success.

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 input schema already documents both parameters and even gives detailed per-type value rules with examples. The description adds no parameter-level meaning, but with full schema coverage the baseline 3 applies.

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

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

The description states a specific action ('Update form field values on an already-created document') with a clear resource and distinguishes it from the read sibling get_document_field_values by framing this as a write operation. It also differentiates from create_document by explicitly targeting documents that already exist.

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: only after document creation when values need to be added or corrected, and points to the preferred alternative (pass values upfront via create_document's fields parameter). It also states a hard constraint: 'Only works on editable fields before anyone has signed.'

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 annotations (which already indicate destructiveHint=true), the description discloses the specific destructive behavior: 'signees not included may be removed.' It also explains the fileId optional behavior and the draft status requirement. This adds meaningful behavioral context 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 zero fluff. It front-loads the core action, the status requirement, the full-replacement semantics, and the fileId optionality. Every sentence earns its place and no information 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?

Given the tool's complexity (12 parameters, nested objects, no output schema), the description covers the essential operational context: what it does, when it applies, and the critical non-obvious behavior around signee replacement. The extensive per-parameter schema descriptions handle the rest, so the description is sufficient 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 coverage is 100% and every parameter has a detailed description, so the baseline is 3. The tool description reiterates key points already present in the schema (e.g., signeeDetails full replacement, fileId retention) but does not introduce new semantic meaning beyond the schema. It effectively highlights the most critical behaviors.

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: 'Update an existing draft.' It clearly distinguishes from siblings like create_draft, send_draft, and update_signee, and adds specificity by noting it is a 'full draft configuration update' and that the draft must still have status 'draft'.

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 precondition (draft must have status draft) and a critical usage caution (include the complete signeeDetails list because omitted signees may be removed). It does not explicitly name alternative tools, but the condition 'existing draft' and 'full configuration update' imply when to use this over create or signee-specific updates.

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/idempotentHint annotations, it discloses the full-replace destructive semantics, the fileId exception, that the public URL survives edits, that editing is not billed again, the 409 on disabled links, and permission restrictions. This is substantial behavioral context that cannot be inferred from annotations or schema alone.

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: full-replace warning, get_link workflow, fileId exception, URL/billing behavior, disabled-link error, and ownership permissions. Critical warnings are front-loaded and not padded with schema repetition.

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 complex 8-parameter update with nested objects, no output schema, and annotations covering mutating/destructive behavior, this description supplies the workflow, edge cases, and permission constraints needed to invoke the tool correctly. No critical selection or invocation detail 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 schema already documents each parameter. The description still adds cross-parameter semantics: complete configuration must round-trip from get_link and only fileId may be omitted to preserve the current document. This is valuable global guidance beyond individual schema field 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 opens with a specific verb-resource pair — 'Replace a public link's configuration' — and the title reinforces it. It is clearly distinguished from siblings like create_link, disable_link and duplicate_link because it frames the operation as replacing an existing link's full configuration.

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 preconditions and alternatives: ALWAYS call get_link first and send back the complete configuration, duplicate a disabled link rather than editing it, and owner-only editing establishes when use is allowed. This tells the agent both how to invoke it correctly and when to route to a different tool.

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 non-read-only and destructive; the description goes much further by disclosing that a successful update sends a new invitation, revokes old links, generates a new signeeId, and invalidates previously read IDs. It also surfaces the 60-minute cooldown and the concrete 403 failure modes, giving the agent a realistic model of side effects.

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 longer than average, but every sentence carries a precondition, side effect, or constraint. The operational prerequisite is front-loaded, and the numbered constraint list makes the 403 conditions scannable and actionable.

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 mutation with no output schema, the description fully covers preconditions, failure modes, cooldown behavior, and the post-update invalidation of signeeId. The agent has everything needed to call the tool correctly and to avoid stale-state mistakes.

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 input schema covers all parameters with descriptions, and the description adds crucial semantics: signeeId must come from get_document and becomes stale after the update; email/phone can only change an existing contact method, not add a new one; and updateCooldown from get_document should be checked before retrying. This goes well beyond the schema's basic field 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: 'Update contact details for one or more signees who have not yet signed.' It immediately scopes the operation to not-yet-signed signees and gives the canonical use case ('fix a wrong email'), which distinguishes it clearly from update_draft and the read-only 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?

It explicitly directs the agent to call get_document first to read signeeId and signatureStatus, and to check updateCooldown before invoking. It also gives strong when-not guidance: signed signees and completed documents cannot be changed, contact methods can only be changed not added, and breaking any constraint results in a 403.

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 readOnlyHint=false, and the description expands on exactly what is destructive: omitting fields loses them, except fileId. It also adds important behavioral context by stating that existing documents are unaffected because they took a copy at creation. This goes well beyond the annotation metadata.

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 sentences with no filler. The irreversible full-replace warning is front-loaded, followed by the essential exception, legacy impact, and permission constraint. Every sentence earns its place and directly affects whether the agent calls the tool safely.

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 update tool with a rich input schema and no output schema, the description covers the required pre-read step, the preservation exception, post-effect on existing documents, and authorization. An agent has everything it needs to decide to call the tool and construct a correct request.

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 a cross-cutting semantic layer — the entire configuration is replaced, not merged — which applies to every parameter and is especially critical for agents composing requests. The fileId exception is also stated globally, which reinforces and extends individual property 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 opens with a specific verb and resource: 'Replace a template's configuration.' It then clarifies the defining behavior — a full replace — which immediately distinguishes it from create, get, delete, and duplicate sibling tools. The name and title are reinforced, not merely restated.

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 clear precondition: call get_template first and send back the complete configuration. It also sets an owner-only permission boundary, explaining that colleagues can use but not edit shared templates. It stops short of explicitly naming alternatives like create_template when a new template is needed, so it is not a 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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description adds server-side download behavior, the 50 MB max size, the ban on password-protected or signed PDFs, and the silent-truncation risk with base64. It also includes a retry-once fallback when fileReference is missing. 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 purpose and return value, then organizes the four input modes in a numbered hierarchy. It is long, but every sentence carries constraint or decision information that an agent needs before calling the tool. 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 states the return value (fileId) and the downstream tools that consume it. It covers prerequisites (request_file_upload_url), size limits, unsupported PDF features, and failure behavior, which is complete for safe 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?

Although the schema already documents all five parameters (100% coverage), the description adds operational meaning: exactly one of the four inputs must be supplied, the preferred order, 'pass it exactly as provided' for fileReference, and the practical 30–50 kB ceiling for base64. This goes well beyond the schema's structural 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 opens with a specific verb and resource: 'Upload a PDF file to Formify. Returns a fileId for use with create_document, create_draft or create_link.' This clearly distinguishes the tool's role from sibling tools like create_document or merge_files, which consume files rather than upload them.

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

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

It gives an explicit decision tree: use fileReference when the host supplies one, url whenever a URL is available, uploadId after request_file_upload_url returns its curlCommand, and base64 only as a last resort. It also states when not to act ('Do NOT use base64 unless...') and a retry rule, so an agent knows which path to choose in each context.

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