Assinafy MCP Server

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely non-derivable behavior: apps-capable hosts render a contract browser while other clients get the same JSON, so output shape varies by host; and reads stay available when the tracking plan lapses, telling the agent this call is not gated by subscription state.

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?

Roughly five short clauses, front-loaded with the action triage, which is the highest-value information. Every sentence carries signal, though the tracking-plan-lapse and host-rendering notes are secondary and could be ordered after the action guidance.

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 15-parameter, three-action tool with no output schema, the description covers mode selection, cross-tool ordering, host-dependent output, and date semantics. Remaining gaps — pagination behavior and what 'related' actually returns — are partly mitigated by 80% schema coverage, but the absence of an output schema means the return shape of get/related is 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 80%, so the schema already carries most parameter meaning (sort default, per_page max, status pattern, ending_within_days timezone). The description's only added semantic is that contract lifecycle dates are distinct from signing deadlines, which helps disambiguate the end_date filters but does not explain any individual parameter or which filters apply to which action.

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 the resource (contracts) and enumerates the three modes the single tool dispatches to: 'list' with filters, 'get' for terms or one amendment, and 'related' for a root plus its amendments. That maps cleanly onto the oneOf schema and lets an agent pick a mode without opening the schema. It stops short of naming any sibling (e.g. assinafy_list_documents) to contrast against.

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 per-action guidance — use 'get' for terms or an amendment, 'related' for a root and its amendments — and adds a cross-tool rule, 'Resolve names before writes', which steers the agent to browse before calling update_contract. There is no explicit when-not or statement of which sibling handles a different case, so it falls short of the 5 bar.

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 non-readOnly, non-idempotent, openWorld, non-destructive, but the description adds real behavioral context beyond them: this action sends invitations, consumes credits, promotes document state automatically for virtual, imposes the collect-only 'metadata_ready' prerequisite, and surfaces the specific failure code digital_certificate_requires_virtual. That is above-bar disclosure for a mutation 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?

Four tight paragraphs, front-loaded with the mode decision and prerequisites, and every sentence carries operational information (states, error codes, step rules, credit cost). It is dense but not padded; a slightly terser step explanation could still earn the same content, keeping it from a perfect score.

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 an 8-param, no-output-schema, side-effecting tool, the description covers mode selection, prerequisites, ordering rules, credit impact and identity/certificate constraints. The main residual gap is that it says nothing about what the created assignment returns (IDs, status), which the absence of an output schema leaves 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 75% and the schema already documents method, entries, verification_method and notification_methods in depth. The description still adds meaning the schema does not: the step contiguity rule ('contiguous starting at 1', all signers must supply it), parallel-vs-sequential signing order semantics, and the virtual/collect compatibility constraint. It stops short of explaining estimate_only and expires_at beyond the schema text, hence not a 5.

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 ('Request signatures on a document') and immediately distinguishes its two modes (virtual vs collect) with the exact conditions that select each. It is clearly separable from siblings like assinafy_send_pdf_for_signature and assinafy_place_fields without 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?

It gives explicit when-to-use rules: virtual for field-less signing, collect for placing fields on specific pages, with the required document states for each. It also routes the agent to sibling tools for inputs (assinafy_list_signers, assinafy_create_signer, assinafy_get_document) and warns to pre-check for existing assignments before spending credits.

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=false, idempotentHint=false and openWorldHint=true, so the write/one-shot nature is known. The description adds genuinely new context beyond that: it 'sends invitations and can consume credits', and the DigitalCertificate template constraint. It does not describe failure behavior, partial-success handling, or whether the call is reversible.

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 sentences, all substantive, with the core action front-loaded ahead of prerequisites and caveats. Nothing is padded, though the prerequisite sentence is dense enough that it could be split for scanability.

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, no-output-schema mutation tool, the description covers the main flow, prerequisite discovery/validation, a signer-type restriction, and the credit cost. It omits what the call returns on success (e.g. the created document/assignment identifier), which an agent may need for follow-up calls.

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 every parameter and nested signer field is already documented in the schema, including the DigitalCertificate and notification_methods constraints the description restates. The description adds only marginal framing (signer by ID vs. name+email), 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?

Names a specific verb and resource: 'Generate a document from a saved template and invite one signer per role, by signer ID or full name and email.' The scope (template-driven, one signer per role) is clear. It stops short of explicitly contrasting with close siblings like assinafy_send_pdf_for_signature or assinafy_create_assignment, so an agent must infer the distinction.

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 concrete prerequisites: find roles with assinafy_list_templates, validate editor_fields with assinafy_validate_fields first, and the constraint that DigitalCertificate signers need a virtual template without placed fields. It names those tools but never states when to prefer a sibling (e.g. send_pdf_for_signature for non-template flows) as an alternative.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), and the description adds two facts not derivable from them: no invitation/notification is dispatched, and duplicates are possible so a prior list is required. It does not say what happens when a duplicate is submitted (error vs. created) or what permissions are needed.

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, zero filler, with the action front-loaded and the prerequisite/side-effect notes immediately after. Every sentence carries distinct 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?

For a 5-parameter, 1-required tool with annotations present, the description covers purpose, a dedupe prerequisite, and the key side effect. No output schema exists and the description does not indicate what is returned (e.g., the created signer id needed by downstream tools), which is the main remaining 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 coverage is only 60%, and the description adds no parameter meaning at all — it never mentions full_name, email, or the optional account_id/government_id/whatsapp fields. The schema does document the non-obvious fields (normalization, CPF/CNPJ requirement, OAuth-derived account_id), so the baseline 3 applies rather than a penalty.

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 signer') plus its scope ('in the workspace'), which cleanly separates it from the sibling read/update tools (assinafy_get_signer, assinafy_list_signers, assinafy_update_signer). An agent can identify the operation without opening the schema.

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

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

Gives an explicit prerequisite and alternative: 'Search with assinafy_list_signers first to avoid duplicates.' It also clarifies the tool's relationship to the notification flow ('Sends no invitation'), implying the agent must separately trigger sending. It stops short of naming update_signer as the path for existing signers, so it is clear but not complete on when-not-to-use.

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

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

Annotations already declare destructiveHint=true and non-idempotent, so the safety profile is covered. The description adds meaningful context beyond that: an authorization prerequisite and the fact that Assinafy enforces which documents may be deleted, implying server-side rejection paths.

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 authorization guard front-loaded, followed by the state-inspection prerequisite. 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?

Covers the key risks for a destructive, non-idempotent operation (authorization, state check, server-side restrictions) with no output schema to explain. It could note irreversibility or the failure response, but is largely complete for a one-parameter delete.

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% with a single well-described document_id parameter. The description adds no format, source, or retrieval guidance for the ID, 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?

Specific verb+resource ('Delete a document') that precisely identifies the operation. It is the only delete-style tool among siblings, so an agent can distinguish it, though the description doesn't name any sibling 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?

Gives a clear precondition ('only when the user's instruction explicitly authorizes deletion') and a sequencing rule ('Inspect its current state first'). It stops short of naming alternative tools or explicit when-not-to-use cases.

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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false, openWorldHint false), so the bar is lower. The description adds genuinely non-annotation context: the response is base64-encoded and the default artifact is 'original', plus the conditional availability of the signed PDF. It does not mention size limits or error behavior on unavailable artifacts.

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, front-loaded with the action and the encoding, with the conditional caveat second. Minor redundancy with the schema's artifact list costs it the top mark, but nothing is 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?

There is no output schema, and the description does the important compensating work of telling the agent the payload is base64 rather than a URL or binary stream. Combined with the artifact enumeration and the availability caveat, an agent can call this correctly; only edge behavior (unavailable artifact, large-file handling) is 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% and the schema already lists the artifact values and marks 'original' as the default, so the description largely repeats structured data. Baseline 3 is appropriate; the description adds no format, ordering, or constraint 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 (download) and resource (document artifact) plus an enumerated set of artifact variants, which is more precise than a generic 'get file'. It implicitly distinguishes itself from assinafy_download_document_page by talking about whole artifacts (original/pades/bundle) rather than pages, but it never names that sibling, so the 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?

It gives one real usage constraint: the signed PDF is only available when the document is certificated and the artifact is listed. That is useful conditional guidance, but it does not say when to prefer this tool over assinafy_download_document_page or assinafy_show_document/get_document, leaving the alternative-selection decision to the agent.

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, idempotentHint and destructiveHint, so the safety profile is covered; the description usefully adds the return encoding ('Returns base64'), which matters because no output schema exists. It still omits practical behavior such as image format, size limits, or error behavior for an invalid page_id.

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 action, followed by the dependency and the return encoding. No filler, no repetition of the 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 two-parameter read tool with full annotation coverage, the description supplies purpose, input provenance, and return type. Only marginal items are missing (image format/size constraints, pagination across pages), which are not strictly needed to invoke it correctly.

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

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

Schema coverage is 100% and both properties are documented, so the baseline is 3. The description adds genuine meaning the schema does not: the provenance of page_id (it must come from assinafy_get_document), which is the one thing an agent could get wrong.

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 ('Download') and a precisely scoped resource ('the rendered image of a specific document page'), which cleanly separates it from the sibling assinafy_download_document (whole document) and assinafy_show_document. An agent can route on 'page' vs 'document' 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?

Gives explicit prerequisite guidance: 'Use a page_id returned by assinafy_get_document,' naming the sibling that produces the required identifier. It does not, however, state when to prefer this tool over assinafy_download_document or how to obtain page IDs when the caller only has a document.

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/idempotentHint/non-destructive, so the safety profile is covered. The description adds genuine domain behavior beyond that: '100% signed does not mean certification is finished; the signed PDF is ready at status certificated' warns the agent about a state distinction it would otherwise get wrong.

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, front-loaded with what is returned, then usage timing, then the certification caveat. Every sentence carries distinct information 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 itself enumerates the return surface (status, assignment, signers with progress, pages, artifacts) and warns about the certification state, which is exactly the context an agent needs to interpret the result.

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 a single required document_id parameter, so the schema fully documents the input. The description adds no syntax, format, or ID-sourcing detail beyond 'known document'. 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?

States a specific verb (inspect) and resource (one known document) and enumerates what it surfaces: status, assignment, signer progress, pages, artifacts. The phrase 'one known document' implicitly contrasts with the list_documents sibling. However, it does not differentiate from the confusingly similar sibling assinafy_show_document, which an agent could easily confuse with this 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?

Gives a clear situational trigger: 'Read it before retrying a send or following up.' That tells the agent when this tool belongs in a workflow. No explicit when-not or named alternative (e.g., vs list_documents or show_document) is provided, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds no behavioral context of its own beyond restating that something is retrieved.

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

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

A single short sentence with zero padding and the key noun front-loaded. It is efficient, though its brevity reflects under-specification rather than deliberate compression.

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 getter with complete parameter coverage and full annotations, this is minimally adequate. There is no output schema, so the description could have said what a 'field definition' contains (type, placement, validation rules), which would help an agent decide whether to call it.

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 both field_id and account_id are already documented, including the OAuth fallback behavior for account_id. Baseline 3 applies: the description adds no syntax, format, or scoping 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 ('Retrieve') and resource ('a single field definition'), and the singular framing distinguishes it from list_fields in a general sense. It does not, however, name or differentiate against close siblings like list_fields or validate_fields, so an agent gets no explicit routing signal.

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 and never mentions the obvious alternative (list_fields) or when a single-field fetch is preferable. Nothing is misleading, but nothing is provided either.

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 readOnly=true, idempotent=true, destructive=false, and openWorld=false, so the safety profile is fully covered. The description adds nothing beyond that — no note on what is returned, auth/permission needs, or error behavior for a missing ID.

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

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

A single short sentence that is front-loaded and wastes no words. It is efficient, though its brevity edges toward under-specification rather than pure conciseness.

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-resource getter with a 100%-documented two-parameter schema and full annotation coverage, the definition is minimally adequate. With no output schema, though, the description could say what fields a signer record contains or how failures surface.

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 signer_id and account_id are fully documented in the schema, including the OAuth fallback for account_id. The description contributes no additional parameter meaning, 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?

Clear verb + resource: 'Retrieve a signer's information' identifies a fetch of a single signer. It does not distinguish itself from the sibling list_signers or clarify what 'information' includes, so an agent must infer the single-vs-collection distinction.

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 when-to-use guidance and no mention of alternatives such as assinafy_list_signers or assinafy_update_signer. The agent gets no help deciding between this and the other signer tools.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description's one added fact — that the response includes roles and field placements — is genuinely useful content context, but it says nothing about failure behavior for unknown IDs or scope of account_id.

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

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

A single tight sentence with zero filler that front-loads the verb and resource. Nothing can be trimmed without losing 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?

For a simple, read-only, two-parameter lookup whose safety semantics are already in annotations, the description plus schema is nearly sufficient. The only shortfall is that no output schema exists and the return shape is summarized in half a clause, leaving the exact structure of roles/field placements unstated.

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 both template_id and account_id documented inline including the default-if-omitted behavior for account_id. The description adds no parameter-level meaning, 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 ("Get one saved template") and adds what the payload contains ("roles and field placements"), which sharpens it beyond the bare title. It implicitly contrasts with assinafy_list_templates via "one," but never names or explicitly distinguishes itself from that sibling.

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 statement of prerequisites, and no mention of the obvious alternative (assinafy_list_templates for enumeration vs this tool for fetching one by ID). The agent must infer that a template_id is required and that enumeration lives elsewhere.

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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds genuinely new context beyond that: each entry includes an event-specific payload snapshot with variable keys and request origin metadata (ip, user-agent), which tells the agent what to expect from the response shape.

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 sentences with no filler; the core action is front-loaded and each following sentence earns its place by describing the payload and origin details.

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 carries the burden of return-value context, and it partially does so by characterizing the payload snapshot and origin fields. It stops short of covering ordering, pagination, or volume of entries, which are minor gaps for a read-only 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 coverage is 100% for the single document_id parameter, so the schema fully documents the input. The description adds nothing about document_id semantics, format, or scoping, 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 and resource: 'List the activities recorded for a document.' The 'activities' resource is distinct from sibling tools like get_document, show_document, and list_documents, so an agent can differentiate it, 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?

'Use it to explain what happened to a document and when' gives an implied usage context, which is better than nothing. However, it offers no when-not guidance, no prerequisites, and does not point to alternatives such as verify_document or get_document for related audit information.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds pagination and filter-based retrieval, which is useful behavioral context, but it does not describe return format, default page size, status value semantics, or authentication/routing behavior beyond what annotations and schema 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?

Two sentences, front-loaded with the core action and followed by a single usage sentence. Nothing is repeated or wasted, and the most important scoping information appears first.

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 rich annotations and 100% schema description coverage, the description covers purpose, primary use case, and pagination. It omits return value shape and status enum semantics, but with no output schema and a comprehensive input schema, the definition is largely complete for invocation.

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

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

Schema description coverage is 100%, so all eight parameters are already documented in the input schema. The description mentions filtering by name and status and pagination, but adds no syntax, default values, or semantic detail beyond what the schema already provides. Baseline 3 applies when the schema carries 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 states a specific verb (search/list) and resource (workspace documents) and names the filters (name, status) and pagination. It does not explicitly distinguish this from get_document or show_document, though the phrase 'before inspecting' hints at the relationship. Clear but missing explicit sibling routing.

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 usage context: use it to find a document the user names before inspecting or following up. This tells the agent when to use it, but it does not state when not to use it (e.g., when a document ID is already known, use get_document) or name alternatives explicitly.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that enabling include_standard returns signature, initial, and signatureDate records, but this largely repeats the schema's parameter description and omits return format or pagination details.

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 definition is short and front-loaded with the core action. The second sentence adds conditional return behavior and a usage hint without significant waste, though it could be slightly tighter.

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 low-complexity list tool with no output schema, the description covers the core purpose, the include_standard effect, and a matching workflow. It lacks explicit routing against siblings like get_field or validate_fields, but annotations and the schema carry most remaining 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?

Schema description coverage is 100%, so the schema already documents all three optional parameters. The description echoes the include_standard behavior without adding syntax or format detail beyond what the 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 states a specific verb and resource: 'List the field definitions of a workspace.' This clearly distinguishes it from singular retrieval tools like get_field, but it does not explicitly name or contrast with any sibling 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 hints at a workflow ('Match definitions to template placement field_id and ask about ambiguous names'), but gives no explicit when-to-use, when-not-to-use, or alternative tool guidance. Usage is implied rather than prescribed.

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, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds only the ambiguity-handling caution and says nothing about pagination, filtering behavior, or workspace scoping beyond what the schema shows. Adequate but thin given the low bar set by 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 zero waste; the scope statement is front-loaded and the actionable guidance follows immediately. Nothing redundant with the title or annotations.

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 annotations covering the safety profile, the description supplies the key missing piece: why you'd call it (recipient-to-signer-ID resolution). Return values and pagination are not described, but there is no output schema to lean on, which is 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% with all four parameters (page, search, per_page, account_id) documented inline, so the schema carries the load. The description mentions 'workspace' loosely but adds no syntax, defaults, or filtering detail beyond the schema. 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 the signers of a workspace'), which distinguishes it from assinafy_get_signer (single signer) and the other list_* tools. It does not explicitly name a sibling to contrast against, but the scope is clear enough to select it correctly.

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 concrete when-to-use context ('resolve a recipient to a signer ID') and an operational caution ('ask the user about ambiguous matches before sending'). It stops short of naming get_signer as the alternative for a known ID, so it is 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 already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds that the response surfaces signer roles, pages, and field placements, which is useful output context, but it says nothing about pagination or result limits.

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 what the tool returns, and the second sentence sets a useful expectation about authoring. 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 partially fills the gap by enumerating returned fields. The main omission is any mention of pagination despite page and per_page parameters, which an agent would need when results are large.

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, search, per_page, and account_id are all documented in the schema. The description adds no parameter-level detail, which is the expected baseline when the schema does the work.

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 saved templates) and goes further by naming what the results contain: signer roles, pages, and field placements with field_id. This distinguishes it from get_template and the create_* siblings without naming them 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?

'Template authoring is done in Assinafy' implicitly tells the agent this tool is read-only and cannot create templates, but there is no explicit when-to-use guidance versus get_template or create_document_from_template, and no mention of pagination behavior.

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?

Goes well beyond the annotations: it describes the return shape (header/body/buttons as the signer sees it), discloses that sandbox/stage runs are simulated with no real delivery, and warns that returned signing links and verification codes are sensitive and must not be used to sign for someone else. That is meaningful behavioral context the readOnly/idempotent hints 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?

Four tight sentences with the core action front-loaded, and each subsequent sentence adds a distinct fact (response shape, sandbox behavior, sensitivity). Dense but no filler; it could be marginally tightened but nothing is wasted.

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

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

With no output schema, the description correctly compensates by explaining the rendered return structure and the sandbox caveat. It does not cover ordering or whether results are paginated/limited, a minor gap for a list tool, 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 description coverage is 100% for the two required IDs, so the schema already carries parameter meaning. The description only restates scope ('for an assignment') without adding format or constraint detail, so the baseline of 3 applies.

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

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

States a specific verb (List) and a narrowly scoped resource (WhatsApp notification messages sent for an assignment), which no sibling tool covers. An agent can tell this apart from resend_notification or list_document_activities without opening the schema.

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

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

Names an explicit use case -- troubleshooting WhatsApp delivery for a single assignment -- which tells the agent when this tool is the right call. It stops short of stating when-not to use it or pointing at resend_notification as the alternative for re-sending, so it does not reach 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds real context: it 'sends nothing by itself,' the user completes the send in apps-capable hosts, and other clients receive page sizes and field IDs as text. That host-dependent behavior is not derivable from 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?

Three sentences, front-loaded with the purpose, with no obvious filler. The middle sentence is slightly dense and the 'then send it with method collect' clause sits awkwardly against the later 'sends nothing by itself' clarification, costing some crispness.

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?

There is no output schema, and the description compensates by describing what non-apps hosts get back (page sizes and field IDs). Combined with the host-dependent behavior and the argument inheritance from create_assignment, an agent has enough to invoke it correctly, though the send/no-send flow could be stated more unambiguously.

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 already 80%, but the description adds a non-obvious mapping ('takes the assinafy_create_assignment arguments except method and entries'), telling the agent which argument set applies without opening the sibling schema. It does not explain individual parameters, but it adds meaning beyond the schema's per-field descriptions.

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?

It states a specific verb+resource ('place signature, initials, date and input fields') and the mechanism ('open a visual editor'), and it distinguishes itself from assinafy_create_assignment by noting it takes the same arguments minus method/entries. The only blur is whether the tool sends or merely stages, though the description resolves this in the next sentence.

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 situational context ('in apps-capable hosts... other clients get page sizes and field IDs') and ties itself to the create_assignment argument set, which implies its place in the workflow. However, it never states explicitly when to choose this over create_assignment or send_pdf_for_signature, so the routing decision is left to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the mutation profile is covered. The description adds real context the annotations cannot: the state-based lock after assignment/certification and the fact that the stored name is normalized (diacritics stripped, unsupported characters replaced with dashes). It stops short of saying what error or state the caller observes when the lock applies.

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, both dense with information, and the primary action is front-loaded ahead of the constraint and the normalization caveat. No filler or restatement of the 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 two-parameter mutation tool with no output schema, the description covers the action, the eligibility window, the lock condition, and the name transformation — enough to call it correctly. It omits failure behavior when the document is already locked and any permission requirements, which are the only remaining gaps.

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 50%: `document_id` is documented in the schema, while `name` has no schema description and the constraints (minLength 1, maxLength 255) live only in the schema. The description adds meaningful semantics for the name value — the normalization rules that transform whatever is submitted — which partially compensates, but it says nothing about the identifier format or uniqueness. Baseline 3 given the mixed 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 ('Update a document's name') with no ambiguity, and no sibling tool performs the same operation, so the agent can route to it unambiguously. The scope is narrowed immediately rather than leaving the reader to infer it.

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 eligibility window ('only allowed before any assignment is created ... while the document is in `uploaded` or `metadata_ready` status and has no signers yet') and an explicit when-not condition ('once the signature process has started or the document is certificated, the name is locked'). The agent knows exactly when to call and when to avoid it, with no alternative tool competing for the same job.

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 readOnly=false, idempotent=false, destructive=false, so safety profile is partly covered, but the description adds real value beyond them: reminder credits may be consumed, delivery is single-shot, and refreshing without progress should not re-trigger. It stops short of describing delivery failures or credit units, but the cost and non-idempotency reinforcement are meaningful context.

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 zero filler; the action and its scope are front-loaded before the precondition and the cost warning. Every clause carries operational weight.

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 non-idempotent, credit-consuming notification with no output schema, the description supplies the precondition, cost awareness, and anti-repeat rule an agent needs. It does not mention what a successful send returns or how to detect delivery failure, a modest 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 each of the four parameters is already documented by the schema; the description adds only the 'pending signer in active step' scoping for signer_id. It says nothing about estimate_only, but the schema covers it, 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+scope: 'Send one reminder to a pending signer in the assignment's active step.' The 'one reminder' and 'active step' qualifiers make it distinguishable from sibling send/notify tools like assinafy_send_pdf_for_signature. An agent can identify the action without opening the schema.

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

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

Gives an explicit precondition ('after confirming with assinafy_get_document that they have not signed'), naming the exact sibling to call first. It also provides a when-not rule: 'never repeat a reminder only because progress is unchanged,' which prevents a common misuse loop.

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, idempotentHint=true and destructiveHint=false, but the description adds the critical nuance that nothing is sent until the user confirms, and that the send path depends on the host (card Send button vs. text summary). That clarifies a deferred side effect the annotations alone would leave ambiguous.

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 front-loaded sentences: what it does, when to use it, then host-dependent behavior. No filler, though the host-rendering sentence is the longest and could be trimmed slightly without losing meaning.

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

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

With no output schema, the description does address the return path ('other clients get the summary as text'), which is the minimum needed. It stops short of describing what the summary contains or what validation failures look like, which is a minor gap for a 7-parameter preview 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 71% and the parameters are heavily documented in-schema (verification_method, notification_methods, display_settings all carry long descriptions). The description only says 'same arguments', adding no parameter-level meaning 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?

States a specific verb and resource ('Preview an assinafy_create_assignment call without sending anything') and explicitly names the sibling it mirrors, so an agent can distinguish it from assinafy_create_assignment immediately. The added clause 'checked against the document and signers' clarifies what the preview validates.

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 a clear selection condition ('Use it when the user wants to review before sending') and implicitly routes to the alternative — the real create_assignment — when review is not wanted. It does not spell out an explicit when-not clause, but the surrounding context makes the split unambiguous.

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 this as a non-read-only, non-idempotent, open-world write, so the bar is lower; the description still adds meaningful behavior: it consumes plan allowance, sends real invitations/notifications via Email verification, blocks on processing, and retains a document ID on partial failure. It stops short of describing what a successful response contains or any auth/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?

Three sentences, front-loaded with the primary action, then cost constraint, then failure-recovery guidance. Dense but every clause carries actionable information; no filler.

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

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

For a 9-parameter mutation with no output schema, the description covers the happy path, the cost/allowance implication, and the partial-failure recovery path. It could say more about what is returned or how signers are matched/reused (left to the schema), but 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 100%, so every parameter including estimate_only, poll_secs, and max_wait_secs is already documented in the schema; the description only echoes signer name/email and the Email verification mode. 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 names a specific multi-step verb chain (upload, wait, invite) on a specific resource (PDF) and identifies the signer identity fields, clearly distinguishing it from the bare assinafy_upload_document sibling.

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 real usage constraint ('use only recipients the user authorized') and explicitly routes the agent to assinafy_create_assignment after a partial failure rather than re-uploading. It does not, however, state when to prefer assinafy_upload_document or the template-based creation path.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context the annotations cannot convey: rendering varies by host (apps-capable hosts get a reminder button, other clients get plain text). It does not describe pagination or error behavior, but for a single-document read 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?

Three tight sentences: purpose first, host-dependent rendering second, prerequisite last. Nothing is repeated from the schema or annotations and no sentence is padding.

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, idempotent, single-parameter tool with no output schema, the description covers what is shown, how it renders per host, and how to obtain the ID — everything needed to call it correctly. The one omission is disambiguation from assinafy_get_document, which matters given the sibling set.

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 is one parameter with 100% schema description coverage, so the schema already documents document_id. The description adds only a light provenance hint ('one known document' resolved via assinafy_list_documents), not format or constraint details, so the baseline 3 for high-coverage schemas 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 names a specific verb and resource ('Show a status card for one known document') and enumerates exactly what the card contains: status, signers completed, signers pending, expiry. That is far more informative than a tautology. It loses a point because it never distinguishes itself from the near-identical sibling assinafy_get_document, which an agent would plausibly confuse with this 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?

It gives explicit workflow guidance: 'Resolve the document with assinafy_list_documents first,' which tells the agent how to obtain the required document_id. What it does not provide is any when-to-use/when-not guidance relative to assinafy_get_document or the other read siblings, so the routing decision is left partly 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 destructiveHint=true and openWorldHint=true already declared, the description adds substantial behavioral context: partial updates only change supplied terms, null clears values or unlinks a pending amendment, external_references replaces the whole list, changes can trigger lifecycle emails/webhooks, and Assinafy owns auto-renewal and owner reminders. It also explains conflict semantics and that the tool does not sign, send, or cancel the document itself.

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

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

The description is dense but front-loaded: purpose and action modes come first, then preconditions and read-first guidance, then mutation semantics and side effects. Every sentence carries useful information for a complex mutation tool, though the semicolon-heavy packing makes it slightly harder to scan than an ideal definition.

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 a complex, destructive, non-idempotent mutation tool with no output schema, the description covers the key operational context an agent needs: action modes, required preconditions, concurrency behavior, partial-update semantics, side effects, and safety boundaries. Return-value details are unnecessary because no output schema exists, and the remaining field specifics are handled by the rich input schema.

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 67% and the schema itself already documents parameters in depth, but the description adds cross-cutting semantics that are easy to miss: only supplied terms change, null clears values, external_references replaces the list, renew needs the current term and updated_at, and terminate needs updated_at. It does not repeat every field-level rule, but it meaningfully supplements the schema for the action-dependent 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 description starts with a specific verb and resource: managing an existing document's CLM record. It explicitly separates the three modes—set/patch terms or link an amendment, renew the next term, and terminate tracking—and states what the tool does not do (sign, send, cancel), which distinguishes it from sibling document-signing tools.

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 explicit preconditions (requires a tracking plan), read-before-write guidance (include terms.updated_at, current term, link updated_at), conflict behavior (fresh read and user review, never blind retries), and authorization guidance (use only for changes the user authorized). This goes well beyond generic usage guidance and tells the agent when and how to invoke each action safely.

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 and idempotentHint=false; the description supplies the real behavioral payload: which fields are immutable in which document states, the exact failure code and its content, and the side effect of rotating access/verification codes for unverified in-flight requests. That is exactly the kind of consequence disclosure an agent cannot get from the schema or annotations.

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

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

One-line purpose statement followed by a bold-labeled block that front-loads the constraint. Every sentence carries non-redundant information (blocking rule, certificated exception, rotation side effect, resend remedy) 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?

For a destructive mutation with no output schema, the description covers the failure mode, the side effects, and the per-field mutability model, which is most of what an agent needs. It omits any notion of partial-update semantics implied by the anyOf requirement and the role of account_id when omitted, minor gaps against otherwise strong coverage.

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 67%, and the description compensates by explaining per-field mutability rules: email/whatsapp_phone_number are blocked under specific conditions, full_name is always updatable, and channel changes ripple into code rotation. It adds no guidance on account_id or signer_id, but the schema covers those, so the gap is small.

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 ('Update a signer's information'), which cleanly separates it from get_signer, create_signer, and list_signers. It does not, however, explicitly name or contrast itself with any sibling, which is the only thing keeping it from 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?

Goes well beyond typical guidance by stating when an update will fail (verified channel on an in-flight document → 400) and when it succeeds (already-certificated documents do not block it), plus what to do instead when codes rotate ('use the resend endpoint to redeliver'). It routes the agent toward the resend capability without naming the exact sibling tool id, so a 4 rather than 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?

Annotations cover the safety profile (readOnly false, destructive false, non-idempotent), so the description adds context beyond them: no invitations are dispatched, the document ID is returned, and re-uploading a known document is discouraged. It doesn't mention size/auth prerequisites, but the schema covers the 25 MiB limit.

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 sentences, front-loaded with the core action and return value, followed by the usage rule and the anti-pattern warning. No filler.

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

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

For a 3-param upload tool with no output schema, the description supplies the return value (document ID) and the intended workflow, which is what an agent needs to chain into create_assignment. Minor gaps around failure behavior are tolerable given the annotations and schema.

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 file_name, account_id, and file_base64 are already fully documented in the schema. The description adds no syntax or format detail beyond it, 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 and resource (upload a PDF) plus a key scope qualifier (without sending invitations) and the return value (document ID). This clearly separates it from send_pdf_for_signature and create_assignment.

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 names the when ('prepare a document now and send it later with assinafy_create_assignment') and an anti-pattern ('never upload again when a document ID is already known'). Both the alternative tool and the exclusion condition are stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds real value beyond them: it discloses that no document is created, no signature request is sent, and that each returned result carries a per-item success indicator — implying partial validation outcomes rather than a single pass/fail.

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, purpose front-loaded, then input mechanics, then a follow-up instruction. The 'the server sends the documented JSON array' clause is slightly redundant/murky but not wasteful enough to hurt scanning.

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 partially compensates by telling the agent results carry success flags. It leaves minor gaps — behavior on unknown field_id, or what a failed validation means — but for a simple two-parameter read-only validator this is 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 description coverage is 100%, so both values and account_id are already documented, and the nested field_id/value pair descriptions are complete. The description's 'supply field/value pairs in values' largely restates the schema, adding only the note that it is sent as the JSON request array. 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?

States a specific verb and resource — validating one or more input values against existing field definitions — and immediately narrows scope with 'without creating a document or requesting signatures'. This clearly separates it from the sibling create/send tools like assinafy_create_document_from_template and assinafy_send_pdf_for_signature.

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

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

Establishes when to use it: as a pre-flight check before requesting signatures ('Check each result's success before requesting signatures'), and implicitly rules out use for document creation. It doesn't name a specific alternative sibling for the same job, so it stops short of the explicit when/when-not/alternative triad.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real value by disclosing that this is a public lookup requiring no workspace connection and transmitting no credential upstream — an auth-behavior detail not present in the structured fields.

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 no filler; the core action is front-loaded and the access constraint follows immediately. Every clause carries information an agent can act on.

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 auth-free nature and the input are covered, and annotations handle the safety profile. But no output schema exists, so the description carries the burden of explaining what verification returns (valid/invalid, signature details, error on unknown hash) and it does not — leaving a meaningful gap for an agent that must interpret the result.

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 is fully documented as the SHA-1 signature hash of the signed document. The description only reinforces this ("its actual Assinafy SHA-1 signature hash") without adding format, source, or validation 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?

The description states a specific verb (verify) and resource (signed document) plus the mechanism (its Assinafy SHA-1 signature hash), which clearly separates it from retrieval-oriented siblings like get_document and show_document. It does not explicitly contrast itself with a sibling, but no other tool in the set performs verification, so the purpose is unambiguous.

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

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

It gives a usage condition — a public lookup that requires no workspace connection and sends no credential — which tells the agent it can call this without auth setup. However, it never states when to prefer this over other document-inspection tools or what precondition (having the signature hash) selects it, so the guidance is implied rather than explicit.

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