Assinafy

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true), and the description adds non-obvious behavior beyond them: 'this sends signing invitations', 'can consume credits', and the automatic promotion from uploaded/metadata_processing to pending_signature. It does not describe the response payload, but with no output schema 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?

Front-loaded with the action and the two modes, then prerequisites, ordering, ID sourcing, and the credit/invitation warning. Dense but every clause carries operational information; slightly long, yet nothing reads as 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?

Given 8 parameters, no output schema and a mutation tool, the description covers the essentials an agent needs: mode selection, document-state preconditions, signer ordering rules, ID sourcing, invitation/credit side effects. It omits what the call returns, but with no output schema declared that omission is acceptable.

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

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

Schema coverage is 75% and the schema itself is very detailed (step only says minimum 1, verification_method and notification_methods carry long docs). The description compensates for the weakest field by explaining `step` semantics: parallel within a step, next step notified after the previous completes, and 'every signer must supply it and values must be contiguous starting at 1'. It also adds state requirements for `method`.

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

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

The opening sentence states a specific verb+resource ('Request signatures on a document') and immediately disambiguates the two modes ('virtual' vs 'collect') by what each one does. An agent can distinguish this from siblings like assinafy_place_fields or assinafy_send_pdf_for_signature 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?

Explicitly states when each method applies (virtual needs no input fields; collect places fields on specific pages), the required document state per method, and the precondition to 'Check with assinafy_get_document that no assignment exists first'. It also names where to obtain signer IDs (assinafy_list_signers / assinafy_create_signer) and page IDs (assinafy_get_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 cover the mutation profile (readOnly=false, idempotent=false, destructive=false, openWorld=true), but the description adds the non-obvious operational facts that this sends real invitations and can consume credits. It does not say what happens on partial failure — e.g. whether some invitations are sent if a later signer fails validation.

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

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

Three sentences with the core action front-loaded, followed by prerequisites and then the cost caveat. No filler, and each sentence carries a distinct piece of 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 9-parameter mutation tool with no output schema, the description covers the action, prerequisites, and credit implications, which is most of what an agent needs. It stops short of describing the result (document ID vs. invitation status) or failure behavior when a role has no matching signer.

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 the nested signer fields is already documented in the schema. The description restates the ID-or-name/email alternative and the one-signer-per-role rule but adds no syntax, ordering, or constraint detail beyond the schema, 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 combination — generate a document from a saved template and invite one signer per role — which separates it from assinafy_send_pdf_for_signature (arbitrary PDF) and assinafy_create_assignment. It never names those siblings outright, so an agent must infer the boundary from the 'saved template' phrasing.

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

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

Explicitly routes the agent to two prerequisite tools: assinafy_list_templates to discover roles and assinafy_validate_fields to check editor_fields values before calling. It gives clear context but offers no when-not guidance distinguishing it from assinafy_send_pdf_for_signature or assinafy_create_assignment.

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 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 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 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 this is a non-read-only, non-idempotent, closed-world mutation. The description adds value beyond that by disclosing a failure mode (provider may refuse already-expired requests) and the accepted timestamp format, which is genuine behavioral context an agent needs before calling.

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, front-loaded with the action and followed by the constraint. No filler, no 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 three-parameter mutation with no output schema, the description covers the action, the format, and one refusal condition. It omits prerequisites (must the request be pending?), whether the change notifies signers, and whether the new expiry must be in the future, leaving a few gaps an agent might need.

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 all three parameters are required and documented in the schema. The description only restates the RFC 3339 requirement for expires_at, adding nothing the schema does not already say, 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?

The description gives a specific verb+resource ('Change when an existing signature request expires') and names the required timestamp format. It is unambiguous as to what is being modified, though it does not differentiate from any sibling (none of which touch expiration) and uses 'signature request' where the name/params say '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?

Usage is implied: only apply this to an existing, not-yet-expired request. The caveat that 'Assinafy may refuse for requests that already expired' is a useful conditional, but there is no explicit when-to-use vs. when-not-to-use routing or mention of alternatives such as re-issuing the assignment.

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.