GoodSign

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

The readOnlyHint annotation already establishes that this is a safe read operation, and the description is consistent with that. It adds useful domain context beyond the annotation by explaining that each envelope costs 1 credit, which helps the agent interpret the returned balance meaningfully.

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 concise and efficiently front-loaded: the first sentence states what the tool returns, and the second provides practical usage context. Every sentence earns its place with no filler or redundancy.

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

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

For a parameterless read-only tool, the description fully covers what the agent needs: what the tool does, what it returns, and when to invoke it. The output is implied by 'account name and remaining credits,' so no output schema is required for adequate guidance.

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

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

The tool has zero parameters, so the schema is trivially complete and the description cannot add parameter-level detail. The baseline of 4 applies because the description accurately reflects the no-input nature of the operation.

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, 'Show,' tied to a clear resource: the GoodSign account name and remaining credits. This unambiguously distinguishes it from all siblings, none of which concern account or credit status.

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 context for when to use the tool: before bulk sending or when the user asks about credit balance. It does not name alternatives, but no sibling tool offers account status, so exclusion guidance is unnecessary.

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

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

The annotations are generic boolean hints and provide little behavioral color, so the description carries full disclosure weight. It reveals non-obvious behaviors: automatic tag discovery, one field per tag, one signer per signer key, template-like non-sending behavior, one-time-only sending, and warning-driven retry. No annotation contradiction exists.

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 appropriately sized, with each sentence contributing distinct information: the core action, automatic tag/signer creation, template and one-time-send behavior, and warning recovery. The main action is front-loaded and there is no filler.

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

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

The description covers the full workflow: prerequisites, automatic field/signer creation, template behavior, one-time sending, and warning recovery. The only gap is that with no output schema, it never states the shape of a successful response (e.g., returned document_id), so an agent must infer how to locate and send the created document via get_document.

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

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

Schema description coverage is 100%, so the schema already documents upload_id as a 40-character hex string and doc_name as optional with a default. The description mostly restates that upload_id must come from a successful PUT, which the schema already says, and adds little new semantic value for the parameters.

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

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

The first sentence names a specific operation: turning a PDF uploaded via create_upload_url into a GoodSign document, with the PUT as an explicit prerequisite. It also separates itself from send_from_template by stating it does not send anything, which clearly differentiates this tool from its siblings.

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

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

The description gives an unambiguous workflow: PUT first, then call this tool, then check with get_document, then send with send_from_template. It also tells the agent when to retry (after unreadable-tag warnings) and when to re-upload the same PDF, leaving no ambiguity about the intended sequence.

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

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

Discloses rich behavioral details well beyond the sparse annotations: short-lived URL, PUT flow, 15-minute expiry, tag parsing rules, key collisions, field sizing, and the fact that tag text is erased from the final PDF. It even warns about corruption or silent drops, which is critical for correct invocation.

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

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

Although long, the description is front-loaded with the core purpose and then organized into a tag reference and numbered rules where every sentence conveys an operational constraint. No filler or redundant restatement is present; the length is justified by the complexity of the PDF tag behavior.

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 that there is no output schema and minimal annotations, the description carries the full burden and succeeds: it identifies the returned upload_id, gives the complete tag spec, explains the required PUT workflow, and recommends verification with get_document. An agent has enough to invoke the tool and the dependent tool correctly.

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

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

The input schema has zero properties, so the 0-parameter baseline of 4 applies. The description adds no parameter details (there are none), but its workflow and tag guidance are the relevant operational semantics for this tool.

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

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

The description immediately states a specific action ('Get a short-lived URL to upload a PDF') and the downstream conversion intent. It differentiates from siblings by explicitly scoping to documents NOT based on an existing GoodSign template, separating it from template-based flows like 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?

Gives explicit when-to-use guidance: non-template documents such as SOW/contract/NDA, and instructs the agent to call create_document_from_upload after the PUT. It also specifies the 15-minute validity and when to embed tags (if generating the PDF yourself), making the usage context unmistakable.

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

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

Annotations already establish readOnlyHint=true, so no safety contradiction exists. The description adds behavioral context beyond the annotation: the returned URL requires the same Authorization: Bearer API key, and the intended consumption pattern is a shell curl command rather than in-conversation byte fetching.

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 deliver the essential information with no filler. The core purpose is front-loaded, and the practical usage instruction follows immediately. Every sentence earns its place.

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

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

For a simple one-parameter tool with no output schema, the description covers the essential points: what is returned, authentication requirements, and how to use the result. It could mention response shape or URL expiration, but nothing critical is missing for correct invocation.

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

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

Schema coverage is 100% for the single uuid parameter, and the schema already describes it as 'Document uuid'. The description does not add additional parameter-specific semantics beyond identifying the resource as a document PDF, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Get an authenticated download URL'), the resource ('a document's PDF'), and adds a useful scoping detail (audit certificate once complete). It distinguishes itself from sibling tools like get_document by making explicit that it returns a URL for shell-based download, not document metadata or content.

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 practical guidance: download the PDF with curl in a shell and do not try to fetch the bytes into the conversation. It does not explicitly name alternative sibling tools or exclusion conditions, but the context of use is strongly implied by the instructions on how to consume the result.

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

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

Even though readOnlyHint=true already covers safety, the description goes well beyond by disclosing what is returned for each entity type, that timestamps are unix epoch seconds, that field entries are structural only, and that signer-entered field values are never returned. This is precisely the behavioral detail an agent needs when there is no output schema.

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

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

Three dense sentences with no filler. The core action is front-loaded, and the template versus sent-document behavior is organized logically. Every clause contributes non-redundant information, making this appropriately concise and well-structured.

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-uuid detail fetch with no output schema, the description fully covers return expectations for both entity types, timestamp format, the structural nature of field entries, and the explicit exclusion of signer-entered values. This is complete enough for an agent to call the tool and interpret its response without surprises.

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

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

The input schema already documents uuid at 100% coverage, including its source (list_templates or list_documents). The description adds the distinction that a single uuid may refer to either a document or template, but this is a minor reinforcement rather than substantial new meaning, so the baseline schema-driven score of 3 is appropriate.

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

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

The description states a specific verb ('Fetch full detail') and a specific resource ('one document OR template by uuid'), and it clearly distinguishes the tool from sibling list tools like list_documents and list_templates by focusing on a single entity's full detail. The dual document/template scope is explicit, leaving no 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 clear context for when to use the tool: check a template's signer keys before calling send_from_template, and check a sent document's per-signer progress when assessing status. It does not explicitly name alternatives or state exclusions, but the guidance is strong enough for an agent to select this tool over list_documents and list_templates for detail lookups.

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

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

Annotations already declare readOnlyHint=true, so the description is not burdened with safety disclosure. It adds useful behavioral context beyond annotations: the default status, what 'sent' and 'complete' mean semantically, and that the result provides uuids suitable for get_document. It doesn't mention pagination or return shape, but that's minor for a read-only list 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?

Three sentences with no waste: purpose, status semantics plus default, and a usage example plus chaining instruction. Information is front-loaded and every sentence contributes to correct use.

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

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

For a simple one-optional-parameter, read-only list tool with full schema coverage, the description covers the essential invocation details: default, filter semantics, and what the results enable (uuid → get_document). It omits explicit result shape and pagination, but the uuid mention implies the necessary output context, making it nearly complete.

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

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

Schema covers the single parameter fully with a description and enum, so baseline is 3. The description adds value by mapping 'sent' and 'complete' to real-world meanings (waiting on signatures vs. fully signed), going beyond the raw enum labels.

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 states a specific verb ('List'), a scoped resource ('this account's documents'), and the filtering dimension ('by status'). It differentiates from the sibling get_document by explicitly routing per-signer detail to that tool, and its use case ('what is still waiting to be signed?') makes the 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?

Provides clear when-to-use guidance: which status values map to which real-world scenario, the default, and a concrete question the tool answers. It names get_document as the follow-up for per-signer detail, but does not explicitly exclude other siblings like list_templates, 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.

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

The annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds useful context that templates define signer keys and that a template uuid is returned, but it does not disclose details like pagination, sorting, or the full set of fields returned. For a simple list operation, this is adequate but not exhaustive.

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 wasted text. The core purpose is front-loaded, followed by actionable workflow guidance, and each sentence contributes a distinct piece of information. Nothing is redundant or tangential.

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

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

The tool is simple (zero params, read-only), and the description covers what the agent needs: what the list contains, why it matters, when to call it, and how to use the result. The absence of an output schema is compensated by the explicit mention of the template uuid and the reference to `get_document` for further detail.

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

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

There are zero parameters, and the schema already covers everything (100% coverage). The description adds meaning about the return value's importance (the template uuid needed for `send_from_template`), which helps the agent understand what to extract from the result. Baseline 4 for zero-parameter tools is appropriate.

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

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

The description uses the specific verb 'List' and identifies the resource: 'reusable document templates in this GoodSign account.' It also distinguishes the tool from siblings by naming downstream tools (`send_from_template`, `get_document`) and explaining the unique role of this list 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?

It explicitly states when to use the tool: 'Call this first whenever the user wants to send a document.' It explains why this tool must precede `send_from_template` (needs a template uuid) and points to `get_document` as the follow-up to inspect signer keys. This gives the agent a clear decision flow.

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

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

The description discloses that the tool sends real email and warns about rate/frequency, which is valuable behavioral context beyond the annotations. Annotations already indicate it is not read-only and not destructive, but the description adds the real-world side effect (email delivery) and the caution about repeated use. It could go further by noting whether reminders are logged or if there are limits, but the key behavioral trait is covered.

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: it states the action first, then explains the two modes, then adds the caution. Every sentence earns its place, and there is no redundant repetition of the schema or title.

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

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

For a simple two-parameter tool with no output schema, the description covers the essential context: what it does, how to target signers, and the caution about real email. It could mention what happens if no signers are pending or whether the response indicates success, but the core information an agent needs to invoke it correctly is present.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds meaningful semantics by explaining the optional signer_email behavior (omit for all, pass for one), which clarifies the parameter's purpose beyond the schema's short description. This is a solid enhancement over the baseline.

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

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

The description clearly states the tool's function: re-sending signing invitation emails to pending signers. It distinguishes itself from siblings by focusing on the reminder action, and it explicitly explains the two modes (all pending signers vs. a specific signer), which is more specific than the title alone.

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

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

The description provides explicit guidance on when to use the tool and how to choose between the two parameter modes. It also warns against repeated calls, advising once per day per signer, which is actionable usage guidance beyond what the schema provides.

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

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

The description goes well beyond the annotations by warning 'THIS EMAILS REAL PEOPLE and spends 1 credit' and instructing the agent to confirm signer details with the user or use draft=true. It also explains sequential signing behavior and that signers are emailed one at a time, which is critical side-effect 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 compact and front-loaded: the real-world consequence and user-confirmation requirement come first, then prerequisites, then optional behavior. Every sentence contributes meaningful guidance with no repetition of the schema.

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

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

For a 9-parameter tool with real-world side effects and no output schema, the description covers the essential operational context: prerequisites, side effects, draft staging, and sequential signing. It does not describe return values or tracking, and leaves some minor parameters to the schema, so it is strong but not fully complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that every signer key must be represented, that field keys come from get_document, that draft=true stages without emailing, and that send_order uses lower values first. It doesn't elaborate on every parameter, but the important semantics are 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 opens with a specific verb and resource: 'Send a document for e-signature using a template.' This clearly distinguishes the tool from siblings like create_document_from_upload and list_templates, and the title reinforces the same intent.

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 for correct use: template_uuid is needed, signers must cover every template key via get_document, and draft=true stages without emailing. However, it never explicitly contrasts with alternatives like create_document_from_upload or says when not to use this tool, so it stops short of a full 5.

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

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

Annotations already mark destructiveHint=true, and the description adds meaningful behavioral context beyond that: the action cannot be undone, signers are notified by default, notify=false enables silent voiding, and user confirmation is required. This is exactly the kind of extra context that helps an agent handle an irreversible action safely.

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, each adding necessary information with no filler. The core action and irreversibility are front-loaded, followed by re-send guidance, notify defaults, and the user-confirmation requirement. Every sentence earns its place.

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

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

For a simple three-parameter, no-output-schema destructive tool, the description covers all critical operational aspects: what the tool does, irreversibility, signer notification behavior, the re-send path, and the need for user confirmation. 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?

Schema description coverage is 100%, so the schema already documents uuid, notify, and message. The description adds some behavioral nuance around notify (default notified vs. silent) but does not substantially go beyond what the schema already states. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Cancel'/'void') and resource ('a sent document') and states the intended effect: 'nobody can sign it anymore.' It also distinguishes itself from the sibling send_from_template by explicitly naming it as the way to re-send, so an agent can clearly differentiate this tool from related 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: use this when a sent document must no longer be signable. It names the alternative (send_from_template) for re-sending, explains the notify behavior, and instructs the agent to confirm with the user before voiding, which is explicit operational guidance.

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