Skip to main content
Glama
BeeL MCP server

BeeL MCP server

Official
by beel-es

beel_resolve_payment_event

DestructiveIdempotent

Marks a payment event as resolved outside BeeL, so it leaves the events that need action without generating an invoice. Use it when the payment was already handled by hand or in another tool.

Instructions

Marks a payment event as resolved outside BeeL, for example when the invoice was issued through another tool or the situation was otherwise handled by hand. The event leaves the events that need action without generating any invoice.

The operation applies to the whole payment the event belongs to. Its scope is every active event of the connection that shares the payment identity of the event named in the request: when the event carries a payment identifier (external_payment_id), every event with that same identifier, whatever its kind (the sale, its failed attempts, its refunds); otherwise, when it carries a source object (source_object_id, such as a credit note or a dispute), every event with that same source object; otherwise, the event alone. Within that scope, the events that need action (the same criterion as the needs_action filter) and are eligible are resolved together, in a single transaction; a failed event still pending automatic retry is resolved as well, so that no retry is attempted for a payment the caller has declared handled elsewhere. Events that do not need action — for instance an event still in RECEIVED state that has not stalled — remain unchanged. The response carries the event named in the request.

  • Eligible events: only events in FAILED, SKIPPED or RECEIVED can be resolved; if the event named in the request is not eligible, the request returns 400.

  • Terminal: a resolved event cannot be retried afterwards.

BeeL API endpoint: POST /v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}/resolve (reference: https://docs.beel.es)

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "company_id": "<company_id>",
      "connection_id": "<connection_id>",
      "event_id": "<event_id>"
    },
    "name": "beel_resolve_payment_event"
  }
}

Input Schema

NameRequiredDescriptionDefault
event_idYesIdentifier of the payment event, as returned by the list operation.
company_idYesUnique identifier (UUID) of the company the events belong to — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A company you do not reach answers `403`, and so does a company that does not exist, so the existence of a company in another account is never disclosed.
connection_idYesUnique identifier (UUID) of the payment connection the operation acts on, as returned by `GET /v1/companies/{company_id}/payment-connections`. A NIF can hold several connections of the same provider, so the provider slug alone does not name one. A connection of another NIF answers `404`, exactly like one that does not exist.
idempotency_keyNoOptional idempotency key for this operation. Omit it and one is derived from the request itself, which makes a blind retry safe but also collapses a SECOND, deliberately identical operation into the first for 24 hours. Set it — to an order id, or anything unique per intended operation — whenever you mean to create something that may look identical to what you just created.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.9.0

TDQS

A4.1/5.0
Behavior5/5

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

Annotations already flag destructive=true and idempotent=true, but the description adds substantial context beyond them: the cascade scope (all active events sharing external_payment_id, else source_object_id, else the event alone), that resolution happens in a single transaction, that pending-retry events are also resolved so no retry is attempted, and that non-actionable events are left untouched. The irreversibility ("a resolved event cannot be retried afterwards") and the 400 failure mode are stated explicitly.

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

Conciseness4/5

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

Purpose is front-loaded in the first sentence, followed by scope and eligibility detail that genuinely earns its place for a cascading batch operation. The middle paragraph is dense and could be split into shorter statements, but nothing is redundant with annotations or schema.

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

Completeness5/5

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

For a destructive, cascading mutation with no output schema, the description covers what is affected, what is left alone, transactionality, failure codes, and what the response returns (the event named in the request). An agent has enough to call this correctly and predict the blast radius.

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

Parameters3/5

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

Schema description coverage is 100%, so company_id, connection_id, event_id and idempotency_key are already documented in the schema, including the 403/404 behavior and idempotency-key derivation. The description adds the scope semantics of the event identifier rather than new meaning for individual parameters, so the baseline of 3 applies.

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

Purpose4/5

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

The description opens with a specific verb and resource ("Marks a payment event as resolved outside BeeL") and immediately gives the motivating scenario (invoice issued through another tool, or handled by hand), which implicitly separates it from retry/discard/restore siblings. It never names those siblings explicitly, so an agent must infer the boundary rather than being routed to an alternative.

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

Usage Guidelines4/5

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

Strong when-to-use guidance: the tool is for cases where the payment was already handled outside BeeL, and it explains that no invoice is generated. Eligibility rules (only FAILED, SKIPPED, RECEIVED; otherwise 400) and the terminal nature of the result give clear context. It lacks an explicit "use beel_retry_payment_event instead when..." exclusion, which is the only gap.

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

Deploy Server

Other Tools