Invio Xero MCP

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description adds substantial behavioral context beyond those: the write hits a live ledger, a failed write cannot be retried (only a new draft can be created), the real outcome must be relayed verbatim, and hesitation does not count as consent. The idempotentHint=true annotation is not contradicted; the one-shot failure description is consistent with idempotent re-execution producing no new effect.

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, but the length is largely justified for a destructive approval tool with safety-critical consent rules; it is front-loaded with purpose and then ordered by consent gate, outcome reporting, and the manual alternative. It is somewhat repetitive across the consent warnings ('never infer... never call speculatively... never approve without...'), which could be tightened without losing meaning.

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 2-parameter destructive write tool with no output schema, the description covers everything an agent needs: what it executes, the consent precondition, how to obtain the pendingChangeId, failure/retry behavior, what to report back, and the equivalent manual path. The absence of a return-format spec is mitigated because the description explicitly tells the agent to report success and Xero-assigned id/number or the failure reason.

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 100% and both parameters are already fully described in the schema, including the consent gate on confirm and where pendingChangeId comes from ('Never invent one'). The description reinforces these constraints in workflow terms but adds no new parameter semantics beyond the schema, so the baseline of 3 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?

States a specific verb and resource ('Approves a change... and immediately executes it') and names the exact draft-creating siblings (create_xero_invoice, update_xero_contact, etc.) whose changes it acts on. It also carves out its unique role as 'the ONE tool in this connector that actually writes to a live Xero ledger', clearly distinguishing it from list_pending_changes and reject_xero_pending_change.

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?

Gives explicit when/when-not guidance: call ONLY after the user has clearly said in their own words to go ahead, never infer approval from context, never call speculatively, and call list_pending_changes first if the summary is not in context. It also names the manual alternative (Invio Settings > MCP > Xero) as an equivalent path, so the agent knows the tool is optional relative to human-approved workflow.

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 goes well beyond the annotations: it discloses the tool only proposes, never creates, requires human approval, provides an approvalUrl, and forbids using the contactId before approval. This is exactly the kind of behavioral context annotations cannot convey. No contradiction with readOnlyHint=false since it still creates a pending change.

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 bit long but front-loads the critical caveat and each sentence adds workflow or usage information. The phrase 'and never will on its own' is slightly redundant with 'does NOT create anything in Xero itself,' but overall it is structured and readable.

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 no output schema, it usefully names the approvalUrl field and the required approval step, and explains downstream use of contactId. It does not describe the full response shape or mention list_pending_changes/approve_xero_pending_change as related workflow steps, but an agent has enough to invoke it 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?

Only 'organisation' has a schema description (25% coverage), and the description only restates that 'name' is required, which is already in the schema. It adds no meaning for phone or emailAddress beyond their self-explanatory names, so it does not compensate for the low schema coverage.

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 uses a specific verb ('Proposes adding') and resource ('new contact (customer or supplier)') and immediately clarifies it does not create anything in Xero itself, distinguishing it from a plain create tool and from siblings like create_xero_invoice. It also names downstream consumers of the resulting contactId, which further disambiguates its role.

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?

It clearly states this queues a pending change requiring human approval and that the contactId can only be used after approval, giving an agent the context to decide whether to call it. It does not explicitly contrast it with update_xero_contact or list_xero_contacts, so there are no formal exclusions.

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 goes far beyond the annotations (readOnlyHint:false, openWorldHint:true, idempotentHint:false, destructiveHint:false) by disclosing the asynchronous approval workflow, the fact that it never touches Xero on its own, the draft-only outcome after approval, currency validation refusal, and the exact handling of lineAmountTypes and ambiguous dates. It also explains that the tool cannot approve changes itself and tells the agent how to communicate this to the user. These are critical behavioral traits not inferable from annotations alone.

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 but every section earns its place: it is front-loaded with the most critical caveat ('does NOT create anything in Xero itself'), then organized into clear thematic blocks (approval, contacts, currency, lineAmountTypes, dates). The length is justified by the tool's complexity and the high risk of user misunderstanding, but it could be tightened by removing some redundancies with the schema, such as repeating the date pattern warning already present in the parameter description.

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 (8 params, no output schema, critical safety implications), the description is complete: it covers the full workflow (contact prerequisite, proposal, human approval in Invio, draft-only result), provides all necessary parameter semantics, explains response fields (approvalUrl), and addresses edge cases like ambiguous dates and currency validation. An agent can invoke this tool correctly and communicate its behavior to the user without any missing information.

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?

Even though the schema already provides detailed descriptions for most parameters (88% coverage), the tool description adds substantial additional meaning: it explains the DATES rules for converting user input, warns about ambiguous bare numeric dates and how to read them in this organisation's region, details the currency check against configured currencies, and clarifies lineAmountTypes with concrete examples ('Inclusive' for 'including GST'). It also provides workflow semantics for contactId (must come from list_xero_contacts and create_xero_contact if needed). This far exceeds the schema's information.

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 opens with a specific verb and resource: 'Proposes creating a new credit note in this Xero organisation' and immediately clarifies the crucial nuance that it does NOT actually create anything in Xero—it queues a pending change. It clearly distinguishes itself from siblings like create_xero_invoice and approve_xero_pending_change by describing the proposal workflow and prerequisite contact creation, leaving no ambiguity about what the tool does.

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 states when to use this tool versus alternatives: contactId must come from list_xero_contacts, create_xero_contact should be used first if the contact doesn't exist, and approval is required via Invio (with the approvalUrl in the response). It also includes guidance on currency handling, lineAmountTypes interpretation, and date conversion rules, including a clear directive to confirm ambiguous bare numeric dates with the user. These are precise usage conditions, not just vague context.

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 only indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, providing minimal behavioral signal. The description compensates heavily: it discloses that the tool only proposes a pending change requiring human approval, that it never emails the invoice, that currency is validated against org config, and that date interpretation follows a specific rule. This is far beyond what annotations offer, and there is no contradiction with 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 long (over 600 words) but highly structured and each section addresses a real pitfall. It front-loads the core purpose and then systematically covers contact, status, currency, tax, and dates. However, there is some redundancy: the date ambiguity is repeated in the schema for both date and dueDate and also in the description's DATES section. While not wasteful, it could be trimmed slightly. The structure is clear, so it earns a 4.

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 (10 parameters, no output schema, minimal annotations), the description is exceptionally complete. It covers the approval flow, the meaning of statuses, currency validation, tax handling, date interpretation rules, and even the behavior when default account is needed. An agent has everything required to invoke the tool correctly, including how to phrase responses to the user.

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?

Despite schema coverage at 90%, the description adds substantial meaning beyond the schema descriptions. For date, it explains the ambiguous bare numeric date rule and how to handle it. For status, it explains the default and why DRAFT should be avoided unless explicitly requested. For currency and lineAmountTypes, it gives concrete examples and clarifies the semantics. This significantly aids correct invocation.

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 opens with a precise statement: 'Proposes creating a new invoice in this Xero organisation - it does NOT create anything in Xero itself, and never will on its own.' This clearly defines the verb, resource, and the crucial distinction from a direct create. It also implicitly differentiates from sibling tools like create_xero_credit_note and create_xero_quote by naming the invoice and its approval flow.

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 gives explicit when-to-use and when-not-to-use guidance: it instructs that contactId must come from list_xero_contacts, tells to use create_xero_contact first if needed, explains when to pass status DRAFT vs AUTHORISED, and clarifies that sending is a separate action with no tool. It also mentions alternatives like list_xero_contacts for getting IDs. No ambiguity is left.

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, it discloses the draft/pending-change workflow, the human-approval requirement, the agent's inability to approve, refusal for terminated employees, the region-specific silent ignoring of title, and immediate usability after approval. This is rich behavioral context that the annotations alone do not provide, and there is no contradiction with readOnlyHint=false.

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 dense, but the core behavior is front-loaded and nearly every sentence carries an operational constraint. Some repetition around Xero not being touched and the approval requirement keeps it from a 5 on conciseness, but it is still highly efficient for the tool's 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?

The description covers nearly all non-obvious context: approval workflow, prerequisites, regional differences, and post-approval behavior, and even mentions the response's approvalUrl despite there being no output schema. However, it references a 'DATES instruction in this tool's description' that is not actually present in the provided description, leaving ambiguous-date handling slightly 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?

Even though schema coverage is 100%, the description adds substantial meaning: employee must be ACTIVE, ids must never be invented, description is shown to the human approver, title is Australia-only, and no hours/units parameter exists. It reinforces and extends what the input schema already specifies.

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 opens with a specific verb and resource: 'Proposes a DRAFT leave application for one employee/period', scoped to Australian, New Zealand, and United Kingdom organisations. It immediately clarifies the tool does not touch Xero itself, which distinguishes it from the other create_xero_* siblings.

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?

It explicitly prescribes predecessor calls: employeeId must come from list_xero_payroll_employees and leaveTypeId from list_xero_payroll_leave_types, with 'call that tool first if you do not already have a real id'. It also says not to pass an hours/units figure, and contrasts its approval lifecycle with create_xero_timesheet/create_xero_pay_run, giving clear when-to-use and when-not-to guidance.

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?

Despite annotations only saying readOnlyHint=false and openWorldHint=true, the description discloses an exceptional amount of behavior: it queues a pending change requiring human approval (the agent cannot approve), rejection of unbalanced entries before queueing, that even approved entries only become DRAFT journals in Xero, and the signed-debit/credit convention with its silent-failure risk. All of this is beyond what the annotations convey and none of it contradicts them.

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 the most critical facts (propose-not-create, approval workflow) and every block earns its place operationally, but it is notably verbose — the date section and repeated warnings about the zero-sum and tax rules overlap with the schema, which already states the sign convention, accountCode requirement, and balancing check. It reads more like an operational playbook than a lean tool description.

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 complex, side-effecting tool with no output schema, the description covers the approvalUrl response field, failure modes (imbalance rejection with the imbalance named), the draft-only outcome post-approval, and user-communication obligations. Minor gaps: no description of other response fields (e.g., pending-change ID) and no error-format detail beyond the imbalance case, but nothing an agent needs to invoke correctly is missing.

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 80% schema coverage the baseline is 3, and the description adds real value on top: the DATES section gives a decision procedure for ambiguous bare numeric dates including the day-first country rule and the requirement to state the interpretation aloud; lineAmountTypes gets when-to-set/omit guidance and explicit prohibitions ('Never adjust the amounts yourself to fake a tax treatment'); lineAmount's sign convention is reinforced with the consequence of reversal. This goes beyond the schema's phrasing.

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 first sentence states a specific verb and resource ('Proposes a manual journal') with concrete use-case examples (reallocating an expense, bank fee, writing off a balance), and immediately draws the critical distinction from siblings by clarifying it does NOT create anything in Xero. The 'proposes' vs 'create' framing cleanly separates it from create_xero_invoice, create_xero_credit_note, and the approve/reject_pending_change tools.

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 gives clear when-to-use context via the general-purpose adjustment examples, and explicitly contrasts with a sibling ('unlike an invoice line, a journal line has no default account'), plus names list_xero_accounts as a prerequisite. However, it never systematically states when to prefer a sibling (e.g., invoice for billing customers) — the when-not is implied rather than 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?

The description goes far beyond the annotations, disclosing that the tool does not touch Xero itself, requires explicit human approval, has no draft state in Xero once approved, applies immediately, and can only be reversed by deleting the payment inside Xero. It also discloses live re-checking, refusal conditions, and the instruction to narrate the proposed payment to the user rather than describing it as recorded or applied. The destructiveHint annotation is consistent with the irreversibility warning, not contradicted.

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 the core purpose and approval model, then organized into sourcing, bank account selection, consequences, and date handling. It is long and at times repetitive, especially around bank-account sourcing, but the length is largely justified by high-risk constraints and edge cases. Every block earns its place even if some wording could be tightened.

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 an eight-parameter tool with no output schema, this description is unusually complete: it covers all parameters, data sourcing, approval flow, the response's approvalUrl field, live re-checks, refusal reasons, irreversibility, and even cultural date ambiguity. Nothing essential is missing for an agent to invoke this tool correctly and communicate the outcome safely.

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?

Although the schema already covers 100% of parameters, the description adds substantial meaning beyond the structured fields: exactly one of accountCode or bankAccountName, never reusing an invoice line item's accountCode, using bankAccountName when list_xero_accounts shows code: null, strict YYYY-MM-DD conversion with a day-first rule for bare numeric dates, and amount/currency constraints such as partial payments and no currency conversion. This significantly exceeds what the schema alone communicates.

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 sentence states a precise action and object: proposing to record a payment against an existing, AUTHORISED Xero invoice. It immediately clarifies that this is a queued pending change requiring human approval, not a direct Xero mutation, which distinguishes it clearly from sibling create/update tools. The 'UNLIKE EVERY OTHER CHANGE' line further separates it from the other draftable changes this connector can produce.

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 is explicit about prerequisites and supporting tools: invoiceId must come from list_xero_invoices/get_xero_invoice, and bank account fields must come from list_xero_accounts. It also tells the agent how to present the proposal and what not to claim. However, it does not explicitly name alternative tools for similar situations (e.g., create_xero_credit_note) or give a clear when-not-to-use condition beyond the ambiguous-date case, so the guidance stops short of a full exclusion set.

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 adds substantial behavior beyond the annotations: the tool only queues a pending change, requires human approval via approvalUrl, never touches Xero itself, and produces a Xero-side DRAFT. This richly supplements readOnlyHint=false, openWorldHint=true, idempotentHint=false, with 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 front-loaded with the core purpose and contains valuable details, but it is somewhat repetitive around the theme of not touching Xero ('does NOT touch Xero itself', 'before Xero is touched at all', 'never posts anything itself'). Still, every sentence 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?

For a tool with no output schema, the description is remarkably complete: it covers geographic restrictions, the approval workflow, the approvalUrl field, the eventual DRAFT state, and the separation from post_xero_pay_run. An agent has everything needed to invoke it 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 coverage is 100%, but the description adds meaningful context by explaining that payrollCalendarId must be sourced from list_xero_payroll_employees and never invented, and why period start/end and payment date parameters are absent. The organisation parameter's optionality is also clarified.

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 states a specific action ('Proposes a DRAFT pay run for one payroll calendar'), a geographic scope, and explicitly contrasts itself with post_xero_pay_run. It is unambiguous about what the tool does and does not do, making it easy to distinguish from siblings.

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?

It gives explicit when-to-use guidance: Australian or New Zealand organisations, not the United Kingdom, and not as a posting step. It names post_xero_pay_run as the irreversible final step and even references list_xero_payroll_employees as the source for payrollCalendarId.

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 provide only broad hints (readOnlyHint false, openWorldHint true), so the description carries the full burden. It discloses the pending-approval queue, that a human must approve before Xero is touched, that the agent cannot approve it, that no email/delivery is ever possible, and that currency is validated against the organisation's configured list. This is exceptionally transparent behavior disclosure beyond what annotations could express.

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, but its length is earned by the tool's complexity and safety-critical approval model. It is front-loaded with the most important caveat (does NOT create in Xero). There is some repetition around 'no way to email/deliver' and 'do not describe as created/sent/delivered,' which is arguably justified for safety but prevents a perfect conciseness score.

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 13-parameter tool with no output schema, the description covers everything an agent needs: the pending-change workflow, the approvalUrl field in the response, the required contact lookup flow, date parsing rules, status semantics, and optional field defaults. Nothing critical is missing for correct 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?

Even though schema description coverage is 92%, the description adds substantial meaning beyond the schema: it explains bare numeric date ambiguity with the day-first convention, gives concrete examples for lineAmountTypes ('$1,500 plus GST'), clarifies currency validation behavior, and states what Xero defaults apply when optional fields are omitted. This is far more than a minimum-viable complement to the schema.

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 opens with a specific verb and resource: it 'Proposes creating a new quote in this Xero organisation' and immediately clarifies it does NOT create anything in Xero itself. This clearly distinguishes it from create_xero_invoice, create_xero_credit_note, and other creation tools, while also differentiating it from get/list quote tools.

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 gives explicit when and how guidance: it names list_xero_contacts as the source for contactId, instructs using create_xero_contact first if the contact doesn't exist, and explains when 'SENT' status is appropriate versus the default. It also tells the agent what to tell the user and what not to claim, leaving no ambiguity about the approval-gated workflow.

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 goes far beyond the annotations: it discloses that the tool queues a pending change, never touches Xero itself, cannot be self-approved, results in a Xero-side DRAFT, and that mismatches are refused only after human approval. It even documents an observed live failure (shorter NZ/UK period) that is not in Xero's spec. This is exceptional behavioral detail.

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, but almost every sentence carries a critical instruction or constraint, and key information is front-loaded in the first sentence. Some repetition exists between the description and the property-level schema descriptions (notably the NZ/UK whole-period rule and date ambiguity), which slightly reduces conciseness but does not undermine usefulness.

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 six parameters, no output schema, and a nuanced approval flow, the description covers everything an agent needs: parameter provenance, regional differences, the draft/approval lifecycle, the approvalUrl pointer, and what can go wrong. The absence of an output schema is compensated by explaining the key response element (approvalUrl) and the resulting Xero-side state.

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 100%, and the description still adds substantial meaning: the source of employeeId/payrollCalendarId, the requirement to use the SAME employee's payrollCalendarId, the AU ordinaryEarningsRateId rule, the NZ/UK earnings-rate lookup path, and the whole-period startDate/endDate requirement. It also flags ambiguous date interpretation, going well beyond the schema.

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 states a specific verb ('Proposes a DRAFT timesheet for one employee/period'), names the exact resource, and scopes it to Australian, New Zealand or United Kingdom organisations. It also makes explicit what the tool does NOT do ('does NOT touch Xero itself') and contrasts itself with post_xero_pay_run, making it clearly distinguishable from siblings.

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 gives strong contextual guidance: it names required prerequisite calls (list_xero_payroll_employees, list_xero_payroll_earnings_rates for NZ/UK), explains that a human must approve via the approvalUrl, and contrasts with post_xero_pay_run. It does not provide an explicit when-to-use vs. every sibling alternative, but the context is concrete and actionable.

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 goes far beyond the readOnlyHint annotation by explaining the flattened row structure, the meaning of SummaryRow, the organisation-specific currency behavior, the end-of-month reporting quirk, and the non-calendar financial-year caveat. This is rich behavioral disclosure that protects an agent from subtle misreporting.

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 but dense, and every major sentence adds operational value. It is front-loaded with purpose and safety, followed by output semantics and date/financial-year caveats. A few phrases, like the implementation-file reference, could be trimmed, but there is no real waste.

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 no output schema, the description compensates thoroughly by explaining result fields (columns, rows, rowType, currency, financialYear) and how to interpret them. It also addresses the most likely misunderstanding—calendar-year assumptions—making the tool safe to invoke and interpret without further probing.

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?

Although schema coverage is 100%, the description adds critical parameter meaning: date is interpreted as end-of-month, omitting date means today, and organisation is needed only for multi-organisation connections. It also connects the financialYear result field to parameter selection, which the schema alone does not convey.

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 opens with a precise statement: 'Balance Sheet report from Xero for the current organisation, as at a date.' It names the specific resource, the verb, and the temporal scope, and clearly distinguishes it from sibling financial-report tools like get_xero_profit_and_loss.

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 when to use the tool (when a balance sheet is requested as at a date) and clarifies its read-only nature, but it does not explicitly contrast it with alternative report tools or state when-not-to-use. There is useful operational guidance, but no explicit sibling-routing decision.

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 and openWorldHint=true. The description adds valuable behavior: it is read-only, and it warns not to restate currency or assume amounts match Invio's. This goes beyond annotations and sets correct expectations about data fidelity. 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?

Two sentences with high information density. The core purpose is front-loaded, and the caveats about ID source and currency are concise. It is not overly long, though the dash-separated clauses could be slightly more readable, but it earns its place with no fluff.

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 get-by-id tool with no output schema, the description adequately covers what the agent gets (full detail, line items), how to obtain the ID, and critical data-handling warnings. It does not cover error cases or pagination, but that is less critical for a single-record retrieval. Overall it is sufficiently complete.

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 covers organisation with a description but not creditNoteId. The description compensates for creditNoteId by specifying it must be a Xero CreditNoteID (GUID) from list_xero_credit_notes, not an Invio id. This adds meaningful semantic context beyond the schema's format field. With 50% schema coverage, the description carries the missing weight.

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 opens with a specific verb+resource: 'Full detail on one Xero credit note, including line items'. It clearly distinguishes from sibling list_xero_credit_notes (which returns summaries) and get_xero_invoice (different document type). The scope is unambiguous.

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?

It explicitly states the ID must come from list_xero_credit_notes and never an Invio id, giving a clear sourcing rule. It also implies use when you need full detail (including line items) of a single credit note, which separates it from list tools. The currency warning further guides correct usage without ambiguity.

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 only cover readOnly/openWorld, so the description carries the rest and does so richly: server-side summation, no intercompany elimination, account matching only by exact code/name, no currency conversion, all-or-nothing failure with no partial total, plan-limit exclusions surfaced in `warnings`, and the required wording ('combined', not 'consolidated').

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?

It is a single dense block, but nearly every clause carries load-bearing behavior an agent needs. It could be broken into labeled sections (dates, currency, failure mode, output) to improve scanning, but there is little pure filler.

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 no output schema, the description fully covers the return shape: `columns` and `values` alignment, Total last, null meaning 'no figure' rather than zero, `matchedBy` values, and the obligation to relay every `warnings` and `conflicts` entry plus the currency and period.

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?

Though schema coverage is 100%, the description adds real semantics beyond it: fromDate/toDate must be supplied together or not at all, the balance-sheet `date` is reported as at month end, `companies` must use exact display names from list_xero_organisations, and organisationDetails[].financialYear matters for one shared date range.

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 and scope: a side-by-side P&L or Balance Sheet for several Xero organisations, one row per account, one column per organisation. It explicitly contrasts itself with siblings by naming get_xero_profit_and_loss and get_xero_balance_sheet as the single-organisation 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?

Gives explicit when-to-use (multiple orgs, same base currency) and when-not (single organisation, mixed currencies, financial-year-end mismatches), plus named alternatives. It also spells out recovery behavior: only re-call with `companies` if the user agrees to drop the failing organisation.

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 read-only behavior, consistent with readOnlyHint, and adds critical behavioral context: amounts and currency come directly from Xero and must not be converted or assumed to match Invio. This goes beyond the annotation and helps prevent incorrect downstream usage.

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?

Two sentences with no filler. The primary purpose is front-loaded, and the critical ID-source constraint and currency warning are stated efficiently.

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 simple single-invoice retrieval tool with no output schema, the description covers the essential return content (full detail, line items) and provides necessary cautions. It is complete enough for an agent to use correctly, though it doesn't describe the exact response structure.

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?

The schema describes the organisation parameter but not invoiceId. The description compensates by explaining that invoiceId must be a Xero InvoiceID (GUID) from list_xero_invoices, adding meaning beyond the format field. This addresses the key parameter semantic gap.

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 returns full detail on one Xero invoice, including line items. It distinguishes itself from list_xero_invoices by specifying single-invoice scope and from other get tools by the resource type.

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?

It explicitly instructs that invoiceId must be a Xero InvoiceID from list_xero_invoices, not an Invio ID, which guides correct usage. It implies using this tool when full detail on one invoice is needed, though it doesn't explicitly contrast with sibling tools or state when not to use it.

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 readOnlyHint=true and openWorldHint=true, but the description adds substantial behavioral context beyond that: it refuses for non-supported countries, requires payroll configuration and admin access, has per-region limits, returns `truncated: true` when more employees exist, and flags negative balances with `negative: true`. It also explicitly states what the tool cannot tell (approval/payment/tax status). No contradiction with 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 long but every sentence carries necessary operational detail. It's front-loaded with the core purpose before diving into regional rules and edge cases. There is some redundancy (e.g., mentioning both 'read-only' and the annotation), but overall it is efficiently structured for the complexity it covers.

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 no output schema, the description must fully explain return values and interpretation. It covers units, negative balances, truncation, and what data is not provided. It also gives the agent authoritative instructions on how to report refusals and incomplete lists. Everything an agent needs to call and interpret the tool correctly is present.

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 100%, so baseline is 3. The description adds meaningful usage semantics: employeeId should come from list_xero_payroll_employees, omit for all employees, organisation only needed for multi-org connections, and includeInactive includes terminated employees. It also explains implications like regional caps tied to employeeId. This adds value above the schema, warranting a 4.

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 resource (employee leave balances), the verb (get), and the scope (by name, in Xero's tracking units). It distinguishes itself from other Xero tools by focusing on leave balances and explicitly listing what it does not do (e.g., cannot indicate approval/payment status). No ambiguity.

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 explicit when-to-use conditions: only for AU/NZ/UK organisations, requires complete payroll setup and admin access. Gives clear guidance on parameter usage (pass employeeId for one, omit for all), regional caps (Australia 100, NZ/UK 25), and how to interpret the `truncated` flag. Also tells the agent how to respond to refusals and missing data, which is exceptional.

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 and openWorldHint, but the description goes far beyond them. It explains truncation (`truncated: true`), the meaning of `unusableAmountCount`, the precise definition of overdue (strictly before `overdueAsOf`, not on the day), timezone handling, and explicitly warns against recomputing overdue with the agent's own clock. This is rich behavioral disclosure that prevents misinterpretation.

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 but every sentence earns its place: it covers purpose, comparative advantage, currency grouping, truncation, unusable amounts, overdue semantics, and timezone intricacies. It is front-loaded with the core purpose and structured logically, with no fluff. The density is justified by the tool's 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?

There is no output schema, so the description carries the full burden of explaining return semantics. It details aggregated per contact, currency handling, truncated flag, unusableAmountCount, overdueTotal, oldestDueDate, timeZone, and timeZoneSource, plus how to present each. It even warns about not treating excluded invoices as paid. This makes the tool fully usable without further assumptions.

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?

There is only one optional parameter (`organisation`), and the schema description already covers it at 100%. The description does not add extra meaning to the parameter itself, but it does discuss output semantics heavily. With full schema coverage, the baseline of 3 is appropriate; the description does not need to add more for this single parameter.

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 states exactly what the tool does: aggregates unpaid/partially-paid AUTHORISED sales invoices per contact to answer 'who owes this business money in Xero right now'. It specifies the invoice type (ACCREC) and status, and distinguishes itself from Xero's AgedReceivablesByContact report, making the purpose distinct from any sibling tool.

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 gives clear context: this tool is for organisation-wide receivable questions, chosen over a per-contact report. It implicitly indicates when not to use it (if you need a single contact's aged breakdown), but it does not explicitly reference sibling tools like list_xero_invoices or get_xero_invoice. Still, the usage context is clear and useful.

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 readOnlyHint, it discloses refusal behavior for unsupported countries and missing setup, region-dependent field differences, the connector-specific 20% threshold, ambiguous notPaidThisRun semantics, and the hard limitation about paid-out/tax-filing status. Nothing 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?

The core result is front-loaded in the first sentence, followed by the input shortcut, gates, and caveats. Although long, every sentence carries a distinct operational fact, and the capitalized limitation warning is justified by a common misinterpretation.

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 no output schema, the description carries the full burden of explaining return semantics, and it does so in detail: employee-level comparison fields, region-specific cost fields, refusal cases, and interpretation warnings. An agent can invoke it safely and phrase the result accurately.

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?

The input schema already documents both parameters at 100% coverage, so the baseline is 3. The description repeats the omit-payRunId rule but does not add new input-level meaning; its added value is concentrated in output interpretation.

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 the exact deliverable: all-in cost, DRAFT/POSTED status, and comparison against the previous pay run of the same payroll calendar. Names output markers like largeChange, newThisRun, and notPaidThisRun, making it unmistakable from list_xero_pay_runs or other getters.

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 explicit when-to-use guidance (omit payRunId for most recent), hard regional when-not gates (AU/NZ/UK only; refuses otherwise), and prerequisite gates (Payroll setup complete and admin access). It also instructs how to report a refused result rather than misreading it as empty data.

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 mark the tool as read-only and open-world, and the description goes well beyond them by warning that SummaryRow totals must not be double-counted, that supplying only one date is rejected, and that currency comes from the organisation's own Xero settings. It also discloses that the financial year may not match the calendar year and explains how to derive date parameters from financialYear.

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 but each sentence addresses a real failure mode, output nuance, or derivation rule, such as double-counting SummaryRows and deriving dates from financialYear. It is front-loaded with the core purpose and structured so that critical warnings are not buried.

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 no output schema, the description carries the full burden of explaining the result shape, and it names columns, rows, section, rowType, currency, and financialYear. It also tells the agent which period label to state when relaying figures and how to avoid calendar-year assumptions, making it complete enough for correct invocation and interpretation.

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?

Parameter schema coverage is 100%, so the baseline is 3; the description adds value by explicitly stating the together-or-omit-both rule, the rejection of a single date, and the 'omit both for current calendar month' convention. It does not add new meaning for the organisation parameter beyond the schema's guidance, so 4 is appropriate.

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 identifies the resource as a Profit and Loss report from Xero for the current organisation and date range, and adds detail about the columns and rows returned. It does not explicitly contrast it with sibling report tools such as get_xero_balance_sheet, so it stops short of full sibling 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 gives strong when-to-use context: it is a read-only report, requires paired dates or no dates, and explains the effect of omitting both dates. It does not name alternative tools or say 'use this instead of X', but the report name and read-only framing make the primary use case 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 mark readOnlyHint=true and the description affirms 'Read-only' without contradiction. It adds substantial behavioral context: a currency caveat (never restate or assume currency matches Invio's), error semantics for 401s (plan lacks Xero Projects or reconnect needed), and a summary of the data covered. This goes well 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 longer than average but every sentence carries operational value: ID sourcing, read-only confirmation, field coverage, currency rule, and error interpretation. The lead sentence front-loads the core purpose before the details. No filler or repetition of schema-restated facts.

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 enumerates the key return fields (task/expense totals, invoiced vs to-be-invoiced, deposits, credit notes) and highlights the currency and error behaviors. Combined with the input schema and annotations, an agent has everything needed to call this correctly and interpret results. The only minor omission is a full response structure, but the detailed field listing makes that unnecessary.

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 50% schema description coverage, the description compensates for the undocumented projectId by defining it as a Xero ProjectID GUID sourced from list_xero_projects and never guessed. The organisation parameter is already explained in the schema, so the description needn't repeat it. Together, both parameters are adequately documented.

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 states a specific verb and resource: full detail on one Xero Projects job, including cost and earned amounts. The phrase 'one Xero Projects job' clearly distinguishes it from list_xero_projects and from get_xero_invoice/quote/credit_note siblings by resource type. Clear and specific.

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 explicit source guidance for projectId (must come from list_xero_projects, never guessed) and confirms the operation is read-only. It also gives domain-specific error handling for 401s. However, it does not explicitly enumerate alternative tools or when not to use this one, though the resource distinction makes this mostly implicit.

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, and the description reaffirms 'Read-only' consistently. Beyond that, it adds crucial behavioral context: amounts are exactly as stored in Xero (never convert or assume match with Invio) and status SENT does not prove actual delivery. This goes well beyond the structured annotations and prevents misuse.

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 concise, with every sentence serving a purpose. It front-loads the primary function and return contents, then follows with crucial usage caveats and data interpretation notes. No redundant or filler content.

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 simple retrieval tool with one required parameter, no output schema, and annotations covering the read-only nature, the description covers all essential aspects: what is returned, how to obtain the correct quoteId, how to treat currency/amounts, and how to interpret status. Nothing an agent needs to call it correctly is missing.

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?

The schema provides a description only for the 'organisation' parameter, leaving quoteId without one (50% coverage). The description compensates by explaining that quoteId must be a Xero GUID from list_xero_quotes, not an Invio id, adding essential semantic meaning beyond the schema's format hint. It does not add details for organisation, but the schema already covers it adequately.

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 states a specific verb ('get') and resource ('Xero quote') and enumerates the returned contents (line items, title, summary, terms). It clearly distinguishes itself from list_xero_quotes by focusing on a single quote's full detail, and is easily differentiated from sibling get_* tools by naming the specific entity.

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?

It explicitly instructs that quoteId must be a Xero QuoteID from list_xero_quotes and never an Invio id, giving a clear prerequisite and source. It also warns about currency/amount assumptions and the meaning of status SENT, which are important for correct usage. It does not explicitly name alternative tools for other purposes, but the context is clear enough.

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 the readOnlyHint annotation, the description discloses rich behavioral details: the three groups' semantics, the 'expired' status and its immediate reporting before the background sweep, the presence of errorMessage/errorCode on failed rows, the result field on sent rows, and the approvalUrl linkage. It also explains truncation behavior and the maxOpenPendingChanges constraint. This far exceeds what annotations provide and fully informs the agent of side effects and edge cases.

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 (~200 words) but every sentence carries essential information given the tool's complexity (three groups, special statuses, truncation, quota). It is structured logically: purpose, group definitions, special cases, usage guidance, and actionable notes. No fluff; each sentence earns its place. For a zero-parameter tool that returns complex data, this is appropriately 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?

With no output schema and no parameters, the description carries the full burden of explaining the tool's behavior. It covers the three return groups, the meaning of fields like errorMessage, result, and approvalUrl, the expiration handling, truncation semantics, and the pending-changes quota. It leaves nothing an agent needs to call and interpret this tool 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?

There are no parameters (input schema is empty), so the baseline is 4. The description doesn't need to add parameter semantics, but it does clarify the output structure (groups, fields, statuses) which indirectly helps understand what the tool returns. Since there are no parameters, no additional value is required, and the description appropriately omits parameter details.

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 states a specific verb ('lists') and resource ('changes YOU (or another assistant) have proposed against Xero'), and explicitly defines three output groups (pending, needsAttention, history). It distinguishes itself from sibling tools like approve_xero_pending_change and the creation tools by focusing on listing proposed changes across all organisations. The inclusion of 'across every organisation this token may reach' adds a precise scope that leaves no ambiguity.

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 explicit when-to-use conditions: 'Use this when asked "what am I waiting to approve" or "what happened to X", after drafting several changes in one conversation to summarise what is now queued, or before drafting another change against the same invoice/contact to check whether an earlier one is still unresolved.' It also gives a negative directive: avoid telling the user to check Xero for history, since this tool covers it. This is clear and actionable.

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 the readOnlyHint and openWorldHint annotations, the description discloses crucial behaviors: accounts with `code: null` genuinely lack a code and must be referenced by exact name, invented codes are rejected before proposal, and the connector has distinct fallback behaviors for authorising invoices. It also clarifies that taxType is only a hint and that archived accounts may be refused, all of which add significant non-obvious context.

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 but each sentence earns its place by introducing a distinct caveat or rule needed for correct usage. It is front-loaded with the core purpose and read-only note, then progressively covers edge cases. Slight redundancy with the annotation's read-only statement and occasional wordiness prevent a perfect score, but the structure is clear and logical.

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 read-only list tool with one optional parameter and no output schema, the description is exceptionally complete. It covers how to handle null codes, how to use the results with invoice tools, when to omit accountCode, the taxType hint, and ACTIVE status preference. Everything an agent needs to call this tool correctly and integrate its output into downstream steps is present.

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?

The single optional `organisation` parameter is fully documented in the schema (100% coverage), and the description does not add any additional meaning about it beyond the schema. The description's 'This organisation's' wording implicitly references the current/default organisation, but the schema already explains when the parameter is needed, so the description provides no extra value here.

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 identifies the resource as 'This organisation's chart of accounts from Xero' and states the action explicitly as listing, with a specific read-only qualifier. It distinguishes itself from sibling create/update tools by emphasizing it is the source of truth for real account codes, and the title itself is unambiguous.

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 gives explicit when-to-use instructions: 'Use this BEFORE proposing an accountCode on a create_xero_invoice or update_xero_invoice line item,' and details what to do when no account fits, including omitting accountCode and letting the connector fill defaults. It also provides concrete alternatives for draft vs authorised invoices and warns about archived accounts, leaving no ambiguity about when to prefer this tool.

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 the readOnlyHint and openWorldHint annotations, the description discloses unique behavioral traits: accountsReceivableOutstanding/Overdue are passed through from Xero and must not be summed across contacts, and status is relayed unfiltered so archived contacts may appear. This helps the agent avoid a real data-integrity mistake and does not contradict 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 front-loaded with the core action and then gives two important caveats, each substantive. It is somewhat long and the 'Read-only; nothing is created or changed' sentence is redundant with the readOnlyHint annotation, but the remaining content is dense and worth including.

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 no output schema, the description covers the main invocation hazards: receivables fields need no aggregation, status may be ARCHIVED, and the correct sibling exists for aggregates. It does not spell out the full response shape or this tool's own pagination behavior, but it gives enough for correct use alongside the well-covered schema.

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 the baseline is 3: all three parameters already have clear descriptions in the schema. The prose adds context about the organisation and contact status but does not add new parameter-level semantics beyond what the schema provides.

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 states a specific verb ('List') and resource ('contacts (customers and/or suppliers) from Xero'), and scopes it to the current organisation. It is clearly distinguishable from sibling tools like list_xero_accounts or get_xero_outstanding_receivables because it names the resource and primary purpose directly.

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?

It explicitly warns against using this tool to answer 'who owes me the most' and directs the agent to get_xero_outstanding_receivables instead. It also gives context-level guidance: surface the contact's Xero status before suggesting the contact for invoices or updates. This is concrete when-not and alternative routing.

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 the readOnlyHint annotation, the description adds substantial behavioral detail: pagination limits and pageCount honesty, per-credit-note currency independence, remainingCredit semantics, and the appliedFilters echo requirement. These are exactly the non-obvious behaviors an agent needs to avoid incorrect assumptions.

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 but each sentence carries operational value, and the most important scoping and behavioral warnings are front-loaded. The only minor redundancy is restating read-only behavior already present in annotations, but this does not significantly bloat the text.

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 no output schema, the description compensates by explaining key response concepts: page size, pageCount, remainingCredit, appliedFilters, and currency. It also covers filter semantics and points to the sibling tool for deeper detail. An agent has enough context to call this correctly and interpret the result responsibly.

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?

Although schema coverage is 100%, the description adds meaning beyond the schema: it explains inclusive date boundaries, the exact-match vs partial-match distinction between reference and referenceContains, the 'use exactly one, never both' rule, and the practical meaning of ACCRECCREDIT vs ACCPAYCREDIT. This materially improves correct parameter usage.

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 opens with a specific verb and resource ('List credit notes from Xero') and immediately clarifies the two credit-note types. It also distinguishes itself from get_xero_credit_note by pointing to that tool for full line-item detail, so an agent can tell them apart.

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 gives clear context: optional filters, read-only behavior, and an explicit pointer to get_xero_credit_note when full line-item detail is needed. It does not explicitly enumerate when not to use this tool versus create_xero_credit_note, but the read-only statement and sibling context make the boundary clear enough.

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 and openWorldHint=true, and the description reinforces this with 'Read-only; nothing is created, sent or changed.' It adds valuable behavioral context beyond the annotations: each invoice carries its own currency, results are paginated at 100 per page, and the response echoes appliedFilters. It does not contradict the annotations. A small gap is that it doesn't describe the exact response shape, but the description carries substantial behavioral context.

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 well-organized: it front-loads the core purpose, then filters, then read-only guarantee, then currency/pagination/appliedFilters caveats, then the sibling pointer. Every sentence earns its place, though it is slightly long and could be tightened without losing meaning.

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 list tool with 8 optional parameters, no required parameters, and no output schema, the description covers the key operational caveats: pagination, currency independence, appliedFilters echo, and the sibling for detail. It doesn't describe the exact return fields, but the absence of an output schema and the presence of a sibling detail tool make this acceptable. The description is complete enough for an agent to call it 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 100%, so the schema already documents all 8 parameters. The description adds meaning beyond the schema by clarifying the reference/referenceContains mutual exclusivity ('use exactly one, never both'), the inclusive date range semantics, and the pageCount caveat. It doesn't restate every parameter, but it adds the cross-parameter constraints that the schema alone doesn't express.

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 states a specific verb ('List') and resource ('invoices from Xero for the current organisation'), and immediately distinguishes the two invoice types (ACCREC sales vs ACCPAY bills). It also names the sibling get_xero_invoice for full line-item detail, so an agent can tell this list tool apart from the detail tool without opening either 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?

The description gives explicit when-to-use guidance: use get_xero_invoice for full line-item detail on one invoice, and it explains the optional filters (status, date range, reference) with clear semantics. It also warns about pagination ('if pageCount shows more pages than were returned, say so') and about relaying appliedFilters, which is actionable usage guidance beyond the schema.

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 only declare readOnlyHint and openWorldHint, so the description carries the burden of behavioral detail. It explains account-wide behavior, restricted-token visibility, the plan-limit distinction, and the complete set of possible `status` values with their meanings, going well 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 but dense and front-loaded: the core purpose comes first, followed by consequential edge cases and status meanings. Every sentence earns its place by carrying operationally important guidance rather than filler.

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 no output schema, the description must explain return semantics, and it does: it names the `organisations` and `status` fields, explains `withinPlanLimit: false`, and enumerates all status values and their fixes. It is complete enough for an agent to know what to expect and how to react to every outcome.

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?

There are zero parameters, so the baseline is 4 per the rubric. The description adds relevant context by explicitly stating the tool takes no `organisation` argument and is account-wide, which clarifies why parameter-free invocation is correct.

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 and resource: 'List the Xero organisations this connector token is currently authorised to read AND that this call is permitted to know about.' It clarifies it returns names only, never internal IDs, and is account-wide, which distinguishes it from the many list_xero_* siblings that target other resources.

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 says when to use it: to find the exact organisation name to pass as `organisation` on another tool when the connection reaches more than one organisation. It also gives operational when-not-to guidance by explaining that organisations with `withinPlanLimit: false` will be refused and should be described plainly rather than attempted.

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 and openWorldHint; the description builds on that by revealing important non-obvious behaviors: amounts are in the linked invoice's currency, invoiceId/invoiceNumber appear only when applied to an invoice (not credit notes/prepayments/overpayments), and results echo applied filters. 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 long but every sentence earns its place: purpose, alternative, currency caveat, invoiceId behavior, pagination handling, and filter echo. It is logically ordered and front-loaded with the core action before the caveats.

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 no output schema, the description shoulders the burden of explaining return behavior, and it covers the essentials: pagination limit, pageCount guidance, currency semantics, and when invoiceId/invoiceNumber are present. An agent has everything needed to call this tool and interpret its results 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 100%, so the schema already documents every parameter thoroughly. The description adds a useful high-level summary of the filter options and inclusive date semantics, but most parameter detail remains in the schema; this is adequate without pushing above baseline.

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 and resource ('List payments already recorded in Xero'), then scopes it precisely: current organisation, optional filters for status, invoice, and date range. It also distinguishes itself from create_xero_payment, so an agent can tell them apart without opening the 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?

Explicitly says this is read-only and nothing is created or changed, and names the sibling to use instead (create_xero_payment). It also gives operational guidance such as relaying pagination state and echoing appliedFilters rather than assuming completeness.

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 and openWorldHint=true, and the description adds meaningful context beyond them: refusal behavior (refuses plainly rather than returning an empty list when prerequisites are missing), prerequisites (Payroll setup complete, admin access at connection time), geographic scope (AU/NZ/UK), and a 100-rate pagination limit. No contradiction with 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?

Long (~200 words) but every sentence earns its place given the regional complexity, prerequisites, and fallback logic. Front-loaded with the core purpose before diving into usage guidance. The only minor inefficiency is that the AU/NZ/UK scope is stated early and the geographic detail is re-emphasized in the timesheet context.

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 no output schema, the description carries the return-format burden and does so adequately: it names the fields returned and the rate-type variants. It also covers prerequisites, refusal behavior, regional scope, pagination, and a default-selection rule. Nearly complete; the only minor gap is not describing the exact response envelope or whether rates are ordered.

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% — both parameters (page, organisation) are already documented in the schema. The description adds the pagination limit context ('Returns up to 100 rates for the requested page') which slightly enriches the page parameter, but mostly the schema carries the semantic load, so baseline 3 is appropriate.

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 (list) + resource (payroll earnings rates) and enumerates the returned fields (name, earnings type, rate type, rate). It distinguishes itself from sibling tools by the three-way rate interpretation (per-unit, multiplier, fixed amount) and by explicitly contrasting with list_xero_payroll_employees' ordinaryEarningsRateId, so an agent can tell them apart without opening schemas.

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?

Exceptionally explicit: names when to use (Australia needs a DIFFERENT rate; NZ/UK timesheets) and when not to (Australia ordinary hours fall back to employee's own ordinaryEarningsRateId). Names the alternative tools (list_xero_payroll_employees, create_xero_timesheet) and even prescribes a default selection (RegularEarnings) when the user hasn't specified. Nothing is left to inference.

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 only declare readOnlyHint and openWorldHint, so the description carries the behavioral burden. It goes far beyond that by disclosing region-based refusal, setup/admin prerequisites, derived employment status for NZ/UK, Australia-only super fund data, explicit non-return of TFN/bank/address, and pagination behavior.

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 but every sentence carries distinct operational guidance. It is front-loaded with the core purpose and then systematically covers constraints, regional differences, exclusions, and pagination without redundancy.

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 no output schema, the description must explain return semantics, and it does thoroughly: what fields are returned, what is derived, what is never returned, what cannot be known, and how pagination works. An agent has enough information to call the tool correctly and interpret results.

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 100%, so the baseline is 3. The description adds meaningful context for page (full page may be incomplete, request next page) and includeInactive (active-only default), which goes beyond the schema's basic field 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 opens with a precise statement of what the tool returns: payroll employees with name, employment status, and Australia-only super fund and earnings rate ID. This clearly distinguishes it from sibling list tools like list_xero_payroll_earnings_rates and list_xero_pay_runs.

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 gives explicit when-to-use context: read-only, for AU/NZ/UK organisations only, with requirements around Payroll setup and admin access. It also states what the tool cannot answer (payment status, ATO/IRD/HMRC lodgement), but it does not name alternative sibling tools for those cases.

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 and openWorldHint=true, so the description doesn't repeat that. It adds valuable behavioral context: the tool requires Xero Payroll setup and payroll administrator access, and it refuses plainly rather than returning an empty list when those are missing. It also mentions pagination (up to 100 per page). These are important behavioral disclosures 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 long but information-dense, covering purpose, prerequisites, usage guidance, and return limit. The critical usage guidance (use before leave application) is placed prominently. There is some redundancy with the schema's parameter descriptions (e.g., 'Omit for page 1') but overall it is well-structured for an agent reading it before a call.

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 that the tool is a simple list with two well-documented parameters and readOnlyHint=true, the description covers all critical operational aspects: prerequisites, failure mode, usage guidance, and return limit. The absence of an output schema is compensated by listing the returned fields (name, paid, shows on payslip, active) and the pagination limit. An agent has everything needed to call it 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 coverage is 100% and both parameters have descriptions in the schema. The description adds context for the 'organisation' parameter ('Only needed if this connection reaches more than one organisation') and hints at pagination. It doesn't fully explain pagination (e.g., that there could be multiple pages), but it is sufficient given the schema already documents 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 tool lists payroll leave types with specific attributes (name, paid status, payslip visibility, active status). It explicitly notes the geographic scope (AU/NZ/UK) and the read-only nature. It is easily distinguishable from siblings like list_xero_payroll_earnings_rates and list_xero_payroll_employees.

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 context: 'Use this BEFORE drafting a leave application (create_xero_leave_application)' and explains why a real leaveTypeId is needed. It also instructs to ask the user when no specific leave type is named rather than guessing, and warns about the refusal behavior when prerequisites are missing.

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 and openWorldHint, but the description goes well beyond them: it discloses regional refusal behavior, prerequisites that cause plain refusals, ordering, regional differences in reported fields, pagination limits, and the tool's inability to confirm actual payment or tax reporting. No contradiction with 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 long but every sentence carries essential operational information: purpose, region restrictions, prerequisites, field semantics, sibling routing, pagination, and limitations. It is front-loaded with the core purpose and then layers caveats in a logical order, with no filler.

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?

There is no output schema, so the description carries the full burden of explaining return values. It covers the fields returned, regional variants (netPay vs totalCost), pagination, refusal behavior, and important limitations. An agent has enough to call this tool correctly and interpret results.

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 both parameters are already documented in the schema. The description adds some useful context, such as 'Most recent first' for page and the single-organisation omission guidance, but it does not substantially extend the schema's parameter explanations. Baseline 3 is appropriate.

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 states a specific verb and resource: it lists the organisation's recent pay runs with period, payment date, status, and totals. It also distinguishes itself from get_xero_pay_run_summary by explicitly naming that sibling for per-employee detail, so an agent can tell them apart.

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 gives explicit routing guidance: 'Use get_xero_pay_run_summary for per-employee detail and a comparison against the previous pay run.' It also specifies when the tool will refuse rather than return data, covering region, Payroll setup, and administrator access prerequisites, which helps an agent decide whether to call it.

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?

Although annotations already declare readOnlyHint=true, the description goes further: it emphasizes 'nothing is created or changed', warns about per-project currency and the risk of assuming it matches the user's business currency, discloses that results include a headline estimate/invoiced/still-to-invoice figure, and explains the meaning of a 401-style error (plan may lack Xero Projects or the connection needs reconnecting). This adds rich behavioral context beyond the annotations and is directly actionable for an agent.

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 long but every sentence earns its place: definition, read-only assurance, filter options, currency caveat, result content, alternative tool, and error interpretation. It is front-loaded with the core purpose and safety, then progressively adds operational detail, with no filler or repetition of schema content.

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 there is no output schema, the description compensates by describing what each result contains (headline estimate/invoiced/still-to-invoice figure, currency-named values) and where to go for deeper detail. It also covers error handling, filtering, and multi-organisation setup. For a list tool with five optional parameters and no return schema, the description provides everything an agent needs to select and invoke it 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 coverage is 100%, so the baseline is 3. The description adds meaningful provenance: contactId is 'a Xero ContactID from list_xero_contacts', and organisation is only needed when the connection reaches more than one organisation, which clarifies parameter semantics beyond the raw schema. It does not repeat every parameter, but the added guidance is valuable and non-redundant.

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 opens with a specific verb and resource: 'List job/project-costing projects from Xero Projects for the current organisation', and clarifies what these projects represent with concrete examples. It explicitly distinguishes the tool from the sibling get_xero_project by pointing to it for the full breakdown, making the purpose unambiguous against a large family of list_xero_* tools.

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 gives clear context: when you need a filtered list of projects with headline figures, use this tool; when you need the full cost-and-earned breakdown on one project, use get_xero_project instead. It also tells the agent where to source contactId (from list_xero_contacts) and how to handle multi-organisation connections, leaving no ambiguity about when and how to invoke it.

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 and openWorldHint=true, but the description adds substantial behavioral context beyond that: currency is independent of the user's business currency, Xero does not report total counts for this endpoint, and the result echoes applied filters. These are critical behavioral traits the agent must know to avoid misinterpretation. No contradictions with 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 long but every sentence earns its place. It front-loads the core purpose and filters, then addresses pagination, currency, appliedFilters, and the sibling pointer in a logical order. There is zero fluff; each clause conveys a distinct, necessary fact.

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 optional parameters, no output schema, and unusual pagination behavior, the description covers everything the agent needs to call it correctly: the filter semantics, inclusive date boundaries, the no-total-count caveat, the 100-per-page limit, the appliedFilters echo, and the currency warning. It even points to get_xero_quote for line-item detail. Nothing essential is missing.

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 the baseline is 3. The description adds value beyond the schema by clarifying that date ranges are inclusive, that fromDate/toDate filter the issue date while expiryFromDate/expiryToDate filter the expiry date, and that quoteNumber is an exact match. It does not repeat every parameter but covers the nuances an agent would otherwise miss.

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 states a specific verb and resource ('List quotes from Xero') and enumerates the optional filters (status, contact, quote number, date ranges). It also explicitly distinguishes itself from the sibling get_xero_quote ('Use get_xero_quote for full line-item detail on one quote'), making it clear this tool is for listing summaries, not details. No ambiguity about what it does.

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 routes to the sibling get_xero_quote for line-item detail, telling the agent when to use that alternative. It also states this tool is read-only and that it returns up to 100 quotes per page, guiding the agent on pagination. The note about relaying appliedFilters is a direct usage instruction. This is explicit, actionable guidance.

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 goes well beyond the annotations by disclosing that the tool is non-reversible once approved, that it requires explicit user confirmation, and that it does not actually execute the posting or payment—it merely proposes a change. It also clarifies the underlying API limitations. These details significantly enhance the agent's understanding of side effects and safety considerations, fully complementing the destructiveHint and readOnlyHint 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 long but every sentence carries essential safety and operational information. While it could be trimmed, the verbosity is justified given the irreversibility and potential consequences of the action. The core purpose is stated upfront, and the critical constraints are front-loaded; the length is a necessary trade-off for completeness.

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 and the absence of an output schema, the description fully explains the tool's behavior: it queues a pending change, requires human approval, and mentions the approvalUrl field in the response. It also covers edge cases like refusing non-AU pay runs and clarifies that it does not handle payroll lodgement or payments. No essential operational detail is missing.

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?

The input schema already provides descriptions for all three parameters (payRunId, confirm, organisation), and the description essentially repeats these details without adding new information. Since schema coverage is 100%, the description adds no extra semantic value beyond what the schema already states. It correctly reinforces constraints like confirm must be true and payRunId must be DRAFT, but does not contribute beyond that.

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: proposing to move an existing DRAFT pay run to POSTED, with a explicit constraint that it is for Australian organisations only. It distinguishes itself from creation tools by emphasizing it operates on an existing pay run and states it does not touch Xero directly. This leaves no ambiguity about what the tool does.

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 when-to-use guidance: only for Australian organisations, and it refuses for NZ and UK. It also clarifies that this tool only queues a pending change that requires human approval, and it is not for lodging with the ATO or paying employees. This effectively routes the agent to use this tool only under the right conditions and explains prerequisites like obtaining payRunId from list_xero_pay_runs.

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 annotations already mark the action as destructive and idempotent, and the description adds meaningful behavioral detail: the change never reaches Xero, there is nothing to undo, the action cannot be reversed, and the optional reason is not stored or displayed by Invio. This materially exceeds what the structured annotations alone convey and does not contradict them.

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 the primary effect and every sentence earns its place for a destructive, irreversible operation. However, some sentences are long and slightly repetitive when emphasizing irreversibility and consent, so it is not maximally 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?

The description is complete for an agent to invoke the tool correctly: it explains the preconditions, what counts as valid consent, where pendingChangeId comes from, the meaning of confirm, the irreversibility, the storage behavior of reason, and the manual alternative. Given the high stakes and no output schema, there are no meaningful 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?

The input schema already documents all parameters at 100% coverage. The description adds important usage semantics: confirm must be true and only after explicit consent, pendingChangeId must come from list_pending_changes or a draft-creating tool and never be invented, and reason is not persisted. This goes beyond the schema even though much of it reinforces what the schema says.

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 and resource: it rejects a pending change that was proposed to Xero but never actually sent. It clearly describes the consequence (discarded, never reaches Xero, irreversible) and is easily distinguishable from the sibling approve_xero_pending_change and list_pending_changes.

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 explicit when-to-use guidance: only after the user has clearly said, in their own words, to discard this specific change. It also tells the agent what not to do (never infer consent from silence or topic changes), suggests calling list_pending_changes first if the summary isn't in conversation, and notes that the manual Invio Settings path remains available.

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 explicitly discloses that no Xero change happens until a human approves, that the approval link is in the response's approvalUrl field, and that the agent cannot approve it itself. It also states the partial-update behavior: only provided fields change. These details go well beyond the annotations and are essential for correct use.

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 the core purpose and each sentence covers a distinct operational fact: approval requirement, approvalUrl location, contactId source, and field-change semantics. There is no filler or redundancy.

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 no output schema, the description provides enough context for correct invocation: it explains the pending-change workflow, the approval mechanism, the required source for contactId, and the at-least-one-field constraint. An agent can confidently select and call this tool without needing additional undocumented details.

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 100%, so the baseline is 3. The description adds meaningful cross-parameter guidance by requiring at least one of name, emailAddress, or phone, and by reinforcing that omitted fields remain unchanged. This supplements the per-field schema 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 opens with 'Proposes a change to an EXISTING Xero contact', giving a specific verb and resource while distinguishing it from create_xero_contact. It further clarifies that this tool queues a pending change rather than directly mutating Xero, making its role unambiguous.

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?

It clearly states when to use the tool: for existing contacts, with contactId sourced from list_xero_contacts, and requiring at least one of name, emailAddress, or phone. It does not explicitly name alternatives like create_xero_contact for new contacts, but the emphasis on 'EXISTING' and the approval workflow makes the intended usage 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 the annotations, the description reveals critical behavior: the tool does not touch Xero directly, queues a pending change requiring human approval, and only changes the fields explicitly provided. It also discloses region-specific phone/address behavior and that conflicting phone/mobile values for NZ/UK are refused before drafting.

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, but nearly every sentence carries a necessary constraint or warning for a complex, region-sensitive tool. There is some repetition of the 'only fields you provide change' and 'nothing else' ideas, so it is not maximally concise, but it remains well-structured and front-loaded.

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 8 parameters, a nested address object, region-specific behavior, and an approval workflow, the description covers everything an agent needs: source of employeeId, minimum required fields, partial update semantics, approval URL, region rules, and explicit exclusions. No output schema exists, but the description adequately explains the pending-change result.

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?

Although schema coverage is 100%, the description adds essential semantics: partial update behavior ('only the fields you provide change'), the source requirement for employeeId, the AU/NZ/UK phone field distinction, and the fact that state is Australia-only while suburb is New Zealand-only. These meanings go well beyond the raw schema.

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 opens with a precise verb and resource: 'Proposes a change to ONE employee's first name, last name, email, phone/mobile, or home address' and immediately narrows scope with 'STRUCTURALLY NOTHING ELSE' and the AU/NZ/UK organisation qualifier. This clearly distinguishes it from sibling tools like update_xero_contact or update_xero_invoice.

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?

It explicitly tells the agent when to use it ('Provide at least one of firstName, lastName, email, phone, mobile, or address'), where to get required data ('employeeId must come from list_xero_payroll_employees'), and what it cannot do ('This tool has NO field for bank details, tax numbers...'). It also clarifies the approval workflow and that the agent cannot approve the change itself.

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 much more than annotations: it does not change Xero directly, it requires human approval via approvalUrl, omitted lineItems will be deleted on replacement, lineAmountTypes reinterpretation changes the total, and bare numeric dates are interpreted day-first. These side effects and constraints add significant safety-relevant context beyond readOnlyHint and destructiveHint.

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 but front-loaded with the core approval semantics, then organizes constraints, replacement behavior, and date rules into clear blocks. Every sentence carries actionable guidance with no filler or repetition of what annotations already state.

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 absence of an output schema and the high-stakes propose/approve behavior, the description covers prerequisites, approval flow, parameter pitfalls, and the response's approvalUrl field. An agent has all the information needed to invoke the tool correctly and communicate the outcome honestly to the user.

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?

Although schema coverage is 100%, the description adds decisive meaning for ambiguous parameters: bare numeric date resolution ('I read 9/8 as 9 August'), lineItems as full replacement, currency validation against organisation setup, and lineAmountTypes reinterpreting existing amounts. It also establishes the omit/leave-unchanged behavior for several optional fields.

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 opens with a specific verb+resource: 'Proposes a change to an EXISTING Xero invoice' and immediately distinguishes it from create_xero_invoice and approve_xero_pending_change by clarifying it only queues a human-approved change. It further scopes the tool to DRAFT/SUBMITTED invoices and states what it cannot change, making its role unambiguous.

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?

It tells the agent to check status first via get_xero_invoice, states the only valid statuses, and gives an explicit when-not with the alternative: 'void it and create a new one' for contact/type changes. It also provides clear directives on when not to send lineAmountTypes and how to handle ambiguous bare-numeric dates.

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