Merit Write Financial Confirm

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.