Skip to main content
Glama
Sign In

Ambr

by io.github.getambr
OverviewDiscussionsAdmin

ambr_check_transaction

Read-onlyIdempotent

Check one payment against what an agreement allows. Advisory only: Ambr compares what you report with the agreement's terms; it does not authorize, block or see payments, and in_scope is not an approval or a guarantee.

Tests the payment against the agreement's status, validity window, currency, per-transaction limit, monthly limit, approved categories, enumerated actions and approval threshold. If the agreement was amended, the newest approved version is checked. Free: no credits are burned. Ambr does not hold funds or track spend, so the monthly limit is checked only when you pass period_spent. A rule the agreement sets no limit for comes back as not_evaluated, never as a pass. If a rule has a limit but you did not send what it needs (category, action, currency, period_spent), the verdict is "incomplete", not "in_scope". Send everything the agreement limits.

Access: a public contract is open to anyone; otherwise use the creator's API key or pass a share_token.

Args:

  • contract_id (string, required): Contract ID (amb-YYYY-NNNN), SHA-256 hash, or UUID

  • amount (number, required): payment amount, zero or more

  • currency (string, optional): e.g. "USD"

  • category (string, optional): spending category

  • action (string, optional): the action the agent is taking

  • period_spent (number, optional): already spent this month, to check the monthly limit

  • share_token (string, optional): share token for a private contract

Returns: verdict ("in_scope" | "out_of_scope" | "incomplete" | "needs_approval"), the per-rule checks, plain-language reasons, and the contract that was checked (contract_id, effective_contract_id, sha256_hash, reader_url).

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": {
      "contract_id": "<contract_id>",
      "amount": "<amount>"
    },
    "name": "ambr_check_transaction"
  }
}

Input Schema

NameRequiredDescriptionDefault
actionNoAction the agent is taking
amountYesPayment amount
categoryNoSpending category
currencyNoPayment currency, e.g. USD
contract_idYesContract ID, SHA-256 hash, or UUID
share_tokenNoShare token for a private contract
period_spentNoAlready spent this month

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.6/5.0
Behavior5/5

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

Adds substantial context beyond the readOnly/idempotent annotations: it is advisory only, does not authorize or block payments, is not an approval, holds no funds, burns no credits, and checks the newest approved version if amended. It also discloses access rules for private contracts and the not_evaluated behavior. This is well past what the annotations convey.

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?

Front-loaded with the core purpose, then caveats, then args and returns — a sensible order with no filler sentences. The Args block largely restates schema descriptions, which is mild redundancy given 100% coverage, but it stays readable.

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?

With no output schema, the description carries the return-shape burden and does so: it enumerates all four verdict values and lists returned components (per-rule checks, reasons, contract identifiers, reader_url). Combined with the access and input-completeness rules, an agent has everything needed to call and interpret it.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: period_spent exists solely to enable the monthly-limit check, and category/action/currency are required to evaluate their respective rules. That causal mapping is not evident from the schema alone.

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

Purpose5/5

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

Opens with a specific verb and resource: 'Check one payment against what an agreement allows.' The focus on payment-vs-agreement evaluation clearly separates it from siblings like get_contract or get_contract_status, which deal with the contract itself rather than a payment test.

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

Usage Guidelines4/5

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

Gives strong situational guidance: send everything the agreement limits, pass period_spent to check the monthly limit, and expect 'incomplete' rather than a pass when inputs are missing. It also notes the call is free. It stops short of naming sibling tools or explicitly stating when not to use this versus ambr_get_contract_status, which keeps it from a 5.

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

All Ambr toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources