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., "@oblio-mcp create an invoice for client SC Test SRL for 1500 RON"
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 Oblio API, enabling Claude and other MCP-compatible platforms to interact with Oblio.eu accounting software.
Create invoices, manage documents, collect payments, query nomenclatures, and submit e-Factura to Romania's SPV system -- all through natural language.
Node.js >= 22.0.0
Docker (optional)
An active Oblio.eu account with API access
Related MCP server: Cuéntica MCP
Log in at oblio.eu
Go to Setari > Date Cont
Copy your email and API secret
Note your company CIF (e.g. RO37311090)
Environment variables are passed through the MCP client configuration:
Add to your Claude Desktop config or other MCP-compatible AI tool (claude_desktop_config.json):
Once the package is published to npm, no installation will be required:
{
"mcpServers": {
"oblio": {
"command": "npx",
"args": ["-y", "oblio-mcp"],
"env": {
"OBLIO_API_EMAIL": "your-email@example.com",
"OBLIO_API_SECRET": "your-api-secret",
"CIF": "your-company-cif"
}
}
}
}git clone https://github.com/valentinludu/oblio-mcp.git
cd oblio-mcp
npm installThen add to your config:
{
"mcpServers": {
"oblio": {
"command": "node",
"args": ["/path/to/oblio-mcp/dist/index.js"],
"env": {
"OBLIO_API_EMAIL": "your-email@example.com",
"OBLIO_API_SECRET": "your-api-secret",
"CIF": "your-company-cif"
}
}
}
}docker build -t oblio-mcp .{
"mcpServers": {
"oblio": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"OBLIO_API_EMAIL",
"-e",
"OBLIO_API_SECRET",
"-e",
"CIF",
"oblio-mcp"
],
"env": {
"OBLIO_API_EMAIL": "your-email@example.com",
"OBLIO_API_SECRET": "your-api-secret",
"CIF": "your-company-cif"
}
}
}
}Variable | Description |
| Your Oblio account email |
| API secret from Oblio settings |
Variable | Description | Default |
| Company CIF (can also be set via API) | None |
| Logging level: error, warn, info, debug |
|
| API request timeout in milliseconds |
|
| Server port for future HTTP transport | None |
Tool | Description |
| Creates an invoice (factura), proforma, or delivery notice (aviz). Requires client details, at least one product, a series name, and issue date. Returns the created document's series, number, and link. |
| Retrieves a single document by type, series name, and number. Returns document details, link, and payment history. |
| Lists and filters documents with pagination. Supports filtering by series, date range, client, draft/cancelled/collected status. Returns up to 100 results per page. |
| Permanently deletes a document. Only the last document in a series can be deleted. Optionally removes the associated payment. |
| Cancels (annuls) a document, marking it as void. The document remains in the system. |
| Restores a previously cancelled document, making it active again. |
Tool | Description |
| Records a payment against an existing invoice. Supports payment types: Chitanta, Bon fiscal, Ordin de plata, Card, CEC, and others. Defaults to the full invoice amount if value is omitted. |
Tool | Description |
| Fetches reference data from Oblio. Types: |
Tool | Description |
| Submits an existing invoice to Romania's SPV system for e-Factura. Returns status code: 0=processing, 1=success, 2=errors, -1=not sent. |
| Downloads the e-Invoice archive (XML) from SPV for a previously submitted invoice. |
Tool | Description |
| Sets the company CIF (tax ID) used for all subsequent API requests. |
| Returns the currently configured company CIF. |
The server includes 28 prompt templates for common operations: creating documents, retrieving documents, cancelling/restoring/deleting documents, searching nomenclatures, collecting payments, listing invoices, and managing e-Factura submissions.
If you encounter issues:
Verify your Oblio account is active and has API access
Check that OBLIO_API_EMAIL and OBLIO_API_SECRET are correctly set
Ensure your company CIF is set (via CIF env var or the set_cif tool)
Confirm you have the necessary permissions for the operations you're performing
For debugging, set LOG_LEVEL=debug in your MCP client configuration
ISC
Cancels (annuls) a document in Oblio via PUT /api/docs/{type}/cancel. The document is marked as void but remains in the system. Returns: documentType, seriesName, number, and link to the cancelled document.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Document type to cancel | |
| seriesName | Yes | Document series name | |
| number | Yes | Document number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint=true and destructiveHint=false; the description adds that the document is marked void but stays in the system, and lists return values. This adds useful behavioral context beyond 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?
The description is two sentences plus a list of return fields. Every sentence adds value, and the main action is front-loaded. No wasted 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?
Given the tool has 3 parameters and no output schema, the description explains the action, effect, and return fields. It is reasonably complete, though it could mention document status prerequisites for cancellation.
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 does not add parameter-level details beyond what the schema provides, so no additional value.
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 (cancels/annuls), the resource (document), and the effect (marked void but remains). It also names the HTTP endpoint, distinguishing it from siblings like delete_document which likely removes the document.
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 cancellation vs deletion but does not explicitly state when to use this tool over alternatives like delete_document or restore_document. It lacks prerequisites or contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Records a payment (incasare) against an existing invoice via PUT /api/docs/invoice/collect. Identifies the invoice by seriesName + number. The collect object specifies payment method (type), document number, optional value (defaults to full invoice total), and optional issueDate. Available payment types: Chitanta, Bon fiscal, Bon fiscal card, Alta incasare numerar, Ordin de plata, Mandat postal, Card, CEC, Bilet ordin, Alta incasare banca, Ramburs. Returns: documentType, seriesName, number, link, and collects array with all payments on the invoice.
| Name | Required | Description | Default |
|---|---|---|---|
| seriesName | Yes | Invoice series name (e.g. FCT) | |
| number | Yes | Invoice number | |
| collect | Yes | Payment details |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide basic safety profile (non-read-only, non-destructive). Description adds endpoint and return structure but lacks detail on side effects, permissions, or reversibility.
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?
Description is concise and front-loaded with the verb and resource, though slightly redundant on identifying invoice. Adequate for a single paragraph.
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?
Despite lacking an output schema, description explains return fields. For a tool with nested object and many enum options, it covers enough context without missing critical details.
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% coverage, but description adds meaningful defaults (value defaults to total, issueDate defaults to today) and lists available payment types, enhancing usability.
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 it records a payment against an existing invoice via a PUT endpoint, and distinguishes from sibling tools like cancel_document or create_document.
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 for recording payments but does not explicitly state when to use or avoid this tool, nor suggests alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates an invoice (factura), proforma, or delivery notice (aviz) in Oblio via POST /api/docs/{type}. Required fields: cif, client (with at least name), seriesName, issueDate, and at least one product. Optional: inline payment via collect, reference to existing proforma/notice via referenceDocument, stock deduction via useStock, auto e-Factura submission via spvExtern, and idempotencyKey to prevent duplicates. Returns: seriesName, number, and a link to view/download the created document.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Document type to create: "invoice" (factura), "proforma", or "notice" (aviz) | |
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation (readOnlyHint false). The description adds value by mentioning idempotencyKey for duplicate prevention, optional features like stock deduction and auto e-Factura, and return values. It does not contradict 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?
The description is a single paragraph that front-loads the core purpose and then lists important details. It is concise and avoids unnecessary words, though it could be slightly more structured with bullet points.
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 complex nested schema and no output schema, the description adequately covers the tool's functionality, required inputs, optional behaviors, and return value. It does not explain error handling or authorization, but these are common expectations.
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 schema description coverage at 50%, the description compensates by summarizing the required fields and key optional features (collect, referenceDocument, useStock, spvExtern, idempotencyKey). This helps the agent quickly identify critical parameters 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 clearly states 'Creates an invoice, proforma, or delivery notice', which are specific document types. It mentions the API endpoint and lists required fields, effectively differentiating from sibling tools like create_einvoice.
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 lists required fields, providing a clear precondition, but does not explicitly guide when to use this tool versus alternatives (e.g., create_einvoice). No 'when not to use' or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submits an existing invoice to Romania's SPV system via POST /api/docs/einvoice. The invoice must already exist in Oblio. Returns: text (explanation), sent (boolean), code (-1=not sent, 2=errors, 0=processing, 1=success).
| Name | Required | Description | Default |
|---|---|---|---|
| seriesName | Yes | Invoice series name (e.g. FCT) | |
| number | Yes | Invoice number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show non-readOnly, non-destructive, non-idempotent, openWorld. Description adds POST method, endpoint, and return codes (-1, 2, 0, 1) providing context beyond 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 wasted words. First sentence states action and endpoint, second details return values. Optimal conciseness.
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?
Simple tool with 2 required params, no output schema but return values described. Context about existing invoice is provided. Sufficient for an agent to use 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 clear descriptions for seriesName and number. Description does not add beyond schema, but baseline 3 is appropriate as schema already provides meaning.
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 tool submits an existing invoice to Romania's SPV system via a specific endpoint. It distinguishes from siblings like create_document (creation) and get_einvoice_archive (retrieval).
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?
Explicitly states prerequisite 'invoice must already exist in Oblio' and clarifies return codes. No guidance on when not to use or alternatives, but adequate for the task.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently deletes a document from Oblio via DELETE /api/docs/{type}. Constraint: only the last document in a series can be deleted. This cannot be undone. Set deleteCollect to true to also remove the associated payment (invoices only). Returns: documentType, seriesName, number of the deleted document.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Document type to delete | |
| seriesName | Yes | Document series name | |
| number | Yes | Document number | |
| deleteCollect | No | true to also delete the associated payment collection (invoices only). Default false | |
| idempotencyKey | No | Unique key to prevent duplicate deletion |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive behavior; description adds irreversibility warning and return values, providing context beyond annotations without contradiction.
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?
Three concise sentences, front-loaded with main purpose and endpoint, 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?
Covers behavior, constraints, return values, and parameter hints adequately for a 5-param tool without 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?
Schema has 100% coverage, so baseline is 3. Description adds value for the deleteCollect parameter, but does not elaborate on others like idempotencyKey.
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 deletes a document permanently via a specific endpoint, and includes a constraint (only last in series), distinguishing it from siblings like cancel_document or restore_document.
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 explicitly states when the tool can be used (only last document) and explains the deleteCollect parameter for invoices, but does not contrast with alternative tools like cancel_document.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the currently configured company CIF (tax ID) used for Oblio API requests.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint true, destructiveHint false. Description adds 'currently configured' confirming idempotent, read-only behavior. No contradictions.
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 'Returns', no unnecessary words. Perfectly 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 no output schema, description explicitly states return value (company CIF). For a simple parameterless tool, this is complete and sufficient.
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?
Tool has zero parameters, schema coverage is 100%. Description explains what is returned, fully compensating for lack of parameter details. Baseline 4 for 0 params, but description adds value.
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 uses specific verb 'Returns' and clearly identifies the resource 'company CIF' with context 'used for Oblio API requests'. This distinguishes it from siblings like 'set_cif'.
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?
Description clearly states it returns the current CIF, implying use for reading. While no explicit when-not-to-use, the sibling 'set_cif' provides contrast. Slight room for improvement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves a single document from Oblio via GET /api/docs/{type}. Returns: documentType, seriesName, number, link (view/download URL), and collects array (list of payments with issueDate, type, number, value).
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Document type to retrieve | |
| seriesName | Yes | Document series name (e.g. "FCT", "PR") | |
| number | Yes | Document number within the series |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by detailing the return fields (documentType, seriesName, number, link, collects array) and that it uses a GET endpoint. Annotations already indicate read-only and idempotent, so no contradictions or missing safety info.
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 compact sentence that efficiently conveys the tool's purpose and return values, with no unnecessary words. It is front-loaded with the action and resource.
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 read-only tool with three required parameters and no output schema, the description fully covers what the tool does and what it returns. No important behavioral aspects are omitted given its straightforward nature.
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 each parameter is described in the schema. The description adds that type is used in the endpoint path (GET /api/docs/{type}), providing contextual placement beyond basic schema 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 clearly states 'Retrieves a single document from Oblio via GET /api/docs/{type}', specifying verb, resource, and method. It distinguishes from sibling tools like list_documents and create_document by emphasizing single document retrieval.
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 context that it is for retrieving a single document by type/series/number, but does not explicitly contrast with sibling tools (e.g., list_documents for batch) or state when not to use. No alternate tool names are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Downloads the e-Invoice archive (XML) from Romania's SPV system via GET /api/docs/einvoice. The invoice must have been previously submitted to SPV. Returns the SPV archive data for the specified invoice.
| Name | Required | Description | Default |
|---|---|---|---|
| seriesName | Yes | Invoice series name (e.g. FCT) | |
| number | Yes | Invoice number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's mention of 'downloads' and 'GET' adds context but not beyond what annotations imply. No edge cases or error behavior described, but annotations cover safety profile.
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, zero wasted words. Front-loaded with the core action and method. Efficient.
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 retrieval tool with two parameters and no output schema, the description provides the key behavioral context (precondition, data format). Lacks details on error responses but is otherwise sufficient.
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 both parameters (seriesName and number). The tool description does not add further parameter semantics, 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?
Clearly states the tool downloads an e-Invoice archive (XML) from Romania's SPV system via a specific API endpoint. Verb+resource is specific and distinguishes it from siblings like create_einvoice (submission) and get_document (document retrieval).
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 a precondition: invoice must have been previously submitted to SPV. However, it does not explicitly exclude cases when not to use or name alternatives, leaving the agent to infer usage context from sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches reference/lookup data from Oblio via GET /api/nomenclature/{type}. Types and their returns:
"companies": returns cif, company name, userTypeAccess for each account company
"clients": returns cif, name, rc, code, address, state, city, iban, bank, email, phone, vatPayer. Filterable by name, clientCif
"products": returns name, code, description, measuringUnit, productType, price, currency, vatName, vatPercentage, vatIncluded, and stock[] for stocked items. Filterable by name, code, management, workStation
"vat_rates": returns name, percent, default for each VAT rate
"series": returns type (Factura/Proforma/Aviz), name, start, next, default for each document series
"languages": returns code and name for each configured language
"management": returns management, workStation, managementType for each stock location Paginated: max 250 results per page, use offset filter (0, 250, 500...) for next pages.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Nomenclature type to retrieve | |
| name | No | Search by name (for products and clients nomenclatures) | |
| filters | No | Additional filters as key-value pairs. For products: code, management, workStation, offset. For clients: clientCif, offset. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds crucial behavioral details: pagination (max 250 results per page with offset), filter structure per type, and exact return fields per type, which is beyond 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?
The description is well-structured with a clear purpose statement followed by bullet-point style enumeration of types. It is appropriately sized for the complexity, though slightly verbose in the listing of return fields.
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 no output schema, the description comprehensively covers return structures for all 7 types, includes pagination and filter details, and explains parameter usage. This fully compensates for the lack of 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?
Schema coverage is 100% with descriptions for each parameter. The description enhances schema by explaining which filters apply to which types (e.g., 'name' for products/clients, 'clientCif' for clients), adding practical usage context.
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 explicitly states the tool fetches reference/lookup data via a specific API endpoint and enumerates all valid types with their return fields. This clearly distinguishes it from sibling tools which deal with document 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?
The description provides clear context by listing all types and their applicable filters, guiding the user on which type to use. However, it does not explicitly state when not to use this tool or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists documents from Oblio via GET /api/docs/{type}/list with filters and pagination. Each result contains: id, draft, canceled, seriesName, number, issueDate, dueDate, precision, currency, exchangeRate, total, collected (0=unpaid, 1=paid), mentions, useStock, type, link, einvoiceStatus (text, sent, code), and client object (clientId, cif, name, rc, code, address, etc.). Optionally include product lines (withProducts=1), payment details (withCollects=1), or e-Invoice SPV status (withEinvoiceStatus=1). Max 100 results per page.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Document type to list | |
| filters | Yes | Filter and pagination options |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Description adds: it's a GET request, lists return fields, max 100 results per page, optional includes. No contradiction.
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?
Three sentences: purpose+endpoint, result fields, optional includes+max. Front-loaded, no wasted 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?
Covers result fields, pagination limit, optional includes. No output schema, but return values listed. Slight gap: offset semantics not explained, but schema provides. Sufficient for complex 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 100% with descriptions. Description adds context: 'Max 100 results per page', optional flags (withProducts, withCollects, withEinvoiceStatus). Adds value 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?
Description states 'Lists documents from Oblio via GET /api/docs/{type}/list' with filters and pagination. It clearly identifies the resource (documents) and action (list), distinguishing from siblings like get_document (single).
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?
Implies usage for listing documents with filters; sibling list shows get_document for single, create_document for creation. No explicit when-not-to-use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restores a previously cancelled document in Oblio via PUT /api/docs/{type}/restore. Reverses a cancellation and makes the document active again. Returns: documentType, seriesName, number, and link to the restored document.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Document type to restore | |
| seriesName | Yes | Document series name | |
| number | Yes | Document number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent and non-destructive, and description adds endpoint and return values. No contradiction, but doesn't mention error handling or prerequisites.
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, no redundancy. First sentence states action and endpoint, second lists return values. Efficient and front-loaded.
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?
Provides method, endpoint, and return fields in lieu of output schema. Covers essential aspects but omits error conditions or prerequisite status (document must be cancelled).
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 provides full descriptions for all 3 parameters. Description adds return values but doesn't enhance parameter understanding. 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?
Clearly states the action (restores), resource (previously cancelled document), and effect (makes active again). Distinguishes from siblings like cancel_document and delete_document.
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?
Implies use for previously cancelled documents but lacks explicit guidance on when to use or not. No contrast with the related sibling cancel_document.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sets the company CIF (Cod de Identificare Fiscala / tax ID) used for all subsequent Oblio API requests. Must be called before other tools if the CIF environment variable is not configured. The CIF identifies which company's data to access (e.g. RO37311090).
| Name | Required | Description | Default |
|---|---|---|---|
| cif | Yes | Company CIF / tax ID (e.g. RO37311090) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the idempotentHint annotation, the description explains that the tool sets a configuration value for all subsequent requests, disclosing its non-destructive, state-changing nature. It adds context about the optional environment variable fallback.
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 long, with no wasted words. It front-loads the primary action and purpose, then adds necessary 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 tool with one parameter, no output schema, and comprehensive annotations, the description covers all needed information: purpose, parameter format, and usage prerequisites.
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 reinforces the parameter's meaning with an example ('e.g. RO37311090'). This adds clarity beyond the schema's description.
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 ('Sets the company CIF'), the resource ('tax ID'), and its role for subsequent API requests. It distinguishes itself from sibling tools like get_cif by specifying that it sets the value, not retrieves it.
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 states when to use the tool ('Must be called before other tools if the CIF environment variable is not configured'), providing clear context. It does not mention alternatives, but the guidance is sufficient for the tool's prerequisite role.
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.0cancel_documentcollect_paymentcreate_documentcreate_einvoicedelete_documentget_cifget_documentget_einvoice_archiveget_nomenclatureslist_documentsrestore_documentset_cifScored across 12 tools
Each tool targets a distinct operation (cancel vs delete, create document vs create e-invoice, etc.). Even similar-sounding tools like cancel_document and delete_document are clearly differentiated by descriptions, leaving no ambiguity for an agent.
All tools follow a consistent verb_noun pattern in snake_case (e.g., cancel_document, collect_payment, get_nomenclatures). There are no mixed conventions or vague verbs, ensuring predictable naming.
With 12 tools, the server is well-scoped for managing documents in Oblio. Each tool serves a clear purpose without redundancy, covering configuration, document lifecycle, payments, and e-invoice handling.
The tool surface covers creation, retrieval, listing, cancellation, restoration, deletion, payment collection, and e-invoice submission. However, there is no update/edit tool for documents (e.g., modifying invoice lines), which is a notable gap but manageable via cancel+recreate.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Hosted MCP server for Mini Accountant: invoices, expenses, customers, analytics, tax estimates.
MCP server for Quaderno — tax-rate calculation, invoices, contacts, products, receipts & expenses.
Official MCP server for Lovable, the AI-powered full-stack app builder.
