Loading ToolBench
Remote MCP server (Claude connector) for the inv.bg invoicing API, exposing read-only tools over the inv.bg invoicing API
Strong foundation with 15 well-named tools, comprehensive descriptions (avg 180 chars), and complete input schemas using Zod. All tools are read-only with proper annotations. Key gaps: output schemas are not formally documented in the code (responses are JSON-stringified without explicit schema declarations), and error handling lacks recovery guidance. Tool names follow verb_noun pattern consistently (list_, get_, detect_, derive_). Parameters are well-typed with enums for constrained values (status, type, dimension). No secrets exposed as parameters. Pagination properly implemented with per_page limits.
Receivables aging: outstanding balances bucketed by days overdue (not_due, 1-30, 31-60, 61-90, 90+). Grouped by client and currency. Includes oldest invoice date per client and a list of overdue invoices with their days overdue. Useful for collections and cash-flow forecasting.
Cash-flow forecast: expected income per upcoming month from active recurring clients, plus the overdue collections backlog. Identifies clients with stable monthly billing patterns and projects their future revenue. Useful for cash-flow planning.
Client health card: turnover by year, outstanding balance, payment behavior (average days to pay), recurring billing pattern (if any), and unpaid invoice count. Useful for credit risk assessment and relationship management.
Compare two periods: current vs. previous (e.g. this month vs. last month, or this quarter vs. last quarter). Returns totals per currency plus per-client deltas — new clients, lost clients, grown and shrunk ones. Useful for trend analysis and sales performance.
Reconstruct periodic-invoice templates from documents flagged issued_from_periodic_invoice. Returns one record per client+currency with interval (weekly, biweekly, monthly, quarterly, semiannual, yearly), last issue date, next expected issue date, and active status. Useful for understanding automated billing schedules.
Output schemas not formally documented. Tools return JSON-stringified results via jsonResult() helper, but no explicit schema declarations exist in tool registration. LLMs cannot predict response structure for planning downstream calls.
Error handling lacks recovery guidance. errorResult() returns only a message string without categorizing errors as retryable, user-fixable, or fatal. InvBgApiError handling for 401/404 is present but generic, no guidance on next steps (e.g., 'Check INVBG_API_KEY' for 401 is helpful, but 404 should suggest 'verify the ID exists or call invbg_list_clients to find valid IDs').
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 69 | 2026-07-28+ | v2 |
Detect recurring billing patterns: clients billed on a regular cadence. Returns clients with stable monthly amounts and day-of-month patterns, trend analysis (increased, decreased, stable, stopped), and unpaid totals. Useful for revenue forecasting and churn detection.
Retrieve a single client (customer) by its unique ID.
Retrieve a single invoice/document by its unique ID, with full details including line items, payment records, and metadata.
Retrieve line items of a single invoice/document by its unique ID. Returns the items array with name, quantity, unit price, discount, VAT rate and total price per item.
Fetch ALL invoices/documents for a period in one call, auto-paginating through every page. Give either days_back (e.g. 90 for the last 90 days) or an explicit date_from/date_to range. Optionally narrow by client or payment status. Returns compact summaries (id, number, type, date, client, total, status) — use invbg_get_invoice for details of a specific one.
Line-item turnover: aggregates invoice items by name and currency across a period. Returns quantity sold, revenue per item, and invoice count. Useful for product/service performance analysis.
List clients (customers) of the firm. Supports filtering by name, EIK/Bulstat, VAT number, EGN and type, plus free-text search and pagination. Returns total count plus client records with their IDs (use the ID with invbg_list_invoices to get a client's invoices).
List invoices/documents. Filter by client (client_id from invbg_list_clients, or client name), payment status, document type, date range, document number, or free-text search. Returns document summaries (id, number, type, client, amounts, status) without line items — use invbg_get_invoice or invbg_get_invoice_items for the items.
Turnover report: sum invoices by client, creator, day, week, month or year. Breaks down by currency, counts invoices, and splits paid vs. outstanding. Credit notes are subtracted. Useful for revenue analysis, sales team performance, and cash-flow tracking.
Monthly VAT summary: taxable base, VAT and gross totals per currency. Breaks down by month and currency. Useful for VAT return preparation and tax compliance.
Parameter descriptions lack format/constraint details. E.g., date_from/date_to state 'YYYY-MM-DD' but do not specify whether past dates are allowed, whether date_from must be <= date_to, or what happens if both are omitted. days_back lacks min/max bounds (e.g., is 0 valid? Is 10000 valid?).
Tool composition: invbg_list_invoices and invbg_get_invoices_for_period overlap significantly. Both filter by date range, client, status, and type. The distinction (pagination vs. auto-pagination) is not obvious from names. Consider renaming to invbg_list_invoices_paginated and invbg_fetch_invoices_all_pages, or merging with an 'auto_paginate' boolean parameter.
Missing dependency hints in descriptions. E.g., invbg_list_invoices accepts client_id but does not state 'Get client_id from invbg_list_clients first.' Similarly, invbg_get_invoice_items requires an invoice ID but does not hint that invbg_list_invoices or invbg_get_invoice provides it. This forces LLMs to discover tool chains via trial and error.