Invio Xero MCP

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

Annotations already mark this as destructive, non-read-only, open-world, and idempotent. The description adds crucial context beyond them: the write is real and live, the agent cannot retry a failed write itself, it must relay the actual Xero outcome or failure verbatim, and approval through Invio Settings remains equivalent.

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 purpose and immediately follows with the critical approval and execution warnings before the outcome instructions. It is somewhat verbose and repeats consent cautions already present in the schema, but the length is defensible for a destructive live-ledger write.

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 high-stakes destructive mutation with no output schema, the description covers approval preconditions, the need to inspect the pending change first, execution behavior, failure handling, outcome reporting, and the equivalent Settings path. An agent has enough information to call it correctly and report results 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?

Schema coverage is 100%, and both parameters are already fully documented in the schema, including confirm's const true requirement and pendingChangeId provenance. The description reinforces consent semantics and says to call with confirm: true, but it largely repeats what the schema already provides rather than adding new parameter meaning.

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 approves an already-proposed pending change and immediately executes it. It enumerates the draft-creating tools it applies to and explicitly distinguishes itself as the one tool in the connector that writes to a live Xero ledger.

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 and when-not-to-use guidance: only after the user has clearly approved THIS specific change in their own words, never speculatively, and never without first showing them the change summary via list_pending_changes. It also covers hesitation and questions by telling the agent to wait.

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?

Goes well beyond annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false): explains it never creates in Xero on its own, requires human approval, and that the agent cannot self-approve. This is critical behavioral context for a mutation tool.

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?

Front-loaded with the key caveat that this only queues a pending change. Slightly repetitive ('it does NOT create anything' / 'never will on its own' / 'you have no way to approve it yourself') but every sentence carries meaningful constraint.

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?

No output schema, but the description explains the approvalUrl response field and contactId result, plus downstream dependency ordering. Complete enough for a mutation tool; lacks detail on rejection behavior or what happens to queued changes.

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

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

Schema coverage is only 25%; description compensates by stating name is the only required field, but phone and emailAddress remain undocumented in both schema and description. Partial compensation for the coverage gap; no format or syntax added.

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 object - 'Proposes adding a new contact (customer or supplier)' - and immediately clarifies it does not create in Xero directly. Distinguishable from create_xero_invoice (which consumes the resulting contactId).

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?

Explains the approval workflow clearly: queues a pending change requiring human approval via approvalUrl, and states contactId can feed create_xero_invoice or update_xero_invoice only after approval. No explicit guidance versus update_xero_contact, but the 'new contact' scope makes it inferable.

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, it discloses the central behavior: no direct Xero write occurs, a human must approve via Invio, the connector cannot self-approve, and even an approved result is only a DRAFT credit note. It also explains currency validation refusal and date-conversion risks.

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 approval-proposal behavior and structured around key risks such as contacts, currency, tax handling, and dates. It is lengthy and occasionally repetitive, but most sentences carry important behavioral guidance for this high-risk mutation tool.

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 approval workflow, no output schema, and 8-parameter mutation surface, the description is complete enough for correct invocation. It covers prerequisites, approval semantics, draft-only outcome, currency handling, tax interpretation, and date-conversion hazards.

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 already high at 88%, but the description adds meaningful semantics for date ambiguity, currency validation, contactId provenance, lineAmountTypes tax interpretation, and ACCRECCREDIT versus ACCPAYCREDIT. Some parameter guidance is repeated from the schema, but the added cross-field context is substantial.

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 proposes creating a credit note in this Xero organisation. It immediately distinguishes the action from true creation by saying it only queues a pending change and never touches Xero itself.

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 usage conditions: use list_xero_contacts before contactId, use create_xero_contact and wait for approval if the contact does not exist, and rely on the approvalUrl response field for human approval. It also clearly says not to describe the result as done, issued, or created.

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 only say readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true; the description supplies the real behavioral context on top of that. It explains the human-approval gate with the approvalUrl, the fact that this connector never emails the customer, how the accountCode is auto-filled or refused, and how a currency mismatch is refused with the real list. None of that 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 purpose is stated up front and the DATES block is clearly signposted, but the text is roughly 600 words and repeats the bare-numeric-date warning that the date and dueDate schema fields already carry. Repetition weakens focus on a definition this long.

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 10-parameter mutation with a human-approval step and no output schema, the description covers the whole lifecycle: the pending change, the approval link, the default status, the tax-type handling, the currency refusal, and the date-format edge case. An agent has everything it needs in order to call this tool correctly and to tell the user what happens next.

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 already 90%, so the baseline is 3, and this description earns an extra point by explaining how the parameters interact: AUTHORISED requires a real accountCode on every line, and currency is checked against the organisation's configured currencies. Much of the material is repeated from the field descriptions, but the cross-field consequences add real meaning.

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 invoice in this Xero organisation") and immediately distinguishes itself from a direct write: "it does NOT create anything in Xero itself, and never will on its own." It also implicitly separates this tool from approve_xero_pending_change by saying a human must approve the queued 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?

It gives explicit when-to-use rules: contactId must come from list_xero_contacts and never be invented, and create_xero_contact should be used first if the contact does not exist. It also draws a sharp line between the default AUTHORISED state and the DRAFT state ("Pass status \"DRAFT\" only when the user actually says they want to check or edit it in Xero first"), which is exactly the alternative-choice guidance an agent needs.

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 the non-read-only, non-destructive, non-idempotent, open-world profile, and the description goes well beyond them: it queues a pending change that never touches Xero on its own, cannot self-approve, surfaces an approvalUrl, refuses for terminated employees, and leaves no residual Xero-side draft after approval. The only gap is that it doesn't state failure/refusal shape beyond 'refuses plainly' or what a partial/duplicate submission does for a non-idempotent mutation.

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 behaviour is front-loaded in the first clause and most of the length is load-bearing operational detail rather than filler. It is still a single dense semicolon-chained block where the prerequisite and units instructions could be separated for scanability.

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 usefully names the approvalUrl return field and explains the end-to-end approval lifecycle, which is what an agent most needs. It is undercut slightly by the dangling DATES reference the schema points to, which the description never supplies, so date-format ambiguity is left unresolved despite being flagged.

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, but the description adds real meaning on top: employeeId must be an ACTIVE employee id, description is shown to the human approver (max 50), title is AU-only and silently ignored elsewhere, and no units field exists because Xero derives units. However, the startDate/endDate schema entries instruct the agent to 'Follow the DATES instruction in this tool's description' and no such DATES guidance exists in the description, leaving ambiguous numeric dates unaddressed.

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 ('Proposes a DRAFT leave application for one employee/period') plus the exact regional scope (AU/NZ/UK). It also explicitly contrasts itself with create_xero_timesheet and create_xero_pay_run, so an agent can place it among siblings without opening another 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?

Gives explicit prerequisites (employeeId from list_xero_payroll_employees, leaveTypeId from list_xero_payroll_leave_types), a negative constraint ('never invented', must be ACTIVE), and an explicit anti-instruction ('Do NOT compute or pass an hours/units figure'). It also names the human-approval step that must follow, leaving little 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?

Richly discloses behavior beyond the annotations: the call only queues a pending change, a human must approve via the approvalUrl in the response, the agent cannot approve, and even after approval only a DRAFT journal exists in Xero. It also names the validation rule and failure mode (unbalanced entries rejected before queueing with the exact imbalance reported).

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?

Front-loaded with the most important fact (it is a proposal, not a write), but the description is very long and repeats material already in the schema field descriptions, notably the date ambiguity warning and the signed lineAmount convention. The tax paragraph is dense 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?

Given a mutation tool with no output schema, the description covers prerequisites (list_xero_accounts), approval lifecycle, validation rules, tax semantics, date interpretation, and user-facing communication obligations. Nothing an agent needs in order to call it correctly appears to be 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?

Adds substantial meaning over the schema despite 80% coverage: lineAmount is signed with debit/credit convention and the consequence of getting it backwards, lines must sum to zero, lineAmountTypes only affects lines that name a taxType, and date ambiguity for bare numeric formats has an explicit resolution policy rather than a guess.

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 ('Proposes a manual journal') and immediately defines the resource with concrete examples (reallocating an expense, bank fee, write-off). It also disambiguates from sibling write tools by stressing it 'does NOT create anything in Xero itself', so an agent can tell it apart from create_xero_invoice or create_xero_payment.

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 clear operational guidance: get accountCode from list_xero_accounts, never invent one, never call this expecting immediate posting, and tell the user it needs their approval. It contrasts a journal line with an invoice line to explain the schema difference. It stops short of naming when an agent should pick a journal over e.g. create_xero_invoice for a given real-world scenario.

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?

Adds substantial context beyond annotations: the pending-change/human-approval model, that a payment has no draft state and is applied immediately on approval with no connector-level reversal, live re-checking of AUTHORISED status and AmountDue at draft and approval time, and the future-date prohibition. This far exceeds the destructiveHint/openWorldHint hints.

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?

Front-loads the most important fact (proposal, not execution) and organizes details into clear blocks (approval, accounts, DATES). Given the destructive, irreversible nature the length is largely justified, though there is some repetition between the description and the schema's parameter descriptions.

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?

Complete for a destructive, non-idempotent mutation tool: it covers the approval/irreversibility model, currency and amount constraints, account selection, date ambiguity, and partial-payment behavior. With no output schema, the approvalUrl return field is even referenced, so nothing an agent needs to call or narrate 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?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: the day-first locale convention that governs how to interpret bare numeric dates, and the exact-one-of accountCode/bankAccountName rule keyed to the org's code:null behavior. Some overlap with schema prose, but the locale disambiguation is genuine added value.

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 ('Proposes recording a payment against an existing, AUTHORISED invoice') and immediately clarifies the crucial distinction that it does NOT touch Xero but queues a pending change. An agent can distinguish this from create_xero_invoice and other create_* siblings 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?

Explicit routing rules: invoiceId must come from list_xero_invoices or get_xero_invoice, bank account from list_xero_accounts (type BANK), and clear when-to-use-accountCode-vs-bankAccountName logic based on whether code is null. It also states the approval prerequisite and that the agent cannot self-approve.

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 say readOnlyHint=false and destructiveHint=false; the description supplies the far more consequential context: the call queues a pending change requiring human approval via the approvalUrl field, the agent cannot self-approve, and the resulting Xero object starts as a DRAFT. It also discloses a hard regional limitation the annotations cannot express. No contradiction with the annotation set.

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?

Front-loaded with the core fact (drafts a proposal, does not touch Xero) and every sentence carries real information - regional refusal, approval gate, ID provenance, draft state, next step. Some redundancy ('does NOT touch Xero itself, and never will on its own') and a single dense paragraph cost it the top mark.

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 two-parameter mutation tool with no output schema, the description covers everything an agent needs: what is created, what state it lands in, who must approve, where the approval link lives, the regional restriction, and the follow-up tool. Nothing material is left to inference.

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 earns above that by explaining the negative space - Xero computes period start/end and payment date from the calendar, so those parameters are deliberately absent - and by reinforcing the provenance rule for payrollCalendarId. It adds meaning rather than restating 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?

States a specific verb and resource ('Proposes a DRAFT pay run for one payroll calendar') with scope (AU/NZ orgs) and immediately distinguishes it from the write-side sibling by noting it does not touch Xero itself. Read alongside list_xero_pay_runs and post_xero_pay_run in the sibling list, an agent can pick correctly without opening a schema.

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

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

Explicit when-not-to-use ('Refuses plainly for the United Kingdom' with the reason), explicit prerequisite (payrollCalendarId must come from list_xero_payroll_employees, never invented), and explicit hand-off to post_xero_pay_run as a separate irreversible step. Alternatives and exclusions are both named, not inferred.

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?

Goes far beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false): it discloses the human-approval queue, that the agent cannot self-approve, that approvalUrl in the response is the approval link, that no email/delivery happens at any status, that currency is validated against configured org currencies and refused with the real list, and that accountCode is auto-filled only when exactly one default exists. That is precisely the mutation-risk context annotations cannot carry.

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?

Front-loaded correctly: the single most important fact (this creates nothing until a human approves) is the opening clause. It is long, and some beats repeat ('and never will on its own' appears twice, the bare-date caution appears in both description and three schema fields), but given the ambiguity and irreversibility risks, most sentences do earn their 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 13-parameter mutation queued behind human approval with no output schema, the description covers what an agent needs to call it correctly and to speak to the user accurately — proposal summary content, the approval URL, the 'do not say created/sent/delivered' instruction, date conversion, tax-inclusivity, and the currency refusal path. Nothing material 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 coverage is already 92%, so the baseline is 3; the description nonetheless adds meaning the schema does not — the locale convention that this account writes day-first, so a bare '9/8' means 9 August, plus the requirement to state the reading aloud and to ask when the user's own wording conflicts. The lineAmountTypes and currency explanations largely restate the schema enums/patterns, which keeps it from a 5.

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 ('proposes creating a new quote in this Xero organisation') and immediately disambiguates what the tool does NOT do — it does not create anything in Xero, it queues a pending change. That distinguishes it cleanly from real-write siblings like create_xero_invoice and from read siblings like get_xero_quote/list_xero_quotes.

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 routes the agent: contactId must come from list_xero_contacts, and if the contact doesn't exist, propose create_xero_contact first and wait for execution. It also gives conditional guidance for status (SENT only when the user explicitly wants that label), currency, lineAmountTypes, and optional fields — when to set them versus let Xero default.

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?

Goes well past the annotations: it discloses that the call creates only a queued pending change, that a human must approve before Xero is touched, that the agent cannot self-approve, that the resulting record is a Xero-side DRAFT (unlike post_xero_pay_run), and that invalid earnings-rate/calendar combinations fail only at approval time. Annotation hints (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false) are consistent and the description adds the missing causal 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?

Front-loads the most important fact (draft, human approval required, Xero untouched) and every sentence carries operational content. It is long and single-block, and repeats the NZ/UK whole-calendar-period rule that already appears twice in the schema, which costs some readability.

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 6-param, no-output-schema mutation tool it covers the approval lifecycle, return field (approvalUrl), region branches and known live-observed quirks well. However, the schema says to 'Follow the DATES instruction in this tool's description' for ambiguous numeric dates, and no such instruction exists here — leaving a real ambiguity-handling gap.

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 still adds cross-parameter logic — region-dependent selection of earningsRateId, reusing the same employee's ordinaryEarningsRateId for AU, and the whole-payroll-period rule for NZ/UK dates. Much of this duplicates the schema's own field descriptions, so it is additive but not uniquely informative.

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 ('Proposes a DRAFT timesheet for one employee/period') plus the supported regions and the explicit scope limit ('does NOT touch Xero itself'). It also distances itself from the sibling post_xero_pay_run, so an agent can tell the two apart 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?

Gives clear prerequisites and ordering: employeeId and payrollCalendarId must come from list_xero_payroll_employees (same employee), and NZ/UK require list_xero_payroll_earnings_rates first. It also names the human-approval path (approvalUrl, approve_xero_pending_change context) and contrasts behaviour with post_xero_pay_run. It stops short of an explicit 'do not use this when...' exclusion, but the routing guidance is otherwise concrete.

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 simple 'readOnlyHint: true' annotation by explaining deep behavioral quirks, such as how Xero flattens nested data into 'columns' and 'rows,' and the complex logic regarding financial year definitions.

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?

While long, the description is highly efficient. Every sentence is dedicated to solving a specific ambiguity (date interpretation, data structure, terminology), preventing potential operational errors during invocation.

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 complexity of financial reporting and Xero's unique data structure, the description is extremely complete. It covers the data source, the date reporting methodology, and the required output style.

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 provides vital semantic meaning beyond the schema. It specifies that the 'date' field implies an 'as-at end of month' report, and clarifies the role of the 'organisation' parameter in multi-tenant scenarios.

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 tool's purpose is immediately clear: retrieving a Balance Sheet report from Xero. It is specific and distinct from other listed sibling tools like P&L or general report queries.

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 crucial usage guidelines by detailing how Xero interprets the request (e.g., stating that date input results in an 'as at the end of month' report) and strictly forbidding common calendar-based phrasing.

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, and the description adds genuinely new behavioral context: amounts and currency are as Xero stored them and must not be restated or assumed to match Invio's. It does not cover failure behavior (e.g., not-found or cross-org access), which keeps it short of 5.

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?

Three tight sentences, front-loaded with what is returned, then the ID constraint, then the currency caveat. Every sentence carries decision-relevant information, though the currency warning is slightly verbose.

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?

No output schema exists, so the description correctly states what is returned (full detail plus line items) and pre-empts the main downstream misinterpretation about currency and amounts. Missing only edge-case behavior such as not-found handling or multi-org ambiguity.

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?

At 50% schema coverage the description must compensate, and it does for creditNoteId by naming the exact provenance and format (Xero CreditNoteID GUID from list_xero_credit_notes, never an Invio id). The organisation parameter's conditional multi-org rule lives only in the schema, so the description does not fully close the coverage 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?

States a specific verb and resource ('Full detail on one Xero credit note') plus the scope it returns ('including line items'), which separates it cleanly from list_xero_credit_notes and get_xero_invoice. An agent knows exactly what it gets back.

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 routes the agent to list_xero_credit_notes as the source of the ID and warns that an Invio id will not work, which is the main misuse failure mode. No explicit 'when not to use' or comparison to sibling getters like get_xero_quote, but the context is clear enough to select correctly.

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 give readOnlyHint/openWorldHint; the description carries the real behavioral burden and does so thoroughly: server-side arithmetic that must not be re-derived, no intercompany elimination, no account mapping, no currency conversion, single-currency refusal with per-org currency listing, all-or-nothing failure with no partial totals, and reporting of `warnings`/`conflicts`. This is exactly the context annotations cannot supply.

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?

Front-loaded correctly — the identity of the tool, its read-only nature and the not-a-consolidation warning come before any mechanics. It is a dense, long block, though, and some rules (the date-pairing rules for profit_and_loss and balance_sheet) restate the schema verbatim and could be trimmed 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 five-parameter, output-schema-less aggregation tool whose failure modes are non-obvious, the description covers everything an agent needs: date semantics, matching semantics, null-versus-zero, currency constraints, partial-failure policy, output field meaning, and the correct user-facing vocabulary. There is no meaningful gap left for the caller to guess.

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, and much of the description's parameter text (date pairing, end-of-month behaviour, display names, 30-org cap) duplicates the schema verbatim. It does add genuine meaning beyond the schema, though: that `companies` selection is bounded by the org's base currency, that restricted team members only ever see their own orgs, and that `matchedBy`/`values` positionally line up with `columns` with null meaning no figure rather than zero.

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?

Opens with a specific verb-resource-scope statement: side-by-side P&L or Balance Sheet across several Xero organisations, one row per account, one column per org plus Total. It explicitly contrasts itself with get_xero_profit_and_loss and get_xero_balance_sheet, so an agent can pick the right sibling without opening any schema.

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

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

Names when to use it (multi-org) versus the single-org siblings, plus concrete decision rules: omit `companies` for all orgs, pass `companies` by display name to narrow, retry with a reduced `companies` list only if the person agrees to drop the failed org. It even covers the 'different financial year ends' case and tells the agent to ask first.

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, so 'Read-only' is partly redundant. The description still adds real context beyond annotations: it specifies that currency and amounts are exactly as Xero stored them and must not be restated or assumed to match Invio's values, which is a meaningful data-fidelity caveat for an agent relaying numbers.

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?

Three short sentences, front-loaded with what is returned, then the id constraint, then the data-fidelity warning. Every sentence earns its place; only the 'Read-only' clause is slightly wasted given the annotation.

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 does enough to set expectations: full invoice detail including line items, with currency/amounts as stored by Xero. For a two-parameter read tool with annotation coverage, the remaining gap (exact fields returned, error behavior for bad ids) is minor.

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 50%: `organisation` is documented in the schema, but `invoiceId` carries only a uuid pattern with no prose. The description fills exactly that gap, insisting the value is a Xero InvoiceID GUID sourced from list_xero_invoices and not an Invio invoice id — critical disambiguation. It says nothing extra about `organisation`, but the schema already handles 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?

States a specific verb and resource ('Full detail on one Xero invoice, including line items') and implicitly contrasts with list_xero_invoices by naming it as the source of the id. An agent can tell this is the single-record detail read versus the list sibling without inspecting 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?

Explicitly tells the agent to obtain `invoiceId` from list_xero_invoices and warns against an Invio invoice id, which routes usage clearly. It doesn't state exclusions against other siblings (e.g. get_xero_credit_note, get_xero_quote), so it stops short of full alternative coverage.

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/openWorldHint, it discloses supported countries, refusal behavior for unsupported countries or incomplete payroll setup/admin access, pagination and truncation limits, and negative balance semantics. It also states what the tool cannot determine, such as leave approval or tax reporting.

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 and every major clause carries useful operational information, but it is a single dense paragraph with several long run-on sentences. The content earns its place, though segmentation would improve readability.

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 lack of an output schema and the tool's regional/pagination complexity, the description is complete: it covers return shape, units, negative balances, truncation, prerequisites, and limitations. An agent has enough information to call it correctly and interpret common edge cases.

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, but the description adds meaningful employeeId semantics: where to get it, what omitting it means, and how regional caps affect fetching all employees. It does not add much for organisation or includeInactive beyond the schema, so it is not a 5.

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 the exact resource: employee leave balances by name and units, with annual/personal/other leave types. It clearly distinguishes this from leave-request approval/payment tools and points to list_xero_payroll_employees as the source for employeeId.

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 usage rules: pass employeeId for one employee, omit it for every active employee, and use employeeId beyond Australia's one-page cap. It also explains the NZ/UK 25-employee cap, what truncated:true means, and how to respond when payroll setup or admin access is 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?

readOnlyHint=true is consistent with the stated "Read-only". Beyond annotations, the description discloses the pagination/scan limit behind `truncated`, the exclusion of invoices with no reliable amount due, the strict-before rule for overdue, and the timezone source fallback to UTC — all behavioural traits annotations do not carry.

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 purpose is front-loaded in the first clause, and every subsequent sentence carries real semantics rather than filler. It is dense and runs long — several 'do not do X' warnings could be tightened — but nothing is redundant.

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 must explain the return shape, and it does: `currencies`, `truncated`, `overdueTotal`, `overdueAsOf`, `timeZone`, `timeZoneSource`, `unusableAmountCount`, `oldestDueDate`. It also warns against recomputing overdue from the agent's own clock, which is exactly the failure mode this tool would otherwise invite.

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 one optional parameter (`organisation`), and the schema already documents it at 100% coverage, including the omit-when-single-organisation guidance. The description adds nothing further to the parameter itself — correct baseline is 4 for a near-zero-param tool.

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 plain-language question the tool answers ("Who owes this business money in Xero right now, and how much") and then specifies the exact data source and filters: aggregated per contact, unpaid/partially-paid ACCREC invoices with Status AUTHORISED. This is specific enough to distinguish it from list_xero_invoices and from Xero's own receivables reporting, which it explicitly names.

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 names the alternative (AgedReceivablesByContact) and states the concrete reason it loses here — that report requires naming ONE contact per call and cannot answer an organisation-wide question. It also tells the agent how to interpret edge cases (`truncated`, multiple currencies, `unusableAmountCount`) rather than leaving them to guess.

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 real behavioral load and does: region gating, the Payroll-setup and payroll-admin prerequisites, the fact that failure is a hard refusal not an empty result, and the important disclosure that largeChange is the connector's own 20% threshold rather than Xero's. It also draws explicit epistemic boundaries (cannot distinguish terminated vs unpaid leave vs not rostered; cannot report payment or ATO/IRD/HMRC filing status), which prevents confidently wrong answers.

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 lead clause is well front-loaded (cost, status, comparison), but the rest is a single dense paragraph of ~250 words where region field differences, prerequisite failures, and interpretation caveats run together without segmentation. Nearly every sentence is useful, but the lack of structure makes it harder to scan than the content warrants.

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 describe the return shape and does so thoroughly: per-employee net pay and net change, largeChange flagging, newThisRun/notPaidThisRun sets, and the wages/tax/super versus totalCost split by region. Combined with the refusal semantics, an agent has everything needed to call it and interpret or explain the result 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 are already documented in-schema (payRunId omit-for-latest, organisation only when multi-org). The description's 'Omit payRunId for the most recent pay run' largely restates the schema rather than adding syntax, defaults, or edge cases beyond it, so the baseline 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 very specific verb+resource: the all-in cost of one pay run, its DRAFT/POSTED status, and a per-employee comparison against the previous run of the same calendar. It is unmistakable against siblings like list_xero_pay_runs (enumeration) and create_xero_pay_run/post_xero_pay_run (mutation), and it even names the comparison sets (newThisRun, notPaidThisRun) it returns.

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 concrete selection rules: omit payRunId for the most recent run, only pass organisation when the connection spans multiple orgs, and it plainly states the tool refuses outside AU/NZ/UK and when Payroll setup or admin access is missing, instructing the agent to report the refusal rather than imply empty data. It points to list_xero_pay_runs and list_xero_payroll_employees for related context, though it never explicitly says 'use list_xero_pay_runs to enumerate runs first' — the sibling routing is implied rather than stated.

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; the description adds substantive behavior: currency is sourced from the organisation's own Xero settings and must be stated when relaying figures, a lone date argument is rejected rather than silently widened, and the organisation's financial year may not be the calendar year with financialYear in the result resolving it. It also warns against double-counting SummaryRow alongside the rows it totals — real, non-obvious semantics.

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 critical scoping rules are front-loaded, but the together-or-omitted rule appears in the description and again in both parameter descriptions, and the parenthetical cross-reference '(see each argument's own description for why)' plus the changelog artifacts '(added 11 September 2026 - see lib/xero/financial-year.ts)' are internal noise that does not help an agent invoke the tool.

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-shape burden and does so: it explains columns as period labels, rows as flattened sections with rowType semantics, currency provenance, and financialYear contents. Combined with the invocation constraints, an agent has enough to call it and to report 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 coverage is 100%, so baseline is 3; the description earns above that by tying fromDate/toDate to financialYear's dates as the authoritative source for named periods, which the schema does not say. The `organisation` parameter is left entirely to the schema, and the columns/rows discussion describes returns rather than inputs.

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 names a specific verb+resource (retrieve the Profit and Loss report from Xero) and its scope (current organisation, date range), which is clearly distinct from the create/list/approve siblings. It stops short of naming the adjacent reporting siblings (get_xero_balance_sheet, get_xero_group_report), so an agent must infer which report type fits a given request.

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

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

Explicit constraints on invocation: fromDate and toDate must be supplied or omitted together, omitting both yields the current calendar month, and 'this financial year'/'year to date' must be derived from the returned financialYear rather than the calendar year or country. No guidance on when to pick this report over the balance sheet or group report siblings, which keeps it from a 5.

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?

'Read-only' merely restates readOnlyHint, but the description adds substantial context the annotations cannot: the 401 may mean the Xero plan lacks Projects or the connection needs reconnecting, and every money figure carries its own Xero currency that must not be restated. Those are non-obvious failure and interpretation behaviors an agent would otherwise get wrong.

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?

Front-loaded with purpose, with constraints and currency/error caveats after. The long enumeration of cost and invoice fields is dense but earns its place as a stand-in for the missing output schema; it could be tightened by grouping the invoiced/to-invoice pairs.

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 deliberately names the return fields (totalTaskAmount, totalExpenseAmount, projectAmountInvoiced, deposits, credit notes) so the agent knows what the response contains. ID sourcing, currency semantics, and failure modes are all covered.

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 50% (only `organisation` is documented in the schema); the description compensates by pinning `projectId` to a Xero ProjectID GUID sourced from list_xero_projects. It does not address `organisation`, but the schema already explains the single-vs-multi-org rule.

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?

Opening clause gives a specific verb and resource ('Full detail on one Xero Projects job') plus the scope of what is returned (cost, earned). It is clearly distinguishable from the sibling list_xero_projects, which is named as the only legitimate source of the ID.

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 states that `projectId` must come from list_xero_projects and 'never guessed', which is a real usage constraint. It also tells the agent how to interpret a 401 rather than accept a generic failure, though it never states when to prefer a sibling over this tool beyond the ID-sourcing rule.

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?

Well beyond what readOnlyHint/openWorldHint already declare: it warns that currency and amounts are authoritative as Xero stored them and must never be restated or converted, and it clarifies that a SENT status does not prove delivery. Both are non-obvious behavioral caveats an agent could not infer from annotations or schema.

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?

Three sentences, each carrying distinct payload: purpose/contents first, then the ID constraint, then data-fidelity and status caveats. No filler and the primary purpose is 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?

With no output schema, the description still tells the agent what comes back (line items, title, summary, terms) and how to interpret amounts and status. Nothing an agent needs to call this correctly and interpret the result 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 documents only 50% of parameters (organisation has a description; quoteId has format/pattern but no prose). The description compensates by explaining what quoteId actually is and where to obtain it, which is the more important half. The organisation parameter is left entirely 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?

Opens with a specific verb+resource+scope: "Full detail on one Xero quote", and enumerates what detail means (line items, title, summary, terms). This cleanly separates it from list_xero_quotes and the many get_xero_* siblings that target different 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?

The ID provenance rule ("must be a Xero QuoteID (a GUID) from list_xero_quotes, never an Invio id") effectively routes the agent to the listing tool first and blocks a common wrong-ID failure. It gives clear use context but no explicit when-not-to-use case, so it stops short of a 5.

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?

Annotations only declare readOnlyHint/openWorldHint; the description adds real behavioral context beyond them: null `code` values are genuinely absent in Xero, invented codes are rejected pre-proposal, ARCHIVED accounts may be refused by Xero and are refused outright by this connector on AUTHORISED invoices. `taxType` is scoped as a per-account default rather than the org's exhaustive rate list.

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?

Front-loaded with what the tool is and its read-only nature, then the operational rules. The long middle sentence following the null-`code` explanation is dense and could be split, but every sentence carries actionable content rather than repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by explaining the shape of the returned data (`code`, `name`, `taxType`, `status`) and how each field should be used downstream. An agent has everything it needs to call this and interpret the 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?

There is one parameter (`organisation`) at 100% schema description coverage, so the schema already carries its meaning (display name, omit when single org). The description adds nothing about it, 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?

Opens with a specific verb+resource: this organisation's chart of accounts from Xero, plus an explicit read-only statement. It is immediately distinguishable from the many create_/update_/get_ siblings because it frames itself as the lookup source those tools depend on.

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 ordering ('Use this BEFORE proposing an accountCode on a create_xero_invoice or update_xero_invoice line item'), names the fallback when nothing fits (omit accountCode), and explains what happens in each case (DRAFT filled by human, AUTHORISED auto-filled or prompted). It also names create_xero_payment's bankAccountName as the place to use `name` instead of `code`.

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 carry readOnlyHint=true, so the 'Read-only; nothing is created or changed' sentence is largely redundant. What does add value beyond annotations is the disclosure that accountsReceivableOutstanding/Overdue are raw per-contact figures from Xero (not to be aggregated by the caller) and that `status` is relayed unfiltered, including ARCHIVED, so a listed contact may not be usable. Pagination behaviour and the page cap are left to the schema, keeping it from a 5.

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?

Front-loaded with purpose and read-only status, then the cross-tool disambiguation, then the status caveat. Every sentence carries information, but the final status sentence is long and slightly repetitive of the includeArchived wording; it could be tightened without losing the warning.

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 naming the key returned fields (accountsReceivableOutstanding/Overdue, status) and their provenance and semantics, and by warning about archived entries. Nothing an agent needs to call this correctly or interpret the response 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 goes beyond it by explaining the practical consequence of `includeArchived` (archived contacts are never filtered out once included, and their `status` must be surfaced) and by defining the `status` vocabulary (ACTIVE/ARCHIVED). It does not clarify the `page` or `organisation` semantics further, which the schema already covers.

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 contacts ... from Xero') plus scope ('customers and/or suppliers', 'current organisation'), and explicitly routes the aggregation case to get_xero_outstanding_receivables. An agent can distinguish it from create_xero_contact/update_xero_contact and the receivables tool without opening any schema.

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

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

Gives an explicit when-not: never sum accountsReceivable* across contacts for 'who owes me the most', use get_xero_outstanding_receivables instead. It also gives an explicit downstream usage rule for `status` (mention it before suggesting a contact be invoiced or updated) and states includeArchived defaults to active-only, so the agent knows the shape of the result 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?

Beyond the readOnlyHint annotation it adds real context: nothing is created or changed, the 100-per-page cap with pageCount guidance, the warning to relay appliedFilters rather than memory, and the caveat that each credit note carries its own currency. It does not clarify auth/scope requirements or rate limits, so it stops short of a 5.

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?

Front-loaded with purpose and type definitions, and every sentence carries operational content (pagination, currency caveat, appliedFilters, sibling pointer). It is a single dense paragraph that slightly restates the type meanings already in the schema enum descriptions, keeping it from a 5.

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?

No output schema exists, yet the description explains the key return semantics (remainingCredit, appliedFilters, pageCount) so an agent can interpret results correctly. For an 8-param, filter-only read tool this covers everything needed to call and interpret it.

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 schema already documents all 8 params; the description nonetheless adds value by reinforcing inclusive fromDate/toDate semantics, the exact-vs-partial reference distinction, and the mutual exclusion rule. It adds marginal but genuine meaning on top of the schema rather than repeating it wholesale.

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?

Specific verb+resource ('List credit notes from Xero for the current organisation') with an immediate disambiguation of the two types (ACCRECCREDIT vs ACCPAYCREDIT) including their business meaning. It also names the sibling it is not (get_xero_credit_note), so an agent can route 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?

Explicit exclusivity rule: 'use exactly one, never both' for reference vs referenceContains, with the condition that selects each ('when you know the reference verbatim' vs 'only know part'). It also routes to get_xero_credit_note for line-item detail and states that omitted filters mean 'both types' / 'every status'.

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, yet the description adds substantive behavior: a 100-per-page cap, pageCount-driven pagination meaning it is not necessarily the full list, and the appliedFilters echo that must be relayed rather than reconstructed. It also warns that each invoice carries its own Xero currency, which the annotations cannot convey. Only slight deduction for restating 'read-only; nothing is created' which the annotation already covers.

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?

One dense paragraph that front-loads the core purpose and document types before filters and caveats, with no filler sentences. It loses a point for duplicating schema-level guidance (reference vs referenceContains exclusivity) and for packing several agent-directed instructions into a single run-on block.

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 eight optional parameters and no output schema, the description carries the burden well: it describes the return shape (per-invoice currency, pageCount, appliedFilters) and the pagination ceiling, which is exactly what an agent needs to interpret results without an output 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%, and the schema already documents inclusivity, the YYYY-MM-DD pattern, the mutual exclusivity of reference/referenceContains, and the organisation-omission rule. The description largely restates these rather than adding new meaning such as reference collation behavior or pageCount signaling thresholds, so baseline 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 (list invoices from Xero) and immediately enumerates the two document families (ACCREC sales invoices vs ACCPAY bills), so an agent understands exactly what the result set contains. It also names the sibling get_xero_invoice as the detailed-single-record alternative, distinguishing itself without the schema being opened.

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

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

Explicit routing is given: use get_xero_invoice for full line-item detail on one invoice. It also states the exclusive choice between reference and referenceContains ('use exactly one, never both') and the condition selecting each. Filter-omission semantics (omit status for every status, omit type for both) tell the agent when not to narrow.

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?

Goes well past readOnlyHint/openWorldHint: discloses the 100-per-page cap, the pageCount-may-exceed-returned caveat, the appliedFilters echo, the currency-of-linked-invoice trap, and that payments may be applied to credit notes/prepayments/overpayments rather than invoices. These are real behavioral traits an agent would otherwise get wrong.

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?

Six sentences, each carrying distinct information, with the read-only assertion and sibling routing front-loaded. Dense but every clause (currency, invoice-application, pagination, appliedFilters) survives a 'does it earn its place' test; minor trim possible in the invoice-application sentence.

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?

No output schema exists, so the description must carry return-shape burden and does: page size, pageCount, appliedFilters echo, conditional invoiceId fields, and currency semantics. An agent has everything needed to call and interpret 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 baseline is 3. The description adds meaning beyond it: fromDate/toDate both inclusive, status filter is AUTHORISED vs DELETED, and invoiceId/invoiceNumber presence is conditional on payment application type. It does not restate the page/organisation semantics the schema already covers.

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) plus resource (payments recorded in Xero) and scope (current organisation), then explicitly contrasts with create_xero_payment. An agent can distinguish it from all 35 siblings without reading any schema.

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

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

Explicitly routes the write case elsewhere: 'to RECORD a new payment, use create_xero_payment instead.' Also gives the condition for filtering (status, invoice, date range), so when-to-use and when-not-to-use are both covered.

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, and the description adds substantial context beyond them: region eligibility (AU/NZ/UK), the requirement that Xero Payroll setup be complete and the connecting user have held payroll administrator access, and the important failure-mode disclosure that a hard refusal must not be reported as an empty list. It also states the 100-item page cap.

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 purpose and region scope are front-loaded, and the longer sentences carry genuinely load-bearing content (auth prerequisites, failure semantics, default-rate rule). It is dense to the point of being a single wall of text with limited visual separation, which slightly hurts scanability, but little is redundant.

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 no output schema and full schema coverage, the description covers everything an agent needs: what comes back, which regions work, what preconditions can cause failure, how to report a refusal, and how to pick a default rate. No material gap remains.

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 both page and organisation are already documented, establishing a baseline of 3. The description adds useful return-shape context tied to pagination ('up to 100 rates for the requested page'), which helps the agent size its paging strategy beyond what the schema alone conveys.

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?

Opens with a specific verb+resource and enumerates the returned fields (name, earningsType, rateType, rate), including the rateType-dependent semantics of the rate value. It clearly separates itself from list_xero_payroll_employees by explaining that this tool exposes the full rate list rather than an employee's single default rate.

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 routing rules: use list_xero_payroll_employees' ordinaryEarningsRateId for an employee's own ordinary hours, and use this tool when a DIFFERENT rate is needed (overtime, allowance). It also mandates calling this before drafting NZ/UK timesheets because each line needs a real earningsRateId, and prescribes a default selection rule (earningsType=RegularEarnings) when the user names no rate.

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; the description adds substantial context beyond them: regional API coverage, two distinct hard-refusal preconditions (payroll setup complete, connecting user held payroll admin), the active-only filter, per-country caveats on how employment status is derived, super fund data being Australia-only, and explicit non-disclosure of TFN, bank account and address. This is exactly the extra behavioural context annotations cannot carry.

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?

Front-loaded with what is returned and the region gate, and almost every sentence carries operational consequence. It is dense rather than padded, though the 'still accurate, just not Xero's own word for it' aside and the repeated 'this refuses plainly' framing 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?

With no output schema, the description compensates by enumerating the returned fields, the optional super fund data, the omitted sensitive fields, and the pagination shape. The main gaps an agent would hit — unsupported regions, incomplete payroll setup, absent NZ/UK super data, and partial pages — are all pre-answered.

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 schema already documents all three parameters including includeInactive's semantics. The description adds one genuinely useful fact not in the schema — the 100-records-per-page page size — but says nothing further about page bounds or the organisation 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?

Opens by naming the exact resource (this organisation's payroll employees) and the specific fields returned (name, employment status, super fund presence, ordinary earnings rate id), which cleanly separates it from siblings like list_xero_payroll_earnings_rates and list_xero_payroll_leave_types. Scope qualifiers (AU/NZ/UK, active-only default) sharpen the identity further.

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

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

Explicit about when it applies (three supported countries), when it refuses and how to report that refusal rather than implying zero employees, how to use includeInactive, and how to handle a full page of 100. It also states outright what the tool cannot answer (payment status, ATO/IRD/HMRC lodgement), which steers the agent away from misusing it. No sibling is named, but no viable alternative exists for this resource.

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?

Goes well beyond the readOnlyHint/openWorldHint annotations: discloses geographic scope (AU, NZ, UK), two prerequisites (completed Payroll setup, connector user holding payroll admin access at connect time), a failure mode that refuses plainly instead of returning an empty list, and a 100-item page cap. The refusal guidance is especially valuable because the agent is told how to interpret and report the error.

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?

Front-loads what is returned, then prerequisites, then the call-ordering rationale — a logical sequence where each sentence carries information. It is on the long side and the 'ask rather than guessing' point is restated twice, which keeps it from a 5.

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 listing the returned attributes and the page-size limit, and it covers prerequisites, failure behavior, and how to proceed downstream. An agent has everything needed to call it correctly and interpret an error.

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%, with both 'page' (1-based, omit for page 1) and 'organisation' (omit when only one org) fully documented inline, so baseline 3 applies. The description adds only the page-size cap of 100, which is useful but marginal.

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 (this organisation's payroll leave types) and enumerates the fields returned (name, paid, payslip visibility, active status). It is clearly distinguishable from sibling tools like list_xero_payroll_earnings_rates and create_xero_leave_application without opening any schema.

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

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

Explicitly names the downstream tool it precedes (create_xero_leave_application) and why (a real leaveTypeId is required and cannot be guessed from a name). It also gives a negative rule: when the user has not named a specific leave type, ask rather than assuming a common name exists for every 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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses regional eligibility, payroll setup and admin-access prerequisites, plain refusal behavior, pagination size, field availability differences by region, and an important limitation about POSTED pay runs. It even warns not to interpret absent regional fields as zero.

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 and every sentence carries operational value: scope, regional constraints, refusal semantics, field differences, alternative tool, pagination, and a critical limitation. There is no filler or repeated schema text beyond what is necessary for safe interpretation.

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 supplies the return shape, regional field differences, pagination behavior, refusal semantics, and the important inability to determine whether a POSTED pay run has actually been paid or reported. An agent has enough context 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?

The schema already documents both parameters at 100% coverage, including page numbering and the organisation display name. The description adds only limited parameter-specific meaning, notably the 100-pay-run page size and most-recent-first ordering, so it does not need to carry the parameter explanation burden.

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 recent pay runs) and immediately names the key returned fields: period, payment date, status, and organisation-wide totals. It also distinguishes itself from the sibling get_xero_pay_run_summary by scoping that sibling to per-employee detail and prior-period comparison.

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 names the alternative tool and the condition that selects it: use get_xero_pay_run_summary for per-employee detail and comparison against the previous pay run. It also gives clear usage constraints by region and explains how to interpret refusal cases rather than treating them as empty payroll 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 declare readOnlyHint=true, and the description corroborates with "Read-only; nothing is created or changed." It adds genuine behavioral context annotations cannot carry: every project has its own currency independent of the Invio business currency, and a 401/unauthorized failure may mean the Xero plan lacks Projects or the connection needs reconnecting rather than a generic error. It stops short of describing pagination behavior beyond the schema fields.

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?

Front-loaded with purpose and scope before the caveats, and nearly every clause carries operational value. Slightly overlong: the currency warning is stated twice ("Each project carries its OWN currency..." and "every money figure names its own currency alongside its value"), which could be tightened into one sentence.

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 describing what each result carries (headline estimate/invoiced/still-to-invoice figures, per-project currency) and by pre-explaining the most likely failure mode. An agent has everything needed to call this correctly and interpret the response.

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, but the description adds real meaning: contactId is tied to a Xero ContactID obtainable from list_xero_contacts, and state is characterized as INPROGRESS/CLOSED with the omit-for-both default. page and pageSize are left entirely to the schema, which documents them 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?

States a concrete verb and resource ("List job/project-costing projects from Xero Projects for the current organisation") and immediately grounds it with what a project represents ("the jobs or engagements time, expenses and invoices get tracked against"). It also explicitly distinguishes itself from the sibling get_xero_project, which returns the full breakdown for one project.

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 routing: this tool for the list view, get_xero_project for the full cost-and-earned breakdown on a single project. It also states the filtering conditions (one contact, one state, or neither) and where a valid contactId comes from (list_xero_contacts).

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 adds important behavioral details: quotes carry their own currency from Xero, the endpoint does not report total counts, exactly 100 results may mean more pages exist, and appliedFilters is echoed in the response.

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 purpose and filters, then moves into critical behavioral caveats around currency and pagination. Every sentence carries useful operational information, and the structure makes the important warnings easy to find.

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 9-parameter list tool with no output schema, the description is complete enough to use correctly. It covers filtering, pagination ambiguity, returned currency behavior, appliedFilters echoing, and the sibling tool for detail.

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 parameter meanings are already fully documented in the schema. The description summarizes the filter groups and inclusive date behavior, but it does not add significant semantic detail beyond what the schema already 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 and resource: list Xero quotes for the current organisation, with optional filters. It also distinguishes this tool from the sibling get_xero_quote by explaining that the sibling is for full line-item detail on one quote.

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 explains when to use this tool, which filters are available, and when to switch to get_xero_quote for single-quote detail. It also gives explicit pagination guidance for the ambiguous case where exactly 100 quotes are returned.

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 flag destructiveHint=true and openWorldHint=true, and the description goes well beyond them: it explains this queues a pending change rather than touching Xero, that posting is irreversible through Xero's Payroll API, and that STP lodgement and wage payment happen entirely outside the connector. It also warns that regions NZ/UK will refuse plainly, which is a real behavioral trait an agent needs before calling.

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 long, but the length is earned: purpose and scope are front-loaded, then irreversibility, then the STP/payment misconceptions. A couple of meta-instructions to the agent ('in these words, not a softened version') are borderline but serve the destructive nature of the 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?

For a destructive, irreversible, queued mutation with no output schema, the description covers everything an agent needs: region restriction, the approval queue model, irreversibility, and the downstream processes this tool does not perform. Nothing material is left to guesswork.

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 100% schema coverage, the schema already documents all three parameters including the explicit-consent semantics for confirm and the DRAFT precondition for payRunId. The description reinforces consent and region scoping but adds no syntax or format detail the schema lacks, 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 precise verb and resource ('moving an EXISTING DRAFT pay run to POSTED') and draws a hard boundary against create_xero_pay_run by insisting the pay run already exists. The regional limitation (AU only; refuses NZ/UK) further pins down what the tool will and won't do.

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?

Preconditions are explicit: the pay run must currently be DRAFT, confirm must be true only after explicit user consent, and organisation is omitted when only one org is reachable. It frames the follow-on approval step ('a human must explicitly approve' via approvalUrl) but never names the sibling approve_xero_pending_change tool directly, leaving that hop 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?

Goes well beyond the annotations by explaining the consequence model: nothing was ever sent, there is nothing to undo, and the action cannot be reversed once called. It also discloses that reason is not stored or displayed anywhere and that the equivalent Settings > MCP > Xero path remains available, so the agent won't overstate what the call accomplishes.

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?

Dense but front-loaded: the action and its irreversibility come first, then the consent gate, then parameter guidance, then the UI alternative. A few clauses (the reason-disclosure sentence, the Settings > MCP > Xero note) are repeated in substance from the schema, which trims the score slightly.

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 destructive pending-change tool with no output schema and full schema coverage, it supplies everything an agent needs: prerequisites, consent bar, irreversibility, post-call honesty about reason, and a fallback path. Nothing material is left to inference.

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 procedural meaning by tying confirm to a consent gate and sequencing it after informing the user ("Make sure they know what they are turning down first ... then call this with confirm: true"). The reason guidance largely restates the schema's own description, so it is reinforcement rather than new semantics.

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 ("Rejects a change ... proposed to Xero") and immediately scopes the effect: the change is discarded and never reaches Xero. It implicitly but unmistakably distinguishes itself from the sibling approve_xero_pending_change and from the list tools that surface these rows.

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 conditions (only after the account holder has clearly said, in their own words, to discard THIS change) and explicit when-not conditions (never from silence, a change of topic, or them not mentioning it). It also names the prerequisite alternative: call list_pending_changes first if the summary is not already in conversation.

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 say readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true — a generic write profile. The description adds the essential behavioral fact that this enqueues a pending change requiring human approval and that nothing is written to Xero until then, plus partial-update semantics ('only the fields you provide change, everything else is left exactly as it is'). That is substantial context beyond the annotations and does not conflict with 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 most important fact — this is a proposal, not a write — is front-loaded, and the parameter rules follow in a tight sequence. It is a dense multi-clause passage; a small amount of repetition ('it does NOT change anything in Xero itself, and never will on its own') could be trimmed, but no sentence is 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, and the description compensates by naming the return field the agent needs (approvalUrl) and the human-approval workflow that follows. For a five-parameter, non-destructive queued write, an agent has everything needed to call it correctly and to explain the outcome to a 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?

Schema coverage is 100%, so the baseline would be 3, but the description adds a real constraint the schema does not encode: a cross-field rule that at least one of name, emailAddress, or phone must be provided, since only contactId is required in the schema. It also reinforces the contactId provenance rule and the omit-to-leave-unchanged semantics for organisation.

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 ('Proposes a change to an EXISTING Xero contact') and immediately clarifies the critical distinction that it does not mutate Xero directly, unlike a direct update. The word 'Proposes' plus the explicit non-mutation framing separates it cleanly from create_xero_contact and update_xero_invoice 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?

Explicit preconditions: contactId must come from list_xero_contacts and never be invented; at least one of name/emailAddress/phone must be supplied; organisation is only needed for multi-org connections. It also explains the downstream approval path (human approves via the connector's approvalUrl, the agent cannot self-approve), leaving nothing 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?

The annotations only say readOnlyHint=false and destructiveHint=false, which alone would leave the agent guessing whether the write is immediate. The description closes that gap decisively: it does not touch Xero, it queues a pending change, a human must approve via the response's approvalUrl, and the agent cannot self-approve. It also discloses the refusal behavior for conflicting phone/mobile values in NZ/UK, which is behavioral information available nowhere else.

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 key operating model (proposal, not execution) is front-loaded in the first two sentences, which is exactly right for a tool whose biggest misconception is that it writes to Xero directly. It is dense and long, with capitalized emphasis and some duplication of the phone/mobile and address rules that already appear in the schema, which costs a point but not more.

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 burden of explaining the return value, and it does by naming the approvalUrl field and the pending-change lifecycle it participates in. Combined with the region matrix and the employeeId provenance rule, an agent has everything needed to call this correctly and to know what happens next.

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 per-field meanings are already documented, including the AU-vs-NZ/UK phone/mobile split. The description still adds value the schema lacks: the 'at least one mutable field' requirement (the schema only requires employeeId), and the note that only supplied fields change while everything else is preserved. It largely restates the region rules already present in the phone/mobile schema descriptions, which keeps it below a 5.

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 (proposes a change to ONE employee) and enumerates the exact mutable field set, explicitly bounding it with 'STRUCTURALLY NOTHING ELSE.' An agent can immediately distinguish this from update_xero_contact or the create_* payroll tools 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?

Gives explicit prerequisites (employeeId must come from list_xero_payroll_employees, never invented), an invocation constraint (provide at least one of the six fields), and negative guidance on what is out of scope (bank details, tax, pay templates, KiwiSaver, dates) because no such fields exist by design. It also explains the downstream approval step that follows, so the agent knows this is not a terminal call.

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 say readOnly=false/openWorld=true; the description supplies the whole approval mechanic (pending change, human approves via the response's approvalUrl, agent cannot self-approve) that an agent could not otherwise infer. It also discloses the lineItems replace-all semantics and that omitted currency/lineAmountTypes are never reset to defaults, which is exactly the surprising behavior annotations do not cover.

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?

Front-loaded well: the first sentence carries the single most important fact (nothing is changed until a human approves). But it runs very long and the DATES paragraph spends ~150 words on a rule already spelled out in two schema fields, and the lineItems replace-all rule appears verbatim in both description and schema.

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, yet the description tells the agent what comes back (an approvalUrl) and how to narrate the result to the user ('never describe it as done'), closing the loop an agent would otherwise have to guess. For an 8-parameter mutation-queueing tool, nothing needed for correct calling 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 and the description largely repeats field docs (currency validation, lineAmountTypes enum, lineItems replacement). It does add cross-field consequence – that lineAmountTypes re-interprets EVERY existing amount and moves the total – but that is essentially restated from the schema. The long DATES section is duplicated in the date/dueDate schema descriptions, so it earns little extra credit 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?

Opens with a precise verb+resource+scope: 'Proposes a change to an EXISTING Xero invoice', and immediately distinguishes it from create_xero_invoice ('EXISTING') and from approve_xero_pending_change ('you have no way to approve it yourself'). An agent can route correctly without opening any schema.

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

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

States the precondition ('Only works on invoices that are still DRAFT or SUBMITTED - get_xero_invoice tells you the current status first') and the hard exclusions ('Cannot change which contact the invoice is for, or its type - void it and create a new one for that'), naming the sibling to use instead. It also tells the agent what to say to the user, which is part of correct invocation for a queued-approval tool.

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