ZapSign

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

The description adds meaningful behavioral context beyond annotations by explaining that a config-header approach is permanent and non-expiring, while pasting a token is session-only, and no args returns a link. It does not contradict the annotations (idempotentHint=true, destructiveHint=false).

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 somewhat dense and includes setup guidance, but every sentence contributes useful operational information. It is front-loaded with the core purpose and then branches into config vs session modes, making it reasonably efficient for the guidance it provides.

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 authentication tool with no output schema, the description covers the main expected behaviors: login link retrieval, session token submission, and permanent config setup. It could be more complete by describing the response format and handling of invalid tokens, but it is adequate for typical agent use.

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

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

With 0% schema description coverage and only a 'token' string property, the description compensates well by explaining the token is a JWT to paste, that passing it authenticates for the session, and that omitting it returns the login link. It adds practical meaning to the parameter beyond the raw schema.

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

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

The description clearly explains that this tool authenticates to MCP.AI by either returning a login link (no args) or accepting a pasted JWT token. It is specific about the resource and action, but it does not explicitly distinguish this from sibling tools like 'connect' or 'marketplace'.

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

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

The description gives strong usage guidance: permanent config via Authorization header is recommended, session-only login uses the token argument, and no args returns the login link. It explains when to use each invocation mode but does not mention alternatives or explicitly state when not to use the tool.

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?

Beyond the read-only and idempotent annotations, the description discloses specific behavioral details, such as returning authenticated:true with empty pending[] or providing connect_url when credentials are missing, enhancing transparency.

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

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

The description is concise, consisting of two clear sentences with no redundant or extraneous information, and is well-structured.

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

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

The description adequately explains the main output scenarios (all connected vs. missing credentials), which is sufficient for a simple tool with no parameters or output schema, though it does not cover partial connection states.

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

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

The tool has no parameters, so schema coverage is 100%. The description adds no parameter-specific details, which is appropriate given the absence of parameters, so a baseline score of 3 is warranted.

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

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

The description clearly states that the tool returns connection status and URLs, and differentiates itself from sibling tools like authenticate or toolkit_info by focusing on connection status.

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

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

The description gives context on when certain outputs occur (all providers connected vs. missing credentials), but does not explicitly state when to use this tool over alternatives or provide 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?

The description goes well beyond the annotations (readOnlyHint:false, destructiveHint:false) by revealing key runtime behaviors: invoke runs the MCP one-off without installing or bloating the tool list, returns a connect link if credentials are needed, returns a checkout/top-up link if the wallet is empty and the user must complete the flow before retry, and writes require workspace owner/admin. These details add substantial context not captured in 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?

The description is dense but well-organized, front-loading the primary purpose and then using clear separations for flow, key caveats, installation guidance, and feature areas. Every sentence contributes meaningful behavioral or usage detail, though the length (roughly 4-5 sentences of substantial prose) is high; given the tool's complexity, this is justified.

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

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

Given the high complexity (23 params, 14 actions, no output schema), the description covers a great deal: the end-to-end discovery-to-invocation flow, the invoke-vs-install tradeoff, auth/payment edge cases, installed flag distinctions, write-permission requirements, and the separate prompt library. It does not detail all parameters or exact return shapes, but it provides enough behavioral context for an agent to pick the right action and understand the main side effects.

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

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

With schema description coverage at 0% and 23 parameters, the description must compensate; it names 'tool_id' and enumerates the possible 'action' values (search, describe, install, invoke, etc.), which helps, but it does not explain other parameters like limit, query, arguments, prompt_vars, conversation, or immediate. The description covers the conceptual flow but leaves most parameter-level semantics undocumented.

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 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them,' clearly stating both the resource (marketplace) and its actions (search, describe, invoke, install). It differentiates itself from the sibling tools, which are all zapsign or authentication related, as the sole marketplace/catalog 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 provides explicit guidance on when to use which action: the core flow 'action=search discovers MCPs by intent → describe returns one MCP's full profile... → invoke RUNS that tool,' and clarifies 'Use install only to make an MCP PERMANENT... prefer invoke for a single/occasional use.' It also names alternatives like list_tools for currently callable tools and search_prompts for prompt text, giving clear decision criteria.

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

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

The description mentions including the conversation array for reproduction, which gives some insight into expected input behavior. However, it does not disclose what happens after reporting (e.g., ticket creation), and no annotations provide explicit safety or side-effect details beyond the idempotent hint.

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

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

The description is concise, consisting of two short sentences that convey the essential purpose and key parameter guidance without redundancy.

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

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

The description is adequate for a simple feedback tool, covering the main action and one important parameter. However, it lacks details about expected return values or error scenarios, though the output schema is absent so this is not mandatory.

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

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

The description clarifies the 'conversation' parameter (recent messages for reproduction) but does not explain 'message' or 'context'. Given the schema has no parameter descriptions, the coverage is partial, but the purpose makes these reasonably inferable.

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

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

The description clearly states the tool's purpose: reporting bugs, missing features, or sending feedback. It is distinct from sibling tools which focus on CRUD operations for documents, accounts, and webhooks.

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 implies when to use this tool (when there is a bug or feedback to report) and there are no alternative tools for this purpose. It lacks explicit exclusions but the intent is clear.

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 read-only and idempotent behavior, and the description's 'Show' is consistent. The description adds value by specifying exactly what is displayed (platform and adapter versions), providing context beyond the annotations.

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

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

The description is a single, front-loaded sentence that conveys the purpose efficiently without any unnecessary words or details. It earns its place with zero fluff.

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

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

For a zero-parameter tool with no output schema, the description is fully sufficient. It clearly states what information is shown, which covers the expected behavior. There are no missing prerequisites, side effects, or return format requirements for such a simple read-only tool.

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

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

The tool has zero parameters, so there is no schema coverage issue. The description does not need to explain parameters, and with 0 params, the baseline is 4. No additional parameter semantics are required.

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

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

The description clearly states the tool shows current MCP platform and adapter versions, using a specific verb ('show') and a precise object (platform and adapter versions). This distinguishes it from sibling tools like 'toolkit_info' or 'connect', which serve different purposes.

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 explicit usage guidance is provided, such as when to use this tool versus alternatives. The zero-parameter nature makes the use case obvious, but the description relies on implication rather than stating exclusions or alternatives.

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, covering safety. The description adds value by enumerating the specific returned data (installed MCPs, connection status, accounts, catalog tool counts), which helps the agent understand the output scope beyond the basic read-only nature.

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

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

The description is a single, front-loaded sentence with no extraneous words. It clearly states the action and enumerates the return components, maintaining high information density without fluff.

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 tool with no parameters and no output schema, the description fully covers the returned content (installed MCPs, connection status, accounts, tool counts). It is complete for the agent to know what to expect and how to use 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?

The tool has zero parameters, so the description does not need to explain them. The schema coverage is 100% (vacuous). The description adds the context of what state is returned, which is sufficient given no inputs.

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

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

The description clearly states the tool returns the current toolkit state, specifying the exact components: installed MCPs, connection status, connected accounts, and catalog tool counts. This is a specific verb+resource and differentiates it from siblings like show_version or connect.

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 implies usage for inspecting toolkit state but does not explicitly state when to use it versus alternatives or provide exclusions. The purpose is clear, but there is no guidance on when not to use it or mention of related 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=true, idempotentHint=true, and destructiveHint=false. The description adds useful context that the account read includes plan credits, status, and period, and mentions 25/page for the users action. It does not contradict annotations, but it adds only modest behavioral detail beyond them.

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

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

The description is compact and front-loaded with 'Conta ZapSign (leitura)', which is good. However, it includes the 'users' action even though the tool is flattened to 'plan', adding unnecessary noise and potential confusion.

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 no output schema and 0% parameter coverage, the description should fully explain the tool's behavior and inputs. It mentions plan fields but leaves the 'page' and 'account' parameters unexplained and does not describe what the output looks like or error/edge-case behavior.

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

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

Schema description coverage is 0% and the description provides no explanation of the 'page' or 'account' parameters. Neither the description nor the schema clarifies what these parameters mean in the context of the plan action, so the agent cannot properly determine how to fill them.

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 read action for the account plan: 'plan (info do plano: créditos, status, período)'. This clearly identifies the resource and the kind of data returned. However, it muddles the purpose by also listing a 'users' action followed by '[Flattened action: plan]', which creates ambiguity about whether the tool also lists users.

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

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

No guidance is given about when to use this tool versus the sibling zapsign_account_users or other account tools. The description implies it is for reading account plan information but does not state exclusions or name alternatives, leaving usage context weak.

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

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

The description aligns with annotations (read-only, idempotent) by saying 'leitura' (reading). It adds the pagination detail of 25 per page, but does not disclose any additional behavioral aspects like rate limits or response structure. Given the annotations already cover safety, this is adequate but not enhanced.

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

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

The description is compact but structurally confusing because it mixes two potential sub-actions. The inclusion of 'plan' may be irrelevant or redundant given the tool name, making it less focused than it could be. It is not overly verbose but lacks clarity.

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

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

The description provides some context about returning users per page, but it does not specify the output format or fully clarify that it returns a list of users only. The ambiguity about 'plan' and the lack of a clear output specification reduce completeness. Without an output schema, more explanatory detail is needed.

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

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

The description only indirectly references the 'page' parameter (via '25/página') and vaguely mentions 'account' as 'conta', but does not explain what the account parameter is or how it should be used. The schema lacks descriptions, so the coverage is below 50%, requiring more explicit parameter information.

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 the tool reads a ZapSign account, but it lists two actions (plan and users) while the tool name is 'users', causing ambiguity about the actual purpose. The core function (listing users) is mentioned, but the inclusion of 'plan' muddies the intent.

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

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

The description does not provide guidance on when to use this tool versus related tools such as zapsign_account_plan or user creation tools. It lacks any mention of alternative tools or specific use cases, leaving the agent uncertain about selection.

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 state readOnlyHint=false and destructiveHint=false, so the write nature is known. The description adds no additional behavioral context such as authentication requirements, potential failures (e.g., duplicate email), or side effects. The only extra info is about deletion (donos cannot be removed), which is irrelevant to the create action.

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 relatively concise and uses bullet points for structure. It is front-loaded with the overall purpose and then details actions. However, including both create_user and delete_user adds unnecessary length for a tool that is specifically for create_user, making it slightly less efficient than it could be.

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 3 parameters, 0 required, a nested data object, and no output schema, the description leaves significant gaps. It does not clarify the structure and purpose of the 'data' and 'account' parameters, nor does it describe return values or error scenarios. For a write operation, this is insufficient for an agent to use correctly without additional assumptions.

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

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

Schema description coverage is 0%, so the description must compensate. It does list the key fields for create_user (email required, optional role with enum values, and other optional fields), providing meaning beyond the schema. However, it fails to explain the top-level 'data', 'email', and 'account' properties, and the relationship between them is unclear.

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

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

The description clearly states the tool manages ZapSign users and lists create_user as the primary action (with flattened action noted). The verb+resource is specific ('adiciona usuário'), but the inclusion of delete_user in the same description introduces ambiguity and detracts from a focused purpose.

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 explicit guidance is provided on when to use this tool versus alternatives. The description mentions delete_user but does not clearly direct the agent to use a separate sibling tool for deletion. It lacks any context on prerequisites or scenarios, leaving the agent to infer usage from the action list.

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

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

The description states 'remove usuário' (delete user), which is a destructive operation. However, annotations declare destructiveHint: false, directly contradicting the description's implied behavior. Additionally, no information is given about permissions, reversibility, or side effects beyond the owner restriction.

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 not concise; it includes an entire create_user specification that is irrelevant to the actual operation. It is not front-loaded with the delete action, and the 'flattened action' note appears at the end. The structure does not efficiently communicate the intended usage.

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 deletion tool with minimal parameters, the description should explain the delete operation more fully. It mentions only the owner restriction but omits details like account parameter usage, potential errors, or expected outcomes. The inclusion of create_user adds noise without clarifying the actual delete workflow. No output schema is provided, but that alone does not excuse missing essential context.

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

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

The schema includes 'email', 'data', and 'account' parameters, but the description only explains email for delete_user (used as identifier). The 'data' parameter is explained only for create_user, which is not the flattened action. 'account' is completely undocumented. With 0% schema coverage, the description fails to clarify which parameters are needed for the delete operation.

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

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

The description lists two actions (create_user, delete_user) while the tool name and '[Flattened action: delete_user]' indicate it is specifically for deleting a user. This ambiguity prevents clear identification of the tool's core purpose, making it difficult for an agent 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?

No guidance is provided on when to use this tool versus the sibling zapsign_account_write_create_user. In fact, the description includes the create_user action, which is misleading since a separate tool exists for that. There is no mention of when deletion is appropriate or any exclusions beyond owners cannot be removed.

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. The description adds that it returns a status (with possible values) and a PDF report, and that it supports batched execution via check_ids. This provides behavioral context beyond the annotations without contradicting them.

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

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

The description is concise and well-structured: an opening sentence with purpose, a brief action/response summary, and a separate mention of bulk support. The '[Flattened action: get]' line is somewhat redundant after 'Ação: get', but the overall text remains tight and scannable.

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 tool with 3 parameters, no output schema, and comprehensive annotations, the description covers the core purpose, return values, and bulk capability. However, it omits the meaning of the 'account' parameter, error behavior, and the exact format of the PDF report, leaving minor gaps in completeness.

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 0%, so the description must compensate. It explains check_id as the identifier and check_ids for bulk execution, but the optional 'account' parameter is not explained at all. It also doesn't clarify the relationship between check_id and check_ids or any format constraints, leaving parameter semantics partially incomplete.

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

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

The description clearly states it is a background check verification in ZapSign (leitura) and specifies the action 'get', with explicit return values (status with enumerated values + pdf_report). The resource 'checks' distinguishes it from sibling tools for documents, templates, and signers.

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

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

The phrase 'leitura' (read) and action 'get' clearly indicate this is for read-only retrieval of check statuses. It doesn't explicitly name alternatives, but the resource specificity and read-only nature provide clear context. Bulk support via check_ids is mentioned, though there is no explicit guidance on when to use batch vs single.

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 signal a non-read-only operation (readOnlyHint=false), and the description adds valuable behavioral context: it consumes credits and requires user_authorized=true. It does not discuss side effects or auth prerequisites, but the added cost and authorization detail go beyond what the annotations provide.

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

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

The description is short and front-loaded with the main purpose. It contains redundancy with 'Ação: create' and '[Flattened action: create]' repeating the action, but overall the text is compact and scannable.

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

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

The description covers the essential fields and enums, but the nested 'data' structure may have additional fields not documented, and there is no mention of the response format, error behavior, or the 'account' parameter. With no output schema and sparse annotations, some important context remains missing.

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

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

The input schema has 0% description coverage for the 'data' and 'account' parameters. The description compensates by listing the key fields inside 'data' (country* with allowed values, type* with examples, user_authorized, and identifier options), which is essential guidance for a nested object with no schema 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?

The description clearly states it creates ('Criar') a background check ('verificação de antecedentes') in ZapSign, naming both the action and resource. It distinguishes itself from read-only siblings like zapsign_checks_get by explicitly indicating a write operation.

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

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

The description specifies context by noting that the operation consumes credits ('consome créditos'), which is a meaningful usage caution. It lacks explicit alternatives or when-not-to-use guidance, but the purpose and cost side-effect make the expected usage clear.

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 clear. The description adds valuable context: file URLs expire in 60 minutes, signer_log provides an audit trail, and download_pdf returns the PDF log. This goes beyond annotations and helps the agent understand side effects and limitations.

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

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

The description is compact and front-loaded with the main purpose. It uses a structured list of actions and filters, which is efficient. The 'Flattened action: get' note is a bit cryptic but adds clarity about the active action. No wasted words, though the formatting could be slightly cleaner.

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

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

Given the tool's complexity (12 parameters, 3 actions) and no output schema, the description does a good job covering the main behaviors: listing with filters, getting details with expiring URLs, and signer log with PDF download. It doesn't explain return values in detail, but that's acceptable without an output schema. The description is complete enough for an agent to use the tool effectively, though it could mention the 'account' parameter and clarify the flattened action concept.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain many parameters (page, status, folder_path, deleted, signer_email, created_from/to, sort_order, include_signers, doc_token, download_pdf) but not all (account is missing). The description adds meaning to most parameters, but the 'account' parameter is undocumented, and the description doesn't clarify value formats (e.g., date format for created_from/to is mentioned as YYYY-MM-DD, which is good). Overall, it covers most but not all 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 clearly states this is for reading ZapSign signature documents and lists three actions: list, get, and signer_log. It distinguishes from siblings by naming specific actions and filters, though it doesn't explicitly contrast with zapsign_documents_list or zapsign_documents_signer_log, which are separate sibling 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?

The description provides explicit filter options and action parameters, giving clear context on how to use the tool. It doesn't explicitly state when not to use it or name alternative tools, but the action list and filters imply usage scenarios. The flattened action note clarifies that 'get' is the active action, which helps.

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

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

The description adds useful context beyond the readOnlyHint/idempotentHint/destructiveHint annotations: it lists allowed status values, date format requirements (YYYY-MM-DD), sort directions, and the 60-minute expiration behavior for file URLs in the 'get' action. It does not describe pagination behavior or return conventions for a full list, but the provided additions are meaningful and consistent with 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?

The text is dense and mostly compact, but it mixes three actions into a single tool that is explicitly meant to be the 'list' action. The '[Flattened action: list]' tag appears almost as an afterthought, and the list of filters is a single string rather than a clean structured description. This is not minimal enough for a focused tool description.

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

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

For a 12-parameter list operation with no output schema, the description is incomplete. It does not explain pagination defaults, what fields are returned, whether 'deleted' means include or only deleted, or how 'account' affects the search. Some context is provided via annotations and sibling tool names, but the description itself leaves important gaps for this broad 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?

With 0% schema description coverage, the description is responsible for explaining parameters. It covers several: page, status, folder_path, deleted, signer_email, created_from/created_to, sort_order, and include_signers. However, it leaves some parameters unexplained in context (account, doc_token, download_pdf), and these parameters seem borrowed from the get/signer_log actions rather than clearly for list. That ambiguity prevents a higher score.

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

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

The description clearly identifies 'Documents in ZapSign (read-only)' and names 'list' as the primary action, with parameters for filtering. However, it also documents 'get' and 'signer_log' actions before the '[Flattened action: list]' note, which creates some ambiguity about the actual scope of this tool. It is still stronger than a vague or tautological description, so it earns a 4.

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 implies a clear context: use the list action with filters to search/enumerate documents, while 'get' is for document details and file URLs, and 'signer_log' is for audit trails. This gives an agent separating guidance without an explicit 'when not to use' statement. The read-only annotation and mention of 'Leitura' also support the safe usage context.

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

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

The description clearly indicates read-only behavior ('leitura') and mentions important details like file URLs expiring in 60 minutes and the optional PDF download for signer logs. It also aligns with the readOnlyHint and idempotentHint annotations, though it does not mention rate limits or auth requirements.

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

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

The description is concise, structured into actions with relevant parameters, and avoids excessive verbiage. It is easy to scan and understand the high-level functionality, though the redundancy of mentioning URL expiration for both get and signer_log is minor.

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

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

The description fails to contextualize its role relative to the many sibling tools. It does not mention that zapsign_documents_list and zapsign_documents_get exist, nor does it explain why this tool also offers list and get actions. This omission can confuse an agent about the intended scope and appropriate usage.

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

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

The description lists parameter names and some enum values (e.g., status pending|signed|refused), but it does not explain the meaning or purpose of most parameters like 'account', 'deleted', 'folder_path', or 'include_signers'. Since the schema has no parameter descriptions, the description carries the burden but fails to provide sufficient detail.

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 the tool is for reading signing documents and explicitly lists three read actions (list, get, signer_log) with their key parameters. However, the tool name focuses on 'signer_log', which creates some ambiguity about whether this is a combined tool or specific to signer log, and the description does not clarify this naming discrepancy.

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 lists actions and filters but does not explain when to use this tool versus the separate sibling tools like zapsign_documents_list and zapsign_documents_get. No guidance is given on choosing between them, making it unclear for an agent when this tool should be preferred.

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 (readOnlyHint=false, destructiveHint=false) already indicate a write operation. The description adds only the basic behavior 'anexa PDF extra' but does not disclose side effects, auth requirements, error states, or document modification details. Minimal added value beyond annotations.

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

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

The description is a long block listing seven actions, while the actual tool is only for add_extra_doc. The extraneous content bloats the text and detracts from the intended function. A focused description of the add_extra_doc action would be far more concise and effective.

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?

Despite verbosity, the description provides enough parameter details for the primary action (name, url/base64) and confirms it's a write operation. However, it lacks context about the document state, required conditions, and the 'account' parameter's role. The tool is simple, so completeness is moderate but not poor.

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 0%, so the description must explain parameters. It does specify 'doc_token, data' and that data must contain 'name*' and one of 'url_pdf | base64_pdf'. However, it omits the 'account' parameter entirely and leaves the data object schema loosely defined. Partial coverage, not comprehensive.

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

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

The description clearly states the core action: 'add_extra_doc (doc_token, data): anexa PDF extra' with required fields. It distinguishes this from sibling operations (create, update, delete) via the flattened action label. However, including a list of all other actions creates confusion, so it doesn't earn 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?

No explicit guidance on when to use this tool versus alternatives. The description mentions other actions but doesn't state conditions like 'use when you need to attach an extra PDF to an existing document' or reference prerequisites (e.g., document in progress). Usage is only implied by the tool's name and the flattened action note.

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 indicate a non-read-only, non-destructive write, and the description adds useful constraints: update requires a document 'em andamento', delete is a soft-delete, and create requires exactly one file source among five types. However, it does not explain side effects such as default signer emails, return format, or permission requirements; it also includes behaviors that are not this tool's actual flattened action. There is no direct contradiction with annotations.

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

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

The description is a large multi-action reference with seven bullets, most of which are irrelevant to the flattened create tool and duplicate sibling tool names. While the bullet structure is readable, it includes substantial extraneous content and buries the disambiguating '[Flattened action: create]' at the end.

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 complex create operation with nested objects and no output schema, the description gives a fairly complete field specification for `data` and notes conditions like soft-delete and update state. It is incomplete regarding `account`, the return value, and the fact that the other listed actions are not available through this 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 0%, so the description compensates strongly for the main `data` parameter by naming required fields (name, signers[]), nested signer attributes, the mutually exclusive one-file-source set, and optional fields. However, `account` is not described, and `doc_token` is only explained implicitly for non-create actions, leaving some schema parameters without semantic grounding.

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 'Criar/alterar documentos de assinatura' and enumerates seven write actions (create, create_from_template, update, delete, refuse, place_signatures, add_extra_doc), making the tool's actual scope ambiguous. The final '[Flattened action: create]' hint disambiguates to create, and the create action is described with required fields, but the broad action list undermines separation from sibling tools such as zapsign_documents_write_create_from_template and zapsign_documents_write_update.

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 explicit when-to-use or alternative guidance is provided. The description lists create_from_template, update, delete, and other operations as if they might be available here, but it never clarifies that this flattened tool only executes create and that sibling tools should be used for the other actions. The only conditional note is for update ('só com doc em andamento'), which does not help tool selection.

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 indicate readOnlyHint=false, and the description says it creates/alters documents, which is consistent but adds little beyond that. It does not disclose side effects, idempotency, destructive behavior, or any operational constraints. For a write action, it fails to mention prerequisites or consequences of using this 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?

The description is verbose and includes a long list of actions and field definitions for multiple modes, most of which are irrelevant to the flattened action. It is not front-loaded; the key 'create_from_template' detail is buried among others. The trailing note attempts to clarify but does not mitigate the overall bloat.

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?

Provides a complete list of parameters for create_from_template, but does not explain return values (no output schema) or any behavioral caveats (e.g., what happens on failure, whether the document is immediately active). It also does not clarify that other actions are not available in this tool, leaving potential for misuse. Adequate but not thorough.

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

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

The input schema is extremely generic (data object with additionalProperties), so the description carries the burden. It clearly specifies required fields for create_from_template (template_id, signer_name, data[]) and optional ones (signer_email, etc.), and explains the data array structure. This adds significant meaning beyond the schema.

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

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

The description states it creates/alters documents, and specifically lists 'create_from_template' with its fields, but also lists many other actions (create, update, delete, refuse, etc.) that are not the flattened action. This adds ambiguity about what this specific tool does, though the final note '[Flattened action: create_from_template]' clarifies the intent. It is not a tautology but lacks focus.

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 explicit guidance on when to use this tool versus siblings like zapsign_documents_write_create. The description lists other actions (e.g., 'create') which are handled by separate tools, potentially misleading an agent into thinking they are available here. There is no mention of alternatives or exclusions.

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

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

The description explicitly states 'soft-delete' for the delete action, which adds behavioral context beyond the annotations (which do not indicate destructiveness). However, the rest of the description provides unrelated behavioral details, and no other traits (auth, side effects) are disclosed for delete.

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 excessively long, listing seven distinct actions for a tool that is only supposed to handle delete. The delete-specific information is buried in a large block of irrelevant text, making it inefficient and poorly structured.

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

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

For a delete operation, the description only says 'soft-delete' and names the doc_token parameter. It lacks details on required fields, how to structure the request, expected outcomes, or error conditions. The tool is not fully described for practical use.

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

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

The description clarifies that delete uses doc_token, but it does not explain the purpose of 'data' and 'account' parameters. With 0% schema coverage, the description should compensate, but it leaves these unexplained, making parameter usage incomplete.

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 begins with a broad statement about creating/altering documents and lists many actions, but only the line 'delete (doc_token): soft-delete.' relates to the tool's actual purpose. The inclusion of unrelated actions (create, update, refuse, etc.) makes the purpose confusing and not focused on delete.

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 guidance on when to use this tool versus siblings like zapsign_documents_write_create or zapsign_documents_write_update. The description simply lists actions without contrasting them or explaining contexts, leaving the agent without direction.

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 do not include safety hints (readOnlyHint=false, destructiveHint=false). The description only mentions 'soft-delete' for one action but does not disclose side effects for the place_signatures action, such as whether it modifies the document irreversibly or requires specific conditions.

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 overly verbose for a tool named 'place_signatures', containing a large block of text that covers seven different actions. This is not concise and does not have a clear structure focused on the tool's actual purpose.

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

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

The description fails to clarify that this tool is for placing signatures only, and it does not explain return values (no output schema). The presence of multiple actions makes it incomplete for the intended use case, leaving the agent uncertain about what to expect.

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

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

The input schema is generic (data, account, doc_token) with no field descriptions. The description provides some explanation for the data field in the place_signatures action (rubricas[] with coordinates), but it also lists parameters for other actions, creating confusion about which fields apply to this tool. The coverage is partial and not exclusive.

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 lists multiple document actions (create, update, delete, refuse, place_signatures, etc.) without indicating that this tool is specifically for placing signatures. The tool name suggests a focused purpose, but the description is ambiguous, making it unclear what the tool actually does.

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

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

No guidance is provided on when to use this tool versus the sibling tools (e.g., zapsign_documents_write_create, zapsign_documents_write_update). The description does not differentiate use cases or mention any alternatives.

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 indicate a write operation (readOnlyHint=false) but say destructiveHint=false. The description's 'refuse (data): cancela/recusa' implies a state change, yet does not disclose side effects like signer notifications (notify_signer field) or reversibility, nor does it clarify that the refuse action is non-destructive per annotations.

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

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

The description is a long, dense block listing all write actions with detailed fields, burying the actual intended action (refuse) at the very end. This is a wall of text with no prioritization or structure, making it hard to quickly locate the relevant 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?

While the refuse action is mentioned, the description lacks important context: no stated purpose for refusing, no mention of when refusal is appropriate, no side effects or return values (no output schema), and no distinction from similar write tools. It is incomplete for an agent to correctly use this 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 0%, so the description must compensate. It does provide fields for refuse (doc_token, rejected_reason, notify_signer), but it mixes them with other actions' parameters, and the top-level 'doc_token' is duplicated. No explanation is given for 'account' or the structure of 'data' for refuse specifically.

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 lists many actions (create, update, delete, refuse, etc.) without clearly indicating this tool is only for the 'refuse' action. Although it ends with '[Flattened action: refuse]', it is buried among many irrelevant actions, making the purpose ambiguous and potentially misleading for an agent.

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

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

The description provides no explicit guidance on when to use this tool versus its siblings (e.g., zapsign_documents_write_create, zapsign_documents_write_delete). It does not mention that this tool is only for refusing documents and that other actions have their own 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 declare readOnlyHint=true and destructiveHint=false, and the description adds that it returns id and nickname. It does not mention any other behavioral aspects like pagination or limitations, but given the safe-read annotations, the description provides minimal extra context. No contradiction.

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

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

The description is a single short sentence that conveys the essential purpose and output, with no redundant words. It is appropriately concise for the simple functionality.

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?

While the tool is simple Basket (list accounts, no output schema), the description is very minimal and doesn't cover the parameter role or any extra context like return details beyond id and apelido. It could be more helpful for an agent deciding if this tool is appropriate.

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

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

The schema has one optional parameter 'account' with no description, and the schema coverage is 0%. The description does not explain the parameter's purpose or format, leaving the model without useful guidance for filling it.

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

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

The description clearly states the tool lists ZapSign accounts linked to this install, specifying that it returns id and nickname. It distinguishes itself from other account-related tools like zapsign_account_plan and zapsign_account_users by focusing on the account list itself.

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 implies it is used to view linked accounts, but does not explicitly state when to use it over alternatives or when not to use it. It does not mention any filtering or selection criteria beyond the optional 'account' parameter.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that the tool returns status, sign_url, views, geo, and auth_mode, but it does not mention response format, auth requirements, or any operational caveats. The '[Flattened action: get]' note is redundant rather than informative.

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 text is very short but contains repetition: 'Ação: get' and '[Flattened action: get]' say the same thing. It is still front-loaded with the essential read nature of the tool, but the duplicated metadata weakens the structure.

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 tool with one required parameter and clear read-only annotations, the description is minimally adequate. However, there is no output schema and the optional 'account' parameter is not described, so the description does not make the invocation completely self-contained.

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

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

The schema has 0% description coverage and two parameters: signer_token and account. The description mentions signer_token as the core keyword/identifier, but does not actually explain what it is or how it is formatted. The optional 'account' parameter is completely omitted, so the description does not compensate for missing schema explanations.

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

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

The description clearly states this is a read operation for ZapSign signers, with the action 'get' and the resource being signers. It also enumerates the kind of data returned (status, sign_url, views, geo, auth_mode), which distinguishes it from the zapsign_signers_write_* sibling 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?

The phrase 'leitura' makes it clear that this is a read-only invocation, but there is no explicit guidance about when to use it versus other ZapSign read/get tools or any exclusions. The intended usage is implied rather than fully spelled out.

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 signal readOnlyHint=false and destructiveHint=false, and the description adds useful field-level behavior such as required name/email and optional auth_mode/send_automatic_email. It does not disclose side effects like whether adding a signer triggers an invitation or whether duplicate adds are possible, but it does not contradict 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?

The description is overlong for a single flattened add tool because it documents update, remove, and sign operations that belong to sibling tools. Only the add bullet is relevant, and the clarifying '[Flattened action: add]' note appears at the end rather than front-loaded.

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

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

There is no output schema and the description does not explain return values, errors, or prerequisites for adding a signer. It also fails to clarify why signer_token is present in the input schema for an add-only action, making the tool incomplete for reliable 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 0%, but the description compensates by enumerating the data fields: name*, email*, and optional phone_country, phone_number, auth_mode, lock_name/email/phone, qualification, and send_automatic_* flags, including auth_mode enum values. However, account and signer_token remain unexplained in the add-only context.

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

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

The description opens with the vague phrase 'Gerenciar signatários no ZapSign' and lists add, update, remove, and sign actions, so it does not crisply isolate this tool's add-only purpose. However, the line 'add (doc_token, data): adiciona signatário' and the trailing '[Flattened action: add]' do make the core operation identifiable.

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 action list implies when each operation is appropriate, e.g., 'atualiza (só antes de assinar)' and 'remove (não pode remover quem já assinou)', but it never explicitly says this tool is only for adding signers or points to sibling tools as the alternatives for update/remove/sign. Guidance is present but 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.

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

Annotation contradiction: the annotations set destructiveHint to false, but the tool name and description describe a removal action, which is inherently destructive to the signer relationship. The description adds constraints but does not resolve the contradiction.

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

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

The description is compact in formatting but includes full action docs for add, update, and sign, which are sibling-tool concerns. The actual remove behavior is buried near the end and the '[Flattened action: remove]' line carries the disambiguation burden.

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 important precondition is present, but the description omits return behavior, error conditions, and meaning of several schema properties. Without an output schema and with all annotations false, the agent cannot fully predict the consequences of calling this 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 0%, and the description only explains signer_token for the remove action. The other schema parameters (data, account, doc_token) are not explained for this flattened remove tool, so the agent receives incomplete parameter guidance.

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 lists a remove action as 'remove (signer_token)' and the '[Flattened action: remove]' indicator makes the current tool's purpose clear. However, the description is wrapped as a generic signer-manager helper and includes add/update/sign actions, so the actual purpose is not front-loaded.

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 useful constraints: you cannot remove a signer who has already signed and cannot remove the only signer, and it notes that update is only allowed before signing. This provides enough context to reason about when removal is appropriate versus other signer operations.

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

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

The description mentions 'assina em lote via API (assíncrono)' indicating asynchronous batch signing, but does not disclose other side effects like notifications, document status changes, or failure conditions. Annotations do not add read-only/destructive hints, so more transparency would be expected.

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

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

The description is a monolithic block listing all signer actions, including unrelated ones (add, update, remove). It is verbose and unfocused, repeating information that belongs to sibling tools, which hampers quick comprehension of the specific sign operation.

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

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

The description gives some details about the sign action's data fields but does not clarify which top-level parameters are required or how they relate to the operation. It also lacks return value information (no output schema), leaving the overall context incomplete for a complex write operation.

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

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

The 'data' parameter is partially explained for the sign action, specifying fields like signer_tokens and optional selfie_photo. However, the other top-level parameters (account, doc_token, signer_token) are not described at all, and the schema provides no descriptions for any parameters, leaving most of the interface unclear.

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 broadly states 'manage signers in ZapSign' and lists multiple actions (add, update, remove, sign), but does not clearly identify that this specific tool is for the 'sign' action. Since sibling tools exist for add/update/remove, the purpose is ambiguous and not focused on the actual operation.

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

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

No guidance is provided on when to use this tool versus the sibling tools for add/update/remove. The description lacks any mention of when signing is appropriate or what distinguishes it from other signer operations.

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

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

The description adds useful non-annotation behavior: update is only allowed before signing and can resend reminders. However, it does not disclose side effects, whether changes are reversible, permission requirements, or what happens under failure, so transparency beyond annotations is limited.

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 not concise: it includes full explanations for add, update, remove, and sign even though this tool is flattened to update. Only the update bullet and final 'Flattened action: update' note are relevant; the rest is noise for an agent selecting this specific tool.

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

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

With no output schema and annotations that only indicate readOnly/idempotent/destructive hints, the description should cover response/error behavior and clarify all parameters. It gives update constraints and field lists, but omits the meaning of account/doc_token, required-parameter details, and post-update behavior, leaving the tool incomplete for reliable 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 0%, so the description must compensate. It documents the data fields (name*, email*, and optional fields) and mentions signer_token, but it never explains the 'account' parameter or why doc_token is in the schema for update. The nested 'data' object is partially clarified but not fully.

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

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

The description identifies 'update' as the flattened action and states that it updates a signer or resends a reminder, which is a clear verb+resource combination. It also distinguishes from sibling operations by listing add/remove/sign as separate actions, though the overall header 'Gerenciar signatários' is generic.

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 concrete usage context: update only works before signing and can also resend a reminder. It implies this tool is for update rather than add/remove/sign, but it does not explicitly say 'when not to use' or name alternative tools beyond the action list.

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. The description adds that it's a 'leitura' (read) operation and mentions pagination (20 per page) for list action. However, it does not describe behavior of the get action (e.g., errors, relationships) beyond including inputs[] of variables. The description does not contradict annotations; it aligns with read-only, idempotent nature.

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

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

The description is concise, with a short introductory sentence and a bullet list of actions. It uses a compact format that is easy to scan. However, the phrase '[Flattened action: get]' is somewhat cryptic and may add unnecessary confusion, but overall it is efficient.

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

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

Given the tool has 3 parameters with 0% schema description coverage, and no output schema, the description is insufficient to fully understand how to use the tool. It does not explain the response format for get, nor does it clarify the purpose of the 'account' parameter. The presence of sibling tools like zapsign_templates_list and zapsign_templates_write_* increases the need for clarity on when this specific tool is used, which is only partially provided.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions page (for list) and template_token (for get), but does not explain the 'account' parameter at all. The description does not provide complete semantics for all three parameters; account is missing entirely. This is a gap since the schema only provides type 'string' for account without further context.

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

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

The description clearly states this tool handles templates (DOCX models) in ZapSign, with actions list and get. The flattened action is 'get', which matches the tool name 'zapsign_templates_get'. However, the description mixes two actions (list and get) and mentions the flattened action, which might be confusing but still clearly indicates the purpose of retrieving template details.

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 lists the actions and their parameters (page for list, template_token for get), but does not explicitly state when to use this tool versus alternatives like zapsign_templates_list. It implies that 'get' is the intended action but doesn't provide clear guidance on when to choose this tool over sibling 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=true, idempotentHint=true, and destructiveHint=false, which cover safety. The description adds a behavioral detail: pagination with 20 items per page for the list action. However, it does not mention other behaviors such as whether all templates are returned, sorting, or filtering. Given the strong annotations, the extra info is minimal but sufficient for a basic list operation.

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

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

The description is concise but includes both list and get actions, which is redundant for a tool specifically named zapsign_templates_list. It has a structured format with actions and parameters, but the inclusion of get adds noise. It is not overly verbose but could be more focused and clearly front-loaded on the list action.

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 list tool with three parameters and no output schema, the description only addresses pagination and omits explanations of 'account' and 'template_token'. It also does not describe what the list returns or how it differs from other listing tools like zapsign_documents_list. The lack of parameter details and output expectations makes it incomplete for an agent to use 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 description coverage is 0%, so the description must compensate. It only explains the 'page' parameter (with 20/página), while 'account' and 'template_token' are not described at all in the context of the list action. The description adds no meaning for two of the three parameters, leaving their roles ambiguous.

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 translates to 'Templates (DOCX models) in ZapSign (read)' and then lists both 'list' and 'get' actions, with a note that this tool is the flattened 'list' action. It is not explicitly stated that this tool lists templates; the verb is implied rather than expressed. It does not clearly differentiate from the sibling zapsign_templates_get since both actions are mentioned in the same description.

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 guidance on when to use this tool versus alternatives. The description mentions both list and get actions but does not advise that list should be used for enumerating templates while get is for individual details. No exclusions or alternative tool references are provided.

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 indicate a non-read-only, non-idempotent write operation. The description adds no meaningful behavioral detail for the create action itself, such as duplicate handling, required permissions, or return data. The update/delete details are mostly irrelevant to the flattened create operation.

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 bulleted structure is compact and scannable, but it includes update and delete actions in a create-specific flattened tool, which is extraneous and potentially misleading. Abbreviations like 'opc' and Portuguese phrasing reduce clarity for non-Portuguese agents.

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, weak annotations, and a nested data parameter, the description should explain return values, invocation prerequisites, and the exact role of 'account'. It explains the data object reasonably well but leaves these important aspects 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?

The schema provides zero descriptions, so the description compensates by listing meaningful data-object fields: required name and docx_url/base64_docx, plus optional first_signer, lang, observers, folder_path/folder_token, and redirect_link. However, the 'account' parameter is never explained, and 'template_token' is only contextualized through the irrelevant update/delete actions.

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

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

The description clearly states 'create (data): cria template DOCX', identifying the specific action and resource. The '[Flattened action: create]' note anchors the tool's scope, though including update/delete actions alongside creates some confusion.

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 explicit guidance on when to use this tool versus sibling tools like zapsign_templates_write_update or zapsign_templates_write_delete. The description lists update/delete actions but does not clarify that this flattened tool is only for creation.

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

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

The description adds important context by calling delete 'irreversível', but this directly contradicts the annotation destructiveHint=false. An irreversible delete is destructive, so the description and annotation are in conflict.

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 delete line is short and clear, but the description dedicates significant space to create/update field lists that are irrelevant for a delete-only flattened tool. This clutter reduces conciseness without adding value for the actual operation.

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 delete tool with no output schema and misleading annotations, the description should cover success/failure behavior, account handling, and whether template_token is the only needed parameter. It only mentions irreversibility, leaving key operational details unexplained.

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

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

With 0% schema description coverage, the description must compensate. It only clarifies that template_token identifies the template for deletion, but does not explain account or data parameters, nor does it state requiredness or parameter format.

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 explicitly states 'delete (template_token): irreversível' and ends with '[Flattened action: delete]', making it clear the core operation is deleting a template. However, it also lists create/update actions, which introduces ambiguity about whether this exact tool can perform those operations.

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

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

No guidance is given on when to use this delete tool versus the create/update siblings. The description merely enumerates all possible actions without stating 'use delete only to permanently remove a template' or explicitly excluding create/update from this flattened tool.

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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the tool is a non-read, non-destructive write operation. The description adds valuable behavioral context beyond that: it states the DOCX file is immutable and only metadata can be updated, which is a key constraint not captured in annotations. It also notes for the delete action (included in the description) that deletion is irreversible, though that's not directly relevant to this update tool. No contradiction with annotations.

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

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

The description is organized in a bulleted action list, making it scan well. It includes create and delete actions even though this tool is only for update, adding some extra content that could be trimmed, but the flattened action marker helps isolate the relevant part. Each sentence adds value: the metadata limitation, field lists, and immutability notice are all useful. Slightly verbose but not wasteful.

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 write/update tool with no output schema, the description is fairly complete. It explains what can be updated, notes the immutability constraint, and indicates the required token parameter. It doesn't describe return values or error scenarios, but such details are often not necessary in MCP descriptions when an output schema is absent. Overall, it provides enough context for an agent to correctly invoke the update operation.

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

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

The input schema has 0% description coverage and only lists generic properties (data, account, template_token) without detail. The description compensates by enumerating the updatable fields inside the data object (name, lang, observers[], first_signer, folder_path/token, redirect_link) and clarifies that template_token is required for the update action. It also distinguishes required fields for create but not for update, providing clear semantic meaning beyond the bare schema.

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

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

The description clearly states the tool manages ZapSign templates and explicitly describes the 'update' action: 'update (template_token, data): metadados (o DOCX em si é imutável)' with a list of updatable fields. The flattened action marker '[Flattened action: update]' confirms this tool is specifically for updating templates, distinguishing it from sibling create/delete 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?

The description provides implicit usage context: it notes the DOCX itself is immutable, so only metadata can be updated. It lists the fields that can be changed, which helps an agent know when to use this tool (to modify template metadata). However, it does not explicitly state 'use this instead of create/delete' or mention any prerequisites, so it's clear but not fully explicit about when not to use it.

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

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

The annotations say readOnlyHint=false and destructiveHint=false, so the behavior is carried mainly by the description. It adds useful context: one webhook per account, no listing endpoint, optional type defaulting to '', returns {id}. But it does not clarify whether creating another webhook replaces/fails when one already exists, and the bundled delete action causes scope confusion.

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

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

The description is compact, uses labeled bullets, and front-loads the key facts. It is slightly cluttered by including both create and delete actions together with a 'Flattened action: create' tag, but overall it earns its length.

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 low parameter coverage, so the description must bear the explanatory load. It gives enough to start creating a webhook and tells the agent what the response contains ({id}). However, it lacks overwrite/existing-webhook behavior, prerequisites/authorization expectations, and exact header/field formatting details, leaving meaningful 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 description coverage is 0% and `data` is an unstructured object, so the description is essential. It correctly documents the main payload fields: url*, optional type defaults, doc_token, and headers. It does not explain the `id`/`ids`/`account` fields for this flattened create tool, but the addressed create% from create fields is the dominant behavior.

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

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

The description clearly states the create action: 'create (data): cria webhook' and even gives the unique behavioral note that one webhook covers all documents. It loses a point because it also documents a delete action and bulk 'ids' behavior, which muddies what this specific `_create` flattened tool is responsible for.

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 useful caveats: there is no listing endpoint, and only one webhook per account exists covering all docs. However, it does not explicitly explain when to use this tool versus the sibling delete tool, nor what to do if a webhook already exists.

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

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

The description explicitly says 'delete (id): remove webhook' which is a destructive operation. However, the annotation `destructiveHint: false` contradicts this behavior, indicating the description contradicts the annotation. This is a serious inconsistency, so the score is reduced to 1.

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

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

The description is compact and well-structured with bullet points for each action, includes a note about the absence of a listing endpoint, and mentions bulk support in a single line. It front-loads the purpose and avoids unnecessary verbosity, earning top marks for 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?

The description covers key aspects: return value for create ({id}), the lack of a listing endpoint, the one-per-account constraint, and creation fields. However, it does not explain the 'account' parameter or specify the return behavior for delete. Given there is no output schema, these omissions prevent a full score.

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?

Despite 0% schema description coverage, the description adds significant meaning: it explains that 'data' contains the webhook fields (url, type, doc_token, headers), and that 'id' is the webhook identifier for deletion. It also mentions 'ids' for bulk operations, though it does not clarify the 'account' parameter. This goes beyond the bare schema property names.

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

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

The description clearly states 'Gerenciar webhooks no ZapSign' (manage webhooks) and enumerates the create and delete actions with specific details. It also mentions the lack of a listing endpoint, which distinguishes it from potential listing tools and the sibling create-only tool, making the purpose 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 provides clear context for usage: create requires a URL and optional type, delete uses the id returned from creation, and notes '1 por conta cobre todos os docs' and bulk support via ids. However, it doesn't explicitly state when to prefer this tool over the sibling create-only tool, though the combined write/delete scope is implied.

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