Skip to main content
Glama

taxapp.nz

List income records

list_income
Read-onlyIdempotent

Lists income records. Each is one amount received, with its date, the contact who paid it and its income type: commission income names the contractor who earned it; rent and tenant reimbursements name the property and tenancy. Amounts are what was received, in NZD; commission records also show the GST within the amount and taxapp's indicative KiwiSaver, ACC levy, income tax and take-home. Every record names its property (propertyId and propertyName). A short stay's paid is the payout that reached the bank: its income is shortStay.guestPaid, and its nights count once per booking (a deposit and its balance share one booking reference). Each short stay also has its platform fees, flat-rate credit, booking reference, check-in and check-out, guests, the main guest's name, whether it was cancelled, stayStarted (the guest's stay has begun) and gstTreatment (standard: the GST shown is in what the guest paid; zeroRated: a platform that charges guests GST sold it for a registered host; notRegistered: no GST). A short-stay refund takes its guestPaid off the income; it is never income itself. To list one property's stays, give property_id and income_type shortStay. Filter by tax year, type, contact, contractor, property, tenancy or dates. Pages of up to 500: the answer gives items, total, offset and limit.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_income"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoThe last New Zealand date to include, yyyy-MM-dd.
fromNoThe first New Zealand date to include, yyyy-MM-dd.
limitNoHow many records to return, 1 to 500. The default is 100.
offsetNoHow many records to skip, to page through a long list: the answer's total says how many there are. The default is 0.
tax_yearNoThe New Zealand tax year, named by the year it ends in: 2026 is 1 April 2025 to 31 March 2026. Leave it out for the current tax year.
contact_idNoOnly records with this contact (the payer or supplier), from list_contacts.
tenancy_idNoOnly rent and reimbursements under this tenancy, from list_properties.
income_typeNoOnly this income type: commission (a contractor's commission income), rental (rent from a tenancy), tenantReimbursement (a tenant repaying a bill the owner paid), shortStay (a payout for a stay booked through a platform such as Airbnb, or directly) or shortStayRefund (money given back to a short-stay guest). Short stays are offered only while the organisation has them switched on.
property_idNoOnly records for this rental property, from list_properties.
organisation_idNoThe id of the organisation to use, from list_organisations. Leave it out when the connection covers only one organisation; it is required when it covers more than one.
contractor_contact_idNoA contractor's contact id, from list_contacts (contact type contractor), for one contractor's figures.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / income_type / description
      Previous value: -"Only this income type: commission (a contractor's commission income), rental (rent from a tenancy) or tenantReimbursement (a tenant repaying a bill the owner paid)."New value: +"Only this income type: commission (a contractor's commission income), rental (rent from a tenancy), tenantReimbursement (a tenant repaying a bill the owner paid), shortStay (a payout for a stay booked through a platform such as Airbnb, or directly) or shortStayRefund (money given back to a short-stay guest). Short stays are offered only while the organisation has them switched on."
    • changedInput schema / properties / income_type / enum
      Previous value: -[
      -  "commission",
      -  "rental",
      -  "tenantReimbursement"
      -]New value: +[
      +  "commission",
      +  "rental",
      +  "tenantReimbursement",
      +  "shortStay",
      +  "shortStayRefund"
      +]
  2. First observed

TDQS

A4.2/5.0
Behavior5/5

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

Annotations already declare a safe, idempotent read, and the description adds substantial behavior on top: page size capped at 500 with items/total/offset/limit in the answer, amounts are net received in NZD, refunds subtract guestPaid and are never income themselves, and nights count once per booking. That is real domain behavior an agent cannot get from the structured fields.

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

Conciseness3/5

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

The core purpose is front-loaded in the first sentence, but the body is a long undifferentiated block covering short-stay GST treatment, platform fees, guest details and cancellation flags. Because there is no output schema much of that is justified, yet it reads as dense prose with no structure and could be tightened.

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

Completeness5/5

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

With 11 optional parameters, no output schema, and a domain with several non-obvious record types, the description supplies the record taxonomy, the pagination envelope, currency, and refund semantics. An agent has enough to call it and interpret the response without further context.

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 100%, so the baseline is 3, but the description earns more by explaining filter interactions the schema does not: the property_id plus income_type=shortStay combination, and how refund records relate to the shortStay type. Most remaining parameter meaning (date formats, tax-year convention) is already in the schema.

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

Purpose4/5

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

Opens with a specific verb and resource ('Lists income records') and then defines what a record is (amount received, date, contact, income type) plus type-specific fields. It never names the sibling read tools (get_income_record, get_income_history) so the boundary between listing and fetching a single record is left implicit, which keeps it out of the top band.

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 concrete usage direction: which filters exist ('tax year, type, contact, contractor, property, tenancy or dates'), and the non-obvious rule 'To list one property's stays, give property_id and income_type shortStay.' It does not say when to prefer this over get_income_record or get_income_history, so there is no explicit when-not guidance.

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.