Skip to main content
Glama

top_up_credits

Top up the signed-in mentee's credit balance. Mentorships are billed from credits, not from a Stripe Connect subscription on the agent's card. Without an MPP credential this returns payment_required. MCP clients cannot send HTTP Payment headers — pass payment_credential (Stripe shared payment token object) if the host wallet provides one, or use open_dashboard and pay in the browser, then retry.

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": {
      "amount_usd": "<amount_usd>"
    },
    "name": "top_up_credits"
  }
}

Input Schema

NameRequiredDescriptionDefault
amount_usdYes
payment_credentialNo

Output Schema

NameRequiredDescriptionDefault
endNo
kindNointro_call, mentorship_call, or session.
errorNopayment_required, invalid_payment, auth_required, not_found, etc.
startNo
intentNocharge
methodNostripe
statusNo'paid', 'topped_up', or absent on payment_required.
messageNo
pay_urlNoREST URL to retry with an MPP Payment credential.
receiptNoBase64url MPP receipt.
currencyNousd
setup_idNo
availableNo
challengeNoMPP challenge. Present when error is payment_required.
next_stepNo
amount_usdNoCharge or top-up amount in whole USD.
mentorshipNo
applicationNo
credits_usdNo
billing_noteNo
booking_hashNo
calendar_linkNo
dashboard_urlNo
mentorship_hashNo
application_hashNo
www_authenticateNoWWW-Authenticate Payment header value from the REST 402.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.9/5.0
Behavior4/5

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

Annotations only declare it is a non-destructive write with open-world access; the description adds the billing model (credits, not a Stripe Connect subscription), the explicit error contract (returns payment_required without an MPP credential), and the MCP client limitation on HTTP Payment headers. It does not address idempotency, retry safety, or whether a failed attempt consumes anything, which matters for a payment mutation.

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?

Three sentences, front-loaded with the action, then the billing rationale, then the failure/fallback path. The billing rationale is slightly tangential but justifies the tool's existence; no sentence is pure filler.

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

Completeness4/5

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

For a payment mutation with an output schema and partial annotation coverage, the description supplies the auth prerequisite, the error mode, and the recovery route. Missing are amount units/bounds and idempotency behavior, which are the remaining things an agent needs to call it safely.

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 coverage is 0%, so the description must carry the load: it explains payment_credential well (a Stripe shared payment token object supplied by the host wallet) and its optionality. amount_usd is left entirely uninterpreted — no indication of dollars vs. cents, minimum, or maximum — which is a real gap for a money-handling parameter.

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

Purpose4/5

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

States a specific verb and resource: 'Top up the signed-in mentee's credit balance,' which no sibling tool does, so it is distinguishable from the surrounding book_/pay_/list_ tools. It stops short of naming a contrasting sibling, but the resource scope is unambiguous.

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 a clear condition for the alternative path: pass payment_credential if the host wallet supplies one, otherwise use open_dashboard, pay in the browser, then retry. It does not state any case where a top-up should be avoided (e.g., existing sufficient balance), which keeps it just under full marks.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources