Code samples, a sample dataset, and a full workflow notebook for the Zillow Leads & Property Data Apify actor.
The actor pulls Zillow listings enriched with agent/broker contact info, full price-history timelines, 20yr+ tax history, foreclosure/distress flags, schools, and the resoFacts long tail (heating/cooling/construction). Pay-per-event pricing, no subscription: $0.70 per 1,000 bare rows, $1.20 per 1,000 enriched rows.
Actor: https://apify.com/germane_binoculars/zillow-leads-property-data
Architecture writeup: Predictable web scraping with web extensions — why this actor runs on a real browser session instead of a proxy farm, and what that buys you against Zillow's PerimeterX + AWS WAF.
The actor's catalog mode returns a cached, already-enriched snapshot
instantly, no bounding box, no wait:
{ "mode": "catalog", "metro": "Chicago" }Run it from the Apify Console
or via apify-client (see examples/ below).
Related MCP server: Zillow MCP Server
Path | What it is |
| 20 real enriched rows (Chicago/Houston/Phoenix) — flat, spreadsheet-ready |
| Same rows, one JSON object per line, with a nested |
| Call the actor from Python via |
| Same, in Node, via |
| One-tool MCP server for Claude Desktop, Cursor and any MCP client; see |
| A realistic lead-gen workflow: run the actor, dedupe against a prior export, filter to rows with agent phone numbers, export a clean CSV |
Two depths, listings (bare) and enriched (the default):
listings: address, price, beds/baths, status, lot/living area, listing-type flags — whatever Zillow's own search API returns, no detail-page fetch involved. See sample_listings.csv for the shape (a subset of the columns shown there — the sample above is enriched-depth, listings-depth rows omit everything past the bare fields).
enriched (default): everything in listings, plus agent/broker contact (name, phone, email, brokerage, MLS attribution), full price-history and 20yr+ tax-history timelines, foreclosure/distress signals, assigned + nearby schools, HOA fees, and the resoFacts long tail (heating/cooling/parking/construction).
Full field list, pricing table, and every input mode (catalog / custom_search / recent_activity) are documented on the actor's own README.
Every delivery writes a DEDUP_UPDATE record to the run's key-value store:
the union of the zpids and MLS IDs you already had plus everything just shipped.
Feed those two arrays back into your next order's dedupZpids/dedupMlsIds
fields and you're never charged for the same row twice. See
notebook/zillow_leads_workflow.ipynb for a worked example.
This actor is callable as a tool via Apify's hosted MCP server
(https://mcp.apify.com) or the local @apify/actors-mcp-server, no manual
input-form filling required — catalog mode (the default) is a good agent
smoke test since it returns cached rows in seconds with no polling loop
needed. See the actor's own README for the full agent-facing input schema
and the fire/poll/fetch pattern for a live-collection order.
This repo is documentation and samples only — it doesn't run the actor
itself. For a specific order that isn't behaving as expected, check that
run's key-value store STATUS record first (the actor writes a plain-English
reason there for any zero-row or partial result), then open an issue here or
reach out via the actor's Apify Store page.
Abort an Actor run that is currently starting or running. Results include the updated run details.
| Name | Required | Description | Default |
|---|---|---|---|
| runId | Yes | The ID of the Actor run to abort. | |
| gracefully | No | If true, aborts gracefully with a 30-second timeout. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the run must be active and that results include updated run details, but it does not disclose whether aborts are irreversible, whether permissions are required, or what happens to intermediate results. This is a significant gap for a state-changing operation.
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?
A single, tight sentence that front-loads the action and ends with the return type. No filler or unnecessary elaboration.
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 two-parameter tool with no output schema, the description supplies the essential information: the action, the applicable run state, and the response content. It lacks error-handling context (e.g., what if the run is already finished), but this is a minor gap for a straightforward abort action.
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 schema fully documents both parameters. The description adds no new parameter-level detail; the phrase 'currently starting or running' reinforces runId semantics but is already implied by the schema.
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 description states a specific verb ('Abort') and resource ('Actor run'), and qualifies the target state ('currently starting or running'). This clearly distinguishes it from sibling tools like get-actor-run, which reads run details rather than mutating them.
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?
The phrase 'currently starting or running' provides a clear contextual condition for when this tool is appropriate. However, it does not explicitly name alternatives or state when not to use it, such as checking run status with get-actor-run first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calls the Actor "germane_binoculars/zillow-leads-property-data" and retrieves its output results: Zillow listings enriched with agent/broker contact info, price/tax history, foreclosure flags, and schools. Catalog mode is an instant paid sample that usually returns rows in a single call. Every other mode dispatches a live-collection order measured in minutes to hours; such calls return a runId plus status immediately — poll via get-actor-run, then fetch rows with get-dataset-items. If a previous call was lost to a client timeout, DO NOT re-submit (you would pay twice): recover the existing runId with get-actor-run-list.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Pick ONE mode; only that mode's fields apply. Catalog: instant snapshot from the pre-seeded catalog pool, returns in seconds, always fully enriched; metro (below) optionally scopes it to one metro, otherwise the whole pool counts. Custom search: your own lat/lng bounding box or a named metro, live-collected, the only mode with a cheaper 'listings' depth option. Recent activity: Zillow's sitemap feed of newest/changed listings nationwide, no bounds, always fully enriched. | catalog |
| depth | No | Only read when mode = custom_search; ignored (always enriched) for catalog and recent_activity. 'listings': bare address/price/beds/baths/status, cheaper, faster (see README 'Bare listing schema'). 'enriched': full agent contact, price/tax history, foreclosure, schools, resoFacts (see README 'Enriched schema'), costs more per row. | enriched |
| metro | No | Pick a named metro instead of typing lat/lng bounds by hand. Covers the metro's whole urbanized area, not just city limits, so results genuinely include real suburbs along with the named city (e.g. Phoenix also returns Scottsdale/Tempe/Glendale); see the README. For custom_search: required if bounds is not set; bounds always wins when both are present. For catalog: optional, scopes the instant snapshot to this metro instead of the whole cached pool; leave unset to use everything cached. For recent_activity: ignored. | Phoenix |
| bounds | No | custom_search only (ignored for catalog/recent_activity). A lat/lng box, for a precise custom area metro doesn't cover. North/south are latitude, east/west are longitude, and north/east must each be numerically LARGER than south/west respectively (it's a box, not two arbitrary points; a swapped box is rejected). Takes priority over metro if both are set. Leave empty to use metro instead. | |
| source | No | Which Zillow sitemap feed to pull recent activity from. Always fully enriched (no bare/listings option exists for this mode; the sitemap feed itself carries nothing beyond a listing URL, so there's no cheaper variant to offer). | agent |
| waitSecs | No | Max seconds (0-45) to block on this single call waiting for terminal run status. Unset: catalog smoke tests block up to 30s and often return rows in one call; every other mode is fire-and-forget (returns runId immediately) because collection takes minutes. Poll with get-actor-run, then fetch rows with get-dataset-items. | |
| dedupZpids | No | Optional. zpids you've already received from a prior run, e.g. [43814015, 43828670]; never re-shipped. | |
| dedupMlsIds | No | Optional. MLS IDs you've already received from a prior run, e.g. ["A12046823"]; covers re-listings, which get a new zpid but keep the same MLS ID, so zpid-only dedup would miss them. | |
| minEnriched | No | Optional, defaults to 500 (the recommended floor). Only meaningful when rows are actually being enriched: custom_search + depth=enriched, catalog, or recent_activity. Ignored (forced to 0 internally) for custom_search + depth=listings, since a listings-depth order never enriches anything by design. Must be <= whatever minListings you set; asking for more enriched rows than total rows is a nonsensical order and won't be satisfiable. | |
| minListings | No | Optional, defaults to 1000 (the recommended floor). The floor for how many rows (bare or enriched, whichever depth you asked for) this run must return before considering itself done. Applies to every mode. Set lower (e.g. 10-50) only for a quick test run before committing to a full one. | |
| timeoutSecs | No | Optional, defaults to 7200 (2 hours), minimum 300 (5 minutes). Max wait for the minimums to be satisfied before returning a partial dataset. A cache-satisfiable order (catalog, or already-covered ground) finishes in seconds regardless; this only matters when live collection is needed. The 5-min floor exists because live collection needs that long for PX-safe warmup pacing. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the full behavioral burden, and it does so thoroughly: it discloses paid catalog behavior, minute-to-hour live collection, immediate runId;+status return, polling requirements, and the financial risk of duplicate submission. This goes well beyond the input schema and explains the tool's real runtime behavior.
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?
The description is dense but every sentence earns its place, front-loading the core action (actor call plus output) before covering mode timing, polling workflow, and the duplicate-payment warning. It manages to capture a complex tool's essential behavior without padding 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 an 11-parameter, multi-mode tool with no output schema and no annotations, the definition is remarkably complete when combined with the schema: it explains mode selection, timing expectations, minimums, dedup, bounds, and post-run follow-up. There is no obvious critical context an agent would need to invoke this tool correctly that is left unaddressed.
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 schema itself already documents every parameter and mode interaction; the scoring baseline is therefore 3. The description does add high-level context around modes and run lifecycle, but it does not meaningfully enrich individual parameter semantics beyond the schema.
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 description opens with a specific verb plus resource: it calls the Actor "germane_binoculars/zillow-leads-property-data" and retrieves its output results. It names concrete data content (Zillow listings, agent/broker contacts, price/tax history, foreclosure flags, schools), which makes the tool's purpose unmistakable and distinct from the sibling retrieval tools.
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?
The description gives explicit mode-based usage guidance: catalog is instant, other modes launch live collection, and follow-up should use get-actor-run and get-dataset-items. It also includes a strong exclusion/alternative rule: do not resubmit after a client timeout; recover the runId with get-actor-run-list instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific Actor run: status, storages (datasets/key-value stores alias map), stats, summary, nextStep.
| Name | Required | Description | Default |
|---|---|---|---|
| runId | Yes | The ID of the Actor run. | |
| waitSecs | No | Max seconds to wait for terminal status (SUCCEEDED, FAILED, ABORTED, TIMED-OUT). 0 returns immediately. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool returns information but does not disclose potential side effects (none obvious for a get), authentication requirements, or rate limits. The waitSecs parameter hints at polling behavior but is not explained beyond the schema. Description is neutral and does not contradict any annotations since none exist.
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?
The description is a single, tightly packed sentence that front-loads the purpose and lists the returned fields. No fluff or repetition; every element adds information. Ideal conciseness for an agent to parse quickly.
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?
No output schema is provided, so the description carries the burden of indicating what the tool returns. It enumerates key fields (status, storages, stats, summary, nextStep), which is sufficient for most agents. It does not mention edge cases (e.g., what happens if the run does not exist) or error behaviors, but given the simplicity of the operation nominal completeness is high. Sibling tools exist but are not referenced, which slightly lowers the score.
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?
The input schema already provides clear descriptions for both runId (required) and waitSecs (max wait time). The tool description does not add any additional semantic meaning beyond what the schema covers, so it meets the baseline but provides no extra clarity on how parameters affect the call.
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 description clearly states the tool retrieves detailed information about a specific Actor runasi and enumerates the data returned (status, storages, stats, summary, nextStep). This distinguishes it from sibling tools like get-dataset-items and get-key-value-store-record, which fetch specific storage data rather than the run itself. The verb 'Get' and resource 'Actor run' make the purpose unambiguous.
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?
The description implies usage when you need run-level metadata but does not explicitly contrast with alternatives. It does not state when to use this instead of get-dataset-items or abort-actor-run, and it lacks exclusionary guidance (e.g., 'use get-dataset-items to fetch raw data'). Adequate but not proactive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Actor runs for the authenticated user, newest first with desc=true — the recovery entry point when a previous actor-tool call was lost to a client timeout. Account-wide (there is no per-actor filter): match entries on their actId if the account runs other actors too. Each entry's id field is the runId the companion tools take, and entries also carry defaultDatasetId and defaultKeyValueStoreId.
| Name | Required | Description | Default |
|---|---|---|---|
| desc | No | If true, runs are sorted by startedAt descending (newest first). | |
| limit | No | Maximum number of array elements to return. The default value (as well as the maximum) is 10. | |
| offset | No | Number of array elements that should be skipped at the start. The default value is 0. | |
| status | No | Return only runs with the provided status. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It adds useful behavioral details: sorting behavior when desc=true, account-wide scope (no per-actor filter), the actId field for matching, and that entries contain defaultDatasetId and defaultKeyValueStoreId. It could mention pagination behavior, but the schema covers limit/offset.
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 dense, purposeful sentences: the first states the primary function and the use case, the second removes a potential ambiguity (account-wide, no per-actor filter), and the third connects the results to the companion tools. 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?
Even without annotations and an output schema, the description explains the main behavior, scope, sort order, and what the returned entries contain (runId, dataset/KVS ids). It is sufficient for an agent to select and call the tool; the schema fills the remaining parameter details.
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 schema already documents all four parameters. The description adds context around desc=true and the run-related fields, but it does not deepen parameter meaning beyond what is in the schema; thus a baseline of 3 is 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?
The description uses a specific verb and resource ('List Actor runs for the authenticated user') and clarifies the key ordering behavior ('newest first with desc=true'). It clearly differentiates this list tool from the sibling get-actor-run and get-actor-run-log by framing it as the account-wide entry point to obtain runId values.
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?
Strong usage context: it declares this is the recovery entry point after a client timeout and explicitly states there is no per-actor filter; it tells the agent to subsequently use the id field as runId for companion tools. It does not name the alternative tools explicitly, but the intended routing is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve recent log lines for a specific Actor run — live collection progress, or the tail of a FAILED run.
| Name | Required | Description | Default |
|---|---|---|---|
| lines | No | Output the last NUM lines, instead of the last 10. Pass 0 to return the entire log. | |
| runId | Yes | The ID of the Actor run. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full behavioral burden. It states what the tool retrieves and hints at the type of run states (live vs failed), but it does not disclose behavior like whether logs are truncated, how pagination works, or any side effects. It is functional but minimal.
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?
The description is a single, front-loaded sentence that conveys the core function and the key usage context. Every part adds value, and there is no repetition of schema details.
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 two-parameter read tool with complete schema coverage, the description provides enough context to choose and invoke it correctly. A bit more detail about the return format or when to prefer sibling tools would be helpful, but this is adequate.
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 both parameters are already documented. The description adds no additional meaning to the parameters; it merely frames the tool's purpose.
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 description names a specific verb ('Retrieve'), a specific resource ('recent log lines for a specific Actor run'), and clarifies its intended use for live progress or debugging failed runs. This clearly distinguishes it from siblings like get-actor-run.
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?
The description communicates when the tool is useful: to inspect live collection progress or diagnose a failed run. It does not explicitly exclude alternatives or name a sibling to use instead, but the context is clear enough for an agent to match its intent to this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get items (rows) from a dataset — the output/results produced by an Actor run. When the actor tool returns RUNNING, this fetches rows once terminal.
| Name | Required | Description | Default |
|---|---|---|---|
| desc | No | If true, results are returned newest first. | |
| omit | No | Comma-separated list of fields to exclude. | |
| clean | No | If true, returns only non-empty items and skips hidden fields. | |
| limit | No | Maximum number of items to return. | |
| fields | No | Comma-separated list of fields to include (dot notation supported). | |
| offset | No | Number of items to skip at the start. | |
| flatten | No | Comma-separated list of fields to flatten. | |
| datasetId | Yes | Dataset ID or username~dataset-name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden. It does reveal a key behavioral trait (waits for terminal Actor run state before fetching), which is useful, but it omits other behavioral aspects like error handling, pagination nuances, or response format. It provides moderate transparency but lacks depth.
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?
The description is a single, efficient sentence that front-loads the core purpose and includes a relevant timing constraint. Every word contributes meaning with no 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?
Given the complexity (8 parameters, no output schema, no annotations), the description is too sparse. It fails to explain the return structure, default behavior, or limitations (e.g., handling large datasets). The minimal context leaves significant gaps for an agent to call the tool correctly in edge cases.
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 all 8 parameters are already documented in the schema. The tool description adds no additional parameter semantics beyond what the schema provides, aligning with the baseline of 3 for high coverage.
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 description clearly states the verb 'Get' and the resource 'items (rows) from a dataset', and explicitly ties it to the output of an Actor run. This distinguishes it from siblings like get-actor-run (run status) and get-key-value-store-record (KVS records) without ambiguity.
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?
The description provides clear context on when to use the tool: after an Actor run reaches terminal state ('once terminal'). However, it does not explicitly mention alternative tools or state when not to use it, stopping short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List datasets on the account — locates a run's output dataset when its ID was lost. Actor runs produce unnamed datasets, so set unnamed=true.
| Name | Required | Description | Default |
|---|---|---|---|
| desc | No | If true, datasets are sorted by createdAt descending (newest first). | |
| limit | No | Maximum number of array elements to return. Default is 10. Maximum is 20. | |
| offset | No | Number of array elements that should be skipped at the start. Default is 0. | |
| unnamed | No | If true, all datasets are returned. Default is false (named datasets only) — actor runs produce unnamed datasets, so pass true here. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries main responsibility. It discloses the important behavior that unnamed datasets are excluded by default and that actor-run outputs are unnamed, but it does not describe the response format, pagination behavior, or potential errors. This is partial transparency.
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 with no wasted words. The first states the action and the use case, and the second provides a critical usage hint. Every part earns its place.
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?
The four parameters are fully documented in the schema, and the description covers the main use case and a key filtering nuance. The lack of an output schema is not critical for a basic list operation, though a brief note on return value shape would make it complete.
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. The description restates the unnamed flag's purpose but does not add meaning beyond the schema, except contextual rationale for why the flag is needed.
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 action 'List datasets on the account' with a concrete use case: locating a run's output dataset when its ID was lost. This clearly distinguishes it from siblings like get-dataset-items, which targets items within a dataset.
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?
Provides clear context: use this when you need to find a run's output dataset, and explicitly signals that unnamed=true is required for that purpose. It does not mention alternative tools to avoid, so it misses the full 'when-not-to-use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the keys in a key-value store with pagination — for this actor's runs, look for ORDER_SUMMARY, DEDUP_UPDATE and STATUS.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of keys to be returned. Maximum is 10. | |
| keyValueStoreId | Yes | Key-value store ID or username~store-name. | |
| exclusiveStartKey | No | All keys up to this one (including) are skipped from the result. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Because no annotations are provided, the description carries the burden of behavior disclosure. It does communicate that this is a paginated read operation, which is helpful, but it does not describe what the returned representation looks like or how pagination continuation is surfaced beyond the exclusiveStartKey schema.
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?
The description is a single, well-structured sentence that front-loads the main operation, includes the pagination qualifier, and then gives a concrete domain hint with expected keys. Nothing is redundant or wasted.
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 list-keys operation, the description plus a fully-covered schema is largely complete: it names the resource, the operation, pagination, and even relevant expected keys. It would be stronger with a note on whether the response includes just keys or also pagination metadata, but that is a minor gap for 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?
The input schema already covers all parameters with full descriptions (100% coverage), including the requirement for keyValueStoreId and the meaning of exclusiveStartKey. The description adds no additional parameter-specific semantics, so the baseline of 3 is 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?
The description names a specific verb and resource: listing keys in a key-value store, and adds the pagination behavior. It is clearly distinct from siblings like get-key-value-store-record and get-key-value-store-list, which return a record's value or list stores rather than keys.
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?
The description provides concrete usage context: keys expected in this actor's runs are ORDER_SUMMARY, DEDUP_UPDATE, and STATUS. It does not explicitly name alternative tools or when not to use it, but for a simple list operation the intended use case is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List key-value stores on the account — locates a run's store (ORDER_SUMMARY / DEDUP_UPDATE / STATUS records) when its ID was lost. Set unnamed=true to include run-produced stores.
| Name | Required | Description | Default |
|---|---|---|---|
| desc | No | If true, stores are sorted by createdAt descending (newest first). | |
| limit | No | Maximum number of array elements to return. Default is 10. Maximum is 10. | |
| offset | No | Number of array elements that should be skipped at the start. Default is 0. | |
| unnamed | No | If true, all stores are returned. Default is false (named key-value stores only). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It makes the listing nature and the relevant special case ('unnamed=true to include run-produced stores') clear, which is useful. However, it does not disclose output shape, pagination behavior, or any access prerequisites, so it is only moderately transparent.
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?
The description is two succinct sentences with no wasted words. The main action and scope comes first, and the important behavioral note about unnamed stores is in the second sentence. Every sentence contributes to understanding the tool's purpose.
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 four-parameter listing tool with no output schema, the description covers the motivating use case and relevant filtering behavior. The only real gap is that it does not describe the shape of the returned list, but the schema and straightforward list semantics make this a minor limitation.
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?
The schema already documents all four parameters with 100% coverage, so the baseline is 3. The description adds semantic value by explaining that unnamed=true includes 'run-produced stores' and connecting the list operation to locating a store after ID loss, which clarifies why and when that parameter matters.
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 description identifies a clear verb ('List') and a specific resource ('key-value stores on the account'), and distinguishes this tool from sibling record/key operations by framing it as the way to to locate a store when its ID was lost. The mention of ORDER_SUMMARY / DEDUP_UPDATE / STATUS records gives concrete context that is not available from the tool name alone.
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?
The description gives a clear use case: use this tool when you need to find a run's key-value store after losing its ID. It also explains when to set unnamed=true. It does not explicitly state when to prefer get-key-value-store-record or get-key-value-store-keys, so it lacks explicit sibling exclusions, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single record from a run's key-value store: ORDER_SUMMARY (what actually applied), DEDUP_UPDATE (re-upload on your next order), STATUS (zero-row explanation).
| Name | Required | Description | Default |
|---|---|---|---|
| recordKey | Yes | Key of the record to retrieve. | |
| keyValueStoreId | Yes | Key-value store ID or username~store-name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that exactly one record is retrieved (a 'single' record) and enriches understanding of the built-in keys, which is beyond the schema. However, it omits details like idempotency, error behavior, or whether it is read-only—though 'Get' implies safety. The added key semantics justify an above-baseline score.
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?
A single sentence that front-loads the main action and resource, then uses a colon to introduce a compact parenthetical list of the most important key-value store records. Every word earns its place; no fluff.
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 two-parameter GET-like tool with no output schema and no nested objects, the description adequately covers the core purpose and the special records. It could mention the return format or error handling, but given the simplicity of the operation, the current coverage is sufficient.
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 schema already documents both parameters. The description adds value by enumerating the special values for 'recordKey' (ORDER_SUMMARY, DEDUP_UPDATE, STATUS) and what they map to, which goes beyond the schema's generic 'Key of the record' – hence above the baseline of 3.
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 description states a specific verb ('Get') and resource ('a single record from a run's key-value store'), clearly distinguishing it from sibling tools like 'get-actor-run' (run metadata) and 'get-dataset-items' (dataset items). No ambiguity about what it operates on.
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?
The description names three special keys (ORDER_SUMMARY, DEDUP_UPDATE, STATUS) and explains their meaning, giving clear context for when to use this tool. However, it does not explicitly contrast with alternatives or state when not to use it, so it stops short of a 5.
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.
v1.0.9germane_binoculars--zillow-leads-property-data1 field changedInput schema / properties / waitSecs / descriptionPrevious value: -"Max seconds (0-45, default 30) to block on this single call waiting for terminal run status. Long-running orders return a status plus nextStep instead."New value: +"Max seconds (0-45) to block on this single call waiting for terminal run status. Unset: catalog smoke tests block up to 30s and often return rows in one call; every other mode is fire-and-forget (returns runId immediately) because collection takes minutes. Poll with get-actor-run, then fetch rows with get-dataset-items."get-actor-run-listget-actor-run-logget-dataset-listget-key-value-store-keysget-key-value-store-listv1.0.7abort-actor-runget-actor-runget-dataset-itemsget-key-value-store-recordv1.0.5germane_binoculars--zillow-leads-property-data5 fields changedInput schema / properties / bounds / additionalPropertiesAdded value: +falseInput schema / properties / bounds / propertiesAdded value: +{
+ "east": {
+ "description": "Right edge longitude; must be numerically larger than west.",
+ "title": "East",
+ "type": "number"
+ },
+ "north": {
+ "description": "Top edge latitude; must be numerically larger than south.",
+ "title": "North",
+ "type": "number"
+ },
+ "south": {
+ "description": "Bottom edge latitude.",
+ "title": "South",
+ "type": "number"
+ },
+ "west": {
+ "description": "Left edge longitude.",
+ "title": "West",
+ "type": "number"
+ }
+}Input schema / properties / bounds / requiredAdded value: +[
+ "north",
+ "east",
+ "south",
+ "west"
+]Input schema / properties / dedupMlsIds / items / titleRemoved value: -"MLS ID"Input schema / properties / dedupZpids / items / titleRemoved value: -"zpid"v1.0.4germane_binoculars--zillow-leads-property-data2 fields changedInput schema / properties / dedupMlsIds / itemsAdded value: +{
+ "title": "MLS ID",
+ "type": "string"
+}Input schema / properties / dedupZpids / itemsAdded value: +{
+ "title": "zpid",
+ "type": "integer"
+}v0.1.2germane_binoculars--zillow-leads-property-dataScored across 10 tools
Each tool targets a distinct resource or action: actor invocation, run management, dataset reads, and key-value store reads are well separated. A few pairs like get-actor-run vs get-actor-run-list could be confused by name alone, but the descriptions clarify their roles.
Most tools consistently follow a get-<resource>-<detail> pattern, with abort-actor-run as a clear exception. The main inconsistency is the actor invocation tool, which uses the actor identifier instead of a descriptive action verb, making the set slightly uneven.
Ten tools is well-scoped for this server: one to start/collect data, a few to monitor runs, and several to retrieve or recover outputs and storage. Each tool has a clear role without redundancy or bloat.
The toolset covers the full lifecycle of the Zillow leads collection workflow: launching, launching/collecting, polling, aborting, reading logs, fetching dataset rows, and recovering lost run/store/dataset IDs. The recovery and monitoring utilities prevent common dead ends and paid re-execution mistakes.
Zillow real estate listings for sale, rent, and sold, via an Apify Actor, hosted MCP.
Zillow for-sale, for-rent and sold listings, and full property details, as structured JSON.
Zillow homes and agent contacts for AI agents — search by ZIP, by URL, or look up a zpid.
Redfin for-sale, for-rent and sold listings plus full property pages, as structured JSON.
