xero_upload_attachment

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

The description adds meaningful behavioral context beyond the annotations: `effect` is a self-claimed read/write flag that Spring verifies, `approval_ref` is required when resuming writes, `idempotency_key` provides stable business-action identity, and routing is confined to a governed connector authority. These details give concrete meaning to the destructiveHint/idempotentHint annotations. Not a 5 because it never discloses what the upload actually mutates or what side effects follow a successful write.

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?

Compact and well-organized: a two-sentence header carries the operation identity and the critical governance constraint up front, followed by a tight aligned Args list. Each parameter line is short and consistent, with no filler. Slightly formulaic in the autogenerated style, but every line earns its place.

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 having an output schema and rich annotations, the description omits the operational core: it never explains what an attachment upload entails (target entity type, how the file/content is identified or transmitted) nor what shape the `arguments` JSON must take. With 7 parameters, 0 required, and the primary payload opaque, an agent cannot reliably construct a valid call from this definition alone.

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 Args block compensates by glossing all 7 parameters — distinguishing project_id from project_ref, explaining connector_account_ref's alias role, and clarifying approval_ref's write-resumption purpose. The weakness is `arguments`, described only as "JSON string of arguments for the connector operation," which is circular and gives the agent no information about the actual Xero upload payload.

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 opening line "Xero connector operation `upload_attachment`" largely restates the tool name rather than explaining its function — no sentence actually says "uploads an attachment to a Xero record." It gains a point from the name's self-descriptiveness and the routing sentence, but the description never articulates what the operation does in domain terms.

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 only usage signal is the routing constraint "Routes only through the exact project/account governed connector authority," which tells the agent when it may not be used but not when to choose it over alternatives. Among dozens of sibling Xero tools (xero_upload_file, xero_api_request, xero_get_attachment), nothing distinguishes when to pick this one for attachment uploading, nor does it warn against using raw xero_api_request instead.

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