Formify — AI Assisted E-Signing

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

Annotations declare readOnlyHint=false and destructiveHint=true, so the description inherits a mutation/send profile. It adds context beyond annotations: the document name is visible to signees, signature placement defaults to new_page, and preview is recommended for risky placement. It could explicitly state that sending is immediate and irreversible, but the workflow warning about preview conveys it without contradiction.

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 block earns its place for a tool with 12 parameters and branching orchestration. It is front-loaded with the core action, then provides clear mandatory pre-call questions and alternate paths. It could be tightened slightly, but it is dense, not redundant.

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

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

For a complex tool with nested objects and no output schema, the description covers the full decision tree: template vs file, preview vs direct send, questions to ask, capability gates, and parameter origins. The only minor gap is not explicitly describing the return value, though the action 'create and send' strongly implies the outcome.

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

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

Schema coverage is 100%, so the baseline is 3. The description meaningfully adds cross-tool semantics: templateId comes from list_templates, fileId from upload_file, field names from get_template_fields/get_file_fields, and capabilities from get_account_capabilities. It also clarifies the mutually exclusive templateId/fileId relationship beyond raw schema fields.

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

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

The description opens with a specific action and resource: 'Create a document and send it for electronic signature.' It clearly distinguishes this from sibling tools like create_draft and upload_file, and highlights the template/file source trade-off. An agent can immediately tell this is the direct-send creation tool.

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 when-to-use vs alternatives: use create_draft/get_draft_file_url/send_draft when a preview is needed; use get_template and get_template_fields when using a template; use get_file_fields when using a file. It also requires querying the user for specific preconditions and lists conditions with their dependencies.

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 behavioral context not available in the annotations: no invitations are sent at draft time, full validation occurs only when send_draft is called, and the draft name will become visible to signees once sent. These are concrete side effects beyond the metadata flags and do not contradict 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?

Although long, the description is dense with decision-relevant detail: the opening sentence gives the core purpose, the fileId and template constraints follow, and the preview workflow is clearly sectioned. Every sentence earns its place and no fluff is present.

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 11 parameters, nested objects, zero output schema, and many eligible siblings, the description is unusually complete. It guides the agent through the typical lifecycle: upload_file → get_file_fields → create_draft → get_draft_file_url → update_draft → send_draft, making it clear which prerequisites matter.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by tying parameter usage to the document lifecycle: fileId must come from upload_file, fields come from get_file_fields, and signee details are optional at this stage but validated at send_draft. This is workflow-level meaning beyond the raw 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 purpose opens with 'Create a draft document without sending invitations,' a precise action, resource, and immediate outcome. It also differentiates the tool from siblings by stating that templates are not supported and that fileId comes from 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 explicitly explains when to use drafts: 'Requires fileId from upload_file; templates are not supported for drafts.' It also gives the full workflow for the preview-only case: build configuration here, call get_draft_file_url, let the user verify via update_draft, then call send_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?

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?

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?

Annotations already declare readOnlyHint=true, idempotent, and non-destructive, so the description need not restate safety. It adds feature examples but does not disclose any additional behavioral traits such as return shape or auth requirements. This is adequate but not rich.

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

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

One short sentence with no filler. The examples carry useful semantic weight without bloating the description.

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 no-param read-only capability lookup, the description gives enough to understand the operation. It does not specify the exact return shape (e.g., feature list vs. booleans), but the name and examples provide a workable baseline in the absence of an 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?

The tool has zero parameters)Skip? The 0 params baseline is 4: no parameter semantics need compensationjack. The description still clarifies the account context that would otherwise be ambiguous.

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: checking which account features are enabled, with concrete examples (BankID, templates, AI assistant). It is immediately distinguishable from sibling tools like get_current_user or get_document because it targets account capabilities, not user or document 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?

The description makes the usage context clear: call this when you need to know which features are enabled for the account. There are no competing sibling tools for retrieving capabilities, so explicit alternatives are unnecessary, though it does not spell out when not to use it.

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

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

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?

The description adds substantial behavioral context beyond the readOnlyHint annotation: the URL is one-time-use, expires after 10 minutes, is consumed on successful download, requires no Authorization header, and only works while the draft is in draft status and not expired. It also documents that fields without valid coordinates are omitted from the rendered PDF but remain in draft data.

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 adds relevant information: core behavior, return format, authentication, alternative tool guidance, workflow order, coordinate rendering behavior, expiry, and state requirements. It is front-loaded with the primary purpose and contains 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 single-parameter read-only tool with a high-coverage schema, the description is complete: it covers the return JSON fields, auth requirements, expiry and consumption semantics, valid state conditions, and how it fits into the broader preview flow. No output schema exists, so the explicit return format description is especially valuable.

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 documents draftId with 100% coverage. The description reinforces that the ID identifies the draft to preview and ties it to the draft's status constraints, but it does not add much beyond the schema's own description.

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

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

States a specific verb and resource: gets a short-lived, one-time-use download URL for a PDF preview of a draft with signature fields rendered at coordinates. It explicitly distinguishes itself from the sibling get_draft_file by noting it returns a clickable URL rather than an embedded resource.

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 involving create_draft, get_draft_file_url, update_draft, and send_draft, giving clear context.

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?

Discloses important behaviors beyond the minimal annotations: first-use generation and persistence with idempotency, security (verification-locked links, one-time code sent to contact on file), automatic browser verification with no extra calls, omission of unverifiable recipients, and duplication for dual-channel recipients. All of this aligns with readOnlyHint=false, destructiveHint=false, idempotentHint=true.

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

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

Front-loaded with the core purpose, then security, output shape, and caveats. It is long, but every sentence carries unique information and the output format detail justifies the length. Slightly dense with security detail, but not padded.

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

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

Covers the full contract: what links are, when to use, how verification works, exact response fields and cardinality (two entries for dual-channel recipients), omitted recipients, idempotency, and the sent-not-draft constraint. No output schema exists, so this description fully compensates.

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 gives documentId only a generic description ('Unique identifier of the document'), and coverage is 100%. The description adds meaningful constraint: it must identify a sent document, not a draft. It could further clarify what happens with non-existent document IDs or error behavior, but for one param the added semantics are 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?

The description clearly states the verb ('Get'), the resource ('unique, self-distributable signing links for a document'), and the exact purpose. It distinguishes itself from the alternative of relying on Formify's email/SMS/WhatsApp invitations, making its identity unambiguous.

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

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

Explicitly states when to use it: for signees created with disableInvitationMessage: true or whenever the user wants to distribute links manually. It also states exclusions: only works on a sent document, not a draft, and directs the user to update_signee when a contact method is missing.

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

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

Annotations 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, so the safety profile is covered. The description adds scope context (owned or shared documents), but does not disclose anything further such as pagination behavior or whether drafts are included.

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, efficient sentence with no redundant wording. It front-loads the verb and resource, and every word contributes to comprehension.

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 list tool with two documented parameters and covered annotations, the description is nearly sufficient. It lacks explicit clarification about whether drafts are excluded (given there is a separate list_drafts tool) and does not describe the return shape, but overall it covers the essential contract.

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?

Both parameters (limit and offset) are fully documented in the input schema with descriptions, defaults, and constraints, so schema coverage is 100%. The description adds no param-level context, but it is not required given the 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?

The description states a specific verb ('List'), resource ('documents'), and scope ('created by the user or shared within the account'). It clearly distinguishes the tool from siblings like list_drafts, list_templates, and list_webhooks by naming the document resource.

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 retrieving all visible documents, but it does not explicitly say when to use this tool versus alternatives such as list_drafts or get_document. Since list_drafts exists as a sibling, a quick pointer or exclusion such as 'this does not include drafts' would provide valuable 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, so the safety profile is covered. The description adds useful context about what drafts are and the recommended workflow, 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 three sentences with no filler. The core action, resource, and pagination are front-loaded, and the additional draft definition and workflow guidance earn their place.

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

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

For a read-only, paginated list tool with a fully documented schema and safety annotations, the description is nearly complete. It clearly conveys what is listed and the draft lifecycle context, though it does not describe the exact response shape or pagination metadata.

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 schema already documents limit, offset, and userId with descriptions and defaults. The description adds no extra parameter detail, so 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 the specific verb 'List', the resource 'draft documents', and the pagination behavior. It also defines drafts as saved configurations that have not been sent for signing, which distinguishes this tool from list_documents and list_templates.

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 by defining drafts and recommending get_draft before updating, sending, or deleting a draft. However, it does not explicitly state when to prefer list_drafts over alternatives or mention when not to use it.

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

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

Annotations already convey readOnly/idempotent/non-destructive behavior, and the description adds meaningful presentation guidance: results should be a short scannable list of template names only, hiding IDs and metadata. This is valuable beyond annotations. Minor inconsistency: 'all available' is somewhat at odds with the default limit of 10, but the schema covers that.

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

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

Two sentences with no filler. The core purpose and the key presentation constraint are front-loaded, 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 straightforward read-only list operation, the description, schema, and annotations cover the essential needs: what to list, how to present results, parameter constraints, and safety profile. The only minor gap is not mentioning pagination response behavior or ordering, but the schema documents the pagination inputs.

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 limit and offset are already fully documented in the input schema. The description adds no parameter-level detail beyond what the schema provides, landing at the baseline score.

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 ('all available signing templates'), which clearly distinguishes it from unrelated sibling tools. The phrase 'all available' also sets it apart from get_template, which retrieves a single 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 implies the tool is for listing templates, but it does not explicitly state when to use it versus alternatives such as get_template or list_documents. No when-not-to-use or alternative routing guidance is provided.

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

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

Annotations already declare readOnlyHint=true, 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 declare readOnlyHint=false, openWorldHint=false, destructiveHint=false, so the description carries the burden of behavioral disclosure. It discloses the critical sequencing requirement (wait for HTTP 200 before calling upload_file), the 10-minute URL expiry, the fact that the staged entry holds no bytes until upload completes, and the failure-mode behavior (do not retry on network/DNS/allowlist errors). This is rich, actionable behavioral context 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 long but every sentence earns its place: it covers the flow, the critical wait-for-200 constraint, the expiry, and the failure fallback. It is front-loaded with the core purpose and the most important usage condition. It could be slightly tightened, but the density of critical operational detail 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 tool with one parameter, no output schema, and minimal annotations, the description is remarkably complete. It explains the full lifecycle (stage → run curlCommand → wait for 200 → call upload_file with uploadId), the failure mode, and the fallback path. An agent has everything needed to invoke it correctly and recover from the most likely error.

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 single parameter fileName is already documented in the schema with an example. The description adds context about what the file is (a PDF attached to the conversation) but does not add new parameter-level semantics beyond the schema. 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 ('Stage an upload'), a specific resource (a PDF attached to the conversation), and the intended audience (clients that can execute shell commands). It clearly distinguishes this tool from upload_file by explaining the presigned URL + curlCommand flow, so an agent can tell them apart 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?

The description gives explicit when-to-use guidance ('Only use this tool if you are able to run that command'), explicit when-not-to-use guidance ('if you cannot, skip it'), and names the alternatives (upload_file with `url` or with `file` as base64 plus `fileName`). It also provides a fallback path for blocked outbound requests, leaving little to inference.

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

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

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?

Annotations already signal destructive and idempotent behavior. The description adds valuable specifics: signees not included in the complete signeeDetails list may be removed, and omitting fileId preserves the current file. This goes beyond the annotations and helps the agent understand the destructive nature of a full update.

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, front-loaded with the core action and the critical status prerequisite. It includes only high-value behavioral warnings and avoids repeating schema content. No filler or unnecessary detail.

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

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

Given the tool's complexity, the exhaustive schema carries most of the parameter documentation burden, and the description covers the two high-risk behaviors: signee removal and file preservation. It does not describe return values or error cases, but there is no output schema and the schema's parameter detail is 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?

The input schema provides 100% coverage with rich descriptions for every parameter, including nested objects and coordinate systems. The description adds little parameter-level meaning beyond the schema; it reinforces signeeDetails completeness and fileId optionality, but those points are also present in the schema.

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

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

The description clearly states the action ('Update an existing draft') and the resource, and adds the prerequisite that the draft must still have status draft. It frames the tool as a full draft configuration update, which distinguishes it from create_draft and update_signee 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 gives a clear when-to-use condition: the draft must still have status 'draft'. It also conveys that this is a full-update operation, which implies it is the right tool for comprehensive draft edits. However, it does not explicitly mention alternatives like update_signee for single-signee changes or say when not to use 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 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 report destructiveHint=false and readOnlyHint=falsearen't set, which is the correct neutral baseline for an upload operation. The description goes beyond annotations by disclosing the 50 MB size limit, the password/digital-signature restriction, and the critical truncation risk that silently corrupts files. It doesn't detail failure modes or return error behavior, but the warning about truncation is a meaningful behavioral disclosure for a file upload tool.

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

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

Well-structured with numbered paths in priority orderressing the most important guidance upfront)Skip. Each sentence has a clear purpose: what the tool returns, which path to prefer, the caveat on base64, size limit, and password/signature restriction. 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 an upload tool with no output schema and zero required params, the description covers return value (fileId), usage paths, integration with sibling tools, limits, and corruption warnings. The only gap is explicit error behavior on failure (e.g., if uploadId is expired, what error occurs), but the description is otherwise thorough for its 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?

Schema coverage is 100%: all four parameters (url, file, fileName, uploadId) have descriptions. The description's three-path guidance adds ordering and selection semantics that the schema alone doesn't convey, which is valuable. However, most of that value is parameter-level guidance, and the description doesn't add much beyond what the schema already documents for each parameter. Baseline 3 with modest increment withheld because the schema already covers descriptions; the added value is in sequencing, not new semantic depth.

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 uploads a PDF to Formify and returns a fileId, with an explicit link to downstream use with create_document or create_draft. It lists three distinct input paths with precedence, making the tool's purpose and scope unambiguous and distinguishable 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?

Provides explicit when-to-use guidance: URL first, then uploadId, then base64 file. It names the sibling tool request_file_upload_url and explains the exact sequence (call it, run curl, pass uploadId). It also gives a clear exclusion rule: avoid base64 unless you can guarantee completeness. This is exemplary usage guidance.

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