Skip to main content
Glama
hermoso-ai

Hermoso

Official
by hermoso-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

Buy credits

buy_credits

Buy credit packs to top up your account. List available packs, receive a quote, then confirm with the quote token to charge your saved card.

Instructions

Out of credits? Top up with a credit PACK. Call with no argument to list the available packs (id · credits · price). If the account has a saved card and you have billing-admin rights, calling with pack quotes the exact charge and calling again with confirm:true AND the quote's quote_token charges the saved card instantly (same one-click top-up as the app — no redirect). If there's no saved card yet, you get a Stripe checkout URL to hand your human for the FIRST purchase; their card saves for one-click after that. Packs only; subscriptions are managed by a person in Settings -> Billing. IF YOU ARE AN AGENT HOLDING YOUR OWN PAYMENT CREDENTIAL, there is a third path that needs no human at all: POST /api/billing/machine-payment with a packId answers HTTP 402 carrying an MPP challenge, and grants the pack once you authorise and retry with the credential — the same packs, the same prices, the same credits. GET /api/billing/config carries a machinePayments block listing the packs with their per-credit rates and saying whether that lane is enabled on this server. Most agents do NOT have their own credential yet, so the checkout link above remains the normal path. To stop running out entirely, turn on auto-reload with set_auto_reload (admin) — low balances then top themselves up from the saved card automatically.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
packNothe pack id to buy (e.g. pack-2k) — omit to list the available packs first
confirmNoset true to actually charge the saved card for `pack` (required for the one-click charge; ignored on the checkout-link path)
quote_tokenNothe quoteToken returned by the quote step — REQUIRED (with confirm:true) to charge; it binds the exact pack + price you quoted (10-minute validity) and makes a retried confirm idempotent

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.161
    • changedOutput schema / (root)
      Previous value: -{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "additionalProperties": false,
-  "properties": {
-    "amountUsd": {
-      "description": "USD amount of the checkout link",
-      "type": "number"
-    },
-    "credits": {
-      "description": "credits added by a completed top-up (or bought by the checkout link)",
-      "type": "number"
-    },
-    "ok": {
-      "description": "true when a one-click top-up charge succeeded",
-      "type": "boolean"
-    },
-    "packId": {
-      "description": "the pack id the checkout link buys",
-      "type": "string"
-    },
-    "packs": {
-      "description": "available credit packs ({id, credits, priceUsd}) when listing",
-      "items": {},
-      "type": "array"
-    },
-    "quote": {
-      "description": "the one-click charge quote ({packId, credits, priceUsd, card}) awaiting confirm:true"
-    },
-    "url": {
-      "description": "Stripe checkout URL for a first purchase (no saved card yet)",
-      "type": "string"
-    }
-  },
-  "type": "object"
-}New value: +null
  2. Changed1 schema field changedv0.1.15
    • addedInput schema / properties / quote_token
      Added value: +{
+  "description": "the quoteToken returned by the quote step — REQUIRED (with confirm:true) to charge; it binds the exact pack + price you quoted (10-minute validity) and makes a retried confirm idempotent",
+  "type": "string"
+}
  3. First observedv0.1.0

TDQS

A5/5.0
Behavior5/5

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

The description goes well beyond the sparse annotations (readOnlyHint=false, openWorldHint=true) by disclosing that the tool charges a saved card, requires billing-admin rights, produces a Stripe checkout URL on first purchase, and mentions the 10-minute validity of quote_token plus idempotency on retried confirm. It also reveals the HTTP 402 MPP challenge flow and the config endpoint, giving a full behavioral picture. 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.

Conciseness5/5

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

The description is long but every sentence earns its place given the tool's three distinct paths, auth requirements, and exception cases. It is front-loaded with the core use case and uses typographic emphasis (caps, bold) to highlight the machine-payment lane. The structure flows logically from normal flow to edge cases to alternative tools, keeping it scannable despite its length.

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 must explain result formats, and it does: list returns packs with id·credits·price, quote yields quote_token, first purchase yields a Stripe checkout URL, and machine-payment answers with an HTTP 402 MPP challenge. It also covers prerequisites, auth, exclusions, and sibling alternatives, making the tool fully callable without external documentation.

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

Parameters5/5

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

Though the schema covers 100% of parameters, the description adds critical workflow semantics: 'Call with no argument to list the available packs,' explains that pack selects a pack id and triggers a quote, confirm:true actually charges, and quote_token binds the exact price, has 10-minute validity, and makes retries idempotent. This is precisely the kind of meaning that lets an agent invoke the tool correctly without guessing.

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?

The description clearly identifies the resource (credit packs) and the action (top up/buy), and explicitly delineates three distinct paths: listing packs, one-click charge with quote_token+confirm, and the machine-payment lane for credential-holding agents. It also distinguishes itself from subscriptions and names the sibling set_auto_reload, leaving no ambiguity about what this tool does.

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

Usage Guidelines5/5

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

The description gives explicit when-to-use guidance: it starts with 'Out of credits? Top up with a credit PACK,' explains the exact call sequence for quoting and confirming, notes when the checkout URL applies vs. the one-click path, and explicitly routes auto-reload to set_auto_reload ('To stop running out entirely...'). It also states that subscriptions are handled by a person, preventing misuse.

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