Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@simple_invoicing-mcp List all unpaid invoices"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP (Model Context Protocol) server that acts as a bridge to any deployed simple_invoicing FastAPI instance.
This server exposes the simple_invoicing REST API as MCP tools, making it usable directly from Claude Desktop, Cursor, or any other MCP-compatible client.
Node.js ≥ 18
A running simple_invoicing FastAPI backend
A long-lived bearer token (API token) for the backend
Related MCP server: Prism
git clone https://github.com/nikhilb2/simple_invoicing-mcp.git
cd simple_invoicing-mcp
npm install
npm run buildSet these environment variables before running:
export INVOICING_BASE_URL=https://your-invoicing-instance.example.com
export INVOICING_API_TOKEN=your-long-lived-bearer-token-hereOr copy .env.example to .env and fill in the values.
Open your simple_invoicing backend's Swagger UI (usually at /docs)
Use the /api/auth/login endpoint with your credentials
Copy the access_token from the response
Use this token as INVOICING_API_TOKEN
npm run devThis starts the MCP server on stdio using tsx.
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"invoicing": {
"command": "node",
"args": ["/absolute/path/to/simple_invoicing-mcp/dist/index.js"],
"env": {
"INVOICING_BASE_URL": "https://invoicing.example.com",
"INVOICING_API_TOKEN": "your-token-here"
}
}
}
}Add to .cursor/mcp.json in your project root:
{
"mcpServers": {
"invoicing": {
"command": "node",
"args": ["/absolute/path/to/simple_invoicing-mcp/dist/index.js"],
"env": {
"INVOICING_BASE_URL": "https://invoicing.example.com",
"INVOICING_API_TOKEN": "your-token-here"
}
}
}
}Tool | Description | Parameters |
| List all invoices with optional filtering |
|
| Get a single invoice by ID |
|
| Create a new invoice |
|
| Get the PDF for an invoice |
|
Tool | Description | Parameters |
| List all products |
|
| Get a single product by ID |
|
| Create a new product |
|
Tool | Description | Parameters |
| List all ledgers |
|
| Get the statement for a ledger |
|
| Get the day book entries |
|
Tool | Description | Parameters |
| List all inventory items |
|
Tool | Description | Parameters |
| List all buyers |
|
| Get a single buyer by ID |
|
Tool | Description | Parameters |
| List all payments |
|
| Create a new payment |
|
npm install # Install dependencies (set NODE_ENV=development for devDeps)
npm run build # Compile TypeScript
npm test # Run testsMIT
Create a new invoice
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Invoice data object matching the API schema |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fails to disclose behavioral traits such as mutability, side effects, or required permissions. The one-line description simply states the action without further context.
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?
The description is very short and to the point, but it sacrifices completeness. It is front-loaded with the purpose, yet lacks other important information that could be included concisely.
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?
For a tool with one required nested object parameter and no output schema, the description does not explain the structure of the data object or what the response contains. This leaves significant gaps for an AI agent.
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 coverage is 100% and the parameter description in the schema already indicates it is an invoice data object. The function description adds no additional semantic value, but the schema documentation is sufficient for basic understanding.
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 'Create a new invoice' clearly identifies the verb and resource, but does not distinguish it from sibling tools like create_payment or create_product. It is specific enough to avoid confusion with get or list operations.
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?
No guidance is provided on when to use this tool instead of alternatives such as create_payment or get_invoice. The description lacks context about prerequisites or typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new payment
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Payment data object matching the API schema |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It fails to disclose any behavioral traits such as idempotency, side effects, or required permissions.
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?
The description is under-specified, consisting of a single sentence that adds no value. It lacks substance and fails to earn its place.
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?
Given the tool's complexity (nested object parameter, no output schema, no annotations), the description is completely inadequate. It provides no information about the data object structure or return value.
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 coverage is 100% and the description does not add meaning beyond the schema. Baseline of 3 is appropriate as the schema documents the parameter adequately, albeit generically.
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 'Create a new payment' is a tautological restatement of the tool name. It provides a verb and resource but offers no additional context to distinguish it from sibling tools like 'create_invoice' or 'create_product'.
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?
No usage guidance is provided. There is no indication of when to use this tool versus alternatives, nor any prerequisites or constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new product
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Product data object matching the API schema |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only repeats the title with no additional behavioral context. No annotations are provided, so the description must carry the full burden, but it fails to disclose any traits such as idempotency, auth requirements, or side effects.
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?
The description is very short (one sentence) but lacks substance. It is under-specified and does not provide valuable information beyond the tool name, making it insufficient rather than concise.
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?
Given the lack of output schema and nested object parameter, the description is incomplete. It does not explain the return value, required fields, or when creation fails, which an agent would need to use the tool correctly.
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 coverage is 100% with one parameter described as 'Product data object matching the API schema'. The tool description does not add any further meaning beyond the schema, so baseline 3 is appropriate.
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 clearly states 'Create a new product', which is specific verb+resource. However, it does not differentiate from sibling tools like create_invoice or create_payment, all of which have similar 'Create a new...' descriptions.
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?
No usage guidelines are provided. The description does not specify when to use this tool versus alternatives, nor any prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single buyer by ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Buyer ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states 'Get', implying a read operation. It does not disclose behavior on missing IDs, error handling, or any other behavioral traits that the agent should know.
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?
The description is extremely concise (6 words) and front-loaded with all essential information. Every word adds value with no 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?
For a simple get-by-ID tool with one required parameter and no output schema, the description is nearly complete. It could optionally explain the return value structure, but it is adequate as is.
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 coverage is 100%, so the schema fully documents the parameter. The description adds minimal value beyond restating the parameter ('by ID'). Baseline score of 3 is appropriate.
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 clearly states the action ('Get'), the resource ('buyer'), and the criterion ('by ID'). It effectively distinguishes from sibling tools like 'list_buyers' which return multiple results.
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?
The description provides no guidance on when to use this tool versus alternatives. For example, it does not mention 'use list_buyers to get all buyers, use this to get a specific one', leaving the AI without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the day book entries with optional date range
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | Start date (YYYY-MM-DD) | |
| end_date | No | End date (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description implies read-only but does not explicitly state safety, side effects, pagination, or auth requirements.
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?
Single, clear sentence with no fluff. Appropriate for a simple tool.
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?
Tool is simple with 2 optional params, no output schema. Description minimally sufficient but lacks explanation of return format or performance implications.
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 has 100% description coverage for both parameters. Description adds no extra meaning beyond 'optional date range' already implied by schema.
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?
Description clearly states verb 'Get', resource 'day book entries', and optional date range. Distinguishes from siblings like get_ledger_statement by specifying 'day book'.
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?
No guidance on when to use this tool versus alternatives (e.g., get_ledger_statement, list_invoices). Does not mention prerequisites or restrictions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single invoice by ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Invoice ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description only restates the purpose. No information on error handling, response structure, or side effects is given.
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?
Single sentence, front-loaded with key information, no filler words.
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?
For a simple get-by-ID tool with no output schema or annotations, the description is adequate but lacks context on response format or error behavior.
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 coverage is 100% and the single parameter 'id' is described; the description adds no additional meaning beyond the schema.
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?
Description clearly states the action ('Get') and resource ('single invoice by ID'), distinguishing it from siblings like list_invoices which retrieves multiple.
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?
Usage is implied (get by ID) but no explicit when-to-use or alternatives are mentioned; no exclusions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the PDF for an invoice (returns base64 if available)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Invoice ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions "if available", hinting at conditional behavior but does not explain what happens if the PDF is unavailable (e.g., error or empty). No mention of idempotency or safety beyond the implied read nature.
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?
The description is a single sentence with no wasted words, front-loading the purpose and key detail about return format.
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?
Given the tool's simplicity (1 parameter, no output schema), the description covers the core purpose and return format. However, it lacks details on error handling or behavior when PDF is not found, which slightly reduces completeness.
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 coverage is 100% with description "Invoice ID". The tool description adds no extra semantics beyond what the schema already provides. Baseline of 3 is appropriate.
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 clearly states the verb "Get" and the resource "PDF for an invoice", distinguishing it from sibling tools like get_invoice which likely return JSON data. The return format "base64" is also mentioned.
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?
The description implicitly indicates when to use this tool: when the PDF is needed instead of invoice data. However, no explicit when-not-to-use or alternatives are provided. Considering the low complexity, a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the statement for a ledger with optional date range
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Ledger ID | |
| start_date | No | Start date (YYYY-MM-DD) | |
| end_date | No | End date (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description implies a read-only operation with 'get', but does not elaborate on any behavioral traits, return format, or potential side effects. For a simple read tool, this is minimally adequate.
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?
Single sentence, no fluff. Could be slightly improved by specifying what a statement includes or additional context, but it is appropriately concise.
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?
Tool has low complexity (3 parameters, no output schema), but no annotations or explanation of return data. The description is complete enough for a basic understanding but lacks details like what constitutes a statement or any limitations.
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 100%, so baseline is 3. The description mentions 'optional date range', which loosely connects to start_date and end_date, but adds no significant meaning beyond the schema definitions.
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?
Tool name and description clearly state verb 'get' and resource 'ledger statement'. The description adds 'with optional date range', which is specific and distinguishes from sibling tools like list_ledgers and get_day_book.
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?
No guidance on when to use this tool versus alternatives. The description only states what it does, with no mention of when to choose it over similar tools like get_day_book or list_invoices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single product by ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Product ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral transparency. It implies a read-only operation ('Get') but provides no additional context such as rate limits, authentication requirements, or side effects.
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?
The description is a single short sentence that is front-loaded and contains no unnecessary words. Every word earns its place.
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?
Given the low complexity (1 parameter, no output schema) and no annotations, the description is adequate but lacks specifics about what happens if the product is not found or if there are any access restrictions.
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 100% (the parameter 'id' is described as 'Product ID'). The description adds no extra meaning beyond the schema, so baseline score of 3 is appropriate.
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 clearly states the verb 'Get' and the resource 'single product by ID', which distinguishes it from sibling tools like create_product and list_products. It is specific and unambiguous.
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?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of when not to use it or any prerequisites (e.g., if the product exists).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all buyers
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Number of records to skip | |
| limit | No | Number of records to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It says 'all buyers' but input schema shows pagination (skip/limit), so behavior is not accurately disclosed. No mention of read-only nature, rate limits, or authorization.
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?
Extremely short but omits key behavioral details. While concise, it sacrifices informativeness.
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?
Given the tool's simplicity (2 params, no output schema), the description should at least disclose pagination. It is incomplete for an agent to use effectively.
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 coverage is 100% with descriptions for skip and limit. The description adds nothing beyond the schema, but being baseline 3 is appropriate.
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 'List all buyers' clearly states the action and resource. It distinguishes from sibling tools like get_buyer (single buyer) and other list tools. However, it doesn't mention pagination limitations.
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?
No guidance on when to use this vs. alternatives like get_buyer. No mention of prerequisites or context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all inventory items
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Number of records to skip | |
| limit | No | Number of records to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'List all inventory items', but the schema includes skip and limit parameters, indicating pagination—meaning it does not list all items in one call. This contradiction misleads about the tool's behavior. No annotations are present to clarify safety or side effects.
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?
The description is only three words, which is too sparse for a list tool with pagination. It lacks necessary details about ordering, filtering, or result format, making it underspecified.
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?
Given the absence of an output schema and the presence of pagination parameters, the description fails to explain what the tool returns or how to handle paginated results. It is incomplete for effective use.
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?
The schema provides full coverage with descriptions for both parameters (skip, limit). However, the description's claim of 'all' conflicts with the pagination behavior implied by the schema, adding confusion rather than clarifying parameter usage.
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 the verb 'List' and the resource 'inventory items' clearly. However, it does not differentiate from sibling list tools (e.g., list_buyers, list_products) which list different resources.
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?
No guidance is provided on when to use this tool versus alternatives like list_products or list_buyers. There are no exclusions or context for preferred use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all invoices with optional filtering
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_type | No | Filter by invoice type | |
| skip | No | Number of records to skip | |
| limit | No | Number of records to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only says 'list' with optional filtering. It does not disclose pagination behavior, return format, or read-only nature. Minimal transparency.
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?
Ultra-concise single sentence, front-loaded with key action and resource. However, it might be too brief for completeness.
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?
No output schema, but the description and schema cover the input. Lacks details on return format, pagination behavior, or expected output. Adequate for a simple list tool.
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 coverage is 100%, with clear descriptions for each parameter. The description adds 'optional filtering' but no further semantics beyond schema.
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 clearly states the tool lists invoices with filtering, using a specific verb and resource. It distinguishes from 'get_invoice' (single) and other list tools, though not explicitly.
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?
No guidance on when to use this vs alternatives like 'get_invoice' or other list tools. Only implies filtering without specifying scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all ledgers
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Number of records to skip | |
| limit | No | Number of records to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description discloses no behavioral traits beyond the basic listing action. It does not mention pagination behavior, read-only nature, or any side effects, leaving the agent without insight into what happens when the tool is invoked.
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?
The description is very concise (three words), but it is overly terse and lacks structured information. It is front-loaded but fails to provide essential context, making it merely adequate.
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?
Given the lack of output schema and the presence of pagination parameters, the description is incomplete. It does not explain what the tool returns, pagination behavior, or ordering, which is necessary for an agent to use it effectively.
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 100%, with both skip and limit well-documented in the schema. The tool description adds no additional meaning about parameters, so it meets the baseline but does not exceed it.
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 'List all ledgers' is clear about the verb and resource, but the word 'all' is misleading because the input schema includes pagination parameters (skip, limit), implying it may not return all ledgers at once. It does not distinguish from sibling list tools beyond the resource name.
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?
No guidance is provided on when to use this tool versus alternatives like list_invoices or list_payments. The description lacks context for usage scenarios, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all payments
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Number of records to skip | |
| limit | No | Number of records to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description's full burden is behavioral disclosure. It only states 'List all payments', omitting details such as pagination, sorting, or what data is returned. This is insufficient for an agent to understand the tool's full behavior.
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?
The description is a single, concise sentence with no wasted words. It is efficient, though it could benefit from a bit more context without becoming verbose.
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 tool has no output schema and no annotations, so the description must compensate. It fails to mention what is returned (e.g., list of payment objects) or the pagination behavior, leaving significant gaps for an agent to infer.
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 100% for both parameters (skip and limit), with clear defaults and constraints. The description adds no additional meaning, so the baseline score of 3 is justified.
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 'List all payments' clearly states the action and resource, effectively distinguishing it from sibling tools like get_invoice or list_invoices. However, 'all' is somewhat misleading given the pagination parameters, so a 4 is appropriate.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., when to use list_payments vs list_invoices). The description lacks any context for selection, earning a low score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all products
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Number of records to skip | |
| limit | No | Number of records to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits such as read-only nature (implied but not stated) and pagination support (not mentioned). It only says 'list all products', omitting key details.
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?
The description is concise but overly brief for a list tool with pagination. It lacks important structural elements like when-to-use or behavioral notes.
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?
Given the tool has 2 parameters and no output schema, the description should at least mention pagination or return format. It is incomplete for effective selection and invocation.
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 100% for both parameters (skip, limit), so the description adds no value beyond what the schema already provides. Baseline 3 is appropriate.
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 'List all products' clearly states the verb (list) and resource (products), but does not distinguish from sibling tools like list_inventory or list_buyers, which also list resources.
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?
No guidance on when to use this tool versus alternatives or when to filter or paginate. The description is too generic and lacks context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0create_invoicecreate_paymentcreate_productget_buyerget_day_bookget_invoiceget_invoice_pdfget_ledger_statementget_productlist_buyerslist_inventorylist_invoiceslist_ledgerslist_paymentslist_productsScored across 15 tools
Each tool targets a distinct resource (invoice, payment, product, buyer, ledger, inventory) with unique operations (create, get, list). No two tools have overlapping purposes, making it easy for an agent to select the correct one.
All tool names follow a consistent verb_noun pattern (e.g., create_invoice, get_buyer, list_invoices) using lowercase snake_case. No mixing of conventions or vague verbs like 'process' or 'do_thing'.
With 15 tools, the surface is well-scoped for a simple invoicing system covering core entities (invoices, payments, products, buyers, ledgers, inventory). Each tool earns its place without unnecessary bloat or deficiency.
The tool set provides basic CRUD operations (create and read/list) for most entities but lacks update and delete functionalities (e.g., update_invoice, delete_product). While the core workflow of creating and reading is covered, agents may hit dead ends when needing to modify or remove records.
Create and manage invoices and customers on Jupiter Invoice (MCP, API-key auth).
MCP server for Codat — companies, connections, invoices, bills and financial statements.
Fakturownia.pl (Polish invoicing) via MCP: invoices, clients, products, warehouse. Full read-write.
Headless API-first double-entry accounting & bookkeeping engine. 84 MCP tools over HTTP.
