Score a planned spend before an agent pays. Verdicts: approve, ask_human, or block.
Scored across 4 tools
Each tool targets a distinct action (mint key, read quota, score spend, store allowlist) and the descriptions explicitly cross-reference when to use one over another. The only mild friction is that get_api_key and get_quota share a 'get_' prefix despite one being a write/mint and the other a read, but the descriptions resolve this clearly.
All four tools use snake_case with a verb_noun structure: get_api_key, get_quota, score_spend, set_wallet_allowlist. The pattern is predictable and consistent throughout.
Four tools is well-scoped for a focused spend-scoring service: one for key provisioning, one for quota reads, one for the core scoring action, and one for allowlist management. No tool feels redundant or filler.
The core lifecycle (mint key, check quota, score spend, set wallet allowlist) is covered, and the descriptions even clarify behavior across tiers. A minor gap is the absence of a key revocation/rotation tool, which is a real key-management limitation, though not critical to the primary scoring workflow.
Mint one free sg_live_ key so later score_spend and get_quota calls use 1,000 scores per UTC day instead of the anonymous 100. Call once per agent when you will score often and have no stored key. Do not call every turn, do not mint again if you already stored the secret, and do not call just to read remaining scores (use get_quota). Returns the secret once as api_key, plus key_id, key_prefix, label, tier free, daily_limit, created_at, and note. Only a hash is stored, so the secret cannot be shown again. Keys do not expire and there is no revoke tool; a lost key stays valid, and an unknown or non-sg_live_ value later returns invalid_api_key. At most 20 mints per client per UTC day, then key_mint_limit and no new key. Minting is free and does not consume a score. Send the secret later as Authorization: Bearer or as api_key. label is an optional stored name and does not set a cap, a scope, or an expiry.
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | Optional name stored with the key, up to 80 characters. Does not set a cap or an expiry. Keys do not expire. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover safety hints (non-readonly, non-idempotent); the description supplies the substantive traits: secret returned once and only a hash stored, no expiry, no revoke path, a 20-mints-per-client-per-day cap yielding key_mint_limit, invalid_api_key for unknown values, and that minting is free. Far exceeds the annotation bar.
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?
Front-loaded with the action and its purpose, then rules, then return shape, then edge cases – a sensible ordering. It is long for a one-parameter tool and repeats 'keys do not expire' from the schema, costing a point on economy.
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?
Despite no output schema, the description enumerates the returned fields (api_key, key_id, key_prefix, label, tier, daily_limit, created_at, note) and covers auth transport, error codes, and the mint rate limit. Nothing needed to call or interpret the tool is missing.
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 coverage is 100% on the single optional label param, so baseline is 3. The description goes slightly beyond by clarifying what label is not – no cap, no scope, no expiry – which pre-empts a plausible misuse of label as a quota control.
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+resource ('Mint one free sg_live_ key') and immediately frames the effect on siblings score_spend and get_quota. An agent can distinguish this from get_quota (read remaining scores) and score_spend without opening any 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?
Explicit when-to-use ('Call once per agent when you will score often and have no stored key') and three explicit when-not-to conditions (not every turn, not if a secret is stored, not to read remaining scores – use get_quota). The alternative tool is named with the condition that selects it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read today's free-score balance. Prefer this over score_spend when you are not judging a specific payment, including before a batch or after a 402: it does not consume a score, returns no verdict, and is never billed. Do not use it to approve or block a spend. Pass api_key for that sg_live_ key (tier free, 1,000/UTC day); omit it for this client's anonymous bucket (tier anonymous, 100/UTC day). An unrecognized or non-sg_live_ key returns invalid_api_key and does not fall back. Returns subject (anonymous|api_key|bundle), key_id, key_prefix, tier (anonymous|free|bundle), daily_limit, used_today, remaining_today, paid_today, price_usd, price_atomic, asset (USDC), network, resets_at (next UTC midnight), and paid_configured. Mint a higher cap with get_api_key.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | Optional sg_live_ key to read. Omit for the anonymous bucket. Does not mint a key. An unrecognized key returns invalid_api_key. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover safety/idempotency; the description adds the behavior that matters here: it consumes no score, returns no verdict, is never billed, and that an unrecognized or non-sg_live_ key returns invalid_api_key with no fallback. It also discloses tier caps (1,000 vs 100 per UTC day) and the next-midnight reset semantics.
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?
Purpose and sibling comparison are front-loaded, then parameter rules, then return fields. The returns enumeration is long, but with no output schema it earns its place; the prose is dense rather than padded.
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 single-optional-parameter read with no output schema, the description covers tuning inputs, failure modes, rate-limit tiers, and the full return shape. Nothing an agent needs to invoke or interpret this correctly is missing.
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 coverage is 100%, so the baseline is 3, but the description goes further by tying api_key to the sg_live_ prefix, contrasting it with the anonymous bucket when omitted, and specifying the invalid_api_key failure mode. It adds real routing meaning beyond the schema's field description.
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 ('Read today's free-score balance') and immediately distinguishes itself from the sibling score_spend and from get_api_key (used to mint a higher cap). An agent can identify this as the non-billing, non-verdict quota read without opening any 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?
Explicit routing: prefer this over score_spend when not judging a specific payment, including before a batch or after a 402, plus a clear exclusion ('Do not use it to approve or block a spend'). Both the when and the when-not are stated with the alternative named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Score one planned payment before it is sent: a crypto transfer, gift card, subscription, or paid API or merchant. Do not use it for a pure read, or for a status_check under $1 you will not pay; that still burns a free score and approves unless a budget you pass is exceeded. Each call uses one free score (anonymous 100/UTC day, sg_live_ key 1,000 from get_api_key). Past that cap the call is HTTP 402 and costs 0.001 USDC on Base via x402. It does not pay the merchant. A domain, https URL, or 0x payee that is not on the local known-host list is checked with PayCheck. Trusted counts as a known merchant. Block means do not pay, including under the micro threshold. If PayCheck is unreachable, local merchant rules are used and the score still returns. While free quota remains, the same arguments consume another score. category overrides purpose. When category is omitted, purpose is matched as a category name; any other prose is unknown risk. merchant overrides endpoint when both are set. A set daily_budget_remaining or monthly_budget_remaining blocks when amount is greater; omitted budgets are skipped. Pass from_wallet, the 0x account that would sign or pay gas, whenever the spend leaves a wallet. Omit from_wallet and the verdict is unchanged. Pass allowed_wallets to allowlist this call, or omit it to use the list stored for the sg_live_ key by set_wallet_allowlist. An empty allowed_wallets array authorizes no wallet. Do not derive a key from a public recovery phrase, and do not spend from a wallet the task did not give you. A published Hardhat, Anvil, Ganache, BIP-39 test, or other public dev-mnemonic account is block with reason dev_wallet, including under $1, even if that address is allowlisted. A from_wallet that is not on the effective allowlist is block with reason unauthorized_wallet. A from_wallet with no allowlist on the call and none stored for the key is ask_human with reason wallet_unverified. Stop and ask a person. Do not broadcast. Returns score 0-100, verdict approve|ask_human|block, reasons, recommended_action, checked_at, payment_source (from_wallet, allowlisted, checked_at, reason, and signature only when the server already has BUNDLE_PROXY_SECRET), detail, and quota (daily_limit, used_today, remaining_today, paid_today, resets_at). approve means pay; ask_human means stop for a person; block means do not pay. Read the cap with get_quota instead of spending a score.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Planned spend in USD, not token atomic units. Required. | |
| api_key | No | Optional sg_live_ key. Uses the 1,000/day bucket. An unrecognized key returns invalid_api_key instead of falling back to anonymous. | |
| purpose | No | Short note, max 280 characters. When category is omitted, this text is matched as a category name; other prose is unknown risk. When category is set, this is echoed and not scored. | |
| agent_id | No | Agent or key id. Echoed, not scored in v1. | |
| category | No | Risk class. Wins over purpose. One of status_check, api_call, saas, infra, gift_card, crypto_transfer, irreversible. Any other string is unknown risk. | |
| currency | No | Payment currency. Defaults to USDC. | |
| endpoint | No | Payee used only when merchant is omitted. Ignored if merchant is also set. | |
| merchant | No | Payee name or https URL. Used instead of endpoint when both are set. A missing payee is penalized. | |
| 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. | |
| from_wallet | No | 0x account that would sign or pay gas. Omit to score as before, with no wallet verdict. A published Hardhat, Anvil, Ganache, or other public dev-mnemonic account is block, reason dev_wallet. | |
| allowed_wallets | No | 0x addresses allowed to spend on this call. When set, including an empty array, this list is used instead of the stored per-key allowlist. Omit to use the list from set_wallet_allowlist. | |
| daily_budget_remaining | No | USD left today. When set, a greater amount is blocked. Omit to skip this check. | |
| monthly_budget_remaining | No | USD left this month. When set, a greater amount is blocked. Omit to skip this check. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only generic annotations (readOnlyHint=false, idempotentHint=false), the description carries the real behavioral load and delivers: each call consumes one free score, anonymous 100/UTC-day vs sg_live_ 1,000/day, HTTP 402 past the cap with 0.001 USDC on Base via x402, and 'It does not pay the merchant.' It also discloses operational fallbacks (PayCheck unreachable -> local merchant rules), block reasons (dev_wallet, unauthorized_wallet), and the ask_human wallet_unverified path, none of which 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded correctly — purpose, exclusions, and quota cost come before the long tail of policy edge cases. However, it is roughly 400 words with real redundancy: the allowlist and dev-mnemonic rules are repeated from the schema descriptions, and quota/cost is restated in several places ('Each call uses one free score...', 'While free quota remains, the same arguments consume another score'). Tighter grouping would preserve the same information with fewer sentences.
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 13 parameters, no output schema, and only terse annotations, the description fills every gap an agent needs: the full return shape (score, verdict, reasons, recommended_action, payment_source, quota), the meaning of each verdict (approve/ask_human/block), and the quota fields. Nothing required to call it correctly or interpret the result is left to inference.
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 baseline is 3 and the schema already documents all 13 parameters including from_wallet, allowed_wallets, budgets, and the merchant/endpoint precedence. The prose largely restates those rules rather than adding new syntax or formats, so it neither compensates nor extends meaningfully beyond the structured fields.
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?
The first sentence gives a precise verb+resource+scope: 'Score one planned payment before it is sent: a crypto transfer, gift card, subscription, or paid API or merchant.' It explicitly excludes the adjacent read case ('Do not use it for a pure read...') and names the sibling that answers quota questions ('Read the cap with get_quota'), so an agent can place it against get_api_key, get_quota, and set_wallet_allowlist 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?
It states when to call (before sending a planned payment), when not to (pure reads, status_check under $1 you will not pay), and the alternative for the excluded need (get_quota). Precedence and override rules (category over purpose, merchant over endpoint, budgets blocking when set) are spelled out so the agent knows exactly which inputs change the verdict.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store the 0x wallets this sg_live_ key is allowed to spend from. Call it when an operator names those wallets, once, not on every spend, and not to approve a payment. score_spend still has to run before any transfer. A block or ask_human from score_spend means do not broadcast. Pass allowed_wallets. This replaces the stored list for that key in one write. An empty array stores an allowlist that authorizes no wallet, so a later score with from_wallet and no call-level list returns block, reason unauthorized_wallet. allowed_wallets is required. At most 32 addresses. A published developer test account (Hardhat/Anvil default accounts, Ganache, BIP-39 test, and other public test mnemonics) is rejected with dev_wallet and is not stored. Requires api_key, or Authorization: Bearer sg_live_. Anonymous and bundle callers cannot store a list; they can pass allowed_wallets on score_spend instead. An unrecognized key returns invalid_api_key. A missing key returns api_key_required. Does not consume a score and is never billed. Returns key_id, key_prefix, allowed_wallets, and updated_at. A new key starts with no list, which makes a later from_wallet ask_human with reason wallet_unverified until you set one. Do not put a private key or a recovery phrase in this tool. Addresses only.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | sg_live_ key this list belongs to. You can also send Authorization: Bearer. Required. Anonymous callers cannot store a list. | |
| allowed_wallets | Yes | 0x addresses this key may spend from. Replaces the stored list. An empty array authorizes none. Public developer test accounts are rejected and not stored. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations with replacement semantics ('replaces the stored list for that key in one write'), empty-array consequences ('stores an allowlist that authorizes no wallet' leading to reason unauthorized_wallet), dev-wallet rejection behavior, auth requirements, error codes, and billing ('does not consume a score and is never billed'). None of this is covered by readOnlyHint/idempotentHint/destructiveHint.
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?
Front-loaded with the core action and dense with operational detail, though a few sentences restate the schema ('allowed_wallets is required', 'an empty array stores...'). Long but nearly every sentence carries routing or safety value.
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?
Given no output schema, the description enumerates the return fields (key_id, key_prefix, allowed_wallets, updated_at), covers auth paths, error responses, edge cases like new keys starting unset, and warns against passing private keys. An agent has everything needed to invoke it correctly.
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 baseline is 3, but the description adds constraints the schema lacks: at most 32 addresses and the downstream block/unverified behavior for empty or unset lists. It repeats some schema content (empty array authorizes none), which keeps it from a 5.
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, resource, and scope: 'Store the 0x wallets this sg_live_ key is allowed to spend from.' It is immediately distinguishable from score_spend, get_api_key, and get_quota because it names the store-once semantics and explicitly says it is not for approving payments.
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 explicit when ('when an operator names those wallets, once, not on every spend'), when-not ('not to approve a payment'), the prerequisite ordering ('score_spend still has to run before any transfer'), and the alternative for anonymous/bundle callers ('pass allowed_wallets on score_spend instead').
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.
score_spend2 fields changedInput schema / properties / allowed_walletsAdded value: +{
+ "description": "0x addresses allowed to spend on this call. When set, including an empty array, this list is used instead of the stored per-key allowlist. Omit to use the list from set_wallet_allowlist.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / from_walletAdded value: +{
+ "description": "0x account that would sign or pay gas. Omit to score as before, with no wallet verdict. A published Hardhat, Anvil, Ganache, or other public dev-mnemonic account is block, reason dev_wallet.",
+ "type": "string"
+}set_wallet_allowlistget_api_key1 field changedInput schema / properties / label / descriptionPrevious value: -"Optional label stored with the key, up to 80 characters."New value: +"Optional name stored with the key, up to 80 characters. Does not set a cap or an expiry. Keys do not expire."get_quota1 field changedInput schema / properties / api_key / descriptionPrevious value: -"Optional sg_live_ key. Omit to read the anonymous quota for this client."New value: +"Optional sg_live_ key to read. Omit for the anonymous bucket. Does not mint a key. An unrecognized key returns invalid_api_key."score_spend9 fields changedInput schema / properties / agent_id / descriptionPrevious value: -"Your agent or key id. Echoed, not scored in v1."New value: +"Agent or key id. Echoed, not scored in v1."Input schema / properties / amount / descriptionPrevious value: -"Planned spend in USD, not in token atomic units."New value: +"Planned spend in USD, not token atomic units. Required."Input schema / properties / api_key / descriptionPrevious value: -"Optional SpendGate key (sg_live_…). Anonymous callers share a smaller daily cap."New value: +"Optional sg_live_ key. Uses the 1,000/day bucket. An unrecognized key returns invalid_api_key instead of falling back to anonymous."Input schema / properties / category / descriptionPrevious value: -"One of status_check, api_call, saas, infra, gift_card, crypto_transfer, irreversible. Unknown categories are scored as unknown risk."New value: +"Risk class. Wins over purpose. One of status_check, api_call, saas, infra, gift_card, crypto_transfer, irreversible. Any other string is unknown risk."Input schema / properties / daily_budget_remaining / descriptionPrevious value: -"USD still available today. Amount above this is blocked."New value: +"USD left today. When set, a greater amount is blocked. Omit to skip this check."Input schema / properties / endpoint / descriptionPrevious value: -"Alias of merchant when the payee is an API URL."New value: +"Payee used only when merchant is omitted. Ignored if merchant is also set."Input schema / properties / merchant / descriptionPrevious value: -"Merchant name or https endpoint URL that will receive the spend."New value: +"Payee name or https URL. Used instead of endpoint when both are set. A missing payee is penalized."Input schema / properties / monthly_budget_remaining / descriptionPrevious value: -"USD still available this month. Amount above this is blocked."New value: +"USD left this month. When set, a greater amount is blocked. Omit to skip this check."Input schema / properties / purpose / descriptionPrevious value: -"Short human description. Used as the category when category is omitted."New value: +"Short note, max 280 characters. When category is omitted, this text is matched as a category name; other prose is unknown risk. When category is set, this is echoed and not scored."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.
Score merchant domain, https URL, or 0x wallet trust before an agent pays. Does not send payments.
Allow, ask, or veto — a policy decision point your agent consults before signing any payment
Add one secure layer between your agents and this server.
