Manage a Quipu accounting account via MCP: contacts, invoices, additional income/expenses, and VAT/IRPF summaries.
Contacts: list/search, get, create, update, and delete contacts; capture NIF/CIF needed for invoicing.
Invoices: list by period, get details, create with line items (VAT/IRPF), update, delete (flagged as destructive), and fetch temporary PDF download URLs.
Additional incomes & expenses: list by period, get details, create supplier bills/deductible costs, update, delete, and get PDF download links.
Tax summaries: compute output VAT, input VAT, balance, and withholdings for a quarter or custom date range using get_tax_summary.
Design notes: read-only operations are annotated, writes are limited, and tax arithmetic is done in code rather than by the model.
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., "@mcp-quipu ¿Cuánto he facturado este trimestre?"
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 server for the Quipu API: invoicing, expenses, contacts, and accounting for freelancers and small businesses in Spain.
It lets an assistant like Claude query and operate your Quipu account in natural language: “How much have I invoiced this quarter?”, “create the September invoice for this client”, “give me the PDF of the latest invoice”.
Built by Nubiia. Sibling of mcp-holded.
Status: alpha (v0.1.0). 18 tools for contacts, invoices, expenses, and tax aggregation. The rest of the API resources are mapped in
docs/api-map.mdbut not yet exposed.
npm install -g @nubiia/mcp-quipuRelated MCP server: QuickBooks Online MCP Server
You need Quipu API credentials (Settings → API) and your account's slg, which is the first segment of your Quipu URLs: https://getquipu.com/<slg>/…
{
"mcpServers": {
"quipu": {
"command": "npx",
"args": ["-y", "@nubiia/mcp-quipu"],
"env": {
"QUIPU_CLIENT_ID": "tu_client_id",
"QUIPU_CLIENT_SECRET": "tu_client_secret",
"QUIPU_OWNER_SLUG": "tu_slug"
}
}
}
}Tool | Description |
| Lists contacts, with filtering by name and pagination |
| Details of a contact |
| Creates a contact (requires |
| Updates only the specified fields |
| Deletes a contact |
Tool | Description |
| Lists issued invoices, filterable by period |
| Details of an invoice |
| Issues an invoice with its line items, VAT and IRPF |
| Updates an invoice |
| Deletes an invoice |
| Temporary URL to download the PDF |
Tool | Description |
| Lists expenses and income, filterable by period |
| Details of an entry |
| Records a supplier invoice or deductible expense |
| Updates an entry |
| Deletes an entry |
| Temporary URL of the PDF |
Tool | Description |
| Output VAT, input VAT, balance, and withholdings for a quarter or range |
OAuth2, not API key. Unlike Holded, Quipu issues tokens that expire. The client caches them in memory, renews them with a 60-second margin, and shares a single request across concurrent calls. On a 401, it invalidates the token and retries.
Flattened JSON:API. Quipu returns { data: { id, attributes: {…} }. The tools flatten the response to { id, …attributes}, because models reason much better on flat objects and save wrapper tokens.
Writes are more restricted than reads. An invoice created by error is not a row in a database: it is a document with legal effects. Write operations have stricter quotas, and destructive ones are annotated with destructiveHint.
Tax arithmetic is done in code, not in the model. Quipu does not expose any tax form endpoints (130, 303, 111), so the figures must be derived from invoices and expenses. get_tax_summary walks through all pages of both resources, adds with rounding to cents, and returns the already calculated balance. Asking a model to add up a long list of amounts token by token is a sure-fire way to get a wrong tax figure.
Amounts come as text and with non-obvious names. The base amount is total_amount_without_taxes and the tax is vat_amount — there are no total or subtotal. The adder accepts a comma as a decimal separator, ignores empty values, and on a non-parseable value excludes it and warns in the response instead of propagating a silent NaN.
On deleting invoices. Spanish regulations require correcting by means of a corrective invoice, not by deleting an already numbered invoice. delete_invoice exists because the API allows it, but the tool description warns of this so that the model does not propose it lightly.
npm install
npm run build
npm test
npm run lintplified_invoices — receips and simplified invoices (7 ops)
paysheets — payrol (5 ops)
numbering_series, accounting_cateories, accounting_subcateories
atachments and book_entries
Automatic resolution of the owner_lug via GET /users/{id}
MIT
Record an expense or additional income in Quipu. Use it to log supplier bills and deductible costs. Assign an accounting_category_id whenever you know it — an uncategorised expense still counts for VAT but is useless for the profit and loss breakdown.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Entry kind as accepted by Quipu (e.g. "expense", "income") | |
| items | Yes | Line items of the expense | |
| notes | No | Free-text notes | |
| number | No | Supplier document number | |
| paid_at | No | Payment date (YYYY-MM-DD) | |
| contact_id | No | Id of the related Quipu contact, if any | |
| issue_date | No | Issue date (YYYY-MM-DD) | |
| payment_method | No | Payment method | |
| recipient_name | No | Supplier or recipient name | |
| accounting_category_id | No | Id of the accounting category to file this entry under |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the mutation profile is covered. The description adds useful behavioral context about accounting categories — uncategorised expenses still affect VAT but are excluded from profit/loss breakdowns — but it does not disclose other side effects, prerequisites, or response behavior. This is adequate but not rich.
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 compact and front-loaded: it states the core action first, then the primary use case, then the most important parameter guidance. Every sentence earns its place with no filler or repetition.
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 10 parameters and no output schema, the description does not explain every field, but the schema fully covers parameter semantics. What the description adds — purpose, typical use case, and a key accounting-category caveat — is sufficient for an agent to select and invoke the tool correctly. It could be slightly stronger with explicit sibling routing, but it is not incomplete in a harmful way.
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 the baseline is 3 because the schema already documents all parameters. The description adds genuine value by explaining the business impact of accounting_category_id, which goes beyond the schema's simple 'Id of the accounting category' phrasing.
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 names a specific verb ('Record') and resource ('an expense or additional income in Quipu'), and adds concrete use cases like supplier bills and deductible costs. It distinguishes itself from sales-invoice creation implicitly through the supplier-bill framing, but does not explicitly name a sibling or state what it is not.
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 clearly states when to use the tool: 'Use it to log supplier bills and deductible costs.' This gives actionable context for selection. However, it does not explicitly say when not to use it or point to alternatives such as create_invoice for customer-facing documents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a contact in Quipu. name is required. Provide tax_id (NIF/CIF) whenever the contact will be invoiced — Spanish invoices require it and Quipu will reject the invoice later without it.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Contact name or company name | |
| town | No | Town or city | |
| No | Contact email | ||
| phone | No | Contact phone number | |
| tax_id | No | NIF/CIF. Required to issue invoices to this contact | |
| address | No | Street address | |
| zip_code | No | Postal code | |
| country_code | No | ISO 3166-1 alpha-2 country code (e.g. "ES") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already show this is not read-only and not destructive; the description adds meaningful downstream behavioral context by warning that an invoice issued without `tax_id` will be rejected by Quipu. This is useful beyond the schema, though it doesn't describe return values or duplicate-contact 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?
Two concise sentences front-load the action, then cover the required field and the conditional field. Every sentence earns its place, and there is no repetition of schema content.
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 schema fully documents all 8 parameters, and the description covers the one significant conditional, `tax_id`, with a clear failure mode. The only notable omissions are an explicit pointer to update_contact for modifications and any indication of the response format, but these are minor for a simple create operation without an output schema.
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?
All 8 parameters are documented in the schema, so the baseline is 3. The description adds real value by explaining the `tax_id` requirement with concrete consequences and reinforcing that `name` is required. This goes beyond the schema's generic field description without needing to restate every parameter.
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 uses a specific verb and resource ('Create a contact in Quipu') and is clearly distinguishable from sibling tools like update_contact, delete_contact, list_contacts, and get_contact. It also immediately signals that `name` is required, removing ambiguity about the minimum valid invocation.
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 gives a clear decision rule: include `tax_id` whenever the contact will be invoiced, because Spanish invoices require it and Quipu will reject the invoice later without it. It doesn't explicitly name alternatives like update_contact for existing contacts, but the create action and thetax_id condition provide solid context for when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an issued invoice in Quipu. Requires the contact id it is billed to and at least one line item. The contact must already have a tax_id (NIF/CIF) or Quipu will reject the invoice.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Invoice line items | |
| due_date | No | Due date (YYYY-MM-DD) | |
| contact_id | Yes | Id of the contact being invoiced | |
| issue_date | No | Issue date (YYYY-MM-DD) | |
| payment_method | No | Payment method as accepted by Quipu (e.g. "bank_transfer", "cash") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations only indicate readOnlyHint=false and destructiveHint=false; the description adds valuable behavioral context by warning that the contact must already have a tax_id or Quipu will reject the invoice, and that the invoice is 'issued' rather than draft. This goes meaningfully beyond the annotations.
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 first states the action, the second provides the required inputs and the critical rejection condition. Every sentence contributes distinct, necessary information.
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 covers the action, minimum inputs, and a domain-specific failure condition, which is sufficient for a guided call. The only gap is no mention of the return value or side effects such as immutability, but there is no output schema and the core invocation requirements are fully present.
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 the baseline is 3. The description adds value by highlighting the two required parameters and, more importantly, introducing the tax_id precondition on the contact, which is not present anywhere in the schema. It doesn't describe other parameter formats, but the schema already covers them.
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?
States a specific action ('Create an issued invoice'), a platform ('Quipu'), and the core requirements. The word 'issued' meaningfully distinguishes this from draft creation and from sibling tools like update_invoice, delete_invoice, and list_invoices.
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 clearly conveys when to use the tool: to create an issued invoice, and it gives concrete prerequisites (contact_id, at least one line item, existing tax_id). It doesn't explicitly mention alternatives, but there is no competing create tool among the siblings, so the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an additional income or expense entry from Quipu permanently.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Additional income id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true and readOnlyHint=false, and the description reinforces this by adding 'permanently', which is meaningful context about irreversibility. It does not contradict the annotations and adds value beyond the structured metadata, though it does not detail side effects or authorization 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?
The description is a single, well-structured sentence with no filler. The action, target, system, and permanence are all packed efficiently, and each word contributes meaningful information.
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 single-parameter delete operation, the description, combined with the destructive annotation and the schema, is fully sufficient. The return value is not described, but given the low complexity and presence of a destructiveHint, this is not a meaningful gap.
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 fully describes the only parameter 'id' as 'Additional income id', so schema coverage is 100%. The description adds no additional parameter-level meaning beyond what the schema already provides, which meets the baseline.
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 ('Delete'), the resource ('additional income or expense entry'), and the system ('Quipu'). It is immediately distinguishable from sibling tools like update_additional_income or get_additional_income because the verb is explicit 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 implies when to use this tool: when an additional income/expense entry should be permanently removed. It does not explicitly mention alternatives or exclusions, such as using update_additional_income when the entry should be retained but modified, so guidance is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a Quipu contact permanently. Quipu refuses to delete contacts that already have invoices attached; in that case the API returns an error explaining it.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Contact id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint, and the description goes further by stating that deletion is permanent and disclosing the refusal/error behavior for contacts with attached invoices. This adds valuable failure-mode context beyond the structured hints.
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 focused sentences front-load the action and permanence, then provide the critical caveat about invoices. There is no filler or redundant restatement of the schema.
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 single-parameter destructive tool with annotations already declaring destructiveness and no output schema, the description is complete: it states the operation, its permanence, and the main rejection condition. No critical context for correct invocation is missing.
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 input schema already documents the sole required parameter id at 100% coverage, so the description does not need to add much. It does not add extra meaning to the id parameter, matching the baseline for high schema coverage.
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 uses a specific verb and resource ('Delete a Quipu contact permanently') and clearly distinguishes this destructive contact operation from sibling tools like update_contact and delete_invoice. The permanence qualifier adds useful specificity beyond the tool 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?
The description implies usage context: this is the tool for permanently removing a contact. It explicitly states an important when-not case (contacts with invoices cannot be deleted), but it does not name alternatives or tell the agent how to proceed in that situation, such as deleting attached invoices first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a Quipu invoice permanently. Spanish invoicing rules generally require issuing a credit note instead of deleting a numbered invoice — prefer that unless the invoice is still a draft.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Invoice id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish destructiveHint=true and readOnlyHint=false, but the description adds meaningful context: deletion is permanent and subject to legal restrictions. This goes beyond the structured annotations without contradicting them.
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 two sentences with no filler. The core fact (permanent deletion) is front-loaded, and the regulatory caution is placed immediately after as essential usage context.
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 one-parameter destructive tool with annotations already covering the read/write and destructive profile, the description fully equips an agent to decide when to invoke it and what to expect. No missing return-value or schema details are needed for correct 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?
The only parameter, id, is already fully described in the schema as 'Invoice id' with 100% coverage. The description adds no additional parameter-level meaning, so the 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?
States a specific action (delete) on a specific resource (a Quipu invoice) and adds the critical qualifier 'permanently.' This clearly distinguishes it from sibling delete tools like delete_contact and delete_additional_income.
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?
Provides explicit guidance on when not to use this tool: Spanish regulations generally require a credit note for numbered invoices, and deletion should be preferred only for drafts. This directly tells the agent when to favor an alternative approach.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single additional income or expense entry from Quipu by its id.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Additional income id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the verb 'Get' is consistent. The description adds scope context ('income or expense' and 'from Quipu') but does not disclose return format or not-found behavior. With annotations covering the safety profile, this is 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?
A single front-loaded sentence with no wasted words. Every element—verb, resource, qualifier, source, access method—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?
For a single-parameter get-by-id tool with annotations covering safety and schema covering the parameter, nothing needed to call it correctly is missing. The 'income or expense' qualifier also prevents assumption errors.
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 the baseline is 3. The phrase 'by its id' only restates the id paramater and adds no format, type, or semantic detail beyond the schema's 'Additional income id'.
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?
States a specific verb ('Get'), resource ('single additional income or expense entry from Quipu'), and access method ('by its id'). The 'single' qualifier distinguishes it from list_additional_incomes, and the get-by-id pattern separates it from update/delete siblings.
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?
Makes clear this is for retrieving a single existing entry when the id is known. It does not explicitly name list_additional_incomes as the alternative for multiple entries, so it stops short of full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a temporary public URL to download an expense document as PDF. The link is ephemeral and expires.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Additional income id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as readOnly and non-destructive. The description adds useful behavioral context beyond that: the returned URL is temporary, ephemeral, expires, and serves a PDF. This meaningfully informs the agent that the link cannot be persisted indefinitely.
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 short and front-loaded with the core action. The phrase 'ephemeral and expires' is somewhat redundant with 'temporary,' but overall the description contains only one extra clarifier and remains compact.
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 single-parameter, read-only tool, the description provides enough context: it names the output format (PDF), the nature of the URL (temporary, public, expires), and the operation (get download URL). It does not state the expiration duration or error behavior, but these are not essential for initial tool selection.
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 input schema fully documents the single parameter 'id' as 'Additional income id' with 100% coverage. The description adds no extra parameter-level meaning, so the 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 states a specific verb ('Get') and a concrete resource ('temporary public URL to download an expense document as PDF'). It is clear enough, though it does not explicitly differentiate itself from the sibling get_invoice_download_url and refers to 'expense document' rather than 'additional income,' which introduces slight ambiguity.
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 implies when to use the tool: whenever a temporary PDF download URL for an additional income document is needed. However, it provides no explicit guidance about when not to use it, such as pointing to get_invoice_download_url for invoice documents or noting any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single Quipu contact by its id, with all available attributes (name, tax_id, email, phone, address, town, zip_code, country_code).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Contact id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by enumerating the returned attributes, but does not explain error behavior or edge cases such as missing contacts. This is adequate but not rich.
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?
One tight sentence that front-loads the action and resource, followed by a useful parenthetical attribute list. 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 single-parameter read tool with annotations covering safety, the description is nearly complete. It lists the attributes the agent can expect in the response, which compensates for the lack of an output schema. Minor omissions like not-found behavior prevent a perfect score.
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?
With 100% schema description coverage, the single 'id' parameter is already documented as 'Contact id'. The description does not add format or type details beyond the schema, landing at the baseline of 3.
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 verb and resource: 'Get a single Quipu contact by its id', clearly distinguishing it from list_contacts (all contacts) and mutation tools like update_contact and delete_contact. The attribute list adds further concreteness.
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 context is implied: use this tool when you have a contact id and need the full attributes. However, no explicit alternatives or exclusions are provided, even though list_contacts exists as the obvious sibling for fetching multiple contacts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single Quipu invoice by id, with all of its attributes and totals.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Invoice id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the response includes all attributes and totals, which is useful because there is no output schema. It does not disclose error behavior, authorization requirements, or rate limits, but these are less critical for a simple read operation.
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, front-loaded sentence. It starts with the core action ('Get a single Quipu invoice by id') and then appends the return detail ('with all of its attributes and totals'). There is no filler or redundant text.
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 single-get tool with one parameter and annotations covering the safety profile, the description is largely complete. It names the resource, identifies the lookup key, and summarizes the return payload. It could optionally mention not-found behavior, but that is not necessary for basic 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%—the parameter 'id' is described as 'Invoice id', which fully documents the parameter. The tool description only restates 'by id' and adds no format, source, or constraint information beyond the schema. The baseline of 3 applies because the schema already handles parameter documentation.
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 uses a specific verb ('Get') and identifies the exact resource ('a single Quipu invoice by id') plus what is returned ('all of its attributes and totals'). It clearly distinguishes itself from list_invoices and get_invoice_download_url by emphasizing 'single' and 'by id'.
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 usage context is implied: you call this when you have an invoice id and need the full invoice object. However, there is no explicit mention of alternatives or when-not-to-use conditions, such as 'use list_invoices to find ids' or 'use get_invoice_download_url for the PDF'. The guidance is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a temporary public URL to download a Quipu invoice as PDF. The link is ephemeral and expires, so fetch it when the user actually needs the document rather than storing it.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Invoice id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds critical behavioral context: the URL is ephemeral and expires, so it cannot be cached or stored. This directly shapes agent behavior and is not available from annotations or schema.
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 action is stated first, followed by the essential caveat about ephemerality. 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?
For a single-parameter read-only tool with full schema coverage and annotations already covering safety, the description fully explains the purpose and the key usage constraint. The absence of an output schema is mitigated by the tool name and first sentence making clear a URL is returned.
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 a single well-described parameter (id: 'Invoice id'). The description adds no additional parameter meaning, 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 states a specific verb and resource: 'Get a temporary public URL to download a Quipu invoice as PDF.' It clearly distinguishes from siblings like get_invoice and get_additional_income_download_url by naming the exact action and resource.
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 explicitly advises when to invoke the tool ('fetch it when the user actually needs the document') and what to avoid ('rather than storing it'). It does not name alternative tools explicitly, but the guidance is clear and sufficient for this simple tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Work out the VAT and IRPF position for a period from the invoices and expenses recorded in Quipu. Give it a year and a quarter (or an explicit date range) and it returns output VAT charged on invoices, input VAT paid on expenses, the resulting balance, and withholdings. Use this instead of listing invoices and adding them up by hand: Quipu has no endpoint that returns tax models (130, 303, 111), so the figures must be derived, and doing the arithmetic in code avoids the mistakes that come from adding long lists token by token. Treat the result as an estimate for orientation, not as a filed return.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date (YYYY-MM-DD), overrides quarter | |
| from | No | Start date (YYYY-MM-DD), overrides quarter | |
| year | No | Year, e.g. 2026 | |
| quarter | No | Quarter: 1, 2, 3 or 4. Ignored when `from` and `to` are provided |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds useful behavior: figures are derived, Quipu has no tax-model endpoints, and the result is an estimate rather than an official return. This enriches the safety profile without contradicting it. Some granular behavior such as rounding or exact date-boundary handling is not disclosed, but the annotation burden is already low.
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?
Every sentence earns its place: purpose and outputs, rationale and alternative, and reliability caveat. It is front-loaded with the actionable 'how to call' information before the background reasoning.
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?
With no output schema, the description compensates by listing the major returned values and explicitly labeling the result as an estimate. Params are fully covered by the schema, annotations cover safety, and the caveat about tax-model endpoints gives enough context for an agent to select and invoke it correctly. It could be even more complete by noting edge cases or exact date handling, but these are minor.
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 covers 100% of parameters with clear descriptions, including the from/to overriding quarter behavior. The description reinforces this by saying 'year and a quarter (or an explicit date range)' but does not add substantial new parameter-level meaning beyond the schema. 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 opens with a specific action and resource: 'Work out the VAT and IRPF position for a period from the invoices and expenses recorded in Quipu.' It also names the returned components (output VAT, input VAT, balance, withholdings) and explicitly distinguishes itself from listing invoices and adding them by hand, which separates it from sibling list_invoices.
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 gives a clear when-to-use instruction: 'Use this instead of listing invoices and adding them up by hand.' It also states the input shape ('Give it a year and a quarter, or an explicit date range') and gives a when-not-to-relly scenario: 'Treat the result as an estimate for orientation, not as a filed return.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List additional incomes and expenses recorded in Quipu — everything that is not an issued invoice: supplier bills, purchases, tickets and other deductible costs. Returns kind, total_amount_without_taxes, vat_amount and retention_amount. Bound the period with filter_from / filter_to. This is the input-VAT side needed to work out what a quarter actually owes.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, starting at 1 (default: 1) | |
| filter_to | No | Only entries issued on or before this date (YYYY-MM-DD) | |
| filter_from | No | Only entries issued on or after this date (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context: it clarifies that the tool returns non-invoice entries including expenses despite the 'incomes' name, discloses the specific returned fields, and states how the period can be bounded. This goes beyond the structured annotations.
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?
Four dense sentences with no filler. The key scope distinction is front-loaded, the returned fields are listed concisely, and the VAT context is a single useful closing sentence. Every sentence 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?
For a read-only list operation with three optional, fully documented parameters and no output schema, the description is largely sufficient. It communicates the resource scope, return fields, and date-filtering behavior. It does not describe pagination behavior or sort order, but those are not critical for a simple list tool and are partially covered by the page parameter in the schema.
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 all three parameters, so the schema already documents page, filter_from, and filter_to. The description reinforces filter_from/filter_to as period bounds but does not add new semantic meaning beyond what the schema 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 starts with a specific verb and resource ('List additional incomes and expenses recorded in Quipu') and immediately distinguishes its scope from invoices: 'everything that is not an issued invoice'. Concrete examples (supplier bills, purchases, tickets) make the resource unambiguous even though the tool name could be misleading.
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 clearly defines what this tool covers and positions it as 'the input-VAT side needed to work out what a quarter actually owes.' This gives strong contextual guidance, but it does not explicitly name sibling alternatives such as list_invoices or get_tax_summary, leaving some routing inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List contacts (clients and suppliers) from Quipu. Returns id, name, tax_id (NIF/CIF), email, phone and address fields. Results are paginated: use page to walk through pages. Quipu returns JSON:API, but this tool flattens each resource so attributes appear at the top level alongside id.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, starting at 1 (default: 1) | |
| filter_name | No | Filter contacts whose name contains this text |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as read-only and non-destructive. The description adds meaningful behavioral context beyond that: results are paginated, and Quipu's JSON:API shape is flattened so attribute fields appear at the top level alongside `id`. This is exactly the kind of behavioral disclosure an agent needs.
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 compact and front-loaded: it opens with the purpose, then lists return fields, pagination, and the flattening behavior. Every sentence earns its place with no filler or repetition.
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 read-only list tool with two optional parameters and no output schema, the description is complete. It explains what is returned, how pagination works, and the unusual flattening behavior, so an agent can invoke and interpret the result 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 description coverage is 100%, so both `page` and `filter_name` are already documented in the schema. The description reinforces the pagination behavior by explaining how to walk pages, but adds no new 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?
The description states a specific verb and resource: 'List contacts (clients and suppliers) from Quipu.' It also names the exact fields returned, making the tool's role unmistakable and distinguishing it from sibling operations like get_contact or create_contact.
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 gives clear usage context: use this tool to retrieve contacts, and explicitly explains how to handle pagination with the `page` parameter. It does not explicitly contrast with alternatives like get_contact, but the list-versus-single-object distinction is clearly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List issued invoices from Quipu, with number, issue_date, due_date, total, subtotal and payment status. Paginated via page. Use filter_from and filter_to to bound the period — this is the tool to use when asked about revenue or VAT for a quarter, since Quipu has no endpoint that returns tax models directly and the figures must be derived from invoices.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, starting at 1 (default: 1) | |
| filter_to | No | Only invoices issued on or before this date (YYYY-MM-DD) | |
| filter_from | No | Only invoices issued on or after this date (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry the safety profile (readOnlyHint=true, destructiveHint=false), so the description's job is to add behavioral context, which it does: pagination via `page`, period bounding via filters, and the domain constraint that tax figures must be derived from invoices. No contradiction with annotations.
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 zero waste. The first front-loads the core action and output fields; the second packs pagination, filtering, and the key use-case context. Every clause 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?
For a simple tool with 3 optional parameters, no output schema, and no nested objects, the description is complete: it names the returned fields (compensating for the missing output schema), the pagination parameter, the period-filter parameters, and the strategic use case. Nothing needed for correct invocation is missing.
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% — all three parameters (page, filter_to, filter_from) are individually documented, so the baseline is 3. The description mostly restates the schema ('Paginated via page', 'bound the period') and adds only the strategic context tying the filters to the revenue/VAT use case rather than new parameter-level detail.
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 verb and resource ('List issued invoices from Quipu') and enumerates the returned fields (number, issue_date, due_date, total, subtotal, payment status). It also distinguishes itself from the tax-related sibling by explicitly positioning this tool as the source for revenue/VAT figures.
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?
Gives an explicit decision rule: 'this is the tool to use when asked about revenue or VAT for a quarter,' backed by the rationale that Quipu has no endpoint returning tax models directly. It stops short of naming the alternative sibling (get_tax_summary) by name or stating when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing additional income or expense in Quipu. Only the fields passed are modified.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Additional income id | |
| notes | No | Free-text notes | |
| number | No | Supplier document number | |
| paid_at | No | Payment date (YYYY-MM-DD) | |
| issue_date | No | Issue date (YYYY-MM-DD) | |
| payment_method | No | Payment method | |
| recipient_name | No | Supplier or recipient name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only signal a write operation that is not destructive. The description adds the important behavioral detail that unspecified fields remain unchanged, which is not derivable from the annotations or schema alone. It does not cover auth, rate limits, or response shape, so it falls short of a 5.
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 short, dense sentences with no filler. The core action is front-loaded and the partial-update behavior is stated immediately after, so the most important information appears first.
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?
With one required id, six documented optional fields, no nested objects, and annotations present, the description plus schema gives an agent enough to select and invoke the tool correctly. Minor omissions such as return value or validation behavior do not block correct usage.
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 the baseline is 3. The global rule that only passed fields are modified adds parameter-level meaning: callers may send a subset of the optional fields and only those are updated. That is genuinely useful beyond the individual property descriptions.
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 uses a specific verb (Update), names the resource (additional income or expense), and restricts it to existing records in Quipu. This clearly separates it from create_additional_income, delete_additional_income, and the get/list siblings. The partial-update note further clarifies the exact operation semantics.
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 gives clear context: use this when an existing additional income or expense needs to be changed. The statement 'Only the fields passed are modified' is a strong usage rule that prevents agents from sending full-object payloads. It does not explicitly name alternatives like create or delete, but 'existing' implies the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing Quipu contact. Only the fields you pass are modified; everything else is left untouched.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Contact id | |
| name | No | Contact name or company name | |
| town | No | Town or city | |
| No | Contact email | ||
| phone | No | Contact phone number | |
| tax_id | No | NIF/CIF | |
| address | No | Street address | |
| zip_code | No | Postal code | |
| country_code | No | ISO 3166-1 alpha-2 country code |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate that the tool is non-readonly and non-destructive. The description adds a crucial behavioral detail: it performs a partial update, modifying only the passed fields and leaving everything else untouched. This goes meaningfully beyond what annotations or the schema communicate.
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 that front-loads the action and resource, then adds the key partial-update caveat. Every word contributes meaning; there is no redundancy or unnecessary detail.
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 update tool with a required id and 100%-documented optional fields, the description covers the one non-obvious behavior needed to call it correctly. No output schema exists, but the response format is not essential for invoking the tool; the main gap is the lack of workflow guidance relative to sibling tools.
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 baseline is 3. The description adds semantic value by clarifying that all fields except id are effectively optional and that omitted fields retain their existing values. This affects how an agent should construct an update call.
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 action ('Update') and a specific resource ('existing Quipu contact'), which clearly distinguishes it from create_contact, get_contact, list_contacts, and delete_contact. It does not name a sibling explicitly, but the purpose is 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?
No explicit guidance is given about when to use this tool versus create_contact or delete_contact. The word 'existing' implies an id must reference an already-created contact, and the schema confirms id is required, but there is no stated workflow, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing Quipu invoice. Note that Spanish invoicing rules restrict what can change once an invoice is issued and numbered; Quipu returns an error when a field is locked.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Invoice id | |
| paid_at | No | Date the invoice was paid (YYYY-MM-DD) | |
| due_date | No | Due date (YYYY-MM-DD) | |
| issue_date | No | Issue date (YYYY-MM-DD) | |
| payment_method | No | Payment method |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as a mutating but non-destructive operation. The description adds valuable behavior beyond that: once an invoice is issued and numbered, Spanish rules lock certain fields, and Quipu returns an error when a locked field is modified. This sets expectations for conditional failure and legal constraints.
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: the first states the operation clearly, the second adds the most important caveat. No filler or repetition of schema content.
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 5-param mutation tool with no output schema, the description covers what the tool does and a key failure mode. It doesn't describe the success return value, but that is not essential for correct invocation. The annotations cover the read/destructive axis, so overall context is adequate.
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?
All five parameters have schema descriptions (100% coverage), so the description does not need to explain them. It adds no parameter-specific detail beyond the schema, and the legal-lock note applies globally rather than to specific fields. 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?
States a specific verb ('Update') and resource ('existing Quipu invoice'). The word 'existing' distinguishes it from create_invoice, and the mutation orientation distinguishes it from get/list tools. No ambiguity about what it does.
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 gives clear context: updates are for existing invoices and are subject to Spanish invoicing rules. It does not explicitly name alternatives like create_invoice or delete_invoice, nor state when not to use this tool, but the use case is clear enough for an agent to select it among siblings.
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.
v0.1.0create_additional_incomecreate_contactcreate_invoicedelete_additional_incomedelete_contactdelete_invoiceget_additional_incomeget_additional_income_download_urlget_contactget_invoiceget_invoice_download_urlget_tax_summarylist_additional_incomeslist_contactslist_invoicesupdate_additional_incomeupdate_contactupdate_invoiceScored across 18 tools
Each tool targets a distinct resource (contact, invoice, additional income, tax summary) and action (list, get, create, update, delete, download URL). The two download tools are clearly separated by resource type, and the tax summary tool is explicitly positioned as the calculation endpoint rather than a list operation.
Tool names consistently follow a verb_noun pattern: list_*, get_*, create_*, update_*, delete_*. Pluralization is consistent for list operations and singular for single-resource operations, which makes the set predictable.
18 tools is slightly above the ideal 3-15 range but still well-scoped: the count is justified by three resource domains (contacts, invoices, additional incomes) plus a tax summary tool. Each tool has a clear purpose, though the set feels a bit heavy.
CRUD coverage is complete for contacts, invoices, and additional incomes, with download URLs and a tax summary tool as useful additions. The main gap is the lack of a credit-note creation tool despite the delete_invoice description recommending credit notes, and there is no way to list accounting categories referenced by create_additional_income.
Spanish Veri*factu invoicing: create invoices and manage billing from your AI assistant.
Connect your AI to your Well financial data - invoices, companies, contacts.
Malaysian SME accounting, e-Invoice and payroll for your AI. 64 tools; writes are approved drafts.
Log, query, and edit expenses, budgets, and accounts in Manilo (formerly Ledgy) from any MCP-compatible AI assistant.
