LeadMarina

Run an advanced search

run_advanced_search

Start an advanced search: many keywords across many US places — the whole US, whole states or single places — run in the background in batches, each business charged once (1 lead), stopping at lead_cap if set. Estimate first with estimate_advanced_search and confirm with the user: it spends leads. Follow it with get_advanced_search; read its leads with query_leads or send them with export_leads (campaign_id). Up to 25 running or paused at once, and 40 new ones (or 250,000 searches) a day.

Input Schema

Name	Required	Description
`name`	No	Optional name, up to 80 characters.
`places`	No	Single places by name ('Austin'), 'name, region' when a name is in several ('Springfield, Illinois'), or code (find_places). Up to 25,000 regions and places together; keywords × places may come to at most 50,000 searches.
`country`	No	'US' (the default), or a US territory's code ('PR', 'GU', 'VI', 'AS', 'MP') with a place from find_places.
`regions`	No	Whole US states, by name or code (find_places).
`keywords`	Yes	What to search for: up to 20 keywords or Google categories, each up to 100 characters. Each a string, or { keyword, exact } where exact keeps only businesses whose main Google category is that one.
`lead_cap`	No	Stop after this many unique, charged leads: a whole number from 100 to 1,000,000. Omit to search every place.
`everywhere`	No	Every place in the US (or in the territory sent as country).

Output Schema

Name	Required	Description
`id`	No
`name`	No
`leads`	No	Unique leads charged so far.
`places`	No	How many places it searches.
`status`	No	running \| paused \| completed \| stopped. Paused by itself when a Free account runs out of leads (they don't renew: upgrade, then resume).
`estimate`	No	{ expected_leads, low, high, minutes } as estimated when it started.
`keywords`	No	Each { keyword, exact }.
`lead_cap`	No
`next_step`	No
`resume_at`	No	When a waiting search carries on by itself.
`by_keyword`	No	Each { keyword, exact, category, searches, searches_done, leads }.
`created_at`	No
`leads_with`	No	How to read its leads: query_leads or export_leads with campaign_id.
`top_places`	No	Each { place, leads, basis }: basis "leads" — leads delivered there; or basis "businesses_checked" — leads null and businesses_checked the businesses checked there, when leads per place are not known.
`campaign_id`	Yes
`finished_at`	No
`running_now`	No	The newest batch running now: { keyword, places, status, verified, of } — places is the batch's place names.
`finish_reason`	No	all_searched \| lead_limit \| stopped once finished; null while it runs.
`searches_done`	No
`status_detail`	No	One sentence on where it is — e.g. waiting for the daily city budget, and until when, or why it was paused.
`searches_total`	No	Keywords × places.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 1, 2026

changedOutput schema / properties / running_now / description

Previous value: -"The newest batch running now: { keyword, places, status, verified, of }."New value: +"The newest batch running now: { keyword, places, status, verified, of } — places is the batch's place names."

AddedOct 25, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations only say it is a non-idempotent write with open-world scope; the description adds the material traits: it runs in the background in batches, each business is charged once (1 lead), spending stops at lead_cap, and it requires user confirmation before spending. It also discloses hard concurrency and daily quota limits (25 running/paused, 40 new or 250,000 searches a day), which is exactly the operational context an agent cannot get from the schema.

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?

Front-loads what the tool does, then cost/confirmation, then chaining, then rate limits — dense but ordered by decision importance. Every clause carries a fact (cost, cap, quota) rather than 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?

For a costly, non-idempotent, open-world mutation with an output schema already defined, the description covers everything an agent needs before invoking: cost model, confirmation requirement, prerequisite estimator, downstream retrieval tools, and throttling limits.

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

Parameters3/5

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

Schema description coverage is 100%, so all seven parameters including lead_cap ranges and the keywords × places cap are already documented. The description reinforces the geographic trichotomy (whole US / whole states / single places) and the lead_cap stop rule, but adds no value beyond what the structured schema already states — baseline 3.

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 ("Start an advanced search") and immediately scopes it as "many keywords across many US places — the whole US, whole states or single places," which separates it from single-query siblings like search_leads and from the non-mutating estimate_advanced_search.

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 pre-call workflow ("Estimate first with estimate_advanced_search and confirm with the user: it spends leads") and an explicit post-call path ("Follow it with get_advanced_search; read its leads with query_leads or send them with export_leads (campaign_id)"). It names the alternatives and the condition that selects each, leaving nothing to inference.

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

All LeadMarina 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.