Attach receipt to a bank transaction

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

Annotations only declare the generic profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true); the description adds the non-obvious behavior that a transaction holds exactly one attachment and re-attaching overwrites it, plus the accepted file-type set and the server-side location constraint for filePath. This is meaningful behavior beyond the structured fields, and nothing here contradicts 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?

Five dense sentences, front-loaded with purpose and sibling disambiguation, then replacement semantics, then source-parameter rules, then a discovery pointer. No filler or repetition.

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 output schema and low schema coverage, the description covers sourcing, replacement behavior, accepted formats and target discovery well. It omits what the response returns and says nothing about mimeType, a minor gap for a write tool of this complexity.

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

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

Schema coverage is only 14%, so the description carries most of the burden: it clarifies that filePath is on the server's machine, that url and base64 are alternate sources, that base64 must pair with fileName, and that exactly one source must be supplied. mimeType and transactionId are left implicit, so it falls just short of full compensation.

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

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

States a specific verb+resource ('Attach an invoice, receipt or other file to a bank/manual transaction') and names the sibling it is not ('use this instead of upload_document, which only links files to properties and tenants'). An agent can distinguish it from upload_document, link_document and remove_transaction_receipt without opening any schema.

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

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

Explicit routing: use this rather than upload_document, and it names list_transactions (with search/amount/hasReceipt hints) as the way to locate the target. It also states the replacement condition ('a transaction holds ONE attachment: attaching again replaces it') and the exactly-one-of source rule, so both when-to-use and how-to-call are covered.

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