Skip to main content
Glama
Sign In
nubiia-dev

MCP Holded

by nubiia-dev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

pay_document

Register a payment for a Holded document (invoice, purchase, etc.) and optionally link it to a bank account; note that this may auto-approve the document.

Instructions

Register a payment for a document (Holded API v2). Supported docTypes: invoice, salesreceipt, creditnote, receiptnote, purchase — others throw an unsupported error. IMPORTANT: this may AUTO-APPROVE the document as a side effect (status 0→1). paymentmethod is the payment-method catalog id (from list_payment_methods), NOT a bank/treasury id. To link the payment to a bank account, pass bankId: the /payments endpoint can't set it, so the tool performs a second step (PUT /payments/{id}) and reports the outcome in _warnings.

Input Schema

NameRequiredDescriptionDefault
dateNoPayment date as Unix timestamp
amountYesPayment amount
bankIdNoBank account id to link the payment to. Triggers a second step (PUT /payments/{id}) to set the bank link on the payment.
docTypeYesType of document
documentIdYesDocument ID
treasuryIdNoTreasury account ID
paymentmethodNoPayment-method catalog id (from list_payment_methods), NOT a bank/treasury id.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.0.3
    • changedInput schema / properties / bankId / description
      Previous value: -"Bank account id to link the payment to. Triggers a second step (PUT /payments/{id}) because /pay cannot set the bank link."New value: +"Bank account id to link the payment to. Triggers a second step (PUT /payments/{id}) to set the bank link on the payment."
  2. Changed2 schema fields changedv1.7.0
    • addedInput schema / properties / bankId
      Added value: +{
+  "description": "Bank account id to link the payment to. Triggers a second step (PUT /payments/{id}) because /pay cannot set the bank link.",
+  "type": "string"
+}
    • addedInput schema / properties / paymentmethod
      Added value: +{
+  "description": "Payment-method catalog id (from list_payment_methods), NOT a bank/treasury id.",
+  "type": "string"
+}
  3. First observedv1.6.0

TDQS

A4.3/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so well: it warns the document may be auto-approved as a side effect (status 0→1), discloses that `bankId` triggers an internal second step (PUT /payments/{id}), and says the outcome surfaces in `_warnings`. Error behavior for unsupported docTypes is also explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tightly packed sentences, no filler. The most consequential facts — supported docTypes, the auto-approval side effect, and the bankId two-step — are front-loaded in that order.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations and no output schema, it covers the essential risks: side effects, partial-failure behavior via the second PUT, the `_warnings` field, and unsupported-input errors. What remains unstated is permission/auth requirements and how the final payment result is shaped.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it constrains `docType` to the five values that actually work, and re-emphasizes that `paymentmethod` is a catalog id, not a bank/treasury id. It does not clarify `treasuryId` or `date` usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Register a payment for a document') and scopes it to Holded API v2 with an explicit list of supported docTypes. It distinguishes itself implicitly from the bare payment tools by being document-scoped, though it never names the sibling `create_payment` to sharpen the contrast.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when-not guidance: only invoice, salesreceipt, creditnote, receiptnote and purchase are supported, others throw an error — even though the schema enum lists more values. It also points to `list_payment_methods` for the paymentmethod id. It does not state when to use this versus `create_payment` or `list_payments`.

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

Deploy Server

Other Tools