Provides tools for managing Xero accounting operations including creating invoices, bills, bank transactions (expenses), and expense claims, with support for attachments and PKCE authentication.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Xero Expenses MCP Create an expense for $29.99 office supplies from Staples today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP (Model Context Protocol) server for Xero accounting. Supports Invoices, Bills, Expenses (Bank Transactions), and Expense Claims with PKCE authentication.
Invoices (ACCREC) - Create sales invoices to send to customers
Bills (ACCPAY) - Create bills you'll pay later
Expenses - Create "Spend Money" bank transactions for already-paid expenses
Expense Claims - Create receipts and submit expense claims for reimbursement
Attachments - Attach PDFs and images to invoices, bills, expenses, and receipts
PKCE Auth - Desktop app OAuth flow (no client secret required)
Related MCP server: Xero MCP Server
npx xero-expenses-mcpOr install globally:
npm install -g xero-expenses-mcpGo to Xero Developer Portal
Create a new app:
App name: Your choice (e.g., "Expense Manager")
Integration type: "Mobile or desktop app" (uses PKCE, no secret needed)
Redirect URI: http://localhost:3000/callback
Note your Client ID
Add to your Claude Code MCP settings:
{
"mcpServers": {
"xero-expenses": {
"command": "npx",
"args": ["xero-expenses-mcp"],
"env": {
"XERO_CLIENT_ID": "YOUR_CLIENT_ID"
}
}
}
}Or use the CLI:
claude mcp add xero-expenses -- npx xero-expenses-mcpThen set environment variables in your shell or .env file.
Variable | Required | Description |
| Yes | Your Xero app's client ID |
| No | Only for Web apps (not PKCE) |
| No | Default: |
On first use, the server will open a browser for Xero OAuth. After authenticating, tokens are stored in ~/.xero-mcp/token.json.
xero_list_accounts - List expense accounts/categories
xero_list_bank_accounts - List bank accounts
xero_list_contacts - Search vendors/contacts
xero_list_users - List organization users (for expense claims)
xero_create_invoice - Create a sales invoice to send to customers
xero_attach_file_to_invoice - Attach file to an invoice
xero_create_bill - Create a bill for future payment
xero_attach_file - Attach file to a bill
xero_create_expense - Create a "Spend Money" transaction
xero_attach_file_to_expense - Attach file to an expense
xero_create_expense_claim - Create receipt + expense claim
xero_attach_file_to_receipt - Attach file to a receipt
In Claude Code:
"Create an expense for $45.50 lunch at Cafe Example on 2024-01-15, categorize as Business Meals (account 620)"Claude will use the xero_create_expense_claim tool with:
{
"vendorName": "Cafe Example",
"amount": 45.50,
"description": "Lunch",
"accountCode": "620",
"date": "2024-01-15"
}Tokens are stored in ~/.xero-mcp/token.json. To re-authenticate, delete this file.
MIT
Add a line item (expense) to an existing DRAFT bill
| Name | Required | Description | Default |
|---|---|---|---|
| invoiceId | Yes | The Xero invoice/bill ID | |
| description | Yes | Description of the expense | |
| amount | Yes | Amount of the expense | |
| accountCode | Yes | Xero account code (e.g., '678' for software) | |
| reference | No | Reference to append (e.g., invoice number) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only mentions the draft requirement. It doesn't disclose other behavioral traits like whether this operation requires specific permissions, if it's idempotent, what happens on failure, or what the response looks like. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that immediately conveys the core purpose without any wasted words. It's front-loaded with the essential information and doesn't include unnecessary details or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description provides adequate basic context about the operation and its draft requirement. However, it doesn't address important aspects like error conditions, return values, or side effects that would be needed for complete understanding, especially given the tool's complexity as a write operation.
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 description coverage is 100%, so all parameters are documented in the schema. The description doesn't add any parameter-specific information beyond what's in the schema (like explaining format constraints or relationships between parameters). This meets the baseline expectation when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Add a line item'), the target resource ('to an existing DRAFT bill'), and the type of item ('expense'). It distinguishes from siblings like xero_create_bill (creates new bills) and xero_submit_bill (submits bills), making the scope and intent unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'to an existing DRAFT bill', providing clear context about when to use this tool (only for draft bills). However, it doesn't mention alternatives like modifying existing line items or when not to use it (e.g., for submitted bills), and doesn't reference sibling tools directly for comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attach a file (PDF, image) to an existing Xero bill
| Name | Required | Description | Default |
|---|---|---|---|
| invoiceId | Yes | The Xero invoice/bill ID | |
| filePath | Yes | Path to the file to attach |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool attaches files but doesn't mention authentication requirements, rate limits, file size constraints, whether the operation is idempotent, what happens on failure, or what the response looks like. For a mutation tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with no wasted words. It's appropriately sized for a simple tool with two parameters, though it could be slightly more informative without sacrificing conciseness.
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 mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens after attachment, whether there are side effects, error conditions, or what the tool returns. Given the complexity of file attachment operations and lack of structured behavioral information, the description should provide more context about the operation's behavior and outcomes.
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 description doesn't add any parameter-specific information beyond what's already in the schema (which has 100% coverage). It mentions 'PDF, image' which relates to filePath but doesn't specify format constraints or supported file types beyond those examples. With complete schema coverage, the baseline is 3 even without additional parameter details in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Attach a file') and target resource ('to an existing Xero bill'), with specific file types mentioned (PDF, image). It distinguishes from some siblings like 'xero_attach_file_to_invoice' by specifying 'bill' rather than 'invoice', but doesn't explicitly differentiate from other bill-related tools like 'xero_add_line_item_to_bill' or 'xero_submit_bill'.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., the bill must exist), when not to use it, or how it differs from similar tools like 'xero_attach_file_to_invoice' or 'xero_attach_file_to_expense' in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attach a file (PDF, image) to an existing Xero expense (bank transaction)
| Name | Required | Description | Default |
|---|---|---|---|
| bankTransactionId | Yes | The Xero bank transaction ID | |
| filePath | Yes | Path to the file to attach |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action is to attach a file, implying a write/mutation operation, but doesn't mention required permissions, rate limits, file size constraints, supported file types beyond 'PDF, image', or what happens on success/failure. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and resource. It uses parentheses for concise clarifications ('PDF, image' and 'bank transaction') without unnecessary elaboration. Every word contributes directly to understanding the tool's function, making it well-structured and appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity as a mutation operation with no annotations and no output schema, the description is incomplete. It lacks details on behavioral aspects (e.g., permissions, errors), output expectations, and differentiation from sibling tools. While concise, it doesn't compensate for the missing structured data, leaving gaps for effective agent use.
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 parameters ('bankTransactionId' and 'filePath') documented in the schema. The description adds minimal value beyond the schema by implying the file types ('PDF, image') and that the expense is a 'bank transaction', but doesn't provide additional syntax, format details, or constraints. This meets the baseline score of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Attach a file') and the target resource ('to an existing Xero expense (bank transaction)'), specifying the verb and resource. However, it doesn't explicitly differentiate from sibling tools like 'xero_attach_file_to_invoice' or 'xero_attach_file_to_receipt', which attach files to different Xero entities, leaving some ambiguity about when to choose this specific tool over similar ones.
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 no guidance on when to use this tool versus alternatives. It mentions attaching to an 'existing Xero expense' but doesn't specify prerequisites, exclusions, or compare it to sibling tools like 'xero_attach_file' (which might have broader scope) or other attachment tools for invoices or receipts. This lack of contextual direction leaves the agent without clear usage criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attach a file (PDF, image) to an existing Xero invoice
| Name | Required | Description | Default |
|---|---|---|---|
| invoiceId | Yes | The Xero invoice ID | |
| filePath | Yes | Path to the file to attach |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It indicates this is a mutation operation ('Attach'), but doesn't mention authentication requirements, rate limits, file size restrictions, supported formats beyond 'PDF, image', or what happens on success/failure. Significant behavioral gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core action and includes only essential qualifiers. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is inadequate. It doesn't explain what happens after attachment, error conditions, authentication needs, or file constraints. Given the complexity of file attachment operations, more behavioral context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters adequately. The description adds minimal value beyond the schema - it mentions file types but doesn't provide additional context about parameter usage, constraints, or examples. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Attach a file') and target resource ('to an existing Xero invoice'), with specific file types mentioned. It distinguishes from generic 'xero_attach_file' by specifying the invoice target, but doesn't differentiate from similar tools like 'xero_attach_file_to_expense' beyond the resource name.
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 no guidance on when to use this tool versus alternatives like 'xero_attach_file' or other attachment tools. It mentions the invoice must be 'existing' but doesn't specify prerequisites, error conditions, or when other tools might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attach a file (PDF, image) to an existing Xero receipt
| Name | Required | Description | Default |
|---|---|---|---|
| receiptId | Yes | The Xero receipt ID | |
| filePath | Yes | Path to the file to attach |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool attaches files, implying a write/mutation operation, but doesn't disclose behavioral traits like required permissions, whether the attachment is reversible, file size limits, supported MIME types beyond PDF/image, or what happens on failure. The description is minimal and lacks operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the core action, zero waste. Every word earns its place by specifying the tool's purpose efficiently without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a mutation tool with 2 parameters, the description is incomplete. It doesn't explain what the tool returns, error conditions, or important behavioral constraints. For attaching files to financial records, more context on permissions, limitations, or side effects would be needed for adequate completeness.
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 parameters clearly documented in the schema. The description adds no additional parameter semantics beyond implying file types (PDF, image) for 'filePath', which is already covered by the schema's description. Baseline score of 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Attach a file') and target resource ('to an existing Xero receipt'), specifying file types (PDF, image). It distinguishes from generic 'xero_attach_file' by specifying receipt attachment, but doesn't explicitly differentiate from 'xero_attach_file_to_expense' or 'xero_attach_file_to_invoice' beyond the resource name.
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?
No guidance on when to use this tool versus alternatives like 'xero_attach_file_to_expense' or 'xero_attach_file_to_invoice'. The description mentions 'existing Xero receipt' which implies the receipt must already exist, but doesn't state prerequisites like receipt creation or availability. No explicit when-not-to-use or comparison with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a bill (accounts payable) in Xero - use for invoices you'll pay later
| Name | Required | Description | Default |
|---|---|---|---|
| vendorName | Yes | Name of the vendor | |
| vendorEmail | No | Email of the vendor (optional) | |
| amount | Yes | Total amount of the expense | |
| description | Yes | Description of the expense | |
| accountCode | No | Xero account code (e.g., '400' for expenses) | |
| date | No | Invoice date (YYYY-MM-DD) | |
| dueDate | No | Due date (YYYY-MM-DD) | |
| reference | No | Reference number from the invoice |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is a creation tool ('Create a bill'), which implies a write operation, but doesn't mention required permissions, whether the bill is saved as draft or submitted, error handling, or what happens on success. This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with no wasted words. It's appropriately sized for a tool with good schema coverage and clear purpose.
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 mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens after creation (e.g., returns a bill ID, saves as draft), error conditions, or authentication requirements. The 100% schema coverage helps with parameters, but behavioral aspects are severely lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 8 parameters. The description doesn't add any parameter-specific information beyond what's in the schema, such as format examples or business rules. This meets the baseline of 3 when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a bill') and the resource ('in Xero'), with the parenthetical 'accounts payable' providing helpful context. It distinguishes this tool from siblings like xero_create_invoice or xero_create_expense by specifying it's for 'invoices you'll pay later', though it could be more explicit about the distinction.
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 some usage context with 'use for invoices you'll pay later', which implies when to use this tool. However, it doesn't explicitly state when NOT to use it or mention alternatives like xero_create_invoice for sales invoices or xero_create_expense for immediate payments, leaving room for confusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a spend money transaction (direct expense) in Xero - use for already-paid expenses like receipts
| Name | Required | Description | Default |
|---|---|---|---|
| vendorName | Yes | Name of the vendor | |
| vendorEmail | No | Email of the vendor (optional) | |
| amount | Yes | Total amount of the expense | |
| description | Yes | Description of the expense | |
| accountCode | No | Xero expense account code (e.g., '620' for meals) | |
| date | No | Transaction date (YYYY-MM-DD) | |
| reference | No | Reference number from the receipt | |
| bankAccountId | No | Xero bank account ID (optional, uses first available if not specified) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It indicates this is a creation/mutation tool ('Create') and specifies the type of transaction ('direct expense'), but doesn't disclose important behavioral aspects like authentication requirements, error handling, rate limits, or what happens if creation fails.
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 extremely concise (one sentence) and front-loaded with the core purpose. Every word earns its place by specifying the action, resource, and key usage context without any fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description provides adequate basic context about what it does and when to use it. However, it lacks information about return values, error conditions, or system behavior that would be important for a creation operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 8 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema descriptions, so it meets the baseline expectation but doesn't provide additional 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?
The description clearly states the specific action ('Create a spend money transaction'), the resource ('in Xero'), and distinguishes it from siblings by specifying it's for 'direct expense' and 'already-paid expenses like receipts'. This differentiates it from tools like xero_create_bill or xero_create_expense_claim.
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 clear context on when to use this tool ('use for already-paid expenses like receipts'), which helps differentiate it from other expense-related tools. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an expense claim for reimbursement - creates a receipt and submits it as an expense claim (deprecated Feb 2026)
| Name | Required | Description | Default |
|---|---|---|---|
| vendorName | Yes | Name of the vendor | |
| vendorEmail | No | Email of the vendor (optional) | |
| amount | Yes | Total amount of the expense | |
| description | Yes | Description of the expense | |
| accountCode | No | Xero expense account code (e.g., '620' for meals) | |
| date | No | Receipt date (YYYY-MM-DD) | |
| reference | No | Reference number from the receipt | |
| userId | No | Xero user ID to claim as (optional, uses first user if not specified) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the tool 'creates a receipt and submits it as an expense claim,' which implies a write operation, but fails to specify required permissions, whether the submission is immediate or pending, error handling, or other behavioral traits like rate limits or side effects. The deprecation note adds some context, but overall, the description is insufficient for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, stating the core purpose in the first clause. The deprecation warning is efficiently appended. It avoids unnecessary details, though it could be slightly more structured by separating the deprecation note for clarity. Overall, it earns its place with minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a mutation tool with 8 parameters, no annotations, and no output schema), the description is incomplete. It lacks critical information: behavioral details like permissions or submission flow, output expectations, and explicit differentiation from sibling tools. The deprecation warning adds some context, but for a tool that creates and submits expense claims, more guidance is needed to ensure proper agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema already documents all 8 parameters thoroughly. The description does not add any parameter-specific information beyond what the schema provides, such as examples or constraints not captured in the schema. However, it implies the tool handles receipt creation and submission, which contextualizes the parameters' role, but this is minimal added value. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create an expense claim for reimbursement - creates a receipt and submits it as an expense claim.' It specifies the verb ('create') and resource ('expense claim'), and distinguishes it from siblings like 'xero_create_expense' or 'xero_create_receipt' by indicating it combines receipt creation and submission. However, it doesn't explicitly differentiate from 'xero_submit_expense_claim', which is a limitation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating and submitting expense claims, but provides no explicit guidance on when to use this tool versus alternatives like 'xero_create_expense' or 'xero_submit_expense_claim'. The deprecation warning ('deprecated Feb 2026') offers some temporal context, but lacks clear when/when-not instructions or prerequisites for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a sales invoice (accounts receivable) in Xero - use for invoices you send to customers
| Name | Required | Description | Default |
|---|---|---|---|
| customerName | Yes | Name of the customer | |
| customerEmail | No | Email of the customer (optional) | |
| amount | Yes | Total amount of the invoice | |
| description | Yes | Description of the goods/services | |
| accountCode | No | Xero revenue account code (e.g., '200' for sales) | |
| date | No | Invoice date (YYYY-MM-DD) | |
| dueDate | No | Due date (YYYY-MM-DD) | |
| reference | No | Reference or PO number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While it indicates this is a creation operation, it doesn't disclose important behavioral aspects like authentication requirements, whether the invoice is saved as draft or sent immediately, error handling, rate limits, or what happens on success/failure. The description is insufficient for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the essential purpose and usage context without any wasted words. It's appropriately front-loaded with the core functionality.
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 mutation tool with 8 parameters and no annotations or output schema, the description is inadequate. It doesn't explain what happens after creation (e.g., invoice status, return values, error conditions), nor does it provide important behavioral context about permissions, side effects, or system constraints that would be crucial for an AI agent to use 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 description coverage is 100%, so the schema already documents all 8 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. This meets the baseline of 3 when the schema does the heavy lifting, but doesn't provide additional semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Create a sales invoice') and resource ('in Xero'), with explicit context ('accounts receivable') and usage scenario ('invoices you send to customers'). It distinguishes itself from sibling tools like xero_create_bill or xero_create_expense by focusing on customer-facing sales invoices.
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 clear context for when to use this tool ('for invoices you send to customers'), which implicitly distinguishes it from tools for bills or expense claims. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a receipt WITHOUT submitting as expense claim - use this to batch multiple receipts into one claim later
| Name | Required | Description | Default |
|---|---|---|---|
| vendorName | Yes | Name of the vendor | |
| vendorEmail | No | Email of the vendor (optional) | |
| amount | Yes | Total amount of the expense | |
| description | Yes | Description of the expense | |
| accountCode | No | Xero expense account code (e.g., '620' for meals) | |
| date | No | Receipt date (YYYY-MM-DD) | |
| reference | No | Reference number from the receipt | |
| userId | No | Xero user ID (optional, uses first user if not specified) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly indicates this is a creation operation (not read-only) and specifies the workflow context (batching receipts for later claim submission). However, it doesn't mention authentication requirements, rate limits, error conditions, or what happens to the created receipt in the system - significant gaps for a creation tool with zero annotation coverage.
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 extremely concise - a single sentence that communicates the core purpose, key behavioral constraint, and usage context. Every word earns its place with no redundancy or unnecessary elaboration. It's perfectly front-loaded with the most important information first.
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 creation tool with no annotations and no output schema, the description provides good workflow context but lacks important details about authentication requirements, error handling, system behavior, and return values. It adequately covers the 'what' and 'when' but misses the 'how' and 'what happens next' aspects that would be important for an agent to use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 8 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. According to the scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no parameter information in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Create a receipt') and distinguishes it from sibling tools by explicitly noting it's 'WITHOUT submitting as expense claim' and contrasting with 'xero_create_expense_claim' and 'xero_submit_expense_claim'. This provides precise differentiation from related tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool ('to batch multiple receipts into one claim later') and when not to use it ('WITHOUT submitting as expense claim'). It clearly distinguishes this from the expense claim submission workflow, offering clear alternatives among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific bill including all line items
| Name | Required | Description | Default |
|---|---|---|---|
| invoiceId | Yes | The Xero invoice/bill ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it 'Get details' which implies a read-only operation, but doesn't clarify if it requires authentication, rate limits, error handling, or what 'details' include beyond line items. For a tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('Get details of a specific bill') and adds useful detail ('including all line items') without waste. Every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (single parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks usage guidelines, behavioral context, and output details. With no annotations or output schema, it should do more to compensate, making it incomplete for reliable agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a clear description for 'invoiceId', so the description adds no additional parameter information. It implies the tool uses an invoice ID to fetch bill details, but doesn't explain format, sourcing, or relationships. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('details of a specific bill including all line items'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'xero_list_draft_bills' or 'xero_get_expense_claim', which would require mentioning it retrieves a single bill by ID rather than listing multiple bills.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a bill ID), contrast with list tools for multiple bills, or specify use cases like retrieving a single bill for review or editing. This leaves the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific expense claim including all receipts
| Name | Required | Description | Default |
|---|---|---|---|
| expenseClaimId | Yes | The expense claim ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is a read operation ('Get'), implying it's non-destructive, but doesn't cover aspects like authentication requirements, rate limits, error handling, or what 'details' and 'receipts' entail in the response. This leaves significant gaps for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the key action ('Get details') and resource ('expense claim'), with no wasted words. Every part of the sentence contributes directly to understanding the tool's function.
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 annotations and output schema, the description is incomplete. It doesn't explain the return format (e.g., what 'details' and 'receipts' include), error conditions, or dependencies on other tools. For a read operation with no structured output documentation, more context is needed to be fully helpful.
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 description coverage is 100%, with the parameter 'expenseClaimId' clearly documented in the schema. The description doesn't add any additional meaning beyond implying the ID is required to fetch details, which aligns with the schema. This meets the baseline score when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'details of a specific expense claim including all receipts', making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'xero_list_expense_claims' or 'xero_get_bill', which would be needed for a perfect score.
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?
No guidance is provided on when to use this tool versus alternatives. The description doesn't mention prerequisites like needing an expense claim ID, nor does it refer to sibling tools like 'xero_list_expense_claims' for obtaining IDs or 'xero_create_expense_claim' for creating claims first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available Xero accounts/categories for expenses
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states it lists accounts/categories. It doesn't disclose behavioral traits like whether it's read-only, requires authentication, has rate limits, returns paginated results, or what format the output takes. This is inadequate for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It's front-loaded with the core purpose, making it highly concise and well-structured.
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 annotations and output schema, the description is incomplete. It doesn't explain return values, behavioral constraints, or usage context, which are critical for an AI agent to invoke this tool correctly in a complex environment with many sibling tools.
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 tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description doesn't add param info, but that's appropriate here, meeting the baseline for zero-param tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and resource ('Xero accounts/categories for expenses'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'xero_list_bank_accounts' or 'xero_list_contacts', which reduces specificity.
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?
No guidance is provided on when to use this tool versus alternatives. The description lacks context about prerequisites, timing, or comparisons to other listing tools in the sibling set, leaving usage unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available Xero bank accounts for expenses
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states it's a list operation. It doesn't disclose behavioral traits such as whether it's read-only, requires authentication, has rate limits, or returns paginated results. For a tool with zero annotation coverage, this is insufficient, scoring a 2.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and appropriately sized, earning a perfect score for conciseness and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema) and lack of annotations, the description is minimally adequate. It states what the tool does but lacks details on behavior, output format, or error handling. For a list tool with no structured support, it meets the bare minimum, scoring a 3.
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 tool has 0 parameters with 100% schema description coverage, so no parameter documentation is needed. The description adds no parameter semantics, but the baseline for 0 parameters is 4, as the schema fully covers the absence of inputs without requiring compensation from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and resource ('Xero bank accounts') with a specific purpose ('for expenses'). It distinguishes from siblings like 'xero_list_accounts' by specifying bank accounts rather than general accounts. However, it doesn't explicitly contrast with other list tools, keeping it at a 4 rather than a 5.
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 minimal guidance with 'for expenses', implying usage context but not specifying when to use this tool versus alternatives like 'xero_list_accounts' or other expense-related tools. No explicit when-not-to-use or prerequisite information is given, resulting in a basic score of 2.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for vendors/contacts in Xero
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | Search term for vendor name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states it's a search operation. It doesn't disclose behavioral traits like whether it's read-only, pagination, rate limits, authentication needs, or what happens on no results. This is inadequate for a tool with potential complexity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's front-loaded with the core action and resource, making it easy to parse quickly without unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a simple but potentially broad search tool, the description is incomplete. It lacks details on return format, error handling, or operational context, making it insufficient for reliable agent use despite the concise structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, documenting the 'search' parameter as a term for vendor name. The description adds no additional meaning beyond implying it searches vendors/contacts, so it meets the baseline for high schema coverage without compensating further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Search') and resource ('vendors/contacts in Xero'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'xero_list_accounts' or 'xero_list_users' beyond specifying the resource type, which keeps it from a perfect score.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context for searching vendors/contacts, or how it differs from other list/search tools in the sibling set, leaving usage ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List draft bills (ACCPAY invoices) - use to find existing draft to add expenses to
| Name | Required | Description | Default |
|---|---|---|---|
| reference | No | Optional reference pattern to filter by |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions listing draft bills but doesn't describe key behaviors like whether this is a read-only operation, if it requires authentication, any rate limits, pagination, or what the return format looks like. This leaves significant gaps for an agent to understand how to interact with the tool effectively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the purpose and usage context without any wasted words. It's appropriately sized for the tool's complexity and gets straight to the point.
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 annotations and output schema, the description is incomplete. It doesn't cover behavioral aspects like safety, authentication, or response format, which are crucial for a listing tool. While the purpose and usage are clear, the overall context needed for an agent to use the tool correctly is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with one optional parameter 'reference' documented as a filter pattern. The description doesn't add any additional meaning beyond this, such as examples or constraints on the reference pattern. Given the high schema coverage, a baseline score of 3 is appropriate as the schema handles the parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('draft bills (ACCPAY invoices)'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'xero_list_expense_claims' or 'xero_list_receipts' beyond mentioning 'draft bills' and the ACCPAY invoice type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool ('to find existing draft to add expenses to'), which is helpful for guiding usage. However, it doesn't explicitly state when not to use it or name alternatives among the siblings, such as 'xero_get_bill' for retrieving a specific bill.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List expense claims - optionally filter by status (SUBMITTED, AUTHORISED, PAID)
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by status: SUBMITTED, AUTHORISED, or PAID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions the list operation and optional filtering, but lacks critical behavioral details: it doesn't specify whether this is a read-only operation (though implied by 'List'), doesn't describe pagination, rate limits, authentication requirements, or the format/scope of returned data. For a list tool with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('List expense claims') and immediately adds the optional filter detail. There is no wasted verbiage, and every word contributes directly to understanding the tool's functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete for a list tool. It covers the basic action and filter, but misses key contextual elements: it doesn't explain what data is returned (e.g., claim fields, pagination), error conditions, or how it fits into broader workflows with siblings like xero_create_expense_claim. The agent lacks sufficient information to use this tool effectively in complex scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the single parameter 'status' fully documented in the schema. The description adds minimal value by restating the filter option and listing status values, but doesn't provide additional context like default behavior when no filter is applied or how filtering interacts with other potential constraints. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'expense claims', making the purpose immediately understandable. It distinguishes this tool from other list tools (like xero_list_accounts, xero_list_bank_accounts) by specifying the resource type. However, it doesn't explicitly differentiate from xero_get_expense_claim (which retrieves a single claim), so it's not fully sibling-aware.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the optional filter by status, suggesting this tool is for retrieving expense claims with possible status filtering. However, it provides no explicit guidance on when to use this vs. xero_get_expense_claim (for single claims) or other list tools, nor does it mention prerequisites or exclusions. The guidance is limited to the filter functionality.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all receipts - optionally filter by user ID
| Name | Required | Description | Default |
|---|---|---|---|
| userId | No | Filter by user ID (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states it's a list operation with optional filtering. It lacks critical behavioral details: whether this is a read-only operation, pagination behavior, rate limits, authentication requirements, or what the output looks like. For a tool with no annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just 7 words, front-loading the core purpose ('List all receipts') followed by the key qualification. Every word serves a purpose with zero redundancy or unnecessary elaboration, making it efficient for an AI agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a list operation that likely returns multiple items, the description is incomplete. It doesn't address return format, pagination, error conditions, or how results are structured. For a tool that presumably returns a collection of receipts, more context about the output would be valuable for the agent.
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 description mentions 'optionally filter by user ID' which aligns with the single parameter in the schema. With 100% schema description coverage, the schema already documents this parameter fully, so the description adds minimal value beyond confirming the optional nature. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all receipts') and resource ('receipts'), making the purpose immediately understandable. It distinguishes from some siblings like 'xero_create_receipt' by specifying listing vs creation, though it doesn't explicitly differentiate from other list tools like 'xero_list_expense_claims' beyond the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance with 'optionally filter by user ID' but offers no context about when to use this tool versus alternatives. There's no mention of prerequisites, limitations, or comparison with other receipt-related tools like 'xero_attach_file_to_receipt', leaving the agent with insufficient guidance for optimal selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List users in the Xero organization (for expense claims)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states this is a list operation, implying it's read-only, but doesn't mention any behavioral traits such as pagination, rate limits, authentication requirements, or what the return format looks like. For a tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It's appropriately sized for a simple list tool and front-loaded with the core purpose, making it easy to scan and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (0 parameters, no output schema), the description is minimally adequate but lacks completeness. It doesn't explain the return values or any behavioral context, which is a gap since no annotations or output schema are provided. However, for a simple list tool, it meets the bare minimum.
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 tool has 0 parameters, and schema description coverage is 100%, so there are no parameters to document. The description doesn't need to add parameter semantics, and a baseline score of 4 is appropriate as it doesn't introduce confusion or omissions regarding 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 description clearly states the verb ('List') and resource ('users in the Xero organization'), making the purpose specific and understandable. However, it doesn't explicitly distinguish this tool from its sibling 'xero_list_expense_claims' or other list tools, which would be needed for a perfect score.
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 includes a parenthetical note 'for expense claims,' which implies a usage context but doesn't provide explicit guidance on when to use this tool versus alternatives like 'xero_list_expense_claims' or other list tools. No when-not-to-use or prerequisite information is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change a DRAFT bill to SUBMITTED status for approval
| Name | Required | Description | Default |
|---|---|---|---|
| invoiceId | Yes | The Xero invoice/bill ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the status change action but doesn't cover critical aspects like required permissions, whether the operation is reversible, potential side effects (e.g., notifications sent), or what happens if the bill isn't in draft state. For a mutation tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action and resource, making it easy to understand at a glance while still providing essential context about the status change.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a mutation operation with no annotations and no output schema), the description is minimally adequate. It covers the basic purpose but lacks details on behavioral traits, error conditions, or return values. For a status-change tool in a financial system, more context about implications and outcomes would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the single parameter 'invoiceId' documented as 'The Xero invoice/bill ID'. The description doesn't add any parameter-specific information beyond what the schema provides, such as format examples or constraints. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but doesn't need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Change') and resource ('a DRAFT bill') with the specific action of transitioning to 'SUBMITTED status for approval'. It distinguishes this from creation tools like 'xero_create_bill' by focusing on status change rather than initial creation, though it doesn't explicitly differentiate from all siblings like 'xero_submit_expense_claim'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying 'DRAFT bill', suggesting it should only be used on bills already in draft state. However, it doesn't provide explicit guidance on when to use this versus alternatives (e.g., when to submit vs. create a bill) or mention prerequisites like needing a draft bill ID, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit multiple receipts as a single expense claim - use after creating receipts with xero_create_receipt
| Name | Required | Description | Default |
|---|---|---|---|
| receiptIds | Yes | Array of receipt IDs to include in the claim | |
| userId | No | Xero user ID (optional, uses first user if not specified) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that this is a submission action (implying a write/mutation operation) and mentions the prerequisite of creating receipts first, but lacks details on permissions, side effects, error conditions, or what happens after submission. For a mutation tool with no annotations, this is a moderate gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose and includes essential usage guidance. Every word earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is moderately complete: it covers purpose and sequencing but lacks behavioral details (e.g., what the submission entails, success/failure responses, or system state changes). Given the complexity, it should do more to compensate for missing structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema (e.g., it doesn't explain receipt ID format or user ID implications). Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('submit multiple receipts as a single expense claim') and resource ('expense claim'), distinguishing it from siblings like 'xero_create_expense_claim' (which likely creates rather than submits) and 'xero_create_receipt' (which creates individual receipts).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('use after creating receipts with xero_create_receipt'), providing clear sequencing guidance and distinguishing it from alternatives like 'xero_create_expense_claim' or 'xero_submit_bill'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0xero_add_line_item_to_billxero_attach_filexero_attach_file_to_expensexero_attach_file_to_invoicexero_attach_file_to_receiptxero_create_billxero_create_expensexero_create_expense_claimxero_create_invoicexero_create_receiptxero_get_billxero_get_expense_claimxero_list_accountsxero_list_bank_accountsxero_list_contactsxero_list_draft_billsxero_list_expense_claimsxero_list_receiptsxero_list_usersxero_submit_billxero_submit_expense_claimScored across 21 tools
Most tools have distinct purposes targeting specific Xero entities (bills, expenses, invoices, receipts) with clear action verbs, but there is some potential confusion between xero_create_expense and xero_create_receipt as both handle expense-related creation. The descriptions help clarify, but the overlap in domain could cause misselection without careful reading.
All tool names follow a consistent xero_verb_noun pattern with snake_case throughout, such as xero_create_bill, xero_list_expense_claims, and xero_attach_file_to_invoice. This predictability makes it easy for agents to understand and navigate the toolset without confusion from mixed conventions.
With 21 tools, the count is on the higher side but reasonable for the comprehensive expense management domain, covering CRUD operations, file attachments, and listing across multiple entities. It might feel slightly heavy, but each tool appears to serve a specific function without obvious redundancy.
The toolset provides complete coverage for Xero expense management, including creation, retrieval, listing, and submission for bills, expenses, invoices, receipts, and claims, along with supporting operations like file attachments and listing accounts/contacts. There are no apparent gaps that would hinder agent workflows in this domain.
Connect CollectiveSpend with Xero to manage contacts. Retrieve, create, and update contact records…
Complete read-only backup and export of Xero accounting data as a ZIP plus a manifest.
Document sharing, invoicing, and personal finance platform. 15+ AI tools via OAuth 2.1.
Create, validate, convert & extract compliant e-invoices (UBL, Factur-X, ZUGFeRD, XRechnung)
