Enables management of international debt recovery directly from VS Code via GitHub Copilot, including case inspection, messaging collection partners, and submitting new collection cases.
The MCP server for cross-border debt collection. Connect Claude, Cursor, VS Code, or any MCP-compatible agent to Debitura and manage international debt recovery from your AI assistant: check case status, read partner conversations, get pricing, and submit new collection cases — handled by vetted local collection partners in 183 countries on a no-cure-no-pay basis.
Endpoint: https://mcp.debitura.com/mcp (streamable HTTP)
Auth: your Debitura API key in the XApiKey header (or Authorization: Bearer <key>)
Get a key: log in at app.debitura.com → API key page
Connector page: debitura.com/integration/mcp-server
Tool | What it does |
| Test the connection — "✓ Connected as {your company}" |
| List your collection cases (paging, status filter, sorting) |
| Fetch one case by ID, your own reference, or Debitura case reference |
| Case timeline — what has happened so far (returns |
| Read the chat with the collection partner |
| Money recovered on a case |
| Which contracts are signed / blocking a case |
| Open tasks (action-items) for one case |
| List documents attached to a case, with time-limited download URLs |
| Case counts per lifecycle stage — a quick portfolio overview |
| Every open task (action-item) across your account, with solutionUrl + resolving action |
| Pricing + eligibility dry-run before submitting (nothing persisted) |
| Your team — used to attribute messages and assign case owners |
Tool | What it does |
| Submit a collection case. Safety-wrapped: preview first → explicit user confirmation → idempotent submit (auto |
| Attach documents to a case (invoice copies, contracts — max 25 MB) |
| Message the collection partner on a case, attributed to a named team member |
Every tool carries proper MCP annotations (readOnlyHint / destructiveHint), and create_case
never auto-fires — it is a legal/financial action and always requires explicit human confirmation.
Related MCP server: CurrencyTransfer MCP Server
Debitura runs this MCP server as a hosted service at https://mcp.debitura.com/mcp. That is the
only supported way to use it — point any MCP client at the endpoint and authenticate with your
Debitura API key (see Install below). There is no published npm package: the
@debitura/mcp-server package is private ("private": true) and is not distributed on the npm
registry. The source is published so you can audit it and, if you wish, run your own copy (see
Self-hosting / development) — but normal usage is the hosted endpoint.
Settings → Connectors → Add custom connector → URL https://mcp.debitura.com/mcp.
Anthropic is rolling out a Request headers option in that same dialog that lets you
authenticate without OAuth — but it's a gated beta (Anthropic: "contact us for early
access"), so most accounts won't see it yet. If you do see it, add header x-api-key
with your Debitura API key as the value. If you don't, use Claude Code or the Claude
Desktop config-file method below instead — both work today regardless of beta access.
claude mcp add --transport http debitura https://mcp.debitura.com/mcp --header "XApiKey: YOUR_API_KEY"Bypass the Connectors UI entirely by editing claude_desktop_config.json directly — a
separate mechanism from the web-synced Connectors UI, no OAuth involved — using the
mcp-remote bridge:
{
"mcpServers": {
"debitura": {
"command": "npx",
"args": ["mcp-remote", "https://mcp.debitura.com/mcp", "--header", "XApiKey:${DEBITURA_KEY}"],
"env": { "DEBITURA_KEY": "YOUR_API_KEY" }
}
}
}File location: macOS ~/Library/Application Support/Claude/claude_desktop_config.json,
Windows %APPDATA%\Claude\claude_desktop_config.json. Restart Claude Desktop after
saving — the server appears under Settings → Connectors → Manage connectors, even
though you never touched "Add custom connector".
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"debitura": {
"url": "https://mcp.debitura.com/mcp",
"headers": { "XApiKey": "YOUR_API_KEY" }
}
}
}code --add-mcp '{"name":"debitura","type":"http","url":"https://mcp.debitura.com/mcp","headers":{"XApiKey":"YOUR_API_KEY"}}'Ask your assistant: "Ping Debitura" → you should see ✓ Connected as {your company}.
"What's the status of my Debitura cases? Anything that needs my attention?"
"What would it cost to collect a €12,000 B2B debt in Germany?"
"Any new messages from collection partners this week?"
"Submit a collection case against Acme GmbH in Berlin for invoice 2026-014, €8,400, due 1 March."
Authentication & tenancy. The XApiKey header IS the tenant boundary. The server is
stateless — each request creates a fresh MCP server bound to the caller's API key, which is
passed straight through to the Debitura Customer API. No keys or case data are stored.
Rate limiting is handled at the Cloudflare edge (WAF / rate rules) that fronts
mcp.debitura.com, not in-app. Note that some tools fan out to multiple Customer-API calls per
invocation (e.g. get_account_summary queries one count per lifecycle stage), which the edge
limits account for.
Vulnerability reports: see SECURITY.md.
The supported way to use Debitura's MCP is the hosted endpoint above. The steps below are for local development / auditing of this repository only.
npm install
npm run dev # starts on :3000, POST /mcpEnv var | Default | Purpose |
|
| Listen port |
|
| Point at |
See .env.example for a starter env file.
npm run build && npm start # production-style local run
docker build -t debitura-mcp . && docker run -p 3000:3000 debitura-mcpDeployment note: the hosted service deploys the built app as a zip to Azure App Service (see
.github/workflows/deploy.yml) — it does not run the Docker image in production. TheDockerfileis provided for local/self-hosted use.
Runs every tool against the test environment (creates only tagged isTest cases and deletes them):
DEBITURA_API_BASE_URL=https://testcustomer-api.debitura.com npm run dev # terminal 1
DEBITURA_TEST_API_KEY=<test key> MCP_URL=http://localhost:3000/mcp npx tsx scripts/e2e.tsTypes and the HTTP client are generated from the Customer API's OpenAPI spec
(openapi/customer-api.json) via openapi-typescript — the curated 16-tool layer on top is
hand-written:
npm run fetch:spec # pull latest spec + regenerate src/generated/customer-api.d.tsThe version lives in package.json (config.ts and client.ts derive from it). When bumping
it, also update server.json — its version field is independent and must match the published
registry listing. (smithery.yaml has no version field; Smithery picks up the package version
automatically.)
When adding or removing a tool, also update the tool catalog above and the tools/list
assertion in scripts/e2e.ts (it asserts the exact registered tool set).
Debitura is a global debt collection platform covering 183 countries. Creditors submit overdue B2B and B2C claims; vetted local collection partners in the debtor's jurisdiction recover them, typically no-cure-no-pay. Learn more at debitura.com · API docs at docs.debitura.com.
Submit a debt collection case to Debitura. This is a LEGAL AND FINANCIAL ACTION: a collection partner starts recovery against the debtor, and contractual fees apply on success.
Required workflow — never skip it:
Call preview_case first and show the user the pricing, assigned partner, and any contracts that need signing.
Ask the user to explicitly confirm submission.
Only then call this tool. NEVER call it without the user's explicit confirmation in this conversation.
Submission is idempotent: the server sends a unique Idempotency-Key and safely retries transient network failures without risk of duplicate cases. A 422 response is a business rejection — read its payload (it may contain signing URLs for required contracts, or duplicate-reference details).
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Optional tag for grouping test data | |
| date | Yes | Invoice date (ISO 8601, e.g. 2026-03-01) — required by the API | |
| debtor | Yes | The debtor the claim is against | |
| isTest | No | Create as test data (persisted but excluded from production metrics) | |
| dueDate | Yes | Invoice due date (ISO 8601, e.g. 2026-04-30). Required — Debitura computes the age of the debt from it, which affects pricing. | |
| comments | No | Context for the collection partner, e.g. payment history or prior communication | |
| currencyCode | Yes | ISO 4217 currency code, e.g. "EUR" | |
| amountToRecover | Yes | Total principal amount to recover | |
| claimDescription | No | Description of the claim (what the debt is for) | |
| assignedUserEmail | No | Email of the team member to own the case (use list_team_members to find valid team members) | |
| creditorReference | No | RECOMMENDED: your own reference (e.g. invoice number). Helps avoid business duplicates and lets you look the case up later. | |
| allowPendingContracts | No | Accept the case even if contracts (SDCA/POA) are unsigned — it waits in PendingContractSigning with signing URLs returned |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, but the description adds crucial context: it's a legal/financial action with contractual fees, idempotent behavior, and details on 422 responses (business rejection with signing URLs). 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?
Well-organized with clear sections: action description, required workflow (numbered steps), idempotency note, error handling. Every sentence adds meaningful information without 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?
Given no output schema, the description covers behavior (idempotent, error details) and required context (preview_case, user confirmation). Could mention what a successful response contains (e.g., case ID), but overall 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%, so baseline is 3; description adds value by referencing sibling tools for parameter population (list_team_members for assignedUserEmail, recommend creditorReference) and emphasizing the required preview_case workflow, though it doesn't detail each parameter beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Submit a debt collection case to Debitura' with a specific verb and resource, and distinguishes from sibling tools like preview_case by outlining the required workflow.
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 provides a mandatory 3-step workflow (preview_case, user confirmation, then this tool) and warns never to call without explicit user confirmation, effectively guiding when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a count of cases per lifecycle stage for the creditor's account. Useful for a quick portfolio overview without listing all cases. Stages: PendingContractSigning, PendingVerificationInternal, PendingVerification, NeedsAdditionalDetails, Leads, LeadsQuoteGiven, Active, Paused, Closed, Merged. Note: these counts include the creditor's own test cases; list_cases exposes the isTestCase flag that marks them.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, idempotent, not destructive), description adds behavioral context: it includes test cases, lists all stages, and relates to list_cases. 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?
Three sentences, front-loaded with purpose, followed by usage context, list of stages, and a note about test cases. No redundant 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?
Description covers purpose, stages, and test case inclusion, but lacks explicit output format or structure. Since there is no output schema, a brief mention of the return format would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters, so description carries full burden. It adds meaning by detailing what the tool returns (counts per stage) and listing the stages, which is not present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it returns a count of cases per lifecycle stage for the creditor's account. It distinguishes itself from sibling list_cases by noting it's a quick overview without listing all cases, and explicitly mentions list_cases.
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 when to use ('quick portfolio overview') and when not ('without listing all cases') and provides an alternative tool (list_cases) for detailed access including test case flag.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one collection case in full detail. Look it up by Debitura case ID (GUID), by your own creditor reference (e.g. invoice number), or by the Debitura case reference shown in the portal. Provide exactly one of the three identifiers.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Debitura case ID (GUID) | |
| caseReference | No | Debitura case reference as shown in the portal | |
| creditorReference | No | Your own reference for the case (e.g. invoice number) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description adds minimal behavioral context beyond stating it returns full detail. 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?
The description is two concise sentences: first states purpose, second states usage constraint. Every sentence is necessary and front-loaded with no waste.
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 does not explain what 'full detail' includes, leaving the return structure undefined. The tool is simple but could be improved by noting that it returns all case fields.
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 has a description. The description adds critical constraint 'Provide exactly one of the three identifiers', which the schema does not enforce, thus adding significant 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?
The description clearly states it fetches one collection case in full detail, specifying the resource and verb. It distinguishes from sibling tools like get_case_activity or get_case_payments by implying it returns the complete case rather than a subset.
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 instructs to provide exactly one of the three identifiers, which is clear usage guidance. However, it lacks explicit when-to-use vs alternatives, though the sibling names imply differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the chronological timeline of a case — what has happened so far: status changes, partner actions, communications, and payments. Returns an envelope { items, currentEngagementPhase }: items is the chronological event list, and currentEngagementPhase is the case's current engagement phase ("Pre-legal", "Legal", or "Enforcement"; null when no active engagement exists).
| Name | Required | Description | Default |
|---|---|---|---|
| caseId | Yes | Debitura case ID (GUID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing the return structure (envelope with items and currentEngagementPhase) with possible values, providing behavioral context beyond safety.
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: first defines the purpose, second explains the return shape. No unnecessary words, front-loaded with the main action.
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 one parameter and no output schema, the description fully explains the tool's behavior and return structure, including possible values for currentEngagementPhase. It is complete given the lack of complexity.
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% (caseId described as 'Debitura case ID (GUID)'). The tool description does not add additional parameter semantics beyond what the schema provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and the resource 'chronological timeline of a case', listing specific event types (status changes, partner actions, communications, payments). This distinguishes it from sibling tools like get_case_messages or get_case_payments.
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 by stating what the tool returns (case timeline), but does not explicitly provide when-to-use or when-not-to-use conditions or name direct alternatives. However, the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check which contracts (e.g. debt collection agreement, power of attorney) are signed or still blocking a case, including signing URLs for any outstanding documents.
| Name | Required | Description | Default |
|---|---|---|---|
| caseId | Yes | Debitura case ID (GUID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds that signing URLs are returned for outstanding documents, providing 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?
Single sentence, front-loaded with key information, 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 no output schema, description adequately explains return values (signed/blocking contracts, signing URLs). Could mention scope is per caseId but implied.
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 description for caseId. Description does not add additional meaning beyond what the schema already provides.
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 specific verb 'Check' and resource 'contracts signed or still blocking a case', distinguishing it from siblings which deal with other case aspects.
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?
Implied usage for checking contract status, but no explicit when-to-use, when-not-to-use, or alternative tools provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the chat conversation on a case between you and the collection partner handling it. Each message includes: senderName, role (Creditor / Partner / Managed by partner), sentAt (UTC), message. See the debitura://glossary/chat-roles resource for what each role means.
| Name | Required | Description | Default |
|---|---|---|---|
| caseId | Yes | Debitura case ID (GUID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about the conversation parties, message fields, and a glossary reference, enhancing transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. First sentence states purpose, second lists message fields and provides a helpful link to a glossary.
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 tool with one parameter and no output schema, the description compensates by listing message fields and referencing roles, but could optionally mention pagination or limits.
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 'caseId' described adequately. The description does not add additional parameter-level 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 uses 'Read the chat conversation' as a specific verb+resource, clearly distinguishing it from write tools like 'send_case_message' and other case-related tools.
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 states when to use ('to read chat conversation') but does not explicitly mention when not to use or alternatives, though sibling tools make this clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every payment recorded on a case — money recovered so far.
| Name | Required | Description | Default |
|---|---|---|---|
| caseId | Yes | Debitura case ID (GUID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds minimal behavioral context ('money recovered so far'), but does not explain pagination, ordering, or what constitutes 'every payment'. Acceptable given the safety profile from 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?
Single concise sentence that front-loads the purpose. 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?
For a simple list tool with one parameter and no output schema, the description covers the core functionality. However, it omits potential details like whether results are paginated or ordered, but given the tool's simplicity and annotations, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline 3. The description does not add any extra meaning to the caseId parameter beyond what the schema already provides (a UUID). No elaboration on format or usage tips.
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 ('List') and the resource ('every payment recorded on a case'), with a clarifying note about money recovered. It distinguishes from siblings like get_case or get_case_activity by focusing specifically on payments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when or when not to use this tool. With siblings like get_case_activity or get_case, the description does not explain how this tool fits in or when to choose it over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the open tasks (action-items) attached to one specific case — same data as list_tasks, scoped to a single case. Use this when you're already working a specific case and want just its outstanding tasks.
Note: account-level tasks that aren't tied to any one case (e.g. SignContract, AssignBankAccount — these block the whole account, not one case) never appear here; use list_tasks to see those.
See list_tasks for the full task model (auto-resolve, solutionUrl, action).
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Restrict to specific task types, e.g. ["ReplyToChat", "SignContract"]. Valid values: Generic, ReplyToChat, SelectQuoteWinner, ReviewPartner, ClientInputRequired, SignContract, MoreInfoNeeded, AssignBankAccount, CaseValidationNeedsInfo | |
| caseId | Yes | Debitura case ID (GUID) | |
| status | No | Filter by task status. "Open" (default) or "Solved". |
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 behavioral context: explains that account-level tasks are excluded and references list_tasks for the full task model, enhancing transparency 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 concise, front-loaded with the primary purpose, and includes necessary clarifications in a note without unnecessary 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 full input schema coverage, no output schema, and annotations indicating a safe read operation, the description fully covers the tool's behavior, constraints, and relationship to siblings.
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 description adds little beyond what the schema provides. It does imply default status 'Open' and mentions type filtering, but these are already in parameter 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 it lists open tasks for one specific case, uses the verb 'list' with the resource 'tasks', and distinguishes from the sibling 'list_tasks' by noting scoping and exceptions.
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 when to use ('when you're already working a specific case') and when not to (account-level tasks not here, use list_tasks). Names alternative sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all documents attached to a case: file name, document type, description, upload date, and a time-limited SAS download URL. Each file also carries downloadUrlExpiresAt (UTC) — when the download URL stops working, so a cached URL can be refreshed in time. Use upload_case_file to attach new documents.
| Name | Required | Description | Default |
|---|---|---|---|
| caseId | Yes | Debitura case ID (GUID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds behavioral details like time-limited SAS URLs and downloadUrlExpiresAt for cache refresh, which adds value 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, efficient and front-loaded. Includes purpose, key details, and sibling reference without 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?
Given the simple tool (1 param, clear annotations, no output schema), the description covers return fields, caching behavior, and attachment option, making it complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (caseId already well-described). Tool description does not add additional meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List all documents attached to a case' with specific fields, and distinguishes from sibling 'upload_case_file' by referencing it explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for usage and mentions alternative tool (upload_case_file), but does not explicitly state when not to use or exclude other siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the creditor's debt collection cases with pagination, status filtering, and sorting. Returns compact case summaries: reference, debtor name + country, amounts, lifecycle, partner, key dates. Use get_case for full detail on a specific case.
Lifecycle values (statuses filter and output):
PendingContractSigning · PendingVerificationInternal · PendingVerification · NeedsAdditionalDetails · Leads · LeadsQuoteGiven · Active · Paused · Closed · Merged
Sortable fields: DateCreated · DateUpdated · DateFinished · DateCollectionStarted · DueDate · Date · GrossAmount · Remainder · InterestFees · CollectionFees
Sort format: Field:asc or Field:desc, e.g. GrossAmount:desc
Note: results include the creditor's own test cases; the isTestCase flag on each case marks them.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, starting from 1 (default 1) | |
| sort | No | Sort expression: Field:asc or Field:desc. Valid fields: DateCreated, DateUpdated, DateFinished, DateCollectionStarted, DueDate, Date, GrossAmount, Remainder, InterestFees, CollectionFees. Example: GrossAmount:desc | |
| pageSize | No | Results per page (default 10, max 100) | |
| statuses | No | Filter by lifecycle status. Values: PendingContractSigning, PendingVerificationInternal, PendingVerification, NeedsAdditionalDetails, Leads, LeadsQuoteGiven, Active, Paused, Closed, Merged |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive. The description adds that it returns compact summaries and includes test cases marked by isTestCase, which is useful 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?
Description is well-structured with a concise first sentence, followed by detailed bullet points. No unnecessary words, each sentence adds unique value.
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 no output schema, it describes return fields and the isTestCase flag. Covers pagination, filtering, sorting, and a note about test cases. Complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description lists parameters and explains sort format and enum values, adding minor value over schema. No major shortcomings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists debt collection cases with pagination, status filtering, and sorting. It specifies the resource and actions, and distinguishes itself from get_case for full detail.
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 mentions using get_case for full details, implying list_cases for summaries. It also details filtering and sorting. However, it could more explicitly state when not to use it (e.g., for creation).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every open task (action-item) across your whole account — things the platform needs you to do before a case (or your account) can proceed: reply to a chat, sign a contract, assign a bank account, and so on. Use get_case_tasks instead to scope this to one case.
Tasks auto-resolve once the underlying condition clears — e.g. replying to a case's chat makes its ReplyToChat task disappear on its own. Treat this as a live work queue, not a log: a task seen on one call may no longer be open on the next.
Every task carries a solutionUrl — an absolute link a human can open to resolve it in one click, whatever the type. Some types (today: ReplyToChat, ClientInputRequired, MoreInfoNeeded) additionally carry a non-null action pointing at the exact API call that resolves them — for those, call send_case_message with the task's caseId instead of sending a human to solutionUrl. Tasks without an action rely on solutionUrl alone.
Task types: Generic, ReplyToChat, SelectQuoteWinner, ReviewPartner, ClientInputRequired, SignContract, MoreInfoNeeded, AssignBankAccount, CaseValidationNeedsInfo.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, starting from 1 (default 1) | |
| type | No | Restrict to specific task types, e.g. ["ReplyToChat", "SignContract"]. Valid values: Generic, ReplyToChat, SelectQuoteWinner, ReviewPartner, ClientInputRequired, SignContract, MoreInfoNeeded, AssignBankAccount, CaseValidationNeedsInfo | |
| status | No | Filter by task status. "Open" (default) or "Solved". | |
| pageSize | No | Results per page (default 10, max 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only and idempotent; description adds key behaviors: auto-resolution, solutionUrl usage, action field for certain types, and instructions to call send_case_message for those types. Fully transparent 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?
Description is well-structured: starts with purpose, then differentiation, then behavioral details, and ends with type list. Every sentence adds value without 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?
Despite no output schema, description fully explains return values (solutionUrl, action), task behavior, and how to resolve tasks. Pagination is handled via parameters. Complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. Description does not add additional meaning beyond listing allowed types, which are already enumerated in schema. 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?
Description clearly states it lists every open task across the whole account. It contrasts with sibling tool get_case_tasks, which scopes to one case. Verb 'list' and resource 'tasks' are specific.
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 advises to use get_case_tasks instead for case-scoped tasks. Describes tasks as a live work queue, not a log, guiding appropriate usage. No misleading statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the team members on the creditor's Debitura account. Use this to resolve a valid sender (userId or email) before calling send_case_message, or a case owner for create_case.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default 1) | |
| pageSize | No | Results per page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds the behavioral context of resolving user IDs/emails, which is useful 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 concise sentences with no wasted words. Purpose and usage are 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?
Adequately covers the tool's purpose and usage, but lacks any hint about the output structure (e.g., fields returned). Still, for a simple listing tool with annotations, it is mostly complete.
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 adds no extra meaning beyond what the schema already provides for 'page' and 'pageSize'. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'team members on the creditor's Debitura account', and distinguishes its purpose from siblings by noting its use to resolve a sender or case owner.
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 when to use: 'before calling send_case_message, or a case owner for create_case', providing clear context and practical guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify the connection to Debitura and show which creditor account the API key belongs to. Call this first to confirm the integration is set up correctly.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only and idempotent. The description adds that it reveals the creditor account, which is useful context beyond annotations. 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?
Two sentences, front-loaded with purpose and usage, no unnecessary 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 zero parameters and no output schema, the description fully explains purpose and usage context. Annotations cover safety. No gaps.
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?
No parameters; schema coverage is trivially 100%. Baseline 4 applies as no parameter documentation needed.
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 it verifies the connection and shows the creditor account. Distinguishes from all sibling tools which handle cases, files, etc.
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 says 'Call this first to confirm the integration is set up correctly.' Provides clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dry-run a collection case BEFORE creating it: returns eligibility, the assigned collection partner, pricing (success fee), and any contracts that would need signing. Nothing is persisted. ALWAYS call this before create_case and show the user the pricing and requirements.
| Name | Required | Description | Default |
|---|---|---|---|
| dueDate | No | Invoice due date (ISO 8601) — used to compute debt age for pricing | |
| debtorType | Yes | Company (B2B) or Private individual (B2C) | |
| currencyCode | Yes | ISO 4217 currency code, e.g. "EUR", "USD", "DKK" | |
| amountToRecover | Yes | Total principal amount to recover | |
| debtorStateAlpha2 | No | US state code, e.g. "CA" — REQUIRED when the debtor is in the United States | |
| debtorCountryAlpha2 | Yes | Debtor country, ISO 3166-1 alpha-2, e.g. "DE", "US" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly=true, destructive=false, idempotent=true. The description adds 'Nothing is persisted,' which aligns and further clarifies that no side effects occur. It also details what the tool returns, adding valuable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose and key behavior, and contains no extraneous 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?
Given there is no output schema, the description adequately explains what the tool returns (eligibility, partner, pricing, contracts). With full parameter documentation in the schema and clear behavioral notes, the description is complete.
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 schema already documents all parameters. The description does not add new meaning beyond what is in the schema, meeting 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 clearly states it is a dry-run for a collection case before creation, returning eligibility, partner, pricing, and contracts. It distinguishes itself from the sibling create_case by explicitly recommending to call it before.
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 says 'ALWAYS call this before create_case and show the user the pricing and requirements,' providing clear when-to-use guidance and what to do with the output.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a chat message on a case to the collection partner handling it. The partner is notified by email. The message is attributed to a named team member, so a sender is REQUIRED: pass the sender's userId or email from list_team_members. Ask the user who the message should be sent as if it is not obvious.
| Name | Required | Description | Default |
|---|---|---|---|
| caseId | Yes | Debitura case ID (GUID) | |
| message | Yes | The message to send | |
| senderEmail | No | Team member email sending the message (alternative to senderUserId) | |
| senderUserId | No | Team member ID sending the message (from list_team_members) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the 'destructiveHint' annotation, the description reveals that the partner is notified by email and the message is attributed to a named team member. These behaviors are not captured in annotations. No contradictions 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?
The description is three sentences, front-loaded with the core action, and every sentence adds unique value. No fluff or 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?
The description covers the purpose, behavioral effects (notification, attribution), parameter requirements and sourcing, and user interaction guidance. Given there is no output schema, the description is fully adequate for a send operation.
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 adds meaning by specifying that senderEmail or senderUserId should come from 'list_team_members' and that one is required. It also advises to ask the user when the sender is not obvious.
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 sends a chat message on a case to the collection partner, and it specifies the action ('send'), the resource ('case'), and additional details (notification by email, attribution). It distinguishes itself from siblings like 'get_case_messages' by focusing on sending rather than reading.
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: the partner is notified, the message is attributed, and a sender is required. It references 'list_team_members' as a source for the sender. It also advises to ask the user if not obvious. However, it does not explicitly state when not to use this tool or compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attach a document to a case (invoice copy, contract, correspondence, proof of delivery). Max 25 MB. Allowed extensions: .pdf, .xls, .xlsx, .csv, .txt, .jpg, .jpeg, .png, .gif. Provide the file content base64-encoded.
| Name | Required | Description | Default |
|---|---|---|---|
| caseId | Yes | Debitura case ID (GUID) | |
| fileName | Yes | File name including extension, e.g. "invoice-1042.pdf" | |
| contentType | No | MIME type, e.g. "application/pdf" (inferred from extension if omitted) | |
| description | No | Short description of the document | |
| documentType | No | Document category (default: OriginalInvoice). Values: OriginalInvoice · DebtorDocuments · CreditorDocuments · PartnerDocuments · DemandLetter · Miscellaneous | |
| contentBase64 | Yes | File content, base64-encoded |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true (modification). Description adds concrete behavioral details: file size limit, allowed extensions, and encoding requirement, which are not in 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 clear sentence plus list of extensions and encoding hint. It is concise, front-loaded, and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists; description does not mention return value (e.g., attachment ID). It covers input constraints well but omits post-upload behavior, making it slightly incomplete.
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 parameters described). Description adds overall context (base64, file types) but does not detail individual parameters beyond what 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 clearly states the action: Attach a document to a case, with examples (invoice copy, contract, etc.). It distinguishes from siblings like list_case_files and get_case by focusing on upload/write operation.
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 constraints (max 25 MB, allowed extensions, base64 encoding) but does not explicitly say when to use vs alternatives. Context is clear enough for an upload tool among mostly read 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.
v1.0.0create_caseget_account_summaryget_caseget_case_activityget_case_contract_statusget_case_messagesget_case_paymentsget_case_taskslist_case_fileslist_caseslist_taskslist_team_memberspingpreview_casesend_case_messageupload_case_fileScored across 16 tools
Each tool targets a distinct aspect of case management (payments, activity, messages, files, tasks, preview, creation, etc.), with no overlapping purposes. List tools are scoped appropriately (all cases vs one case, all tasks vs case tasks).
All tools follow a consistent verb_noun pattern in snake_case (e.g., get_case_payments, list_cases, upload_case_file). The naming is predictable and easy to navigate.
With 16 tools, the server covers the essential operations for debt collection case management without being excessive. Each tool serves a clear purpose within the domain.
The tool set covers core workflows (create, read, list, upload, send messages, view payments/activity/tasks). Missing update/close case tools, but these may be handled externally or implicitly. Minor gaps that don't hinder primary agent tasks.
Cross-border payment & banking intelligence for AI agents: SWIFT/BIC, IBAN, sanctions, FX, tracking.
Pay-per-call data APIs for AI agents: business, compliance, procurement, VAT and IBAN via x402.
European business verification for AI agents: registry, VAT, sanctions, IBAN. Pay-per-call x402.
140+ data APIs for agents: finance, banking validation, geo, weather, text. One API key.
