borderou_transaction_update

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

No annotations are provided, so the description carries the full burden. It conveys that this operation modifies ('link or unlink') a transaction match, which is some transparency about mutation. However, it doesn't disclose side effects such as whether unlinking cascades to other records, whether existing matches are replaced, or what happens on partial updates with conflicting params (e.g., both invoiceId and proformaInvoiceId).

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 compact single sentence that front-loads the purpose and gives the core behavior (link/unlink for reconciliation). It's efficient with no wasted words, though it could add a usage note without much cost.

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 7 parameters, no annotations, and no output schema, this mutation tool has moderate complexity. The description explains the general purpose and the companyId fallback, but leaves gaps: how amount override interacts with matching, whether documentType is required when linking, what the response format is, and what mutually-exclusive parameter combinations are valid.

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

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

Schema description coverage is 100%, so each of the 7 parameters is documented in the schema. The description adds the 'link or unlink' semantic for the match operation and clarifies the companyId fallback behavior ('uses active company if not set'), which goes beyond the bare schema. It also ties documentType to the invoice/proforma choice. Schema and description together cover the parameters well.

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 verb ('Update') and resource ('borderou transaction match'), and explains the linking/unlinking behavior against invoices or proforma invoices. It distinguishes from siblings like borderou_transactions_save and borderou_transaction_get reasonably well through its explicit 'match' focus, though it doesn't name sibling alternatives.

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 context (linking transactions to documents for reconciliation) but provides no explicit when-to-use vs alternatives guidance. It doesn't mention how this differs from borderou_transactions_save or borderou_transactions_rematch, which appear to be related sibling tools for the same domain.

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