Assinafy MCP Server

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

Annotations already indicate this is not read-only, but the description adds meaningful behavioral context by stating that email signers are created or reused for template roles. This explains a side effect beyond mere document creation, which is valuable; it stops short of describing post-creation behavior like automatic sending or persistence.

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 front-loaded sentence with no filler. It states the main action and the key behavioral nuance about signer reuse in just 15 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?

The schema comprehensively documents all 7 parameters and annotations cover the mutation profile, so the basics are in place. However, there is no output schema and the description does not hint at what the tool returns (e.g., a document ID), nor does it mention prerequisites like an existing template, leaving some operational context for the agent to infer.

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 no parameter-specific meaning beyond what the schema already provides for template_id, signers, and other fields. The schema itself documents the signers reuse behavior via 'existing exact matches are reused.'

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 and resource: 'Create a document from a saved template.' The added detail about 'creating or reusing email signers for its roles' clarifies what makes this distinct from simply generating a document, though it does not explicitly contrast it with sibling tools like send_document_for_signature.

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

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

The description states core functionality but provides no when-to-use guidance, prerequisites, or exclusions. It never tells an agent when to choose this over send_document_for_signature or other document-related siblings, leaving usage entirely 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?

Annotations already convey that the tool is destructive and non-idempotent, but the description adds little beyond that. It does not mention whether deletion is permanent, whether associated signatures or files are also affected, or how the system responds to invalid IDs.

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, front-loaded sentence with no filler or redundant phrasing. It is appropriately sized for a one-parameter deletion tool.

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 is simple and annotations plus the schema cover the basic destructive nature and parameter. However, with no output schema, the description does not clarify success/failure behavior, irreversibility, or side effects, leaving some uncertainty for an agent planning the call.

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

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

The input schema has 100% coverage for the single parameter and already describes document_id as 'unique document ID to delete.' The description adds no parameter-specific meaning, so the schema carries the full burden and 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 verb and resource: 'Delete a document from the workspace.' The operation is unambiguous and easily distinguished from sibling tools like get, download, create, or send, because no other sibling offers deletion.

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

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

No guidance is provided about when to use this tool instead of alternatives, nor are prerequisites or caveats mentioned. The agent must infer usage purely from the action named in the 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 declare readOnlyHint=true, so no destructive behavior is implied. The description adds useful behavioral context beyond these annotations: the output is base64-encoded and the default artifact is the original PDF, which helps an agent understand invocation results even 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 description is a single, front-loaded sentence with no filler. It communicates the primary purpose and the default behavior efficiently.

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 two parameters and no output schema, the description covers the essential details: what is downloaded, the encoding, and the default variant. The main gap is the lack of guidance on how it relates to sibling download/get tools, but it remains mostly complete for direct 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 schema already documents both document_id and artifact. The description's 'defaults to the original PDF' restates the schema's artifact default rather than adding substantial new parameter meaning, so the baseline score 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 identifies the action ('Download'), the resource ('a document artifact'), and the output form ('base64-encoded string; defaults to the original PDF'). It does not explicitly differentiate this from the sibling assinafy_download_signed_document, though the mention of 'original PDF' is an implicit hint.

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 no guidance about when to use this tool versus alternatives like assinafy_download_signed_document or assinafy_get_document. It explains what the tool does but not the conditions or use cases that should lead an agent to select 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 signal readOnlyHint=true, so the description adds value by disclosing the base64-encoded return format and the precondition that signing must be complete. This complements the annotations rather than duplicating them, though it does not cover failure modes or auth requirements.

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

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

One sentence that front-loads the core action and resource, then states the output format and condition. Every element is necessary and there is no filler.

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

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

For a single-parameter read-only tool with no output schema, the description adequately tells the agent what to pass and what to expect. It could mention behavior when the document is not yet signed or not found, but the stated precondition and return format are sufficient for basic 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 single parameter document_id is fully described in the schema with 'unique document ID', giving 100% schema coverage. The description does not add extra parameter detail, but none is needed given the schema already carries the meaning.

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

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

The description clearly states the action (download), the resource (signed/certificated PDF), and the output format (base64-encoded string). It also distinguishes this from the sibling assinafy_download_document by specifying the signed variant, so an agent can tell them apart without inspecting 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 phrase 'after signing is complete' provides clear temporal context for when this tool is appropriate. It does not explicitly name alternatives or exclusion cases, but the wording implies this should be used for the signed version rather than the generic download tool, which is adequate 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 indicate readOnlyHint=true, so the description's 'Get' behavior is consistent and adds context by specifying the returned information includes status and assignment. Since there is no output schema, this return-content hint provides meaningful behavioral detail 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?

A single, front-loaded sentence delivers the core purpose and key return fields without any filler. Every phrase contributes meaning, 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 one-parameter read-only lookup with no output schema, the description covers the essential invocation context and signals what the response contains. Minor ambiguity remains around what 'assignment' means exactly, but it does not block correct use.

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 document_id described as 'unique document ID'. The tool description does not add extra parameter detail, but the baseline is 3 because the schema already documents the only parameter sufficiently.

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 ('Get') and resource ('full details of a single document'), with explicit contents ('status and assignment'). This clearly distinguishes it from sibling tools like get_signing_progress or list_documents, which target different or narrower 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 phrase 'full details of a single document' implies when to use this tool, but it does not explicitly name alternatives or state when not to use it. There is no direct comparison with siblings such as get_signing_progress, download_document, or list_documents.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value by specifying the shape of the returned summary (signed, total, pending, percentage), which is behavior beyond the structured annotations.

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

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

One concise, front-loaded sentence with no filler. Every word adds meaning.

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 progress query, the description fully covers what the agent needs: the input and the returned summary fields. No output schema exists, but the description compensates by listing the output components.

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, document_id, is fully documented in the schema, and the description adds no additional semantic detail. Baseline 3 applies because the schema carries the parameter documentation 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?

States a specific verb ('Get') with a specific resource ('signing progress for a document') and enumerates the summarized fields (signed, total, pending, percentage). This clearly distinguishes it from siblings like get_document or list_documents.

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

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

No guidance is given on when to use this tool versus alternatives such as get_document or send_document_for_signature. The lifecycle context is only implied by the tool's name and 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 declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds the caveat that this is a live endpoint not in the public API specification, which is useful stability information, but it does not disclose behavior for missing IDs, return format, or authentication requirements.

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: the first states the core action, the second adds an important availability caveat. There is no filler, and the main purpose is front-loaded.

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

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

For a simple get-by-ID tool with two parameters and no output schema, the description is reasonably complete. It identifies the return as full template details and notes the endpoint's non-public status, though it does not enumerate the template fields returned.

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 template_id and account_id are already fully documented. The description adds no parameter-level detail beyond referencing 'full template details' and 'get-by-ID', so the baseline score 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 states a specific verb and resource ('Get full template details') and clarifies it is a live get-by-ID endpoint, which clearly distinguishes it from sibling list_templates. The operation and target resource are 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?

The description implies the tool is for fetching a single template by ID, but it does not explicitly compare it to alternatives like list_templates or provide when-to-use/not-use guidance. The note about not being in the public API specification is availability context, not usage direction.

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 provide readOnlyHint and openWorldHint, and the description adds no side-effect or scope disclosures beyond the workspace context. It is consistent with the annotations and adequate, but does not enrich behavioral understanding further.

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

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

A single front-loaded sentence states the verb and object first, then appends optional modifiers. There is no filler, repetition, 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?

For a read-only listing tool with no required parameters and fully documented optional parameters, the description plus schema is largely sufficient. It could be more complete with explicit return-structure or status-value hints, but the core invocation context is covered.

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?

All six parameters have schema descriptions, so the schema carries most of the semantic load. The description adds a useful high-level grouping of pagination, search, sort, and status filters, but no additional parameter details beyond the schema.

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

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

The description uses a specific verb ('List') with a clear resource ('documents') and scope ('Assinafy workspace'). It also names the key optional capabilities, making it easy to distinguish from sibling tools like list_templates or get_document.

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

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

The description implies a listing/filtering use case but does not explicitly say when to choose this over alternatives such as get_document for a single document or list_templates for templates. Usage context is present but not directly stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the workspace-scoping context, which is useful, but it does not disclose behavioral details like pagination defaults, filtering semantics, or result shape. No contradiction with annotations, so a modest 3 is appropriate.

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 eight-word sentence that front-loads the verb and resource with zero filler. Every word earns its place, and the length is appropriate for a tool of this simplicity.

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

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

For a read-only list tool, the combination of readOnlyHint=true and fully documented optional parameters is mostly sufficient. The main gap is that there is no output schema and no note about what a returned template record contains or how pagination behaves, so an agent must discover the response shape by experimentation.

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% — all four parameters (page, search, per_page, account_id) are documented with meaningful descriptions, including the default behavior for account_id. The description adds no parameter-specific detail, 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?

States a specific verb ('List'), resource ('document templates'), and scope ('available in the workspace'). The resource term inherently distinguishes it from siblings like assinafy_list_documents and assinafy_get_template, though it does not explicitly name them the way the HIGH calibration example does.

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

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

The usage context is implied: call this when you need to see which templates exist in the workspace. However, there is no explicit when-to-use/when-not-to-use guidance or mention of alternatives, and with 13 siblings such as get_template and create_document_from_template, explicit routing would reduce ambiguity.

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

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

The annotations already convey that this is a non-read-only, non-idempotent, non-destructive operation, so the safety profile is covered. The description adds minimal behavioral context beyond the annotation, though 'to a specific signer' usefully scopes the action. It does 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?

The description is a single, tightly written sentence that states the action and the target. There is no filler, and the core purpose is front-loaded.

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

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

For a simple three-parameter tool with complete schema descriptions and annotations covering side effects, the description is largely sufficient. The main missing piece is an explicit note that this is for resending after an initial signature request, which would further disambiguate it from the sibling send tool.

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

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

Schema description coverage is 100%, so all three parameters are already documented structurally. The description adds no new parameter-level meaning beyond the schema, so the baseline of 3 is appropriate. It offers no hints about relationships between the three IDs.

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: 'Resend the signing notification to a specific signer.' It clearly communicates the operation and the target, distinguishing it from initial sending at a basic level. However, it does not explicitly name or contrast the closest sibling 'assinafy_send_document_for_signature', so differentiation is implied rather than explicit.

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

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

The description gives no guidance on when to use this tool versus alternatives like send_document_for_signature or reset_assignment_expiration. It does not state prerequisites, when a resend is appropriate, or when one of the siblings should be chosen instead. The 'resend' wording implies prior sending but leaves the decision 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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the mutation/destructive nature is covered. The description adds the 'existing' qualifier (target must exist) and names the exact field being mutated (expiration date), but it does not add context such as authorization needs, notification side effects, or whether the new date must be in the future.

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, front-loaded sentence containing exactly the necessary scope: what is updated ('expiration date') and on what ('existing signing assignment'). There is no filler or redundant restatement of the tool name.

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

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

For a 3-parameter mutation with full schema coverage and annotations already conveying destructive and non-idempotent behavior, the description is nearly complete. It could add one sentence on allowed expiry values or invocation preconditions, but nothing essential is missing for selecting and invoking this tool among the siblings.

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 each parameter has clear schema-level descriptions, so the baseline is 3. The tool description itself adds no parameter-level meaning beyond the schema, which is acceptable because the schema already documents the expiry format (RFC 3339) and the required IDs.

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 ('Update'), a specific resource ('expiration date of an existing signing assignment'), and identifies the assignment as pre-existing. This clearly distinguishes it from sibling tools like create, delete, send, and verify; no other sibling tool handles expiration changes.

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 operation itself implies the use case (whenever an assignment's expiration needs to change), but the description offers no explicit when-to-use or when-not-to-use guidance and does not mention alternatives or prerequisites beyond the assignment being 'existing'. There is no sibling overlap, so it is not misleading, just implicit.

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

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

The description discloses that the tool waits for processing (hinting at polling) and that signers can be reused, and that it creates an assignment. This adds context beyond the sparse annotations (which only include readOnlyHint, openWorldHint, idempotentHint, destructiveHint). However, it does not disclose side effects like email notifications to signers, failure modes, or non-idempotency (though annotations indicate idempotentHint=false). It does not contradict any annotation.

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

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

The description is a single, concise sentence that front-loads the primary action and the key workflow steps. There is no wasted text or redundancy. Every word contributes to understanding the tool's purpose.

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 8 parameters, no output schema, and minimal annotations, the description provides a high-level workflow that covers the main steps. It does not describe the return value, error handling, or idempotency specifics, but the schema is detailed and the annotations cover some flags. It is adequate for an agent to understand the operation, though it could benefit from mentioning that signers will receive email invitations or that the operation is non-idempotent.

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 all 8 parameters are documented with descriptions. The description adds a little extra context, such as 'create or reuse its signers' relating to the signers parameter behavior, and 'wait for processing' relating to polling parameters. These are minor additions; the schema carries the primary semantic load. Baseline 3 is appropriate.

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

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

The description states a specific multi-step operation: upload a PDF, wait for processing, create or reuse signers, and create a virtual signing assignment. This clearly distinguishes it from siblings like create_document_from_template (which uses a template) and get_document (read-only). It is not a tautology and provides a clear verb+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 workflow description implies when to use it (when you have a PDF to send for signature), but it does not explicitly state exclusions or alternatives. For example, it does not mention that for template-based documents you should use create_document_from_template, or that for checking progress you'd use get_signing_progress. Usage guidance is implicit rather than explicit.

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 little behavioral context beyond the annotations. While readOnlyHint=true indicates a safe read operation, the description does not explain what 'verify' actually entails—whether it returns a boolean, a detailed report, or what happens if the hash is not found. With no output schema, the agent is left unaware of the response format or potential side effects, despite the operation being read-only.

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, focused sentence that front-loads the action (verify) and the resource (signed document). It avoids unnecessary words and clearly states the method (by hash). This is exemplary conciseness for a simple tool.

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 is incomplete for an agent to use correctly because it does not specify the return value or success/failure indicators. Given there is no output schema, the agent cannot anticipate what a successful verification looks like. Additionally, it lacks any usage context or edge-case handling, making it insufficient for a tool that likely needs to interpret results.

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 description merely restates the hash parameter's purpose. The description does not add any extra meaning beyond the schema, such as expected format (e.g., hex string), length, or example values. Since the schema already documents the parameter adequately, a 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's purpose: to verify a signed document using its SHA-1 hash. It distinguishes itself from siblings like download_signed_document (which retrieves content) and get_signing_progress (which checks status) by focusing on verification. The verb 'verify' and resource 'signed document' are specific and 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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of conditions like 'use when you need to confirm signature validity' or any reference to sibling tools. The agent is left to infer usage from the name and description, which is insufficient for a tool with many similar siblings.

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