Score a planned spend before an agent pays. Verdicts: approve, ask_human, or block.
Scored across 3 tools
get_api_key, get_quota, and score_spend have clearly distinct purposes: authentication, quota check, and payment scoring. No overlap in functionality; descriptions clearly differentiate when to use each.
All tool names follow a consistent verb_noun snake_case pattern (get_api_key, get_quota, score_spend), making the set predictable and easy to navigate.
Three tools are well-scoped for a focused spend-scoring service: one for auth, one for quota, one for scoring. Each earns its place and the count matches the narrow domain.
The surface covers the core lifecycle: mint an API key, check remaining quota, and score a planned spend. Minor gaps exist (no key revocation/management or access to past scores), but these are workable for the primary use case.
Mint a free SpendGate API key. The secret is returned once. Store it and send it as Authorization: Bearer, or as api_key on later score_spend calls. Do not call this on every turn.
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | Optional label stored with the key, up to 80 characters. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does most of it: it discloses the one-time secret return ('The secret is returned once'), how to transmit it (Authorization: Bearer or api_key), and a usage-rate caution. It does not state whether a key never expires, whether repeated calls invalidate prior keys, or whether auth is required to mint.
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?
Four short sentences with no filler; purpose and the one-time-secret constraint are front-loaded, and each clause adds operational value (storage, header format, call-frequency warning).
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 must cover the return value and it does ('The secret is returned once'), which is the critical unknown for a key-minting tool. Minor gaps remain around key lifetime/expiry and what happens to previously issued keys, but nothing blocks correct invocation.
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% and the single optional `label` parameter is fully documented (80-character limit), so the baseline is 3. The description adds no meaning about the label parameter itself, and the parameter is optional, so nothing here is required to invoke the tool correctly.
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?
States a specific verb and resource ('Mint a ... SpendGate API key') and resolves the mismatch between the generic name get_api_key and the actual minting behavior. It also names score_spend as the downstream consumer, so an agent can place it among its siblings without opening a schema.
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?
Gives an explicit when-not ('Do not call this on every turn') and implies the consumption workflow via score_spend. It stops short of stating when it should be called (initial setup vs. re-mint after a lost key), so it is clear context without full when/when-not coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read how many free SpendGate scores remain today for this anonymous caller or API key. Does not consume a score and is not billed.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | Optional sg_live_ key. Omit to read the anonymous quota for this client. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description usefully discloses that calling this tool does not consume a score and is not billed, which is critical behavioral context for a quota-check endpoint. It does not cover error cases or rate-limit specifics, but covers the main non-obvious trait.
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 the core purpose and followed by the key behavioral guarantee. No filler 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?
For a simple one-parameter read tool, the description covers purpose, scope, and non-consumption behavior. It implies the return is a count, but does not describe error handling or response shape, which is a minor gap given no output schema exists.
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 api_key parameter is already fully documented. The description reinforces the anonymous-vs-key distinction but adds no syntax or format detail beyond the schema, making the baseline 3 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?
States a specific verb (Read) and resource (free SpendGate scores remaining today), and distinguishes from the score-consuming sibling by noting it does not consume a score. The anonymous caller or API key scope is also explicit.
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?
Usage is implied: check remaining quota without spending a score. The description does not explicitly say when to prefer it over siblings like score_spend or get_api_key, so it falls short of clear routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Score a planned payment before sending it. Call this before any tool that transfers crypto, buys a gift card, starts a subscription, or pays an API or merchant. Pass amount in USD, category, merchant or endpoint URL, and any budget remaining. Returns score 0-100, verdict approve | ask_human | block, reasons, and recommended_action.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Planned spend in USD, not in token atomic units. | |
| api_key | No | Optional SpendGate key (sg_live_…). Anonymous callers share a smaller daily cap. | |
| purpose | No | Short human description. Used as the category when category is omitted. | |
| agent_id | No | Your agent or key id. Echoed, not scored in v1. | |
| category | No | One of status_check, api_call, saas, infra, gift_card, crypto_transfer, irreversible. Unknown categories are scored as unknown risk. | |
| currency | No | Payment currency. Defaults to USDC. | |
| endpoint | No | Alias of merchant when the payee is an API URL. | |
| merchant | No | Merchant name or https endpoint URL that will receive the spend. | |
| risk_hints | No | Self-reported hints. Raising: new_payee, new_merchant, first_payment, high_velocity, mismatched_purpose, off_platform, shared_wallet. Lowering: trusted_repeat, within_policy, human_preapproved. known_merchant marks the payee known. | |
| daily_budget_remaining | No | USD still available today. Amount above this is blocked. | |
| monthly_budget_remaining | No | USD still available this month. Amount above this is blocked. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the return contract: a 0-100 score, verdict values approve | ask_human | block, reasons, and recommended_action, plus the hard-blocks above remaining budget. It stays silent on error/failure behavior, latency, and whether the scoring call itself has a cost, so it is strong but not exhaustive.
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, zero filler: the action, then the precondition that governs invocation, then the return contract. The most decision-relevant information (call before any payment tool) is 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?
There is no output schema, so the description compensates by naming the score range, verdict enum, reasons, and recommended_action. Combined with the fully documented input schema and the budget-blocking rule, an agent has everything needed to invoke and interpret this 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 description coverage is 100%, and the schema already documents each parameter in detail (categories, risk_hints directionality, budget semantics). The description only restates which fields to pass (amount, category, merchant/endpoint, budget), adding no meaning beyond the schema, so the baseline 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?
States a specific verb and resource ('score a planned payment') plus the timing constraint ('before sending it'), and the sibling tools (get_api_key, get_quota) are clearly different concerns. An agent can distinguish this as a pre-flight risk check without opening the schema.
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 lists the trigger conditions: any tool that transfers crypto, buys a gift card, starts a subscription, or pays an API or merchant. That is a strong when-to-use signal, but there is no when-not-to-use guidance (e.g. whether it is needed for tiny/status-check spends) and no advice on acting on a non-approve verdict.
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.
get_api_keyget_quotascore_spendAdvisory policy preflight for AI-agent spend requests; never executes payments or accesses wallets.
Pre-spend firewall for AI agents. Approves, blocks, flags transactions against policy rules.
Check if an ecommerce purchase meets buyer rules before payment. Returns PASS, FAIL, or REVIEW.
Deterministic allow/require_approval/deny verdicts for agent actions, before they happen.
Add one secure layer between your agents and this server.
