Skip to main content
Glama

Data Candy: US business leads

Buy leads

buy_leads
Destructive

Buy leads. THIS SPENDS MONEY AND CANNOT BE UNDONE. max_price_usd is required: nothing is bought if the price is higher. Paid from the account's credits (API key needed) it returns the leads at once: the first 25 inline and download links for the full set. Otherwise it returns a checkout link and an order id; a person pays on that page, then get_order returns the leads. Run quote_leads first.

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": {
      "quantity": "<quantity>",
      "max_price_usd": "<max_price_usd>"
    },
    "name": "buy_leads"
  }
}

Input Schema

NameRequiredDescriptionDefault
emailNoEmail for the receipt and for recovering the order.
freshNoSkip leads this account already received for the same search (default true when an API key is used).
filtersNoSearch filters, all optional. Combine as needed; more filters means fewer leads.
after_idNoContinue after this lead id (use next_after_id from an earlier order to get new leads).
quantityYesHow many leads (1 to 25,000). If fewer match, you get what matches.
max_price_usdYesREQUIRED spending cap in US dollars. Nothing is bought if the price is higher.
payment_methodNoauto (default): account credits when enough, else a Shared Payment Token if given, else a checkout link. checkout: always return a link for a person to pay.
idempotency_keyNoOptional. Send the same value when retrying after a timeout so you are never charged twice for one purchase.
shared_payment_tokenNoStripe Shared Payment Token (spt_...), only with payment_method "stripe_spt".

Output Schema

NameRequiredDescriptionDefault
kindNo
leadsYesAt most 25 leads, only when fulfilled. Use the download links for the full set.
notesNoPlain sentences from the API about this order, for example that the same search already has an unpaid order.
statusYesawaiting_payment, paid, fulfilled, expired, canceled, refunded or failed.
matchedNo
paid_atNo
currencyNo
downloadNo
livemodeNo
order_idYesThe order id. Keep it secret.
quantityNo
deliveredNo
next_stepYesWhat to do next, in plain words.
price_usdNo
created_atNo
expires_atNo
leads_shownYes
leads_totalYesHow many leads the order holds.
price_centsNo
checkout_urlNoOpen this page to pay (a person must do it).
next_after_idNo
payment_methodNo
leads_truncatedYesTrue when more leads exist than the 25 shown inline.
url_elicitationNoWhether the checkout link was also offered through URL-mode elicitation.
unit_price_centsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, but the description still earns credit by adding what the annotations cannot: the spend is financial and irreversible, the price cap is enforced server-side, and the API key unlocks credits-based instant delivery. It also documents the retry-safety mechanism via idempotency_key, which goes beyond the structured hints. The only minor gap is it does not restate rate limits or refund behavior.

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?

The critical warning about spending money is front-loaded in the first sentence and the prerequisite is saved for last, which matches the order an agent should read. Some sentences are run-on and slightly ungrammatical ("Paid from the account's credits (API key needed) it returns the leads at once"), costing a point, but nothing is wasted.

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?

For a 9-parameter, nested-object, destructive purchase tool, the description covers the money risk, the price cap, both payment paths, authentication requirements and retry safety. An output schema exists so return values need not be detailed, and the agent has everything needed to call this correctly or route to a sibling.

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 description coverage is 100%, so the baseline is 3; the description earns an extra point by explaining the semantics of the two required parameters as a pair — max_price_usd is a hard ceiling where nothing is bought if exceeded, and quantity yields fewer results if the match set is smaller. It does not explain the enum values of payment_method beyond what the schema says, which keeps it from a 5.

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 first two words state a specific verb and resource ("Buy leads"), and the body immediately scopes it against siblings by naming quote_leads as the prerequisite step and get_order as the follow-up for the checkout path. An agent can distinguish this from quote_leads, preview_leads and count_leads 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.

Usage Guidelines5/5

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

It gives an explicit ordering instruction ("Run quote_leads first") and explains the conditional routing to get_order when the checkout path is taken. It also tells the agent when the immediate-delivery path applies (account credits plus an API key), which is the key decision point before calling.

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