E-signature API for AI agents: send contracts, sign PDF documents, track and download signed files.
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.
Create a zSign account and API key in one call — no email verification,
no human steps. Email is optional (receipts/recovery only). The returned
key starts with zs_live_; pass it as Authorization: Bearer <key> on
this MCP connection (or REST calls) for all other tools. New accounts
have 0 credits: call get_pricing then buy_credits next.
| 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 only mark this as a non-read-only, non-idempotent, non-destructive operation. The description goes well beyond that by disclosing side effects (account + API key creation), the lack of email verification, optional email purpose, the 'zs_live_' key prefix, the required Authorization header, and the 0-credit initial state. This is rich behavioral context that annotations do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences deliver the core purpose, authentication usage, and next-step workflow with no filler. Each sentence earns its place, and the most important information—account and API key creation—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 there is an output schema, the description does not need to describe the return value. It covers prerequisites (none), credential usage for all other tools, initial credit state, and the immediate next actions. The tool is fully callable and integrable from this description alone.
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 adds real meaning for email ('optional, receipts/recovery only'), but it says nothing about the name parameter beyond what the schema's 'Name' title already implies. Because one of two parameters gains semantic context while the other remains minimally documented, a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Create a zSign account and API key in one call.' It also clearly separates this tool from siblings like get_pricing and buy_credits by framing it as the account-provisioning entry point. Including the API-key creation detail removes any ambiguity about what the tool returns.
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 strong contextual guidance: account creation requires no email verification, and new accounts start with 0 credits, followed by 'call get_pricing then buy_credits next.' It stops short of explicitly stating when not to use this tool or naming alternative account-related tools, but the flow is clear enough for an agent to sequence correctly.
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 (NOT the original document_id). Returns the PDF as
base64. Requires Authorization: Bearer zs_....
| Name | Required | Description | Default |
|---|---|---|---|
| completed_document_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare the operation read-only and idempotent, so the description adds meaningful operational context beyond them: it specifies that the response is base64-encoded and that an Authorization header with a Bearer token is required. This is useful behavioral information that the annotations do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences deliver the essential facts in order: the resource, the critical parameter source, the response format, and the authentication requirement. There is no filler, and every sentence adds functional 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 single-parameter read-only tool with an output schema and safety annotations, the description covers everything an agent needs to invoke it correctly: the resource, the parameter provenance, the return encoding, and the authentication requirement. No critical information 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 zero description coverage for completed_document_id, but the description fully compensates by explaining where the value comes from and explicitly excluding the original document_id. This gives the agent the exact provenance and a concrete negative example, which is far more than the bare schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Download the sealed, signed PDF'), making the tool's function immediately clear. It also disambiguates the required input from the original document ID, distinguishing this tool from get_envelope_status and reinforcing its purpose as the retrieval endpoint for the final signed 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 gives clear, actionable usage guidance by stating that the tool requires the completed_document_id from get_envelope_status and explicitly warns against using the original document_id. However, it does not explicitly spell out when to choose this tool over other siblings, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
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 and WorkflowSettings.sequential.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| draft | No | ||
| fields | No | ||
| filename | No | document.pdf | |
| metadata | No | ||
| auto_send | 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?
With only sparse annotations (readOnlyHint=false, destructiveHint=false), the description carries the transparency burden and delivers richly: it discloses the 1-credit cost, PDF rejection when tags are missing, that each recipient gets a signing email, that tags are deleted on upload and never appear in the final document, that party must match the recipient role, and that draft mode debits no credit. It also reveals side effects like webhook echo of metadata and the sequential signing default. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but the tool genuinely warrants it: field-tag syntax, radio group semantics, and draft-vs-send interplay cannot be compressed further without losing operational necessity. It is well-organized (send/draft behavior, input formats, tag syntax with examples, metadata, sequential) and the correct usage is front-loaded. It is slightly redundant in the radio visible-text rule, stated twice, and could trim a few words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-complexity tool (12 params, dual mode, tag syntax, cost side effects) the description covers the full send workflow, draft workflow, failure conditions (rejection, tag requirements, size cap), post-call behavior (polling), auth, and links to docs and a sample PDF. An output schema exists, so return-value documentation is unnecessary. Remaining gaps are minor: send_invite/send_completion_email semantics and filename behavior are left to inference.
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 for the critical parameters: recipients (exact array shape with name/email/role), document_base64 vs document_url (either-or, 10MB limit), auto_send/draft (full semantics including precedence 'draft=true always wins'), metadata (flat, max 50 keys, webhook echo), and sequential (ordering semantics). However, four secondary parameters (name, filename, send_invite, send_completion_email) receive no semantic explanation beyond their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Send a PDF for legally binding signature, or leave it as a Draft for a human to approve.' It captures the tool's dual-mode behavior and differentiates it from siblings like send_draft (send an existing draft) and get_envelope_status (poll progress). An agent can determine what this tool does and what it is not without inspecting other definitions.
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 decision criteria for the primary fork: use auto_send=true for an immediate send vs draft=true/auto_send=false to defer to a human, and explicitly routes to siblings for follow-up ('poll get_envelope_status for progress', 'call send_draft'). It also states the auth prerequisite. It does not enumerate when-not-to-use cases for other siblings (e.g., void_envelope, update_draft), but the main alternative paths are clearly signaled.
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. Dates show when Glama detected each change.
send_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_envelopeClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Send 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.
Each tool targets a distinct action or resource: account creation, pricing/credits, sending, draft management, status polling, download, and voiding. Even closely related tools like send_envelope and send_draft are clearly separated by whether they create a new envelope or send an existing draft.
All tools follow a consistent lowercase verb_noun pattern: buy_credits, check_balance, create_account, download_signed_document, get_envelope_status, send_draft, update_draft, void_envelope. There are no naming style collisions or vague generic verbs.
11 tools is well-scoped for an e-signature API: account setup, billing, sending, draft handling, status, download, and voiding are each represented. The count feels intentional rather than padded or sparse.
The core envelope lifecycle is covered: create/send, draft update, send draft, status, download, and void, plus account and billing support. Minor gaps exist such as no way to list envelopes, retrieve a draft's current fields, or delete a draft, but agents can still complete the primary workflow.
