pennylane-mcp-server

pennylane_list_customer_invoices

Read-onlyIdempotent

List customer invoices and credit notes, with filters for customer, date range, status, unpaid items, and deadlines; returns compact results by default.

Instructions

Liste les factures clients (et avoirs, montant négatif), en mode compact par défaut.

Filtré côté Pennylane : customer_id, date_from, date_to. L'API ne filtre ni par statut, ni par échéance, ni par montant. Filtré localement : status, unpaid_only, deadline_before. Dans ce cas l'outil pagine seul (plafond 1 000 documents), renvoie toutes les correspondances et indique is_complete ; limit et cursor sont ignorés.

« Payé » : le champ paid ne fait pas foi (les factures annulées ont paid=true). Seuls status et remaining_amount_with_tax comptent. « Impayée » veut dire « non rapprochée dans Pennylane » : pour savoir si l'argent est arrivé, voir Qonto.

Input Schema

TableJSON Schema

Name	Required	Description
`sort`	No	Tri : 'id', '-id', 'date', '-date' (défaut : '-id'). En filtrage local, aussi 'deadline', '-deadline' (défaut : 'deadline').
`limit`	No	Nombre de résultats (1-100, défaut: 20 ; ignoré en filtrage local).
`cursor`	No	Curseur pour la pagination (ignoré en filtrage local).
`detail`	No	true = JSON complet de chaque facture au lieu du mode compact.
`status`	No	Statut exact (filtrage local) : 'upcoming', 'late', 'paid', 'cancelled', 'archived', 'draft', 'credit_note'.
`date_to`	No	Date de facture maximale incluse, YYYY-MM-DD (côté Pennylane).
`date_from`	No	Date de facture minimale incluse, YYYY-MM-DD (côté Pennylane).
`customer_id`	No	Filtrer par ID client (côté Pennylane).
`unpaid_only`	No	Seulement les impayées : ni brouillon, ni archivée, ni annulée, reste dû TTC > 0 (filtrage local).
`deadline_before`	No	Échéance strictement antérieure à cette date, YYYY-MM-DD (filtrage local). Avec unpaid_only=true et la date du jour : les factures en retard.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Oct 4, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Annotations already cover read-only, idempotent, non-destructive, and open-world hints. The description goes further by disclosing compact-mode default, local filtering pagination behavior (1000-document cap, is_complete indicator, ignored limit/cursor), and the critical caveat that the paid field is unreliable and only status and remaining_amount_with_tax should be trusted.

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?

The description is front-loaded with the main purpose and organized into clear paragraphs. It is somewhat lengthy, but every sentence conveys necessary nuance about filtering and semantics, so it earns its place without excessive repetition.

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?

Given 10 parameters, 100% schema coverage, an output schema, and rich annotations, the description fills the remaining gaps: local versus server-side filtering behavior, pagination side effects, and the ambiguous meaning of 'paid' and 'unpaid'. Nothing essential for correct invocation appears to be missing.

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 description coverage is 100%, so the baseline is 3. The description adds meaningful context by grouping parameters into server-side versus local filtering and explaining the consequences for pagination, which goes beyond the schema's individual parameter descriptions.

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?

Clearly states it lists customer invoices, including credit notes with negative amounts, in a compact mode by default. The verb+resource are unambiguous, but it does not explicitly name sibling alternatives such as get_customer_invoice or list_supplier_invoices to help an agent disambiguate in every case.

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?

Explains which filters are applied server-side versus locally, and notes that local filtering forces full pagination while limit and cursor are ignored. It also clarifies that 'unpaid' means not reconciled in Pennylane and points to Qonto for actual cash arrival, giving useful context but not explicit when-to-use-vs-alternatives guidance.

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

Deploy Server