Skip to main content
Glama

Search synced Xero invoices

search_xero_invoices
Read-onlyIdempotent

Search sales invoices from the signed-in owner’s latest completed SHVL Xero sync by invoice number or customer name. Read-only, capped at 20 and not live Xero state. Results are paged. applied_filters echoes validated predicates and calculation date. Use next_cursor with the same filters until has_more is false; total_count counts all filtered matches. Data changes invalidate continuation. Amount filters require currency; case/contact dates use oldest positive overdue date in the selected currency when supplied and amounts use the selected currency overdue subtotal. Returned summaries retain all currencies. Detail filters apply to invoice history, not case metadata.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "workspace_id": "<workspace_id>"
    },
    "name": "search_xero_invoices"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoNumber of matching records to return; omit to use the server default.
queryNoOptional text matched against invoice number or customer name in the selected business; omit to list synced records.
cursorNonext_cursor from the preceding page. Repeat the same filters; changed data requires restarting.
due_toNo
statusNoOptional synced invoice status; overdue selects outstanding invoices past their due date.
currencyNoISO currency. Required with amount bounds; no currency conversion.
due_fromNoInclusive due date; cases use oldest overdue invoice date.
as_of_dateNoUTC date for days-overdue filters. Defaults to today and is fixed across continuation pages.
promise_toNo
case_statusNoExact case-workflow status, including for invoice searches.
customer_idNoExact SHVL customer ID.
promise_fromNoInclusive recorded payment-promise date; excludes cases without a promise.
workspace_idYesSelected business ID from list_shvl_workspaces. Ask the user to choose if several businesses are available; never infer another business.
exclude_statusesNoStatuses to exclude. Invoice searches use invoice status; cases and contacts use case status.
max_amount_minorNoInclusive outstanding amount maximum in the selected currency.
max_days_overdueNo
min_amount_minorNoInclusive outstanding amount minimum in the selected currency; cases use overdue balance.
min_days_overdueNo
readiness_statusNoExact payment-readiness state of the associated case.
exclude_case_statusesNoExclude these case-workflow statuses, including when searching invoices.

Output Schema

NameRequiredDescriptionDefault
sourceYes
filtersYes
has_moreYes
invoicesYes
as_of_dateYes
data_noticeYes
next_cursorYes
total_countYesAll matches after filters, before paging.
organisationYes
invoice_countYes
returned_countYes
applied_filtersYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed23 schema fields changed
    • addedInput schema / properties / as_of_date
      Added value: +{
      +  "description": "UTC date for days-overdue filters. Defaults to today and is fixed across continuation pages.",
      +  "format": "date",
      +  "type": "string"
      +}
    • addedInput schema / properties / case_status
      Added value: +{
      +  "description": "Exact case-workflow status, including for invoice searches.",
      +  "enum": [
      +    "active",
      +    "paused",
      +    "promised",
      +    "disputed",
      +    "closed"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / currency
      Added value: +{
      +  "description": "ISO currency. Required with amount bounds; no currency conversion.",
      +  "pattern": "^[A-Z]{3}$",
      +  "type": "string"
      +}
    • addedInput schema / properties / cursor
      Added value: +{
      +  "description": "next_cursor from the preceding page. Repeat the same filters; changed data requires restarting.",
      +  "maxLength": 2048,
      +  "type": "string"
      +}
    • addedInput schema / properties / customer_id
      Added value: +{
      +  "description": "Exact SHVL customer ID.",
      +  "maxLength": 120,
      +  "type": "string"
      +}
    • addedInput schema / properties / due_from
      Added value: +{
      +  "description": "Inclusive due date; cases use oldest overdue invoice date.",
      +  "format": "date",
      +  "type": "string"
      +}
    • addedInput schema / properties / due_to
      Added value: +{
      +  "format": "date",
      +  "type": "string"
      +}
    • addedInput schema / properties / exclude_case_statuses
      Added value: +{
      +  "description": "Exclude these case-workflow statuses, including when searching invoices.",
      +  "items": {
      +    "enum": [
      +      "active",
      +      "paused",
      +      "promised",
      +      "disputed",
      +      "closed"
      +    ],
      +    "type": "string"
      +  },
      +  "maxItems": 5,
      +  "type": "array",
      +  "uniqueItems": true
      +}
    • addedInput schema / properties / exclude_statuses
      Added value: +{
      +  "description": "Statuses to exclude. Invoice searches use invoice status; cases and contacts use case status.",
      +  "items": {
      +    "enum": [
      +      "authorised",
      +      "overdue",
      +      "paid",
      +      "voided",
      +      "deleted"
      +    ],
      +    "type": "string"
      +  },
      +  "maxItems": 10,
      +  "type": "array",
      +  "uniqueItems": true
      +}
    • addedInput schema / properties / max_amount_minor
      Added value: +{
      +  "description": "Inclusive outstanding amount maximum in the selected currency.",
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / max_days_overdue
      Added value: +{
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / min_amount_minor
      Added value: +{
      +  "description": "Inclusive outstanding amount minimum in the selected currency; cases use overdue balance.",
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / min_days_overdue
      Added value: +{
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / promise_from
      Added value: +{
      +  "description": "Inclusive recorded payment-promise date; excludes cases without a promise.",
      +  "format": "date",
      +  "type": "string"
      +}
    • addedInput schema / properties / promise_to
      Added value: +{
      +  "format": "date",
      +  "type": "string"
      +}
    • addedInput schema / properties / readiness_status
      Added value: +{
      +  "description": "Exact payment-readiness state of the associated case.",
      +  "enum": [
      +    "unchecked",
      +    "ready",
      +    "missing_reference",
      +    "missing_evidence",
      +    "portal_not_submitted",
      +    "receipt_unconfirmed",
      +    "waiting_approval",
      +    "wrong_contact",
      +    "query_open"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / properties / applied_filters
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "as_of_date": {
      +      "description": "UTC date for days-overdue filters. Defaults to today and is fixed across continuation pages.",
      +      "format": "date",
      +      "type": "string"
      +    },
      +    "case_status": {
      +      "description": "Exact case-workflow status, including for invoice searches.",
      +      "enum": [
      +        "active",
      +        "paused",
      +        "promised",
      +        "disputed",
      +        "closed"
      +      ],
      +      "type": "string"
      +    },
      +    "currency": {
      +      "description": "ISO currency. Required with amount bounds; no currency conversion.",
      +      "pattern": "^[A-Z]{3}$",
      +      "type": "string"
      +    },
      +    "customer_id": {
      +      "description": "Exact SHVL customer ID.",
      +      "maxLength": 120,
      +      "type": "string"
      +    },
      +    "due_from": {
      +      "description": "Inclusive due date; cases use oldest overdue invoice date.",
      +      "format": "date",
      +      "type": "string"
      +    },
      +    "due_to": {
      +      "format": "date",
      +      "type": "string"
      +    },
      +    "exclude_case_statuses": {
      +      "description": "Exclude these case-workflow statuses, including when searching invoices.",
      +      "items": {
      +        "enum": [
      +          "active",
      +          "paused",
      +          "promised",
      +          "disputed",
      +          "closed"
      +        ],
      +        "type": "string"
      +      },
      +      "maxItems": 5,
      +      "type": "array",
      +      "uniqueItems": true
      +    },
      +    "exclude_statuses": {
      +      "description": "Statuses to exclude. Invoice searches use invoice status; cases and contacts use case status.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "maxItems": 10,
      +      "type": "array",
      +      "uniqueItems": true
      +    },
      +    "max_amount_minor": {
      +      "description": "Inclusive outstanding amount maximum in the selected currency.",
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    "max_days_overdue": {
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    "min_amount_minor": {
      +      "description": "Inclusive outstanding amount minimum in the selected currency; cases use overdue balance.",
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    "min_days_overdue": {
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    "promise_from": {
      +      "description": "Inclusive recorded payment-promise date; excludes cases without a promise.",
      +      "format": "date",
      +      "type": "string"
      +    },
      +    "promise_to": {
      +      "format": "date",
      +      "type": "string"
      +    },
      +    "readiness_status": {
      +      "description": "Exact payment-readiness state of the associated case.",
      +      "enum": [
      +        "unchecked",
      +        "ready",
      +        "missing_reference",
      +        "missing_evidence",
      +        "portal_not_submitted",
      +        "receipt_unconfirmed",
      +        "waiting_approval",
      +        "wrong_contact",
      +        "query_open"
      +      ],
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedOutput schema / properties / as_of_date
      Added value: +{
      +  "format": "date",
      +  "type": "string"
      +}
    • addedOutput schema / properties / has_more
      Added value: +{
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / next_cursor
      Added value: +{
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / returned_count
      Added value: +{
      +  "type": "integer"
      +}
    • addedOutput schema / properties / total_count
      Added value: +{
      +  "description": "All matches after filters, before paging.",
      +  "type": "integer"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "data_notice",
      -  "organisation",
      -  "source",
      -  "filters",
      -  "invoice_count",
      -  "invoices"
      -]New value: +[
      +  "data_notice",
      +  "organisation",
      +  "source",
      +  "filters",
      +  "invoice_count",
      +  "invoices",
      +  "applied_filters",
      +  "total_count",
      +  "returned_count",
      +  "has_more",
      +  "next_cursor",
      +  "as_of_date"
      +]
  2. Changed5 schema fields changed
    • addedInput schema / properties / limit / description
      Added value: +"Number of matching records to return; omit to use the server default."
    • addedInput schema / properties / query / description
      Added value: +"Optional text matched against invoice number or customer name in the selected business; omit to list synced records."
    • addedInput schema / properties / status / description
      Added value: +"Optional synced invoice status; overdue selects outstanding invoices past their due date."
    • changedInput schema / properties / workspace_id / description
      Previous value: -"Exact workspace_id returned by list_shvl_workspaces and selected by the user. Never infer a different client workspace."New value: +"Selected business ID from list_shvl_workspaces. Ask the user to choose if several businesses are available; never infer another business."
    • addedOutput schema / description
      Added value: +"filters echoes applied query and status; invoice_count counts returned invoices. invoices contains SHVL invoice_id and customer_id values, invoice numbers, dates, currency, total_minor, amount_due_minor and synced status. Monetary values are currency minor units. source records the completed Xero sync; results are not a live Xero lookup."
  3. Added

TDQS

A4.5/5.0
Behavior5/5

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

Annotations cover readOnly/idempotent safety, and the description still adds substantial behavior: capped at 20, snapshot not live data, applied_filters echo, total_count counts all filtered matches while results are paged, continuation invalidation on data change, and currency/date coupling rules. This is real context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose before paging and edge-case semantics, and every sentence adds information. It is a dense, run-on block, though, so the many conditional rules are harder to scan than they could be.

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

Completeness4/5

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

For a 20-parameter tool with an output schema, the description covers paging, currency coupling, date semantics, and the invoice-vs-case filter distinction well. Remaining gaps are individual enum semantics (readiness_status, promise dates) that the schema largely handles.

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

Parameters4/5

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

Schema coverage is 80% so baseline is 3, but the description adds meaning the schema lacks: amount bounds require currency, case/contact dates use the oldest positive overdue date in the selected currency, amounts use the selected-currency overdue subtotal, and detail filters apply to invoice history rather than case metadata. It does not clarify several enum params like readiness_status.

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

Purpose5/5

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

States a specific verb (Search) and resource (sales invoices) plus scope: the signed-in owner's latest completed SHVL Xero sync, matching by invoice number or customer name. Explicitly flags 'not live Xero state', which separates it from a live-invoice getter like get_xero_invoice.

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

Usage Guidelines4/5

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

Gives clear operational guidance: page with next_cursor and identical filters until has_more is false, and restart if data changes. Amount filters require currency. It does not explicitly say when to prefer search_credit_control_cases or search_xero_contacts instead, so sibling routing is left implicit.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources