Documenso MCP by usefulapi

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

Annotations only supply title and destructiveHint=true, so the description carries most of the burden. It adds the v2 endpoint (POST /document/recipient/create) as extra context, but never explains what is 'destructive' about this mutation, whether adding a recipient triggers a notification email, or what permission/state is required beyond 'draft'. Useful but incomplete.

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 the purpose front-loaded and no filler. The endpoint sentence is arguably incidental detail, but it is cheap and does not bury the core statement.

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

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

For a mutation tool with no output schema and only a bare destructiveHint annotation, the description should clarify side effects (emails, document state, rollback) and required permissions. It covers what the tool does and the draft constraint but leaves the mutation's consequences unexplained.

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 all five parameters and the role enum; the baseline is 3. The description's role list adds mild framing but actually under-covers the enum by omitting ASSISTANT, so it contributes little beyond the structured fields.

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

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

Clear verb+resource ('Add a recipient') with the role set enumerated (signer, approver, viewer, CC), which tells the agent what kind of entity is being created. It does not name a sibling to differentiate from (e.g. get_recipient, distribute_document), and it omits the ASSISTANT role present in the enum, so it is clear but not fully precise.

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 'to a draft document' implies the precondition (document must still be a draft, echoed in the schema), but there is no explicit when-to-use/when-not-to-use guidance or pointer to alternatives such as get_recipient or distribute_document. Usage is implied rather than stated.

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

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

Annotations only declare destructiveHint=true, so the description should carry more of the behavioral load. It does add that distribute_document=true sends immediately while false creates a draft, but that same fact is already stated in the schema, and it never explains what is destructive (template placeholder consumption, irreversible send, permission needs).

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

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

Three short sentences, front-loaded with the purpose and followed by the actionable prerequisite and toggle. The trailing 'Documenso v2: POST /template/use' endpoint note is marginal value for an agent choosing a tool but does not bloat the text.

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 5-parameter mutation with no output schema, the definition covers purpose, prerequisite lookup, and the immediate-send toggle, which is most of what an agent needs. It leaves the destructive consequence of the operation and error behavior unstated, but the core call path is 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 description coverage is 100%, so the schema already documents every parameter, including recipient id/name/email and the folderId/externalId fields. The description adds only the cross-tool hint that recipient ids come from the template placeholders, which is useful but not beyond the baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Create a new document from an existing template') and immediately narrows the scope with 'filling in the real recipients'. This distinguishes it from siblings like documenso_duplicate_document and documenso_create_folder without the agent opening any 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?

Gives an explicit prerequisite workflow: 'Call documenso_get_template first to read the placeholder recipient ids', and clarifies the distribute_document toggle for immediate sending. It stops short of naming when to prefer duplicate_document or add_recipient instead, so it is clear context rather than a full routing rule.

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 include destructiveHint=true, but the description doesn't explain why creation is considered destructive (e.g., folder creation may overwrite an existing folder with the same name or be irreversible). With annotations providing some signal, the description misses the opportunity to add context about irreversibility, naming conflicts, or permission requirements.

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

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

Two concise sentences. The first states the purpose clearly, and the second provides an API endpoint reference. No unnecessary words.

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

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

The description is minimally adequate for a creation tool. However, given the destructiveHint annotation and lack of output schema, it should ideally explain what happens on success, whether folders can be nested (parentId parameter is mentioned only in schema), or any rate limits. It leaves important behavioral context unaddressed.

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

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

Schema description coverage is 100%, so all parameter meanings are documented in the schema. The description adds no additional parameter details beyond what's already provided, which is acceptable given the high coverage.

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

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

States a specific verb and resource ('Create a folder') and clarifies its purpose ('for organising documents or templates'), which distinguishes it from siblings like documenso_list_folders. However, it doesn't explicitly differentiate from other create operations in the toolset.

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

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

No guidance on when to use this tool versus alternatives. There's no mention of prerequisites, typical scenarios, or exclusions. The description merely states what it does without indicating appropriate contexts.

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

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

Annotations only carry destructiveHint=true; the description adds critical behavioral context that annotations cannot: 'This emails real people' signals an external side effect, and the version/endpoint detail grounds the call. It doesn't cover reversibility or failure modes, but adds real value beyond 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 tight sentences: purpose front-loaded, then the impactful side-effect warning. Zero waste; endpoint reference is compact.

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

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

For a 3-param mutation with no output schema, the description covers purpose, side-effect, and endpoint. Missing prerequisites (must be a draft, recipients already added) and whether the operation is reversible keep it from a 5.

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

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

Schema description coverage is 100%; all three parameters are documented in the schema (documentId, message, subject). The description doesn't add syntax or formatting guidance beyond what the schema provides, so baseline 3 is appropriate.

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

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

Specific verb+resource+scope: 'Send a draft document to its recipients for signature.' Distinguishes from sibling redistribute_document by the 'draft' qualifier, and from add_recipient by naming the send action.

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

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

Implies usage – send a draft (prerequisite implied), and the sibling list shows redistribute_document as the re-send alternative, but the description doesn't explicitly say 'use this only for drafts, not already-sent documents.' Clear context without explicit exclusions.

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 supply destructiveHint=true, so the safety profile is partially covered. The description adds useful context that the result is a new draft retaining existing fields, implying the source is untouched. It does not cover permissions, side effects on recipients/fields, or what is returned.

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, front-loaded sentences with no filler; the core action leads and the API mapping trails. Efficient, though the endpoint reference is marginal value for an agent choosing a 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?

For a one-parameter tool with full schema coverage and no output schema, the description covers what it does and what it produces (a new draft). Only the return value (e.g., new document id) is unstated, a minor 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?

Schema description coverage is 100% and the single parameter (documentId) is documented in the schema as 'The document to copy.' The description adds nothing parameter-specific, so the baseline of 3 applies.

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

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

States a specific verb+resource (copy an existing document into a new draft) and adds scope detail ('keeping its fields') that separates it from siblings like create_document_from_template. It does not name an alternative tool, but the action 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?

There is no when-to-use guidance, no exclusions, and no mention of the sibling tools (create_document_from_template, list_documents) an agent might otherwise pick. The agent must infer that this is for duplicating a known documentId rather than creating fresh.

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 declare readOnlyHint=true, so the safety profile is already covered, but the description adds real behavioral context: the payload includes recipients, fields and current status, and it maps to the underlying Documenso v2 endpoint GET /document/{documentId}. It does not mention pagination or error behavior, but for a read-only fetch that is a minor gap.

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 read purpose and the returned payload are front-loaded ahead of the endpoint mapping. Every clause carries information.

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

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

With no output schema, the description usefully compensates by naming the returned members (recipients, fields, status). For a one-parameter read-only tool this is close to complete; only error/permission behavior and the exact response shape remain undefined.

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

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

Schema description coverage is 100% and there is only one parameter, so the baseline is 3. The description reinforces the resource identity via the /document/{documentId} path but adds no syntax, format, or range detail beyond 'numeric id' already in the schema.

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

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

States a specific verb (fetch) and resource (a single document) and enumerates what comes back: recipients, fields, current status. The word 'single' implicitly separates it from list_documents and get_documents_by_ids, but no sibling is named explicitly, so it falls short of full differentiation.

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

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

The description gives no guidance on when to choose this over get_documents_by_ids (one id vs many) or how it relates to list_documents. It also does not state prerequisites such as needing a valid documentId or required auth. Usage must be inferred entirely from the name.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds genuinely useful context that the result is a URL rather than file bytes, but says nothing about link expiry, permission requirements, or whether the signed version may be absent – the kind of traits that matter for a signed-document download.

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

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

Three short sentences, front-loaded with the core action and the link-vs-bytes caveat. Every sentence earns its place with no filler.

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

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

With no output schema, the description correctly compensates by stating the return is a link, not bytes, which is the key thing an agent must know. It is complete for a simple two-parameter read, though link validity/lifetime is left unaddressed.

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%, including a clear enum description for 'version', so the schema already carries the parameter burden. The description only references the endpoint path and adds no format or default semantics beyond what the schema states. Baseline 3 applies.

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

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

States a specific verb and resource ('Get a download URL for a document's PDF') and immediately distinguishes the output type from the sibling get_document by noting it 'Returns a link, not the file bytes.' An agent can tell this apart from a metadata-fetch tool without opening either 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?

The description conveys what the tool yields but never states when to prefer it over alternatives such as get_document or list_document_attachments, nor any prerequisites. Usage is only implied by the word 'download'.

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

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

Annotations only assert readOnlyHint=true; the description adds the genuinely useful explanation that this is a read despite being a POST because the v2 API is action-shaped, pre-empting a likely agent misread. It omits practical traits of a batch fetch such as behavior for unknown ids and any cap on array size.

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

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

Three short clauses, front-loaded with the action and scope, with the read-only clarification and endpoint placed after. No filler sentences.

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

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

With no output schema, the description should say what comes back (document objects, ordering, handling of ids that do not exist) and any batch-size limit. For a simple lookup the return shape is inferable, but the missing failure/limit behavior leaves a real 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?

The single documentIds parameter is fully described in the schema, so the schema carries the semantics. The description adds only the notion of 'several' documents, which is already conveyed by the array type, so baseline 3 applies.

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

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

States a specific verb (fetch) and resource (documents) plus the batch scope (several, in one call), which separates it from the singular get_document. It does not explicitly name list_documents as the filtered alternative, so sibling differentiation is implied rather than stated.

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 'in one call' hints the tool exists for batch efficiency when you already hold ids, but there is no explicit when-to-use vs get_document or list_documents guidance. Usage must be inferred from the name and the id-array parameter.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's main added value is disclosing that the response contains type, page, position and the inserted value — useful given there is no output schema. It discloses nothing about auth requirements, error behavior, or permissions.

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 compact sentences with zero filler; the payload of the call is front-loaded and the endpoint reference is a useful trailing detail. Nothing here is redundant or padded.

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

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

For a one-parameter read tool with no output schema, the description compensates well by enumerating the returned attributes and naming the underlying endpoint. It is nearly complete; only guidance on sourcing the fieldId and any error/permission notes are absent.

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% (the single fieldId parameter is documented as 'The field's numeric id'), so the schema already carries parameter meaning. The description adds no syntax, format, or constraint detail beyond routing the id into the path template.

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 ('Fetch a single document field') and enumerates the retrieved attributes (type, page, position, inserted value), which is more than a restatement of the name. It does not compare itself to any sibling, but no sibling is a field-level getter, so the reader can distinguish it from the document-level tools anyway.

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 only implied: you call it when you have a fieldId and need that field's details. There is no statement of when this is preferable to documenso_get_document or how to obtain a fieldId, and no prerequisites or exclusions are given.

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 safe-read profile is covered. The description adds the concrete return payload fields and confirms the HTTP verb/path, which is useful context, but says nothing about error behavior (e.g. nonexistent recipientId) or auth requirements.

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

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

Two short sentences, front-loaded with the action and return fields. The trailing REST endpoint reference is mildly redundant with the tool name but costs little and aids traceability.

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

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

For a simple single-entity read with no output schema, the field enumeration effectively compensates for the missing return-value documentation, and annotations carry the safety profile. Only error/permission behavior is left uncovered, which is minor here.

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

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

Schema description coverage is 100% with a single documented parameter, so the baseline is 3. The description only echoes recipientId in the endpoint path and adds no format, range, or sourcing detail 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?

States a specific verb and resource ('Fetch a single recipient') and enumerates what comes back — email, role, signing order, signed status. An agent can distinguish it from list_documents or get_document, though no sibling is named explicitly.

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?

Implies retrieval of one recipient by id but gives no when-to-use guidance, no prerequisites, and never names an alternative such as documenso_add_recipient or documenso_get_document. The 'single' qualifier hints at list-vs-one but leaves the routing to inference.

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

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

With readOnlyHint=true already covering the safety profile, the description adds useful behavioral context: it discloses what the response contains (recipient placeholders and fields) and the underlying v2 endpoint. It does not mention permission requirements, rate limits, or error behavior, but the annotation carries the safety burden.

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

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

Three tight clauses with zero filler: the action and return content come first, the dependency guidance second, and the endpoint last. Every sentence earns its place and nothing is buried.

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

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

For a simple one-parameter read tool with no output schema, the description compensates by naming what is returned (recipient placeholders and fields) and by routing the agent to the consumer tool. Nothing needed to call it 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 100% and the single templateId parameter is fully documented as the numeric id in the schema. The description adds no format or semantic detail beyond that, so the baseline of 3 is appropriate.

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

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

States a specific verb (Fetch) and resource (a single template), and distinguishes itself from the sibling list_templates by specifying 'a single template' with recipient placeholders and fields. An agent can immediately tell this apart from list_templates and create_document_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?

Explicitly directs the agent to read this before calling documenso_create_document_from_template so it knows the recipient ids, which is a clear when-to-use rule tied to a named sibling. It does not state when not to use it or point to list_templates as the alternative for bulk retrieval, so it falls just short of full guidance.

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

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

readOnlyHint=true already declares the safety profile, so the description's burden is reduced, but it adds almost no behavioral context beyond the annotations: no pagination or result-limit behavior, no ordering, no indication of what an attachment record contains. The only addition is the raw API endpoint mapping, which is not behavioral information.

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 the action and scope front-loaded; nothing is padded. The second sentence is a bare REST mapping that is marginally useful but not essential, keeping it just under a 5.

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

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

For a simple read-only list tool with a single fully-documented parameter and no output schema, the description is close to adequate. However, as a list operation it leaves open whether results are paginated, capped, or ordered, and there is no output schema to answer that, so a clear gap remains.

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

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

Schema description coverage is 100% and the single documentId parameter is fully documented in the schema, so the baseline of 3 applies. The description adds nothing about the parameter (e.g., job/document id vs. template id) beyond what the schema already states.

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

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

States a specific verb and resource ('List the attachments on one document'), and the 'on one document' scoping makes it easy to distinguish from broad siblings like documenso_list_documents or documenso_get_document. It does not explicitly name a sibling alternative, so it falls short of 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?

The description gives no when-to-use guidance, no exclusions, and no alternatives — it never explains how this differs from documenso_get_document, which an agent might reasonably reach for when a caller wants a document's associated files. Usage is only inferable from the tool name.

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 readOnlyHint=true annotation already tells the agent this is a non-mutating read, lowering the disclosure bar. The description adds only the upstream endpoint (GET /document); it says nothing about result ordering defaults, pagination limits, or empty-result behavior beyond what the schema's orderByDirection field already covers. Useful but thin.

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, front-loaded sentences with no filler; the capability statement leads and the endpoint note follows. The endpoint sentence contributes little to an agent's decision, keeping it short of a 5.

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 eight optional parameters fully described and safety covered by annotations, the agent can invoke this correctly. Because there is no output schema, the description should at least hint at the return shape (a page of documents plus pagination metadata) and it does not, leaving a real gap for a paginated list tool.

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

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

Schema description coverage is 100%, so all eight parameters are already documented with their enums and bounds. The description's filter list (status, folder, source template, query) largely restates those same fields and adds no format or interaction detail, so the baseline 3 applies.

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

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

States a specific verb and resource ("List documents") and enumerates the filter dimensions, so the agent knows it is a collection read rather than a single-record fetch like documenso_get_document. It does not explicitly name competing siblings such as documenso_get_documents_by_ids or documenso_list_templates, so differentiation is inferred rather than stated.

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 "optionally filtered by status, folder, source template or a text query" implies the browse/filter use case, which is adequate context for a list endpoint. However, it never says when to prefer this over the ID-based or template-listing siblings, and gives no prerequisites or exclusions.

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 safe-read profile is covered. The description adds the API endpoint (Documenso v2: GET /folder) but says nothing about pagination defaults, filtering behavior, or result shape, so it adds limited behavioral value beyond the annotation.

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

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

Two short sentences, purpose front-loaded with the API reference trailing. Efficient, though the 'Documenso v2: GET /folder' fragment is arguably low-value to an agent caller.

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

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

For a simple read-only list tool with full schema coverage and no output schema, the definition provides enough to call correctly. Missing only optional pagination-default context, which is minor.

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 page, query, perPage, and parentId are all fully documented in the schema. The description adds no parameter meaning on top of that, making the baseline 3 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?

States a specific verb (List) and resource (folders) and clarifies they organise documents and templates, which gives context beyond the bare name. It is not explicitly differentiated from siblings like list_documents or list_templates, but the resource noun 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as create_folder. The agent must infer usage entirely from the name and resource.

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 readOnlyHint annotation already establishes this as a safe read, so the bar is lower. The description adds useful context by naming the underlying API call (GET /template), but says nothing about pagination behavior, default page size, or result scoping beyond the schema. Adequate but not rich.

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

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

Three short sentences with the purpose front-loaded and no padding. The API endpoint mention is mildly redundant but still compact and informative.

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

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

For a read-only list tool with full schema coverage and a safety annotation, this is nearly sufficient. However, it omits how results are paginated/delimited and does not differentiate the tool from its sibling list/get operations, leaving a real routing 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?

Schema description coverage is 100%, so all four parameters (page, query, perPage, folderId) are already documented in the schema. The description adds no additional meaning for any of them, so the baseline of 3 applies.

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

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

States a clear verb+resource ('List reusable document templates') and adds a conceptual definition ('how you create a new document without uploading a PDF'). It does not explicitly distinguish itself from sibling list/get tools like documenso_list_documents or documenso_get_template, 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?

The description explains what a template is but never says when to call this tool versus documenso_list_documents, documenso_get_template, or documenso_create_document_from_template. No prerequisites, exclusions, or alternative-routing guidance is given.

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?

Adds real behavioral context beyond the destructiveHint=true annotation: 'This emails real people' warns the agent that this has an outward-facing side effect on external parties. It stops short of stating permission requirements, rate limits, or what happens to recipients who have already signed.

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

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

Two tight sentences with the action and precondition front-loaded before the side-effect warning. The trailing 'Documenso v2: POST /document/redistribute' is marginally useful endpoint mapping but slightly dilutes an otherwise lean description.

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

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

For a 2-param mutation with no output schema, the description covers action, precondition, side effect, and endpoint. It omits state edge cases (e.g., resending after signing or completion) and permission requirements, which would matter for a destructive call.

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

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

Schema description coverage is 100% – documentId and recipients are both documented in the schema. The description's 'named recipients' phrasing adds only marginal color over 'The numeric recipient ids to email again', so the baseline of 3 is appropriate.

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

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

Specific verb+resource: 'Resend the signing invitation' to 'named recipients'. The qualifier 'of an already-sent document' cleanly separates it from the sibling documenso_distribute_document (initial send) without the agent needing to open either 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?

The 'already-sent document' precondition gives clear context for when this applies versus an initial distribution. It does not explicitly name documenso_distribute_document as the alternative for unsent documents, so the routing is inferable rather than stated.

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