Timesheet Portal MCP server

List invoices

list_invoices

Read-onlyIdempotent

Fetch invoices for a date range, filtered by status, client, project, or invoice type, with optional line items.

Instructions

Invoices dated in a range (POST /invoices, 'Get invoices'; a POST that changes nothing): number, status, dates, client, project, task, worker, currency, net, tax and total, and optionally the line items. invoice_type picks client invoices (default), client credit notes, self-billing invoices or self-billing credit notes (sent as invoiceReportType, whose spec description reads 'Deprecated - (only used by /invoices/ POST endpoint)'). Other filters sent as documented: invoiceStatusFilters (empty returns every status, Draft included), clientCode, costCentreCode, chargeCodeGroupCodes, exportedFilter, modifiedAfter. Self-billing invoices are contractor pay: their amounts only with include_contact_details (any invoice returned for a self-billing type is treated as self-billing, whatever its invoiceSelfBilling flag says). Probably counts against the report limits (24 per hour); the endpoint documents no paging, so at most max_results invoices are shown.

Input Schema

Name	Required	Description	Default
`end_date`	Yes	Invoice date on or before, YYYY-MM-DD (at most 366 days after start_date)
`exported`	No	Filter on export status (exportedFilter)
`statuses`	No	Invoice statuses to include; empty for all, Draft included
`start_date`	Yes	Invoice date on or after, YYYY-MM-DD
`client_code`	No
`max_results`	No	Most invoices to return in this call (default 100); the answer says how many were left out
`invoice_type`	No		ClientInvoices
`include_items`	No	Include each invoice's line items
`project_codes`	No	Only these projects (branches), sent as chargeCodeGroupCodes
`modified_after`	No	Only invoices modified after this date/time (modifiedAfter)
`cost_centre_code`	No
`include_contact_details`	No	Include self-billing (contractor pay) amounts, and stop redacting email addresses, phone numbers, national insurance numbers and UK postcodes typed into names and other text (bank and card numbers are always removed)

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 7, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent, and the description adds genuinely extra behavior: the 'POST that changes nothing' clarification, an approximate rate limit (24/hour), the absence of server-side paging plus the max_results cap, and the redaction rules for contact details with the always-removed bank/card numbers.

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?

One run-on paragraph mixing return fields, filter mappings, deprecation trivia, and rate limits; every claim is roughly relevant but there is filler ('sent as documented') and no structure to help an agent scan. Front-loading the date range is good, but readability suffers.

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?

No output schema exists, so the description must describe returns, and it does: the field list, the optional line items, and the note that the response reports how many invoices were omitted. Combined with the rate-limit and no-paging disclosures, an agent has everything needed to call this correctly.

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

Parameters5/5

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

With 12 params and only 75% schema coverage, the description compensates well: invoice_type maps to the deprecated invoiceReportType, statuses-empty returns everything including Draft, project_codes is sent as chargeCodeGroupCodes, and the self-billing flag quirk (any invoice returned for a self-billing type is treated as self-billing) is spelled out.

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?

The description gives a precise verb+resource ('Invoices dated in a range ... POST that changes nothing') and enumerates the returned fields, so it is unmistakably the invoice-listing tool and not list_projects, list_clients, or list_timesheets.

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?

It states the date-range scoping requirement, explains that invoice_type selects client invoices vs credit notes vs self-billing, and ties include_contact_details to getting self-billing amounts. It does not name an alternative tool or state when-not-to-use, but the sibling set is a different resource so there is little ambiguity to resolve.

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

Deploy Server

List invoices

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools