fawtar_outstandingEvery unpaid issued invoice with its remaining balance and how many days it is overdue, newest due first, plus the totals. This is the answer to 'who owes me money' without composing filters by hand.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| overdueOnly | No | Only invoices past their due date. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds return format and sorting, but it says 'Every unpaid issued invoice' while the schema has a default limit of 50, which could mislead an agent into thinking all are returned. It also does not clarify that the totals are computed over the returned set or all outstanding, leaving ambiguity. This is a transparency gap beyond what annotations cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The core purpose is front-loaded, and the 'who owes me money' framing adds immediate context without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the returned data (unpaid invoices with balance, days overdue, sorted by due date, plus totals) but omits critical details about pagination (limit) and the overdueOnly filter. It also fails to clarify whether totals apply to just the returned page or all outstanding invoices. Since there is no output schema, the description carries the burden of return semantics, and it only partially does so.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (overdueOnly has a description, limit does not). The description does not mention either parameter or how they affect results. It fails to compensate for the missing schema documentation, and the 'Every...' phrasing even conflicts with the limit parameter's existence.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource (unpaid issued invoices) and outcome (remaining balance, days overdue, totals), and explicitly frames it as the answer to 'who owes me money'. It clearly differentiates from siblings like fawtar_list (general list) and fawtar_vat_summary (VAT-specific) by focusing on outstanding balances.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It directly instructs when to use this tool ('This is the answer to who owes me money without composing filters by hand'), giving a clear use case. It does not explicitly exclude alternatives, but the context makes the intended scenario unambiguous. A minor deduction for not naming alternatives or edge cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
fawtar_create and fawtar_create_invoice are clearly separated by the explicit warning that invoices need the specialized tool, and get/list/outstanding/vat_summary each have distinct read/report purposes. The only mild ambiguity is fawtar_outstanding overlapping fawtar_list with filters, but descriptions make the specialized intent obvious.
All tools share the fawtar_ prefix and snake_case, but the action suffix is inconsistent: create/get/list are generic verbs, create_invoice combines verb+noun, and outstanding/vat_summary are noun-phrase report names rather than verb_noun commands.
Six tools is a compact, well-scoped set for a broad API: three generic CRUD-ish verbs and three specialized financial actions (invoice creation, outstanding report, VAT summary). Each tool has a distinct role and the count feels intentional.
The surface covers creation, retrieval, listing, and key financial reports, but there are no update/delete tools for editable master data and no way to create credit notes or debit notes even though the invoice tool explicitly directs corrections to credit notes. These are significant gaps that will make common workflows fail.