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

Annotations already declare readOnlyHint and idempotentHint. The description adds meaningful context by specifying the exact environment variables checked and that the tool provides instructions when not configured. This goes 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 succinct sentence that conveys all necessary information with no unnecessary words. Every part is valuable.

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 zero parameters, present annotations, and an output schema, the description fully covers what the agent needs to know: it will report configuration status and optionally provide setup instructions.

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?

No parameters exist, so schema coverage is effectively 100%. The description does not need to elaborate on parameters; the baseline score of 4 applies.

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

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

The description clearly states the tool's purpose: to report whether MERIT_API_ID and MERIT_API_KEY are configured and provide setup instructions. This distinctively sets it apart from sibling tools which focus on data 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?

The description implicitly indicates when to use this tool (to check configuration status and get setup instructions). While it doesn't explicitly state when not to use it or list alternatives, the sibling tools are so different that usage context 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 provide readOnlyHint, destructiveHint, and idempotentHint. The description's 'Read-only tool' is consistent with annotations but adds no additional behavioral context (e.g., rate limits, auth requirements). This is adequate given annotation coverage.

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 front-loaded with 'Read-only tool' and lists actions succinctly. However, the repetitive 'List ...' structure could be condensed, and the inclusion of periods and semicolons makes it slightly verbose. Adequate but not exemplary.

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 tool with 9 parameters, no output schema, and extensive sibling tools, the description is incomplete. It fails to explain parameter mechanics, filter usage, or return behavior, leaving significant gaps for an agent to select and invoke 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?

With 0% schema description coverage, the description must compensate but does not. It only lists possible values for the 'action' parameter, leaving id, filters, payload, etc. unexplained. The agent cannot infer correct parameter usage beyond action selection.

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 read-only tool for payments, banks, and GL information, distinguishing it from write siblings. However, the purpose is presented as a list of actions rather than a concise single statement, slightly reducing clarity.

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 includes 'Read-only tool,' which implies it should not be used for writes, but it does not explicitly mention alternatives like merit_write_financial or specify when to use this vs. other read tools such as merit_read_purchases. Some guidance is present but incomplete.

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 provide readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds 'Read-only tool' but does not elaborate on permissions, rate limits, or side effects beyond what annotations convey.

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

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

The description is relatively short but uses a run-on list with semicolons. It could be better structured (e.g., bullet points) and still concise.

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 (9 parameters, no output schema, no enums), the description is insufficient. It does not cover parameter interactions, default behaviors, or the full scope of actions and their constraints.

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 9 parameters, the description fails to explain the meaning of key parameters (e.g., action, id, filters, payload). Only action is mentioned via a list of sub-actions, but no enum or format details are provided.

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 read-only tool for inventory, fixed asset, and pricing data with a list of actions. However, it does not explicitly differentiate from sibling tools like merit_read_financial or merit_read_master_data, which may have overlapping scope.

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?

While it identifies the tool as read-only, there is no guidance on when to use it versus alternative tools, nor does it explain which action to use in different scenarios. The description lacks context-specific usage recommendations.

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=true, destructiveHint=false, idempotentHint=true. The description reiterates 'Read-only tool' and lists actions, adding moderate value by specifying the type of data (master/reference), but does not disclose behaviors like rate limits, permissions, or response structure.

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 moderately concise; the action list is structured but somewhat lengthy. It front-loads the read-only nature, but a more compact grouping could improve readability without losing information.

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

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

Given no output schema and 0% parameter coverage, the description should explain what each action returns and how to use optional parameters. It fails to do so, leaving significant gaps for an agent to understand tool usage 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. Only the 'action' parameter is implicitly explained via the list of action values. Other critical parameters (id, filters, payload, etc.) are not described at all, leaving the agent to guess their purpose and 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 clearly states the tool is for reading master and reference data from Merit, and lists 18 specific actions (e.g., customers_list, accounts_list). The purpose is clear but does not differentiate from sibling read tools like merit_read_financial which may also list accounts or other overlapping actions.

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

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

No guidance is provided on when to use this tool versus the many other read tools (e.g., merit_read_financial, merit_read_inventory). The description simply enumerates actions without contextualizing scope 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, so the description's 'Read-only tool' adds no new safety context. It lists actions but lacks details on pagination, error behavior, or output structure, though not required given 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?

Description is short and front-loaded with 'Read-only tool,' then lists actions. No wasted words, though a list format could improve readability.

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?

Description is incomplete given 9 parameters and no output schema. Only action parameter is explained; key details on filters, payload, and response are missing, making it insufficient 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?

With 0% schema coverage, the description must compensate but only explains the 'action' parameter values. Other 8 parameters (id, filters, payload, etc.) receive no explanation, leaving ambiguity.

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 reads purchase invoices and purchase orders, listing specific actions (invoices_list, invoice_get, orders_list), which distinguishes it from sibling read tools like merit_read_sales.

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 purchase documents through naming and actions, but does not explicitly state when not to use it or compare with alternatives like merit_read_financial.

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 provide readOnlyHint, destructiveHint, and idempotentHint. The description adds a list of actions but no additional behavioral details like pagination or error handling. It does not contradict 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 fairly concise but the list of actions is run-on and could be better formatted. It front-loads 'Read-only tool' but is not particularly 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?

No output schema and no explanation of return values or continuation mechanism. Given the complexity (8 reports, 9 parameters), the description is incomplete and does not cover how to use the tool effectively.

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%. The description lists the valid action values, which is critical, but does not explain the other 8 parameters (id, filters, payload, etc.). For a tool with 9 parameters, this is insufficient.

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 reads Merit reports and lists eight specific actions, making the purpose clear. However, it does not differentiate from sibling read tools like merit_read_financial or merit_read_sales, which could cause 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?

No guidance on when to use this tool versus the specific read tools (e.g., merit_read_financial). The description only says 'Read-only tool' but lacks any when-to-use or when-not-to-use instructions.

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, destructiveHint=false, idempotentHint=true. Description reinforces read-only behavior but adds no additional behavioral context beyond listing actions. No contradictions.

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

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

Front-loaded with key purpose ('Read-only tool'). Actions listed in a structured format. Slightly long due to enumeration, but each line is concise. No unnecessary words.

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

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

While the action list is useful, the description fails to document parameter semantics, return values (no output schema), or provide examples. Given 9 parameters and zero schema descriptions, the tool definition is incomplete.

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 description must compensate. It enumerates valid action values in text, aiding the agent. However, it does not explain id, filters, payload, or other parameters, leaving significant gaps.

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?

Clearly states it is a read-only tool for sales invoices, offers, and recurring invoices. Lists all available actions. Distinguishes from sibling write tools like merit_write_sales.

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

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

Explicitly states read-only nature, implying not for modifications. Does not provide explicit when-not-to-use or alternatives, but siblings are clearly write tools. Within the tool, actions list provides guidance on which action to use.

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

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

The description clearly explains the preview-only nature: 'Does not execute changes; returns intended operation details and a confirmation_code.' This aligns with the readOnlyHint annotation and adds value by describing the confirmation flow. 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 informative but somewhat verbose and unstructured. It could be more concise and organized, e.g., bullet points for actions and payload fields. However, it is not excessively long.

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 9 parameters, no output schema, and a complex payload with many fields, the description lacks details on return values, payload structure, and all parameters. It covers only partial context, leaving gaps for effective tool selection and 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%. The description only lists some payload fields (Id, Name, CountryCode, etc.) but does not explain other parameters like filters, add_attachment, delivnote, bank_id, confirmation_code, or confirmed. This leaves many parameters 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 clearly states it is a preview-only write tool for creating/updating customers and vendors, with specific actions like customer_upsert, vendor_upsert, vendor_update. It distinguishes from sibling tools by focusing on customer/vendor writes and explicitly mentioning the confirmation step.

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

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

Provides a typical use case: after receiving a purchase invoice, verify and sync vendor bank details. It also mentions the confirmation_code for merit_write_customers_confirm. However, it does not explicitly state when not to use it or alternative tools for other domains.

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 destructiveHint=true, and the description confirms it's a mutating tool. The description adds details about actions (create/update customers/vendors) and notes that for vendor_update only Id is required. However, it does not describe behavior on failure, rollback, or what happens if confirmed=false, so some behavioral context is missing.

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 multi-sentence but each sentence adds information: purpose, actions, typical use, payload fields. It is front-loaded with the key fact that it is a confirmed mutating tool. Slight redundancy in describing 'Create or update customers and vendors' followed by specific actions, but overall 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 no output schema, the description does not cover return values. It lacks details on error handling, the effect of setting confirmed=false, or prerequisites beyond the preview step. For a confirm tool, this could be more complete, but the typical use case helps.

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 explains payload fields (Id, Name, etc.) and notes required parameters (action, confirmation_code, confirmed). However, it does not describe other parameters like id, filters, add_attachment, delivnote, bank_id, leaving some parameters undocumented. Partial coverage but adds value.

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 executes a previously previewed write operation from merit_write_customers, requiring confirmation_code and confirmed=true. It lists specific actions (customer_upsert, vendor_upsert, vendor_update) and provides a typical use case. This fully distinguishes it from sibling tools like merit_write_customers (preview).

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 when to use the tool: after previewing from merit_write_customers, with confirmation_code and confirmed=true. It includes a typical use scenario involving vendor BankAccount synchronization. Though it doesn't explicitly state exclusions or alternatives, the context of a confirm tool 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?

Beyond annotations (readOnlyHint=true, destructiveHint=false), the description adds significant behavioral context: it is preview-only, returns a confirmation_code, uses different API versions based on currency (v1/v2), and raises errors if IBAN or PaymentDate are unresolved. These details are valuable and extend beyond what 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 long and includes bullet points with action-specific details. It front-loads the key preview-only behavior, but the exhaustive listing of actions and parameter details makes it less concise. It is adequately structured but could be more streamlined.

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 complexity (multiple actions, 9 parameters, no output schema), the description is incomplete. It fails to explain general schema parameters like id, filters, payload, add_attachment, delivnote, bank_id, confirmation_code, and confirmed. It also provides minimal detail for most actions, leaving the agent uncertain about how to use the tool for actions other than purchase_invoice_payment_create.

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 provides detailed parameter semantics for the purchase_invoice_payment_create action (field types, defaults, auto-fetch), but other actions (tax_upsert, dimensions_add, items_add, item_update) receive only one-line summaries with no parameter details. The schema has 9 parameters with no descriptions, and the description covers only a subset, leaving significant gaps.

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 is a preview-only write tool that does not execute changes, returning a confirmation_code for confirmation. It lists specific actions (purchase_invoice_payment_create, tax_upsert, etc.) and distinguishes itself from the sibling confirmation tool (merit_write_financial_confirm). The purpose is specific and well-defined.

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 that this tool should be used for previewing financial write operations before confirming with merit_write_financial_confirm, but it does not explicitly state when to use this tool versus other write tools like merit_write_customers or merit_write_purchases. Usage guidelines are implied but not 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?

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds that it is a 'confirmed mutating tool', mentions error conditions (raises error if IBAN or PaymentDate unresolved), and specifies API versions used (v1/sendPaymentV for EUR, v2 otherwise). This provides behavioral context beyond annotations, though it does not detail all effects of mutations for every 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 lengthy and includes an extensive parameter list for one action, which could be considered verbose. It is structured with a clear first sentence and bullet-like list of actions, but the level of detail is uneven. A more concise approach focusing on the confirm behavior and directing to the preview tool for action details would improve 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?

Given 9 parameters, 1 required, and no output schema, the description covers the return value (raw Merit API response) and error conditions for one action. However, it is incomplete for other actions: parameters like id, filters, payload for tax_upsert, dimensions_add, etc., are not explained. The agent may struggle to use actions beyond purchase_invoice_payment_create without additional knowledge.

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 provides detailed parameter descriptions for the purchase_invoice_payment_create action (e.g., BankId, VendorName, etc.). However, it does not explain the generic parameters (id, filters, add_attachment, delivnote, bank_id) aside from bank_id and confirmation_code/confirmed. Other actions (tax_upsert, dimensions_add, etc.) are only named with no parameter details, leaving gaps.

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 executes a previously previewed write operation from merit_write_financial, with specific verb 'executes' and resource 'write operation'. It lists actions like purchase_invoice_payment_create, which clarifies scope. However, it does not explicitly distinguish it from sibling confirm tools like merit_write_customers_confirm, relying on the tool name for differentiation.

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

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

The description provides explicit usage conditions: must be called with confirmation_code and confirmed=true. It implies the tool is used after merit_write_financial preview. It does not mention when not to use it or alternatives, but the context of sibling confirm tools suggests each corresponds to a preview tool. The guidance is clear for the intended use case.

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 it does not execute changes and returns preview details plus a confirmation_code, which matches the readOnlyHint annotation. It adds context about return values and the workflow with the confirm sibling, going beyond the annotation's simple read-only flag.

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 extremely concise: two sentences and one bullet point. It front-loads the critical preview behavior and action, with no wasted words.

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

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

Given 9 parameters and no output schema, the description is incomplete. It lacks details on other parameters, expected values, or the structure of the intended operation details. The agent would need additional knowledge to use this tool effectively.

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 should compensate by explaining key parameters, but it only mentions 'action' and 'purchase_invoice_create'. It does not describe other parameters (id, filters, payload, etc.), leaving the agent without guidance on how to construct 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 it is a preview-only write tool that creates purchase invoices and returns a confirmation_code for a sibling confirm tool. It distinguishes itself from the confirm sibling and other write tools by highlighting its preview nature.

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 explicitly says 'Preview-only write tool. Does not execute changes; returns intended operation details and a confirmation_code for merit_write_purchases_confirm.' This provides clear guidance on when to use (for previewing) and implies the confirm tool for execution. However, it does not explicitly state when not to use it or list alternatives among siblings.

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 destructiveHint=true (mutating) and readOnlyHint=false. The description adds that it is a 'confirmed mutating tool' and that it executes a write operation. However, it does not elaborate on the consequences or irreversibility, leaving some behavioral aspects ambiguous.

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

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

The description is brief but contains redundancy (e.g., repeating 'Create purchase invoices') and could be streamlined. It front-loads the purpose but could be more organized.

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 9 parameters and no output schema or schema descriptions, the description is insufficient. It does not explain the full workflow (e.g., how to obtain confirmation_code from merit_write_purchases) or the meaning of many parameters, leaving the agent with significant 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?

With 0% schema description coverage, the description only explains 'action' (purchase_invoice_create) and mentions 'confirmation_code' and 'confirmed'. Six other parameters (id, filters, payload, add_attachment, delivnote, bank_id) are left undocumented, requiring the agent to infer or guess their purpose.

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 confirm step for a previously previewed write operation from merit_write_purchases, requiring confirmation_code and confirmed=true. It also specifies the action 'purchase_invoice_create' to create purchase invoices. However, there is slight redundancy and the purpose could be more explicitly tied to the workflow.

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 to use this tool when you have a confirmation_code and confirmed=true, implying it follows a preview from merit_write_purchases. It lists one supported action (purchase_invoice_create). It lacks explicit guidance on when not to use or alternatives, but the context is generally 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?

The description discloses it is preview-only and does not execute changes, but the annotation readOnlyHint=true contradicts this, as the tool performs write operations (even if only preview). This is a serious inconsistency, lowering the score despite some 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 dense but not wasteful; it front-loads the key preview-only nature then covers actions and gotchas. Some sections are run-on but necessary for the complexity.

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 tool with multiple actions and no output schema, the description adequately covers return value (operation details and confirmation_code). It provides gotchas and references sibling tools. However, some parameter descriptions are lacking, and the contradiction with annotations reduces 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 description must compensate. It does explain the 'action' parameter by listing actions and the 'payload' parameter in great detail for sales_invoice_create. However, other parameters (id, filters, add_attachment, bank_id, confirmation_code, confirmed, delivnote) are not explicitly explained, though some context is given via action 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's a 'Preview-only write tool' that handles multiple actions (create, delete, deliver, credit, send email/e-invoice). It distinguishes from sibling tools like merit_write_sales_confirm by mentioning confirmation code and preview nature.

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 explicitly says when to use (for preview, not execution) and when not (e.g., not to use send actions in normal draft creation flow). It also references sibling tools (merit_read_sales, merit_read_master_data) for verification and provides conditions for delivnote use.

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

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

Annotations indicate destructiveHint=true, and the description reinforces this by stating it is a 'mutating tool' and detailing operations. It adds many behavioral gotchas (e.g., payload shape, required fields, limitations like not including DelivNote) that go beyond annotations, ensuring the agent understands side effects.

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 thorough but overly long and dense, mixing general purpose with detailed payload examples. While front-loaded with the main purpose, it could benefit from more structured formatting (e.g., bullet points) to improve readability without losing detail.

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 purpose, usage, and parameter details comprehensively but lacks explanation of return values or error handling, which is significant given no output schema. It also omits descriptions for some schema fields like filters and add_attachment, relying on inference.

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

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

Schema coverage is 0%, but the description extensively explains the payload structure for each action and clarifies the use of confirmation_code, confirmed, and delivnote. However, it does not directly describe all parameters (e.g., filters, id, add_attachment) with equal depth, though their context is 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 it is a 'Confirmed mutating tool' that executes previously previewed write operations from merit_write_sales. It lists specific actions (create, delete, credit, send email, send e-invoice) and distinguishes itself from the sibling tool merit_write_sales by requiring confirmation_code and confirmed=true.

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

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

Explicitly provides when to use (only after preview from merit_write_sales) and when not to use (e.g., do not use send email in normal draft creation). It gives detailed context on alternative flows and prerequisites like confirmation_code and confirmed flag.

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