A successful tool call can hand your retriever a document explaining that the property lookup failed. Your agent gets a citation. You get the small dread of discovering what it cited.
The catch: invalid URLs produce records with inputUrl, error, and scrapedAt, while the rest of the run can continue. A completed run does not make every dataset record usable property evidence.
Lab note 126: can we give an agent useful partial results without letting a failed lookup become a housing fact or an invitation to retry forever?
Split records before they become documents
The dangerous shortcut is fetching a dataset, serializing every row, and sending the lot to an embedding pipeline.
An error record is structured. It has a timestamp. It may mention the address or URL your user asked about. That makes it an embarrassingly plausible retrieval candidate.
We'd put this boundary before text generation, chunking, or embeddings:
def partition_records(records):
listings = []
failed_inputs = []
unclassified_count = 0
for record in records:
if "error" in record:
failed_inputs.append({
key: record[key]
for key in ("inputUrl", "error", "scrapedAt")
if key in record
})
elif record.get("url"):
listings.append(record)
else:
unclassified_count += 1
return {
"listings": listings,
"failed_inputs": failed_inputs,
"unclassified_count": unclassified_count,
}
Presence of error wins, even if another field looks useful. A record without a citation URL also stays out of the evidence collection.
That last check doesn't prove a listing is accurate or complete. It establishes a narrower contract: the adapter has a source URL and hasn't received an explicit error for that record.
The returned envelope is our application structure, separate from the Actor's records.
Give the agent a decision it can actually make
Your agent's job is to inspect approved property sources and answer from the available listing evidence. It also needs to explain which requested lookups failed.
Those are different responsibilities, so give them different paths:
Actor dataset
|
+-- error present ------> failure handling --> correction or stop
|
+-- citation URL -------> property evidence --> retrieval --> answer
|
+-- neither ------------> hold for inspection
Keep failures available to the agent as operational information. Keep them outside the property index.
A failed lookup means the lookup failed. It doesn't establish that a property is unavailable, that its asking price disappeared, or that no comparable sale exists. Those are housing claims, and the error record supports none of them.
Connect MCP without handing over every knob
This configuration connects your application to the upstream Actor tool. The server process inherits APIFY_TOKEN from its environment.
{
"mcpServers": {
"property_upstream": {
"command": "npx",
"args": [
"-y",
"@apify/actors-mcp-server",
"--actors",
"vexaloom-labs/trulia-listings-and-price-history-scraper"
]
}
}
}
The configuration exposes the Actor; it does not enforce application policy.
In your agent host, expose a narrow lookup_properties(urls) wrapper and keep the upstream tool out of the model-visible tool list. Otherwise, instructions saying “please keep the cap small” are doing the work of access control. They have other hobbies.
The wrapper must build the Actor input itself. Passing the agent's arbitrary input object through unchanged defeats the boundary.
Pin scope, expose approved sources
For this task, we'd use the following division:
| Control | Owner | Reason |
|---|---|---|
urls |
Agent selects from application-approved inputs | Lets the agent choose relevant sources without inventing destinations |
mode |
Application | Keeps this tool focused on URL lookup |
maxItems |
Application | Sets the total listing cap across all URLs |
fetchDetails |
Application | Matches enrichment to the question |
Search filters and proxyConfiguration
|
Application | Keeps unrelated controls outside this tool's contract |
Both search and URL modes can be used in the same run. For a property lookup tool, that flexibility is a reason to construct a narrow request deliberately.
Here's a handler core using the SDK, which also makes the boundary inspectable outside an MCP host. Example approved input and pinned settings:
import os
from apify_client import ApifyClient
client = ApifyClient(os.environ["APIFY_TOKEN"])
approved_urls = frozenset({
"https://www.trulia.com/home/"
"1801-w-saint-johns-st-austin-tx-78757-464681422"
})
def lookup_properties(urls):
if not urls or any(url not in approved_urls for url in urls):
raise ValueError("Select URLs approved for this request.")
run_input = {
"mode": "urls",
"urls": list(dict.fromkeys(urls)),
"maxItems": 20,
"fetchDetails": False,
}
run = client.actor(
"vexaloom-labs/trulia-listings-and-price-history-scraper"
).call(run_input=run_input)
if run["status"] != "SUCCEEDED":
raise RuntimeError(f"Property lookup ended: {run['status']}")
records = client.dataset(
run["defaultDatasetId"]
).iterate_items()
return partition_records(records)
lookup_result = lookup_properties(sorted(approved_urls))
The status check handles run failure. The partition handles record failure. Neither replaces the other.
With detail fetching disabled, this tool shouldn't promise a price-history investigation. If the user's question requires history, the application should select an appropriate tool policy before calling it.
Budget the evidence without cutting records in half
Full listing records aren't automatically good context. Photos, contact details, and long descriptions can consume space without helping a price-and-status question.
We'd select a small evidence projection, preserve citation and collection time, and omit whole records when the budget fills. Cutting serialized text mid-record risks separating a price from its address or source.
This builds bounded JSON text with separate diagnostic and evidence collections:
import json
def shape_context(envelope, char_budget=6000):
context = {
"listings": [],
"failed_inputs": [],
"omitted_listings": len(envelope["listings"]),
"omitted_failures": len(envelope["failed_inputs"]),
"unclassified_count": envelope["unclassified_count"],
}
def serialize():
return json.dumps(context, ensure_ascii=False, separators=(",", ":"))
if len(serialize()) > char_budget:
raise ValueError("Budget cannot hold the context envelope.")
def add_if_fits(bucket, omitted_key, item):
context[bucket].append(item)
context[omitted_key] -= 1
if len(serialize()) > char_budget:
context[bucket].pop()
context[omitted_key] += 1
for failure in envelope["failed_inputs"]:
diagnostic = {
key: failure[key]
for key in ("inputUrl", "scrapedAt")
if key in failure
}
diagnostic["error"] = str(failure.get("error", ""))[:240]
add_if_fits("failed_inputs", "omitted_failures", diagnostic)
evidence_fields = (
"url", "scrapedAt", "address", "city", "state",
"listingStatus", "price", "priceCurrency",
"priceMin", "priceMax", "bedrooms", "bathrooms", "sqft",
)
for listing in envelope["listings"]:
evidence = {
key: listing[key]
for key in evidence_fields
if key in listing
}
add_if_fits("listings", "omitted_listings", evidence)
return serialize()
agent_context = shape_context(lookup_result)
This uses a character budget, not an exact token ceiling. Your host still needs to reserve room for instructions, conversation, and the answer, using its tokenizer when enforcing the final context limit.
Only the listings collection belongs in property retrieval. Diagnostic text remains untrusted tool data, even when it arrives in the failure collection.
The projection also preserves rental ranges. A community's price is its lower bound; dropping priceMin and priceMax can turn “starts at” into a confident quote for an unspecified home.
Fields are omitted when no real value was published. Don't replace an absent sale price with a current asking price just to make an answer look finished.
An unchanged invalid URL isn't a retry strategy
Repeating a deterministic input problem doesn't repair it. It mostly gives the same mistake another appointment.
After the host identifies an invalid-URL failure, require a changed, approved input and retain the original inputUrl. This guard permits a bounded correction attempt:
retried_originals = set()
def retry_invalid_url(failure, corrected_url):
original = failure["inputUrl"]
if not corrected_url or corrected_url == original:
raise ValueError("An invalid URL needs a corrected input.")
if corrected_url not in approved_urls:
raise ValueError("The replacement needs application approval.")
if original in retried_originals:
raise RuntimeError("Correction budget exhausted for this input.")
retried_originals.add(original)
return {
"inputUrl": original,
"replacement_url": corrected_url,
"result": lookup_properties([corrected_url]),
}
The set is process-local example state. A deployed agent needs persistent attempt tracking across workers and restarts.
A changed string isn't proof of a valid destination, either. Application approval remains necessary, and the next response still passes through the same record partition.
We wouldn't route every possible error through this correction function. An invalid input and a failed run need different handling.
Count starts when pricing another attempt
The worked example is the Trulia Listings & Price History Scraper.
Its FREE-tier event fees can be calculated from actual charged event counts:
from decimal import Decimal
def free_event_fees(*, start_event_count, dataset_item_event_count):
counts = (start_event_count, dataset_item_event_count)
if any(type(count) is not int or count < 0 for count in counts):
raise ValueError("Use nonnegative integer charged-event counts.")
return (
Decimal("0.10") * start_event_count
+ Decimal("0.00099") * dataset_item_event_count
)
Start-event counts depend on memory: an event per GB, with a minimum of an event. Don't substitute the number of runs for the billed start count without checking that relationship.
Use actual apify-actor-start and apify-default-dataset-item counts. The calculation returns event fees only; add platform usage at your plan's rates. Don't assume an error-shaped record is free, or estimate charges from the number of usable listings.
We'd accept partial success and make evidence admission a separate decision. A green tool status is too far upstream to authorize a housing claim.
Reproduce the boundary with a mixed input
- Submit the input below directly to the Actor as a deliberate failure fixture, outside the production approval gate.
- Fetch the dataset and pass every record through
partition_records. - Check that records carrying
errorreach failure handling and never enter the property index. Inspect run status separately. - Keep the original failed input when proposing a correction; don't automatically resubmit it.
Example mixed input:
{
"mode": "urls",
"urls": [
"https://www.trulia.com/home/1801-w-saint-johns-st-austin-tx-78757-464681422",
"not-a-url"
],
"maxItems": 20,
"fetchDetails": false
}
Drafted with AI assistance and reviewed for accuracy.
Top comments (0)