Paidnice

List invoices

list_invoices

Read-onlyIdempotent

Returns the organisation's sales invoices ordered by due date, earliest first, up to 100 per page. Defaults to unpaid invoices; filter by contact, status, due date range or search text. Use search with status all to find an invoice by number whether or not it is paid. Deleted invoices are never returned. Read only.

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": {
      "organisationId": "<organisationId>"
    },
    "name": "list_invoices"
  }
}

Input Schema

Name	Required	Description	Default
`limit`	No	Maximum number of records to return
`cursor`	No	Opaque cursor from a previous response's nextCursor. Omit to start from the most recent record.
`search`	No	Case insensitive partial match on the invoice number, reference or contact name. The status filter still applies
`status`	No	unpaid: approved invoices with a balance owing. overdue: unpaid invoices whose due date has passed in the organisation's timezone. paid: fully paid invoices. all: unpaid and paid invoices.	unpaid
`dueAfter`	No	Only invoices due on or after this date (YYYY-MM-DD)
`contactId`	No	Only invoices for this contact
`dueBefore`	No	Only invoices due on or before this date (YYYY-MM-DD)
`organisationId`	Yes	Id of the organisation to act on, from list_organisations

Output Schema

Name	Required	Description	Default
`data`	Yes
`nextCursor`	No	Pass as the cursor query parameter to fetch the next page. Absent on the last page.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 9, 2026

TDQS

A4/5.0

Behavior3/5

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

Annotations already declare readOnly, idempotent and non-destructive, and the description redundantly restates "Read only." It does add real behavioral facts beyond annotations: deleted invoices are never returned, results are due-date ordered, capped at 100 per page, and default to unpaid. What is missing is any note on cursor/pagination behavior when more records exist, which matters for a list tool.

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

Conciseness5/5

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

Four short sentences, front-loaded with scope and ordering, then filtering, then the lookup tip. No filler; each sentence carries a distinct fact.

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?

With an output schema present and full parameter documentation, the description covers what an agent needs to call this correctly. The only gap is pagination/cursor guidance for large result sets, which is left entirely to the schema field description.

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

Parameters3/5

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

Schema coverage is 100%, so every parameter is already documented in detail, including the status enum values and date formats. The description only reinforces the status default and the search-plus-status interaction, which the schema itself already states ("The status filter still applies"), so the baseline of 3 applies.

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?

Opens with a specific verb and resource ("Returns the organisation's sales invoices") plus ordering (due date, earliest first) and page size (up to 100). This is clearly a list operation, distinct from the sibling get_invoice which fetches a single 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?

States the default scope (unpaid) and enumerates the filter dimensions, and gives an explicit recipe: use search with status all to find an invoice by number regardless of payment state. It does not explicitly route the agent to get_invoice when the id is already known, so it falls short of full alternative-naming.

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

All Paidnice tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?