E-signature API for AI agents: send contracts, sign PDF documents, track and download signed files.
Glama couldn't complete the latest health check. If this server requires authentication, missing or expired test credentials may be the cause. A test profile lets Glama authenticate for health checks and discover tools; it is separate from your personal connections.
If you are the author, claim ownership, then add or update a test profile under Admin → Test Profile.
Scored across 22 tools
Most tools have clear, distinct purposes (download_certificate vs download_signed_document, get_audit_trail, correct_recipient_email, etc.). There is mild overlap in the send family — send_envelope can also create a Draft, which touches send_draft and send_from_template — and the billing cluster (get_pricing, check_balance, buy_credits, get_usage) is dense, but the descriptions draw the boundaries explicitly.
All 22 tools use snake_case with a consistent verb_noun pattern (add_document_to_draft, create_template, list_envelopes, send_draft, void_envelope, get_envelope_status, etc.). No mixed conventions or vague single-word names; the longest names are still predictable verb_object forms.
22 tools is slightly above the ideal 3-15 band, but the e-signature domain legitimately spans account setup, billing/credits, drafts, templates, envelopes, recipients, and downloads, and each tool appears to earn its place. It is heavier than necessary but not bloated or redundant.
Core envelope lifecycle is well covered: create/draft, add documents, place fields, send, status, remind, correct recipient email, void, download signed PDF, certificate, and audit trail, plus template creation/listing/sending and billing. Minor gaps exist around delete/archive operations (no delete_template, delete_envelope, or draft removal) and richer template/recipient management.
Append a document to an existing Draft. Provide exactly one of document_base64, document_url, or template_id. A multi-document template inserts ALL of its documents (each counts toward the limit of 10) and name is then not allowed. role_mapping (template only) maps the template's roles onto this envelope's roles, e.g. {"customer": "client"}; unmapped roles are inserted as-is, never guessed. Fields already placed keep their pages; inserted pages come after them. Returns the draft with its documents[] (page ranges) so you can place fields with document_id + document-relative page. Requires Authorization: Bearer zs_....
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| filename | No | document.pdf | |
| document_id | Yes | ||
| template_id | No | ||
| document_url | No | ||
| role_mapping | No | ||
| document_base64 | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the sparse annotations, the description discloses meaningful behavior: multi-document templates insert all documents, each counts toward the 10-document limit, unmapped roles are inserted as-is rather than guessed, existing placed fields keep pages, new pages are appended, and the response returns page ranges for field placement. It also states the Authorization requirement.
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 and covers many edge cases without filler, and it front-loads the primary action and core constraint. It is longer than average, but most sentences carry essential behavioral or usage information for a 7-parameter 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 handles template behavior, page ordering, and response semantics well, and the output schema supplies return-type details. Its completeness is undercut by the unexplained required document_id and the tension between the required schema parameter and the 'exactly one of' instruction, leaving a critical call-invariant ambiguous.
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 0% schema coverage the description carries the full burden for parameters, and it does add useful semantics for document_base64, document_url, template_id, role_mapping, and name. However, it never explains the sole required schema parameter, document_id, and its 'exactly one of' instruction creates ambiguity about how document_id relates to the source fields. filename is also left undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence says 'Append a document to an existing Draft,' giving a specific verb, direct object, and state (existing, not new). This is clearly distinct from sibling actions like creating a template, sending a draft, or updating draft metadata.
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 selection rules: exactly one of document_base64, document_url, or template_id, plus role_mapping only for templates and a name restriction for multi-document templates. It does not explicitly name alternatives among sibling tools, but the tool's own input-selection guidance is strong enough to guide invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Stripe Checkout session for a credit pack ('starter',
'growth', or 'scale' — see get_pricing). Returns a checkout_url: open
and pay it (card), and the webhook credits this account automatically
within seconds. Requires Authorization: Bearer zs_....
| Name | Required | Description | Default |
|---|---|---|---|
| pack | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate non-read-only and non-idempotent behavior. The description adds meaningful context: it requires Authorization, returns a checkout_url, and explains that the webhook credits within seconds. It doesn't contradict annotations and provides useful operational detail beyond the structured fields, though it doesn't cover failure cases or edge behavior.
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 filler. The core action is front-loaded, and every clause adds value: pack options, output, payment method, auto-crediting, and auth requirement. It is a model of concise, structured tool documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema (indicated in context), the description fully covers what an agent needs to call it: the action, the parameter values, the returned field ('checkout_url'), the interaction flow (pay and auto-credit), and the required authorization. Nothing essential 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 has no description for the 'pack' parameter (0% coverage). The description compensates fully by enumerating the valid values ('starter', 'growth', or 'scale') and directing to get_pricing for details. This gives the agent precise semantic guidance without needing the schema to be enriched.
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 specific action: 'Create a Stripe Checkout session for a credit pack', and lists the exact pack options ('starter', 'growth', or 'scale') with a pointer to get_pricing. This distinguishes it from siblings like check_balance or get_pricing, providing a precise verb-resource-scope combination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear usage flow: create session, pay, and the webhook credits the account. It also references get_pricing for pack details, implying that the agent should consult pricing first. However, it does not explicitly state when NOT to use this tool (e.g., when credits are insufficient on an existing account), so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current credit balance and available packs. Requires
Authorization: Bearer zs_....
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and idempotent; the description adds an important authentication requirement ('Authorization: Bearer zs_...') and states that the response reflects current balance plus available packs. It doesn't cover error behavior, but for a safe read operation with an output schema, this is useful 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?
Two short sentences with no filler: the first front-loads what the tool returns, the second states the auth requirement. Every sentence earns its place and there is no 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?
This is a simple zero-parameter tool with an output schema and read-only/idempotent annotations, so the description only needs to convey purpose and the auth prerequisite, both of which are present. It stops short of explaining when to choose it over billing siblings, but that gap is covered under usage guidelines.
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 no input parameters to document, so the empty schema plus 100% coverage leaves no ambiguity. The only parameter-like constraint is the auth header, which is mentioned in the description rather than in the schema. Baseline for zero-parameter tools is 4.
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 concrete resource ('credit balance and available packs') and pairs it with the imperative title 'Check Credit Balance', so an agent knows this is a read query for current balance/credits. It doesn't explicitly contrast with siblings like get_pricing or buy_credits, but the resource is distinct enough.
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 only contextual cue is a required Authorization header, which is an invocation prerequisite, not a selection rule. No guidance is given on when to call this instead of get_pricing or buy_credits, and there are several billing-related siblings in the list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Correct the email of an unsigned recipient on an in-flight envelope.
Wraps POST /api/v1/documents/{document_id}/recipients/{recipient_id}/email.
Same recipient_id and signing link — does not void, so signatures already
collected from other recipients stay valid. Refuses a recipient who has
already signed (409 recipient_already_signed) and an envelope that is
voided, completed, declined, or expired. Sends a fresh invite when the
envelope was sent with invites enabled. Later remind_envelope calls go
to the new address. Requires `Authorization: Bearer zs_...`.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | |||
| document_id | Yes | ||
| recipient_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint/idempotentHint/destructiveHint (all false). The description adds substantial behavioral context: it does not void the envelope, preserves collected signatures, returns 409 for already-signed recipients, sends a fresh invite when enabled, and updates future remind calls. It also specifies the auth header. This far exceeds annotation coverage.
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 multi-sentence but every clause adds value: endpoint wrapper, non-destructive behavior, refusal conditions, invite behavior, future remind implications, and auth requirement. It is front-loaded with the core purpose and avoids redundancy, though it could be slightly tightened.
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 modification tool with conditions and an output schema present, the description covers all essentials: what it does, when it refuses, side effects on invites and reminders, and authentication. The output schema handles return values, and the annotation covers idempotency. No critical information is missing 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?
Schema coverage is 0%, so the description must compensate. It does: 'email' is the corrected email, 'recipient_id' must be unsigned, 'document_id' is the envelope. It doesn't specify format constraints, but with only three straightforward parameters, the description provides enough meaning to correctly populate them.
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 precise action: 'Correct the email of an unsigned recipient on an in-flight envelope.' It names the exact resource (recipient) and context (in-flight envelope), and explicitly contrasts with void_envelope ('does not void') and remind_envelope ('Later remind_envelope calls go to the new address'), distinguishing it from 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 states when to use the tool (unsigned recipient on an in-flight envelope) and lists refusal conditions (already signed, voided/completed/declined/expired). It does not explicitly name alternative tools, but the contrasts with void and remind provide sufficient routing guidance for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a zSign account and API key in one call. Email is optional.
The returned key starts with zs_live_; pass it as
Authorization: Bearer <key> on this MCP connection (or REST) for all
other tools. Unverified accounts stay at 0 credits (anonymous-abuse
guard). Pass an email, then POST /api/v1/email/verify with the mailed
token (or click the link) to receive the same starting credits as a
dashboard signup. After that, send_envelope works; buy_credits when you
need more.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare non-read-only, non-idempotent, non-destructive, but the description goes well beyond by disclosing the key prefix (zs_live_), the auth header format, that unverified accounts stay at 0 credits due to an anonymous-abuse guard, and the credit-unlock consequence of verification. This is exactly the behavioral context annotations cannot carry.
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-loads the core action and key deliverable, then layers constraints and next steps. Slightly dense with the verification flow, but every sentence carries actionable information; the endpoint reference could arguably be trimmed.
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 provisioning tool with an output schema present, the description covers what the agent needs: what is created, the key format, where to use it, the credit state and how to change it, and the immediate next tools. Complete given the output schema handles return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It clarifies email semantics ('Email is optional', verification implications) but says nothing about the 'name' parameter. Partial compensation for a 2-param tool, but one parameter is left entirely undescribed. Baseline for low coverage is not met fully.
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 ('Create a zSign account and API key in one call') and distinguishes itself from every sibling, which are all downstream envelope/credit operations. An agent can identify this as the entry-point provisioning call without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent: create here first, then send_envelope works, then buy_credits when more credits are needed. Also states the email-verification path for unlocking starting credits, which is a when/when-not condition tied to a concrete outcome.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save an existing Draft as a reusable template. Mirrors dashboard
POST /api/documents/drafts/{id}/save-as-template (API-key twin
POST /api/v1/documents/drafts/{id}/save-as-template). There is no
blank-template flow — start from a Draft. Returns template_id and
role names. The Draft itself is unchanged. Requires
Authorization: Bearer zs_....
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| document_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral detail beyond the annotations: the Draft itself is unchanged, the call requires an Authorization: Bearer zs_... header, and it returns template_id and role names. It does not contradict the annotations, which only state readOnly false, idemptotent false, destructive false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence contributes a distinct piece of information: purpose, API equivalence, no blank-template flow, return value, side-effect on the Draft, and authentication. The main action is front-loaded and no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with an output schema, the description covers purpose, prerequisites, side effects, return values, and auth requirements. The principal gap is that the parameters are not formally described in the description, especially 'name', though document_id is inferable from the endpoint context.
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 0% description coverage, so the description must compensate for parameter meaning. The endpoint mirrors /drafts/{id}and the phrase 'existing Draft' imply document_id is the draft ID, but the description never explicitly maps document_id or name to their meanings. In particular, 'name' remains unexplained.
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: 'Save an existing Draft as a reusable template.' It also explicitly rules out a blank-template flow, which distinguishes it from broader template-creation ideas and from siblings like list_templates or send_from_template.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states the prerequisite: start from an existing Draft, and that there is no blank-template flow. It does not explicitly name alternative tools for sending or listing templates, but the usage context is clear enough for an agent to decide when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download the standalone Certificate of Signature PDF for a completed
envelope. Takes the original document_id from send_envelope /
get_envelope_status / list_envelopes (NOT completed_document_id).
Incomplete envelopes error. Returns the PDF as base64. Requires
Authorization: Bearer zs_....
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds fresh behavioral context: incomplete envelopes error, the PDF is returned as base64, and an Authorization Bearer token is required. This goes beyond the structured annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences deliver purpose, parameter provenance, failure mode, return format, and authentication requirement. Every sentence adds value, and the primary purpose is front-loaded. There is no filler or repeated schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool, the description covers the key operational facts: what it downloads, when it is valid, what input to use, what errors occur, the return format, and the required auth. The output schema exists, so explaining return shape in detail is unnecessary. Nothing critical 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 only defines document_id as a required string with no description, so 0% schema description coverage. The description compensates fully by specifying that document_id must be the original document_id from send_envelope / get_envelope_status / list_envelopes, and explicitly excludes completed_document_id. This is essential disambiguation that the schema alone cannot 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-resource pairing: 'Download the standalone Certificate of Signature PDF for a completed envelope.' This clearly distinguishes the tool from the sibling download_signed_document, which downloads a different artifact. The statement about using the original document_id rather than completed_document_id further sharpens the tool's identity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear when-to-use context: only for completed envelopes, and it explicitly warns that incomplete envelopes produce an error. It also states which source to use for document_id. However, it does not explicitly name an alternative such as download_signed_document, so the reader must infer the comparison from the certificate wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download the sealed, signed PDF. Takes the completed_document_id from
get_envelope_status; the original document_id also works and resolves to
that document's most recent completed session. Returns the bytes as
content_base64 with content_type from the HTTP response. PDF
responses also include pdf_base64 (same bytes). Requires
Authorization: Bearer zs_....
document_id: one of `documents[].id` from get_envelope_status to download
just that document (its pages plus the certificate pages — an extract;
the certificate hash identifies the full envelope). `format='zip'`:
every document as its own PDF in one archive (`application/zip`).| Name | Required | Description | Default |
|---|---|---|---|
| format | No | ||
| document_id | No | ||
| completed_document_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and idempotentHint annotations, the description reveals the required Authorization header format, the response fields content_base64 and content_type, the pdf_base64 alias for PDF responses, the zip behavior, and the resolution of document_id to the most recent completed session. This is substantial behavioral context that annotations alone 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 more than a sound bite and repeats document_id-related guidance in two places, but each sentence adds a useful detail: auth, output encoding, certificate pages, and zip behavior. The core download purpose is front-loaded and the extra length is mostly justified by the tool's parameter complexity.
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 three parameters, zero schema descriptions, and a sibling download_certificate tool, the description covers the key facts an agent needs: ID sources, optional document selection, output format, authentication, and return field names. Nothing essential to invoking the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden of explaining parameters. It explains completed_document_id as the identifier from get_envelope_status, document_id as a way to download an individual document extract, and format='zip' as the archive behavior. However, the precise interaction between completed_document_id and document_id, and the accepted values for format beyond zip, are not fully spelled out.
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: 'Download the sealed, signed PDF.' It clearly positions this as the tool for retrieving signed documents and even distinguishes it from the sibling download_certificate by explaining that document PDFs include certificate pages and a certificate hash for the full envelope.
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 clear context by telling the agent to obtain completed_document_id from get_envelope_status and notes that document_id can also be used to download a specific document. It does not explicitly name alternatives or state when not to use this tool, but the conditions are largely inferable from the source it names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
JSON audit trail for an envelope. Completed envelopes include the
persisted completion certificate; voided / declined / expired
envelopes return an on-the-fly trail with an empty certificate.
Still-active envelopes are not found. Takes the original document_id.
Requires Authorization: Bearer zs_....
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation as read-only and idempotent, so the description's additional behavior about envelope states is valuable. It discloses that completed envelopes include the completion certificate while voided/declined/expired ones have an empty certificate, and that active envelopes are not found. The authentication requirement is also stated. 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?
Three sentences with no filler; the core purpose is front-loaded, followed by key behavioral edge cases and the auth requirement. Every sentence adds information not available elsewhere.
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 an output schema and read-only/idempotent annotations, the description covers all essential calling context: purpose, envelope-state behavior, required input, and authentication. The only minor omission is a precise definition of 'original document_id', but that is acceptable.
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 provides no description for document_id (0% coverage), so the description must compensate. It does by specifying that the original document_id is accepted, clarifying which identifier to use. It does not explain format or type, but it gives the key semantic distinction.
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 identifies the tool as returning a JSON audit trail for an envelope, which is a specific resource and distinct from sibling tools like get_envelope_status or download_certificate. It also specifies the input (original document_id), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when an audit trail is available: completed envelopes include a persisted certificate, voided/declined/expired envelopes return a trail with an empty certificate, and still-active envelopes are not found. It does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Envelope progress: session status, per-recipient signing status, and —
once completed — the completed_document_id to pass to
download_signed_document. Requires Authorization: Bearer zs_....
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and idempotentHint annotations already establish safety. The description adds valuable behavioral detail: the specific pieces of status returned and the conditional presence of completed_document_id after completion. It also discloses the required Authorization header, which is not captured in the 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?
One concise sentence packs the return payload, the conditional behavior, and the auth requirement with no filler. The most important information 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 read-only status endpoint with an output schema and one required parameter, the description covers the essential behavioral and auth context. The mention of the downstream download_signed_document tool also completes the workflow context.
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 has 0% description coverage for document_id, and the description does not explicitly define that parameter. However, the parameter is a single required string named Document Id, and the description's context around envelope progress makes its role reasonably inferable. It adds little semantic value 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 clearly states what the tool reports: envelope session status, per-recipient signing status, and the completed_document_id when available. It also differentiates itself from the sibling download_signed_document by noting the completed_document_id is meant to be passed to that 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?
The description gives practical context: get envelope status first, and once completed, the returned ID feeds into download_signed_document. It does not explicitly list exclusions or when-not-to-use scenarios, but the relationship to a named sibling provides strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Credit packs and billing model (1 credit = 1 envelope send). No authentication required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds 'No authentication required', a behavioral trait not present in the annotations, and clarifies the billing model. Since annotations already declare readOnlyHint and idempotentHint, the description supplements them with a useful operational detail. There is no contradiction between the description and 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 12-word sentence with every clause carrying meaning: the resource, the conversion factor, and authentication requirement. It is appropriately front-loaded with the core purpose and contains no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with an output schema, this description is complete. It covers the purpose, the critical credit-to-envelopes relationship, and the authentication requirement, leaving no gap for an agent to call it correctly. The output schema handles return-value details, so no further explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the input schema covers everything, so the description has no obligation to explain parameter meanings. The baseline for zero-parameter tools is 4, and the description does not need to add anything here. Its note about authentication is behavioral, not parameter-related.
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 identifies the resource, credit packs and billing model, and the defining conversion factor (1 credit = 1 envelope send), making it clear that this tool returns pricing information. It lacks an explicit action verb, but the tool name 'get_pricing' provides the verb, and the content differentiates it from buy_credits and check_balance.
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 context that implies usage, such as the credit-to-envelope conversion and 'No authentication required', which indicates this is a low-stakes informational call. However, it does not explicitly state when to choose this over buy_credits or check_balance, nor does it name any alternatives or exclusions. Usage must be inferred from the tool name and sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This account's referral code and shareable referral link. Requires
Authorization: Bearer zs_....
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation as read-only and idempotent. The description adds the authentication requirement and clarifies that the returned data belongs to the currently authenticated account, which is useful context beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, stating exactly what is returned and the required authorization in two short sentences. Every word serves a purpose and the most important information 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?
Given the tool's simplicity, the read-only annotations, and the presence of an output schema, the description covers all necessary context. The only extra requirement, authentication, is explicitly stated, making the definition complete for a zero-parameter retrieval 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?
The tool has zero parameters, and the schema fully covers this with an empty properties object. Per the baseline for no-parameter tools, the description does not need to compensate for missing parameter documentation.
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 resource: this account's referral code and shareable referral link. While there is no explicit verb in the description, the title supplies 'Get', and the resource is distinct enough from sibling tools to avoid 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 states an important prerequisite, the `Authorization: Bearer zs_...` header, which helps the agent know when the call can be made. It does not explicitly discuss when to use this tool versus alternatives, but the referral-link resource is unique among the listed siblings, so the omission is minor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch recipient signing URLs for an already-sent envelope without
sending again. Output is the same signing_urls shape
send_envelope / send_draft / send_from_template return:
[{recipient_email, recipient_name, signing_url, token}].
Each signing_url / token authenticates as that recipient on
/sign/{token}, so this tool requires envelopes:send (same class as
send / remind), not envelopes:read.
These URLs are the ordinary agent-link. They are valid iframe
`signingUrl` values for `@zsign/embed` / `@zsign/react`. This tool
does not mint a second URL scheme and does not replace agent-link as
the default. Optional recipient_email keeps one recipient. Requires
`Authorization: Bearer zs_...`.| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | ||
| recipient_email | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds crucial behavior: it does not re-send, each URL/token authenticates as that recipient, requires envelopes:send rather than envelopes:read, and returns ordinary agent-link URLs valid for embedding. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence adds useful information: purpose, output shape, permissions, embedding behavior, and optional parameter. The most important operational fact is front-loaded, and there is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is thorough for a moderately complex tool: it includes the output shape, authorization requirement, iframe compatibility, and the distinction from agent-link. The only real gap is that document_id is not explicitly tied to the envelope identifier, which would make the call fully unambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains recipient_email well ('keeps one recipient') but does not explicitly define document_id or connect it to the envelope ID returned by send_envelope/send_draft/send_from_template. Since there are only two parameters, one is explained well and the other is only implied.
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 'Fetch recipient signing URLs for an already-sent envelope without sending again,' which names a specific verb, resource, and scope. It clearly distinguishes this from sibling send tools by emphasizing the envelope is already sent.
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 states the key condition (already-sent envelope), the permission class (envelopes:send, not envelopes:read), and what the tool does not do (does not mint a second URL scheme, does not replace agent-link). It does not explicitly say 'use send_envelope instead when you need to send,' but the context leaves little ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Daily credit-consumption report. start_date and end_date are
inclusive UTC dates (YYYY-MM-DD). Returns 400 when
(end_date - start_date).days >= 400. Rows are only days with an
envelope debit, refund, or void_refund. Requires
Authorization: Bearer zs_....
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | Yes | ||
| start_date | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds substantial behavioral detail beyond annotations: inclusive UTC date semantics, a 400 error boundary at 400 days, row filtering to only days with envelope debit/refund/void_refund, and the required Authorization header. No annotation contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then adds constraints, error behavior, row filtering, and auth requirements in four tight sentences. Every sentence adds material information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, return values need not be explained. The description covers the key callable constraints: date format, inclusivity, error threshold, row filtering semantics, and authentication, leaving no critical gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the full burden for both parameters. It does so by specifying that start_date and end_date are inclusive UTC dates in YYYY-MM-DD format, plus the range constraint that triggers a 400 error.
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 resource and scope: a daily credit-consumption report. It does not, however, distinguish this tool from sibling tools such as check_balance or get_pricing, so it falls 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?
Usage is implied by 'Daily credit-consumption report' and the date-range constraints, but the description never says when to use this tool versus alternatives like check_balance or get_pricing. It provides context but no explicit routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the caller's envelopes. Optional filters: status (pending,
in_progress, completed, voided, declined, expired, cancelled, draft,
ready_to_send), q (name / filename / recipient / id substring),
date_from and date_to (ISO-8601, inclusive on created_at). limit max
50 (default 20). Includes unsent drafts unless status selects a
session status. Each item includes thin recipients[] (recipient_id,
email, name, status, can_remind) for remind_envelope, plus
document_id for get_envelope_status. Requires
Authorization: Bearer zs_....
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| limit | No | ||
| offset | No | ||
| status | No | ||
| date_to | No | ||
| date_from | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only and idempotent, and the description adds valuable behavior beyond that: unsent drafts are included unless a status filter selects a session status, date filters are inclusive on created_at, limit is capped at 50, and Authorization: Bearer zs_... is required. 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?
Everything in the description is actionable: purpose first, then filters, then the important unsent-drafts caveat, then downstream payload fields, then auth. No filler or 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?
With an output schema present and optional parameters only, the description is nearly complete for a list/search tool. The only gaps are pagination/offset semantics and the slightly vague phrase 'session status', but an agent can still select and invoke this tool confidently.
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?
Despite 0% schema description coverage, the description compensates well for status (all valid values), q (substring targets), date_from/date_to (ISO-8601, inclusive), and limit (max 50). Only offset lacks explicit semantics, relying on its schema default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with 'Search the caller's envelopes' – a specific verb, resource, and scope. It also names downstream tools (remind_envelope, get_envelope_status), which helps distinguish this list/search function from those single-envelope actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this is the search entry point for the caller's envelopes, and the returned fields are explicitly tied to remind_envelope and get_envelope_status. It does not state explicit exclusions such as 'for templates use list_templates', so it stops short of full when/not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List saved templates in the caller's org. Returns template_id,
name, updated_at, and role names — enough to pick a template for
add_document_to_draft(template_id=...) or send_from_template.
Requires Authorization: Bearer zs_....
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, and the description does not contradict them. It adds value beyond the annotations by disclosing the auth requirement (Authorization: Bearer zs_...) and specifying the returned fields, giving the agent useful behavioral context for a safe read operation.
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 waste: purpose first, then return fields, downstream usage, and auth requirement. Every clause earns its place and the critical scoping constraint 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?
With an output schema present and zero parameters, the description covers everything needed to call it correctly: purpose, scope, return content, downstream use, and auth. There are no gaps for a straightforward read-only listing 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?
The tool has zero parameters, so the baseline is 4 per the rubric. There are no parameter semantics to document, and the description correctly avoids inventing any. The schema is empty and fully covered, so nothing is missing.
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 (templates) + scope (caller's org), and names the returned fields (template_id, name, updated_at, role names). It clearly differentiates from siblings like create_template (creation vs. listing) and list_envelopes (templates vs. envelopes). The purpose is 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 frames the use case: the output is 'enough to pick a template for add_document_to_draft(template_id=...) or send_from_template,' telling the agent when this tool is the right choice. It does not enumerate explicit exclusions versus alternatives, but the downstream routing 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.
Send one signing reminder to a still-unsigned recipient.
Wraps POST /api/v1/documents/{document_id}/recipients/{recipient_id}/remind
— same policy as the dashboard Remind button and the cron sweep (cap,
spacing, sequential can_sign_now). REMINDERS_ENABLED does not apply.
Envelopes sent with send_invite=false are refused unless
override_send_invite is true. Not idempotent: each success increments
reminder_count, and a second call inside REMINDER_DELAY_HOURS is 429.
Requires `Authorization: Bearer zs_...`.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | ||
| recipient_id | Yes | ||
| override_send_invite | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations give only idempotentHint=false, but the description adds substantial behavioral detail: each success increments reminder_count, a second call within REMINDER_DELAY_HOURS yields 429, REMINDERS_ENABLED does not apply, and Authorization is required. This goes well beyond the structured fields and makes side effects and rate limits explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: purpose, endpoint, policy context, exception, idempotency warning, and auth requirement. The key action is front-loaded, and no filler or repetition exists.
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 state-changing tool with side effects and rate limiting, the description covers all operational essentials: when it applies, when it refuses, what side effects occur, error behavior, and authentication. An output schema is present, so return-value details are not required in the description.
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 has 0% parameter descriptions, so the description must compensate. It does: document_id and recipient_id appear in the endpoint path, making their roles clear, and override_send_invite is semantically explained in the sentence about send_invite=false envelopes. Slight room remains for explicitly stating that document_id is the envelope/document identifier, but the context suffices.
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?
Description opens with the exact action: 'Send one signing reminder to a still-unsigned recipient,' specifying the verb, resource, and condition. The wrapped endpoint and reminder-specific wording clearly distinguish this from sibling tools like send_envelope or void_envelope, which involve other lifecycle actions.
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 clear when-to-use context: target recipient must still be unsigned, and it explains policy constraints such as cap, spacing, and sequential can_sign_now. It also gives explicit when-not conditions for send_invite=false envelopes. However, it does not name alternative sibling tools or contrast them directly, so the guidance stops short of full 5-level routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a previously created Draft. Costs 1 credit. Recipients default
to those stored when the draft was created. After send, status is Sent
and invite emails fire (unless send_invite=false). sequential defaults
true (one at a time); set false for everyone at once. Requires
Authorization: Bearer zs_....
| Name | Required | Description | Default |
|---|---|---|---|
| metadata | No | ||
| recipients | No | ||
| sequential | No | ||
| document_id | Yes | ||
| send_invite | No | ||
| send_completion_email | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the sparse annotations by disclosing that sending costs 1 credit, default recipients come from draft creation, status changes to Sent, invite emails fire unless disabled, and sequential behavior controls send timing. It also notes the required Authorization header. This gives the 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?
The description is compact and front-loaded: the purpose, cost, defaults, effects, and auth requirement each earn their place. There is no redundant restating of the tool name or obvious 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 main behavioral context: credit cost, recipient defaults, status change, email behavior, sequential flag, and authentication. Since an output schema exists, return-value documentation is not required. The only notable gaps are the semantics of send_completion_email and metadata, which are minor for typical usage.
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 0% description coverage, so the description must compensate. It does clarify recipients, sequential, and send_invite, but it does not explain send_completion_email or metadata at all, even though both are parameters with defaults. This is adequate for core usage but leaves some parameters under-specified.
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 ('Send') and the resource ('a previously created Draft'), which distinguishes it from sibling tools like send_envelope that target envelopes rather than drafts. It also conveys the operation's place in the draft lifecycle.
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 'previously created Draft' implies this tool should be used only after a draft exists, and the contrast with send_envelope is implicit through the resource type. However, the description does not explicitly say when not to use this tool or mention alternatives such as send_envelope or update_draft.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a PDF for legally binding signature, or leave it as a Draft for a human to approve. Immediate send costs 1 credit. Provide the PDF either as document_base64 OR as a public https document_url (max 10MB). recipients = [{"name": "...", "email": "...", "role": "signer"}]. Each recipient gets a signing email; poll get_envelope_status for progress. Requires Authorization: Bearer zs_....
auto_send defaults true (existing one-tool send). Set auto_send=false or draft=true to create a Draft: status Draft, no credit debit, no invite emails. draft=true always wins if both flags are set. Then a human Approves/Sends in the dashboard, or call send_draft.
Immediate send: the PDF is REJECTED unless it contains signing-field placeholder tags. Draft mode accepts an untagged PDF (human places fields) or optional fields.
zSign field placeholder syntax:
Format: {type:party:name} -- add * after the type to mark the field required, e.g. {signature*:signer}
Types: signature, initials, text, date, radio
party must exactly match the recipient's "role" value passed when sending (MCP default role is "signer")
name is optional for signature/initials/date and REQUIRED for text fields; letters, digits, and underscores only
radio fields take FOUR parts: {radio:party:group:option}. Every tag sharing a party and group forms one exclusive set -- the signer picks exactly one, and the chosen option is the value reported back. Mark the set required with {radio*:...} on any of its tags. group is letters/digits/underscores; option may also contain spaces and hyphens
radio tags must be visible text in the PDF body -- they cannot be the name of a PDF form field
Keep each tag on a single line in a standard font -- a tag split across lines is not detected
The tag's position in the document becomes the field's position; the signed value is drawn over it, and the tag itself is deleted when you upload -- signers never see it, and it is not in the completed document
Tags can be visible text in the PDF body, or the name of a PDF form field / annotation (except radio, which must be visible text) Examples: {signature*:signer}, {initials:signer}, {text*:signer:full_name}, {date:signer:signed_on} Radio (visible text only): {radio*:signer:plan:Option 1}, {radio*:signer:plan:Option 2} Sample PDF: https://storage.googleapis.com/zsign-public/simple_contract_1.pdf Docs: https://zsign.io/docs/api
metadata is an optional flat object of string keys/values (max 50 keys) echoed back in every webhook for this envelope -- use it to carry your own record ids.
sequential (default true): recipients sign one at a time in list order. Set false so everyone can sign at once. Same flag as REST POST /api/v1/documents/send sequential.
documents: list of {filename, document_base64 | document_url, name?} to send several PDFs as ONE envelope (one credit, shared recipients, one signing link per signer; at most 10). Mutually exclusive with document_base64/document_url.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| draft | No | ||
| fields | No | ||
| filename | No | document.pdf | |
| metadata | No | ||
| auto_send | No | ||
| documents | No | ||
| recipients | No | ||
| sequential | No | ||
| send_invite | No | ||
| document_url | No | ||
| document_base64 | No | ||
| send_completion_email | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes far beyond the annotations: discloses the 1-credit cost, that Draft mode has no credit debit or invite emails, that immediate send REJECTS untagged PDFs, the full field-tag syntax and its lifecycle (tags deleted on upload, never seen by signers), sequential signing default, and that metadata is echoed in every webhook. The non-idempotent, open-world, non-destructive profile is consistent with this text.
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?
Long, but front-loaded with the core decision (send vs draft) and organized into scannable mode/syntax sections. A few passages (the tag placement/visibility bullets) could be tightened, and the field-syntax block is heavy for a single paragraph, but nearly every line carries 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 13-parameter, zero-schema-coverage, non-idempotent mutation tool this is as complete as an agent needs: cost model, rejection preconditions, draft semantics, recipient/field syntax, portability flags (sequential, docs), and the status-polling follow-up. Return values are covered by the output schema, so omitting them is correct.
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 0% schema coverage across 13 params, the description carries the burden and does so for document_base64/document_url (10MB limit), recipients structure/roles, auto_send, draft, metadata (max 50 keys, echo behavior), sequential, and documents (mutually exclusive, max 10). It leaves name, filename, send_invite, and send_completion_email undocumented, which is the only real gap.
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 precise verb+resource ('Send a PDF for legally binding signature') and immediately distinguishes the two operating modes (immediate send vs Draft) that separate it from siblings like send_draft. An agent can tell exactly what this tool does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes between modes: immediate send vs auto_send=false/draft=true, states draft=true wins on conflict, names the follow-up path (human dashboard approval or send_draft), and points to get_envelope_status for polling. Also names the alternative REST endpoint and mutual exclusivity with the documents list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
First-class send from a saved template. Stamps a new Draft from
template_id (same service as dashboard draft-from-template), then
sends it. Costs 1 credit. recipients =
[{"name": "...", "email": "...", "role": "signer"}]. role_mapping
maps the template's roles onto recipient roles, e.g.
{"customer": "client"}; unmapped roles stay literal. This is the
send-from-template path — do not also pass template_id to
send_envelope. To compose a Draft without sending, keep using
add_document_to_draft(template_id=...). If send fails after the
stamp, the new draft is left in place and the error includes
draft_id. The stamp does not store recipients or send options —
retry with send_draft(document_id=draft_id, recipients=) and repeat any metadata / send_invite /
send_completion_email / sequential, or discard that draft.
Requires Authorization: Bearer zs_....
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| metadata | No | ||
| recipients | Yes | ||
| sequential | No | ||
| send_invite | No | ||
| template_id | Yes | ||
| role_mapping | No | ||
| send_completion_email | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses several important behaviors beyond the annotations: it costs 1 credit, it leaves a draft in place if sending fails, it does not store recipients or send options, and it requires a specific Authorization header. These are exactly the kind of side effects and prerequisites an agent needs to know before calling a mutating 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?
The description is dense but well-organized: it front-loads the core action, then covers cost, parameters, alternatives, failure behavior, and retry guidance. Every sentence adds value, though the retry paragraph is long and could be slightly tightened. It earns a 4 for being information-dense without being bloated.
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 schema descriptions, and no idempotency guarantee, the description covers the critical operational context: cost, failure side effects, retry strategy, and authentication. The output schema exists, so return values don't need to be described. An agent has enough information to call this tool correctly and handle failures.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: it explains the recipients array structure, role_mapping semantics, and the meaning of the send options. It doesn't explicitly describe every parameter (e.g., metadata, sequential, send_invite, send_completion_email), but it references them in the retry guidance, and the schema provides their names and defaults. The description adds significant 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 description states a specific verb ('sends') and resource ('a saved template'), and explicitly distinguishes this from sibling tools like send_envelope and add_document_to_draft. It also clarifies the two-step behavior (stamp a Draft, then send it), which makes the tool's purpose 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?
The description gives explicit when-to-use guidance: it is the send-from-template path, and it warns not to also pass template_id to send_envelope. It also names the alternative for composing without sending (add_document_to_draft) and the retry path (send_draft), so an agent knows exactly when to choose this tool versus others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace the fields on an unsent Draft. No credit debit, no invites.
fields is a whole-list replace: [{type, party, name?, required,
position: {page_number, x, y, width, height}}]. Requires
Authorization: Bearer zs_....
| Name | Required | Description | Default |
|---|---|---|---|
| fields | Yes | ||
| document_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that `fields` is a whole-list replace, that the operation only applies to unsent drafts, that no credits or invites are involved, and that a Bearer token is required. This is exactly the kind of behavioral detail an agent needs beyond readOnly/idempotent/destructive hints.
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 terse sentences deliver scope, field semantics, exclusions, and auth requirements with no filler. The most important information 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?
Given the output schema exists and annotations cover idempotency and read-only behavior, the description provides all necessary operational context: when it is valid, what fields look like, replacement semantics, exclusions, and auth. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by detailing the expected `fields` item shape: `{type, party, name?, required, position: {page_number, x, y, width, height}}`. It also clarifies that `fields` is a whole-list replace. The `document_id` parameter is not elaborated, but its meaning is inferable from the draft context.
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 'Replace the fields on an unsent Draft,' which clearly identifies the verb, resource, and scope. It also distinguishes itself from siblings by explicitly stating 'No credit debit, no invites,' so an agent knows this is not a billing or invitation operation.
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 says this applies to an 'unsent Draft' and excludes credit/invite operations, giving useful context for when to use it. It does not explicitly name an alternative like send_draft for sending, but the boundary is clear enough from the wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Void a sent envelope so it can no longer be signed.
Signing links stop working immediately and recipients who have not yet signed are emailed. The send credit is returned only if nobody has opened the envelope.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| document_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint, idempotentHint), the description details concrete behaviors: signing links stop immediately, non-signers are emailed, and the send credit is returned only if nobody opened the envelope. This adds valuable context about side effects and conditions, fully leveraging the opportunity to disclose behavior.
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, front-loading the purpose first, then adding essential side effects. No waste, no redundancy, and every sentence contributes to understanding.
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 core purpose and side effects effectively, and since an output schema exists, return values are covered elsewhere. However, it omits any guidance on the reason parameter and does not clarify whether the envelope document itself remains accessible. Given the tool's destructive nature, this is a minor but noticeable gap.
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 schema description coverage at 0%, the description must explain the parameters but does not mention document_id or reason at all. It provides zero insight into what these parameters represent or how to use them, leaving the agent to infer from names alone. This is a major gap.
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 'Void a sent envelope so it can no longer be signed' — a specific verb, resource, and outcome that distinguishes it from siblings like send_envelope and get_envelope_status. The purpose is unambiguous and actionable.
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 specifies the condition 'sent envelope', indicating it applies to already-sent envelopes, which provides clear context for when to use it. However, it does not explicitly contrast with alternatives or mention when not to use it, so it falls short of the highest tier.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_usagecorrect_recipient_emailcreate_templateget_signing_linkslist_templatessend_from_templateadd_document_to_draftdownload_signed_document2 fields changedInput schema / properties / document_idAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Document Id"
+}Input schema / properties / formatAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Format"
+}send_envelope1 field changedInput schema / properties / documentsAdded value: +{
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Documents"
+}download_certificateget_audit_trailremind_envelopelist_envelopessend_draft1 field changedInput schema / properties / sequentialAdded value: +{
+ "default": true,
+ "title": "Sequential",
+ "type": "boolean"
+}send_envelope1 field changedInput schema / properties / sequentialAdded value: +{
+ "default": true,
+ "title": "Sequential",
+ "type": "boolean"
+}send_draftsend_envelope8 fields changedInput schema / properties / auto_sendAdded value: +{
+ "default": true,
+ "title": "Auto Send",
+ "type": "boolean"
+}Input schema / properties / draftAdded value: +{
+ "default": false,
+ "title": "Draft",
+ "type": "boolean"
+}Input schema / properties / fieldsAdded value: +{
+ "anyOf": [
+ {
+ "items": {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Fields"
+}Input schema / properties / recipients / anyOfAdded value: +[
+ {
+ "items": {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / recipients / defaultAdded value: +nullInput schema / properties / recipients / itemsRemoved value: -{
- "additionalProperties": true,
- "type": "object"
-}Input schema / properties / recipients / typeRemoved value: -"array"Input schema / requiredRemoved value: -[
- "recipients"
-]update_draftget_referral_linksend_envelope3 fields changedInput schema / properties / metadataAdded value: +{
+ "anyOf": [
+ {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Metadata"
+}Input schema / properties / send_completion_emailAdded value: +{
+ "default": true,
+ "title": "Send Completion Email",
+ "type": "boolean"
+}Input schema / properties / send_inviteAdded value: +{
+ "default": true,
+ "title": "Send Invite",
+ "type": "boolean"
+}void_envelopebuy_creditscheck_balancecreate_accountdownload_signed_documentget_envelope_statusget_pricingsend_envelopeSend AI-created PDFs for signature, track signers, and return verifiable document evidence.
E-signatures for agents: mint a sandbox key, send PDFs, track status, download the sealed result.
Send documents for e-signature, track signing status, and download signed PDFs. No API key required.
E-signatures for contracts and NDAs. Draft with AI, review, and send for signature.
Add one secure layer between your agents and this server.
