Zip-Codes.com Location Intelligence: Spatial Analysis, Districts & 14+ Years of Demographics

Buy credits

buy_credits

Buy a credit pack with a wallet that pays MPP (Machine Payments Protocol) challenges, such as Stripe Link. The credits go on the account or prepaid card of the API key you send. Without a key, the purchase makes a prepaid card: a new API key holding the credits, in the result's api_key; pass it as api_key on later calls, and keep it (it is shown again only while the card is unused, for 24 hours). Name the pack by pack, price_usd or credits (the packs: https://api.zip-codes.com/pricing.json). The first call answers Payment Required (-32042) with a challenge for that pack and charges nothing; a wallet that pays it sends the same call again with its credential and gets the purchase back: its purchase_id, the credits added and a receipt. The same payment sent again is never charged twice. A payment still clearing reads processing, with no credits yet: send the same call again later. Without a wallet, ask your human to buy at https://www.zip-codes.com/api/pricing. By paying you accept the Terms of Service: https://www.zip-codes.com/api/tos

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "buy_credits"
  }
}

Input Schema

Name	Required	Description
`pack`	No	The pack name from pricing.json, any case, for example Mini.
`api_key`	No	Your ZIP-Codes.com API key, only when you cannot send it as the X-Api-Key or Authorization: Bearer header (for example a key bought with buy_credits in this conversation). Leave it out to use the free tier. It is never shown back in a response.
`credits`	No	The pack's credits, for example 6250.
`price_usd`	No	The pack's price in US dollars, for example 5.

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 1, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well beyond the annotations: it discloses that the first call charges nothing, that the retried call with the credential is what actually charges, that resending the same payment never double-charges, that the api_key is only re-shown for 24 hours while the card is unused, and that paying implies ToS acceptance. The idempotency language is scoped to the same payment credential, so it does not conflict with idempotentHint=false.

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?

It is a dense single paragraph, but the purpose and the two-mode behaviour are front-loaded and nearly every clause carries operational information (challenge code, prepaid key lifetime, processing state). A little long, yet nothing is filler.

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?

There is no output schema, and the description compensates by naming the return payload (purchase_id, credits added, receipt, api_key) and the non-success states. For a payment tool with four optional parameters, an agent has everything needed to call it and interpret the response.

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 already 100%, so the baseline is 3, but the description adds the non-obvious relationship that a pack can be named by any one of pack, price_usd or credits, and that a key returned by this same tool can be passed back as api_key. Practical extra meaning beyond the schema's per-field text.

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?

States a specific verb and resource ('Buy a credit pack') and immediately distinguishes two outcomes: credits on the caller's account/prepaid card, or a newly minted API key when no key is supplied. This is unambiguous and cannot be confused with any sibling lookup tool.

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?

Gives an explicit decision path: with an MPP wallet, call this tool and expect a Payment Required (-32042) challenge first; without a wallet, direct the human to the pricing page. It also handles the in-between states (still-closing payment reads 'processing', resend later).

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

All Zip-Codes.com Location Intelligence: Spatial Analysis, Districts & 14+ Years of Demographics tools Inspect

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.