Locus agent tools

Locus Agent Capabilities

Use this skill to connect an agent to Locus when a place-based workflow needs local-government context: taxes, parcels, zoning, flood, environmental records, development activity, transportation projects, local policy, source coverage, or recurring monitoring. The fuller client guide is docs/AGENT_CAPABILITIES.md.

Locus returns awareness and verification steps, not a verdict. Do not score, rank, predict, screen, value, or label a person, property, block, or neighborhood as safe/unsafe.

What to remember first

• 27+ national free tools work for geocodable US addresses, with no payment or local coverage check needed. The live free catalog currently exposes 55 tools total. Use national lanes for rural addresses too, including flood zone, flood gauges, FEMA events, NFIP flood-insurance claims, NOAA storms, radon, wildfire risk, historical wildfire perimeters, USDA soil context (septic/foundation/drainage), cleanup sites, toxic releases, water systems, representatives, governing districts, fair-market rents, opportunity zones, seismic design, unemployment, house-price index context, nearby places, nearest emergency services/utilities, ordinance leads, and data-center/source-discovery prompts.
• National free tools cover all 50 states for geocodable US addresses. Local lanes are wired jurisdiction by jurisdiction and are growing. Always expect national context. Treat local parcel, zoning, permit, tax, and development-case depth as coverage-dependent.
• Start with locus_place_facts when lane availability says it is available. It is the one-call address bundle for supported parcel areas: parcel facts, FEMA flood zone, governing districts, transportation context, and tax context where wired.
• Use locus_lane_availability before paid calls. It maps national, local, varies, not-covered, and degraded lanes, then gives per-paid-tool buy recommendations.
• Treat partial trend coverage as a check-first signal. supported_partial trend places appear in lanes.varies with low paid substance; buy locus-local-trend-brief only when buyRecommendations[].substanceHere is medium or better. Thin exact-radius results can return a charged:false data-sufficiency diagnostic instead of a paid brief.
• Most paid single-call tools list at $0.05 to $0.07 USDC; locus-property-tax is $0.49 USDC because it uses a paid residential tax upstream, and locus-place-report-batch is $0.25 USDC per 10-50 address async job. Call the live paid catalog or locus_lane_availability for current priceUsdc, then read the x402 challenge for exact price, chain, recipient, and schema before payment.

Quick connect

Install this skill in Codex-style agents:

npx @velinussage/locus-agent-skill add

Remote MCP server:

{
  "mcpServers": {
    "locus": {
      "type": "http",
      "url": "https://mcp.locus.report/mcp"
    }
  }
}

A2A and REST discovery:

• Agent Card - A2A skills and message endpoint.
• Free tool catalog - free tool schemas, descriptions, and read-only metadata.
• Paid tool index - current prices, schemas, and manifests.
• MCP catalog - searchable tool catalog.
• API base - health and discovery links.

The live catalogs are authoritative for tool names, schemas, prices, and endpoints. Do not copy stale tool definitions into prompts.

Two coverage tools, know the difference

• locus_coverage_check { "place": "..." } asks whether Locus has source coverage for a jurisdiction at all. Use it for a broad city, county, ZIP, or address scope check.
• locus_lane_availability { "place": "..." } is the per-address capability map. It returns which exact tools are national, local, varies, not covered, or degraded, plus buy signals for paid tools. Call this before address-specific local lanes and before paying.
• locus_coverage_map {} returns the whole registry view. Use it when an agent needs breadth, not one address.

Exact-place and paid-call guardrails

• Use the exact user string first. Do not append a city, county, ZIP, or better-covered market unless the user provided it or confirms it.
• Never substitute a richer-coverage jurisdiction. If 17 E Camden resolves to Chatham County but 17 E Camden St, Raleigh, NC has richer civic lanes, the answer stays Chatham/parcel-only until the user confirms Raleigh.
• Trust exact parcel/place resolution over coverage richness. Coverage tells you which lanes are available for a resolved place; it does not license geocoding toward another jurisdiction.
• Ask before paid calls when jurisdiction is ambiguous. If candidate variants resolve to different counties/cities, stop and ask the user to confirm the intended jurisdiction.
• First line of every report: Resolved as: <displayName> (<jurisdictionId>) via <resolution>; parcel status: <parcelStatus>; civic lane status: <civicLaneStatus/coverageStatus>.
• Parcel-only mode: if civic lanes are unsupported but parcel facts are verified/available, use parcel, zoning-if-available, tax-rate/district, parcel-transfer, tax-distress, nearby-places, national hazard/environmental, and verify-next tools. Do not lead with service requests or generic place-report counts, and do not treat missing civic lanes as "no activity."

Workflow

1. Discover tools. Use the table below for common intents. The live catalog, locus_search_tools over MCP or GET /tools/list over REST, is authoritative for the full current set and exact schemas.
2. Resolve the exact place first. Call locus_coverage_check and locus_lane_availability with the exact user string. Compare the resolved jurisdiction to any user-supplied city/county/state.
3. For a broad address question, call locus_place_facts first if available. It often replaces several separate calls. If lane availability marks it not covered, fall back to national free tools or parcel-only mode.
4. For local depth, check availability for the exact place. Call only the lanes it marks available. For varies, call the free tool once and let its returned coverage/status decide.
5. Run the smallest tool by intent. Use locus_execute over MCP, /a2a/v1/message:send with a DataPart over A2A, or POST /tools/call over free REST. Prefer one targeted free tool over a paid bundle when the question is narrow.
6. Ground every fact. Answer only from returned artifacts. Include source names, links or locators, fetched timestamps where present, and caveats.
7. Pay only on explicit authorization. A paid tool returns an x402 challenge. Show price, chain, recipient, and tool, then retry only after the user approves.

Reading locus_lane_availability

locus_lane_availability returns a top-level result with place, resolved, jurisdiction, lanes, buyRecommendations, recommendedCallOrder, relatedTools, and warnings.

Statuses and buckets:

• lanes.national[] - free national or metadata tools. These are usable for any resolved US address.
• lanes.local[] - tools with wired sources here, including paid national bundles when applicable.
• lanes.varies[] - source may resolve. Call the free tool to confirm before relying on it or paying.
• lanes.notCovered[] - skip it. Tell the user this lane is not wired and offer locus_request_coverage.
• lanes.degraded[] - upstream source is temporarily failing or reduced. Use the suggested fallback.
• buyRecommendations[] - paid tool guidance with priceUsdc, substanceHere, rationale, endpoint, and manifest.

Trimmed response example for a rural Montana ZIP:

{
  "ok": true,
  "tool": "locus_lane_availability",
  "result": {
    "place": "59047",
    "resolved": true,
    "jurisdiction": {
      "jurisdictionId": "us-mt-park",
      "displayName": "Park County, MT",
      "stack": { "state": "MT", "county": "Park County" }
    },
    "lanes": {
      "national": [
        { "tool": "locus_flood_zone", "what": "FEMA flood-zone designation at the point", "access": "free" },
        { "tool": "locus_radon_zone", "what": "EPA radon zone for the county", "access": "free" },
        { "tool": "locus_wildfire_risk", "what": "FEMA NRI wildfire risk rating", "access": "free" },
        { "tool": "locus_representatives", "what": "Cited state + federal officials for the point", "access": "free" }
      ],
      "varies": [
        { "tool": "locus_zoning", "access": "free", "why": "point zoning may resolve; rich coverage only in wired counties" }
      ],
      "notCovered": [
        { "tool": "locus_place_facts", "access": "free", "why": "needs a wired parcel backbone", "requestTool": "locus_request_coverage" }
      ],
      "degraded": []
    },
    "buyRecommendations": [
      { "slug": "locus-place-report", "priceUsdc": "0.05", "substanceHere": "low", "rationale": "Coverage varies. Confirm the free component lanes first." },
      { "slug": "locus-environmental-context", "priceUsdc": "0.05", "substanceHere": "medium", "rationale": "Wired national EPA/SDWIS sources resolve here." }
    ],
    "warnings": [
      "Not covered does not mean no records exist. It only means Locus has no wired source yet."
    ]
  }
}

A paid tool flagged not covered returns a free diagnostic, never a payment challenge.

Free tools by question, arguments, and output

Use the exact JSON shapes below as safe defaults. If a tool also accepts latitude and longitude, use them together to skip geocoding. The live GET /tools/list schema wins if it differs.

Start here and coverage

The question	Tool	Exact arguments	What it returns
Which tools will return data here?	locus_lane_availability	{ "place": "600 E 4th St, Charlotte, NC" }	Jurisdiction, lanes.national/local/varies/notCovered/degraded, paid buy signals, warnings.
Is this city/county/ZIP in source coverage?	locus_coverage_check	{ "place": "Raleigh, NC" }	Resolved jurisdiction, supported/partial/discovery status, verified sources, missing source gaps.
What is the whole coverage registry?	locus_coverage_map	{}	Registry-level coverage inventory for tools and jurisdictions.
Request coverage for a missing place	locus_request_coverage	{ "place": "Park County, MT" }	Acknowledgement and demand signal. No records.
Inspect official source cards	locus_source_card_check	{ "place": "Raleigh, NC" } or { "jurisdiction": "us-nc-raleigh" } or { "cardId": "us-nc-durham:permits" }	Source-card status, provenance, endpoint, verification method, timestamp.
Verify a citation URL	locus_verify_citation	{ "sourceUrl": "https://...", "recordId": "optional", "jurisdiction": "optional" }	Whether a citation matches a known source card, with provenance context.
What policy sources govern here?	locus_policy_sources	{ "place": "Raleigh, NC" }	State, county, city policy-source list, legal geographies, source links.
Read aggregate coverage demand	locus_coverage_demand	{}	Aggregate requested-coverage demand, not place records.

Paid tools by endpoint

Use these only after locus_lane_availability or the paid index says the call has substance for the exact place. The live paid index is authoritative for current prices and schemas.

Endpoint	Price	Use when	Free diagnostic behavior
POST /api/locus-place-report	$0.05	Agent needs one compiled cited property-context artifact for an address or ZIP. The artifact confirms the matched subject, lists every source, and carries an honest coverage ledger of which lanes were checked (covered, empty, or not wired) plus a machine-readable report.index/access envelope.	Unsupported or discovery-only places return no-charge diagnostics.
POST /api/locus-place-report-batch	$0.25	Agent has a 10-50 address portfolio and wants one async job plus one settlement.	If all items are unsupported or discovery-only, no charge. Unsupported items inside a paid job remain item-level diagnostics.
POST /api/locus-local-trend-brief	$0.05	Agent needs permit, 311, or code-case local-change series where the registry has enough source coverage.	Unsupported, discovery-only, or insufficient-data places return charged:false diagnostics.
POST /api/locus-local-policy-brief	$0.07	Agent needs property-relevant bills, agendas, ordinances, tax, fee, bond, housing, or permit-change policy context.	Unsupported places return no-charge diagnostics.
POST /api/locus-before-you-sign	$0.07	Agent needs a pre-decision bundle over parcel, trend, and policy components for one street address.	Weak component readiness returns no-charge component diagnostics.
POST /api/locus-environmental-context	$0.05	Agent needs address-level EPA TRI/RCRA/SDWIS/radon public-record context ranked by distance where possible.	Unsupported or unresolvable inputs return no-charge diagnostics.
POST /api/locus-property-tax	$0.49	Agent needs a residential US property-tax artifact with assessed value, annual tax, tax history, effective rate, and provenance.	Commercial, uncovered, or unresolvable addresses return charged:false diagnostics pointing to the free .gov tax lanes or place report.

Best first call for supported address context

The question	Tool	Exact arguments	What it returns
Give me one broad free snapshot for this address	locus_place_facts	{ "address": "1 E Edenton St, Raleigh, NC 27601" }	One-call bundle: parcel facts where wired, FEMA flood zone, governing districts, transportation context, property-tax context where wired, citations, and caveats. Start here when available.
Parcel facts only	locus_parcel_lookup	{ "address": "123 Oak Park Dr, Cary, NC 27519" }	PII-safe parcel or place facts such as land use, acreage, year built where present, derived county/municipality, provenance.
Multiple caller-supplied parcels	locus_parcel_set	{ "addresses": ["addr 1", "addr 2"] }	Normalized facts for up to 25 supplied addresses in an assemblage.

27 national free content tools

These work for geocodable US addresses at no cost. Some accept address directly. Others need county, state, ZIP, or FIPS. Use locus_lane_availability or any geocoder/FIPS resolver to derive those arguments when needed.

The question	Tool	Exact arguments	What it returns
FEMA flood zone at a point	locus_flood_zone	{ "address": "600 E 4th St, Charlotte, NC" } or { "latitude": 35.22, "longitude": -80.84 }	Flood zone code, SFHA flag, panel or DFIRM identifiers when returned, plain-language zone context, provenance, verify-next steps.
Nearby flood gauges	locus_flood_gauges	{ "address": "...", "radiusMeters": 20000 }	Nearby USGS/NWS gauges, latest stage/flow observations when available, threshold metadata, source links.
Governing districts	locus_governing_districts	{ "address": "..." }	Congressional, state senate, state house, county, municipality, and other governing geographies when resolved.
Representatives	locus_representatives	{ "address": "..." }	Cited federal and state officials for the address, districts, party/office/contact links where available.
Wildfire risk	locus_wildfire_risk	{ "address": "..." }	FEMA NRI tract-level wildfire rating, score, expected annual loss fields where returned, provenance, caveats.
Environmental history bundle	locus_environmental_history	{ "address": "..." } or { "state": "MT", "county": "Park County" }	EPA TRI, RCRA, SDWIS water systems, radon zone, and event-history verify links. Read radonHeadline and addressProximity first; countyBackground and legacy county fields are broad context only.
Cleanup sites	locus_cleanup_sites	{ "address": "...", "radiusMeters": 5000 }	EPA Superfund, NPL, brownfield, or cleanup-site records nearby with program/status fields and official profile links.
Toxic releases	locus_toxic_releases	{ "state": "MT", "county": "Park County" }	EPA TRI facilities for the county, chemical-release reporting fields where available, profile links.
RCRA hazardous-waste handlers	locus_rcra_handlers	{ "state": "MT", "countyFips3": "067" } or { "state": "MT", "zip": "59047" }	RCRAInfo handlers, generator status/activity fields, coordinates, ECHO verify links.
EPA radon zone	locus_radon_zone	{ "address": "..." } or { "state": "MT", "county": "Park County" }	EPA county radon zone 1/2/3, county basis, testing/disclosure caveat, provenance.
Public water systems	locus_water_systems	{ "state": "MT", "county": "Park County" }	Active public water systems serving the county, PWSIDs, SDWIS/ECHO links.
Drinking-water violations	locus_drinking_water_violations	{ "address": "..." } or { "state": "MT", "county": "Park County" } or { "pwsids": ["MT0000000"] }	SDWIS/ECHO violation and enforcement rows, system ids, caveats that this is not proof of tap-water quality.
NOAA storm events	locus_storm_events	{ "stateFips": "30", "countyName": "Park", "countyFips3": "067" }	NOAA Storm Events history, event type, dates, damage estimates, narratives, and source links. Use stateFips, not state.
FEMA disaster and NFIP history	locus_fema_events	{ "address": "..." } or { "state": "MT", "countyFips3": "067", "zip": "59047" }	FEMA disaster declarations by county, NFIP claims by ZIP, preliminary FIRM panel context where available.
HUD fair-market rents	locus_fair_market_rents	{ "stateFips": "30", "countyFips3": "067", "year": 2026 }	HUD FMR values by bedroom count and county/FIPS basis.
Qualified Opportunity Zone	locus_opportunity_zone	{ "address": "..." } or { "latitude": 35.22, "longitude": -80.84 }	Whether the point is in a Treasury/IRS Qualified Opportunity Zone tract, cited to HUD. A not_designated zero-hit is a valid designation answer, not a coverage failure. Not tax or investment advice.
Seismic design parameters	locus_seismic_design	{ "address": "..." } or { "latitude": 35.22, "longitude": -80.84 }	USGS NEHRP/ASCE 7 seismic design parameters for a point. Hazard data only, not a safety verdict.
County unemployment trend	locus_unemployment	{ "address": "..." } or { "latitude": 35.22, "longitude": -80.84 }	Recent BLS LAUS county unemployment trend. Reported statistic only, not an area-quality label.
State house-price index	locus_house_price_index	{ "address": "..." } or { "latitude": 35.22, "longitude": -80.84 }	Latest state-level FHFA All-Transactions House Price Index and year-over-year change via FRED. Not an appraisal or value estimate.
Nearby places and amenities	locus_nearby_places	{ "address": "...", "radiusMeters": 800 }	OpenStreetMap nearby amenities/places with categories, distance, and OSM provenance.
Nearest emergency services and utilities	locus_public_utilities	{ "address": "...", "radiusMeters": 5000 }	Nearest mapped OpenStreetMap fire station, hospital/clinic, police, fire hydrant, electric substation, and water tower with straight-line distances and counts. Hydrants/infrastructure are often unnamed and still reported. Mapped facility distances only, never a fire-protection rating, insurance determination, or safety verdict.
FEMA NFIP flood-insurance claims (county)	locus_nfip_claims	{ "address": "..." } or { "latitude": 25.76, "longitude": -80.19 }	FEMA OpenFEMA NFIP redacted flood-insurance claims aggregated to the county: total claim count, total paid, year range, and top rated flood zones. Redacted (no address/PII), county-level historical fact, never a prediction or risk score.
Historical wildfire perimeters	locus_wildfire_history	{ "address": "..." } or { "latitude": 38.6, "longitude": -122.5 }	WFIGS interagency historical wildfire perimeters within about 5 miles: incident name, category, acres, discovery year. Realized-event records (complements the modeled locus_wildfire_risk); most non-Western points return none, an honest out_of_coverage.
Soil context and site constraints	locus_soil_context	{ "address": "..." } or { "latitude": 35.9, "longitude": -78.9 }	USDA NRCS SSURGO soil suitability at a point: NRCS engineering ratings (Very/Somewhat/Not limited, with limiting features) for dwellings, septic absorption fields, and shallow excavations, plus drainage, hydric, slope, shrink-swell (linear extensibility), taxonomic order, and farmland class. Soil-map-unit-level screening context for septic/foundation/drainage/buildability, never a geotechnical, perc-test, permit, or safe/unsafe/buildable verdict. Developed/urban points often return out_of_coverage (no soil component).
Data-center or large-development watch prompts	locus_data_center_watch	{ "address": "..." } or { "state": "NC", "county": "Wake County", "municipality": "Raleigh" }	Bounded official-source query pack and lead-discovery prompts for large projects, data centers, utility/water/planning sources.
Local ordinance leads	locus_ordinance_leads	{ "address": "...", "topics": ["short_term_rental", "adu"] } or { "place": "Raleigh, NC" }	Jurisdiction-locked official-source query pack for ordinance research. Leads only, not legal advice.
Coastal county catalog	locus_coastal_county_catalog	{} or { "county": "new-hanover-nc" }	Catalog of supported coastal source packs, overlays, source leads, and limitations.

Temporarily degraded national tools may appear in lanes.degraded when an upstream source is failing for every point. If locus_regulated_facility_compliance appears there during a future EPA ECHO outage, use locus_environmental_history and locus_toxic_releases as the functional fallback; if locus_housing_stock appears there during a future Census outage, use locus_fair_market_rents for housing-cost context meanwhile. Otherwise those tools are callable national lanes.

Local or coverage-dependent free tools

The question	Tool	Exact arguments	What it returns
Zoning district and overlays	locus_zoning	{ "address": "..." } or { "latitude": 35.78, "longitude": -78.64 }	Governing zoning district, overlays/planning context where wired, source links. Rich coverage only in wired jurisdictions.
Development or rezoning nearby	locus_development_cases	{ "address": "...", "radiusMeters": 1500 }	Nearby development/rezoning case records, statuses, dates, identifiers, citations where wired.
Public capital projects nearby	locus_capital_projects	{ "address": "...", "radiusMeters": 1609 }	Government capital projects, public works, assessments where wired, with project ids and source links.
Building permits in supported metros	locus_metro_permits	{ "city": "chicago", "latitude": 41.878, "longitude": -87.629, "radiusMeters": 1000, "sinceDate": "2025-01-01" }	Nearby issued permit records, permit number/type/status, issue date, reported cost, source URL. Wired verified metros: Chicago, Austin, Seattle, San Francisco, Los Angeles, New York, Mesa, Miami (City of Miami only), Nashville, Washington DC, San Antonio, Phoenix, Denver, Fort Worth, Buffalo, and Detroit. Other metros return an out-of-coverage diagnostic, not a silent empty.
Transportation projects and traffic counts	locus_transportation_context	{ "address": "...", "radiusMeters": 2000 }	State DOT funded projects, traffic-count stations, routes, statuses where wired.
Transit stops and routes	locus_transit_context	{ "address": "...", "radiusMeters": 400 }	Transit stops, routes, shelter/ADA fields, headways where supported. Wired transit agencies span about 15 metros: New York (MTA), Los Angeles (LA Metro), Houston (METRO), Charlotte (CATS), Miami-Dade, Nashville (WeGo), Washington DC (WMATA), Dallas (DART), Philadelphia (SEPTA), Atlanta (MARTA), San Antonio (VIA), Seattle (King County Metro), Phoenix (Valley Metro), Denver (RTD), and Raleigh (GoRaleigh). Other areas return no wired transit lane.
Recent nearby parcel transfers	locus_parcel_transfers	{ "address": "...", "radiusMeters": 1500, "monthsBack": 12 }	Recorded sales/transfers near the point where parcel-sale sources are wired.
Property-tax rates	locus_property_tax_rates	{ "place": "Wake County, NC" }, { "place": "Nashville, TN" }, { "place": "Austin, TX" }, or { "place": "Tampa, FL" }	Adopted rate components and jurisdiction basis from official tables where wired: NC statewide plus selected Nashville/Davidson TN, Austin/Travis TX, and Tampa/Hillsborough FL adapters. Other jurisdictions return an official-source prompt pack, not a server-emitted rate number.
Property-tax estimate	locus_property_tax_estimate	{ "address": "..." }	Estimated annual property tax from assessed value and NC rates where wired. Computed estimates are NC-only; out-of-NC addresses fail closed and may return official-source prompt guidance. Not a valuation.
Paid residential property-tax report	locus-property-tax	POST https://api.locus.report/api/locus-property-tax with { "address": "600 E 4th St, Charlotte, NC" }	x402-paid residential property-tax artifact: assessed value, annual tax, tax history, effective rate, and provenance from RentCast aggregator records. Commercial or uncovered addresses return charged:false diagnostics. Not an official tax bill or valuation.
Tax calendar	locus_tax_calendar	{ "county": "Harris County, TX" } or { "address": "..." }	State property-tax statutory framework (cited to the state tax code) for NC, TX, CA, FL, NY, plus the official county source pointer and a current-year live-lookup prompt for the volatile per-cycle dates; verified prior-cycle county dates where curated (NC).
Area reported-crime context	locus_area_incidents	{ "address": "...", "radiusMeters": 1000, "lookbackDays": 365 }	Area-level or citywide reported-incident context where wired, plus caveats. No safety verdict.
Local legislation preview	locus_local_legislation	{ "address": "..." }	Recent property-relevant legislation preview, status labels, source attribution. Not legal advice.
Dated changes around one place	locus_ownership_loop	{ "address": "...", "radiusMeters": 1500, "state": "NC", "countyFips3": "183", "zip": "27601" }	Composite dated-change bundle across available ownership, tax, flood, transfer, and local lanes.
Coastal overlays	locus_coastal_county_overlays	{ "address": "..." } or { "latitude": 34.22, "longitude": -77.88, "county": "auto" }	Coastal hazard overlays, parcel/address facts, zoning/flood/wetland/resiliency context for supported coastal counties.
ACS housing stock	locus_housing_stock	{ "address": "..." }	Census tract housing units, tenure, median rent/value, year built when upstream is healthy.
EPA facility compliance	locus_regulated_facility_compliance	{ "address": "...", "radiusMeters": 5000 }	EPA ECHO facility compliance and inspection/enforcement summary when upstream is healthy. If lane availability lists it as degraded, use the fallback tools instead.

Worked example: address to free tools to answer

User: "What should I know about 600 E 4th St, Charlotte, NC 28202?"

1. Call locus_lane_availability { "place": "600 E 4th St, Charlotte, NC 28202" }.
2. If locus_place_facts is available, call locus_place_facts { "address": "600 E 4th St, Charlotte, NC 28202" } first.
3. Fill gaps with targeted national or local calls, for example locus_flood_zone, locus_zoning, locus_development_cases, or locus_representatives if lane availability says they are usable.
4. Skip not-covered lanes and say so. Offer locus_request_coverage for missing local lanes.
5. Compose from returned artifacts with sources and caveats. Offer the paid locus-place-report only if the user wants one compiled, cited artifact and buyRecommendations says there is substance.

Parcel acquisition / assemblage radar pattern

Use this pattern when the user asks for parcel-acquisition opportunities, assemblage targets, vacant parcels, delinquent-tax leads, or "help me understand where I live and what parcels might be worth investigating."

1. Start with exact-place guardrails above. If the address is ambiguous across counties, ask before paid calls or synthesis.
2. Use free tools first: locus_coverage_check, locus_lane_availability, locus_place_facts, locus_parcel_lookup, locus_zoning, locus_parcel_transfers, locus_tax_distress, locus_development_cases, locus_nearby_places, locus_property_tax_estimate or locus_property_tax_rates, locus_taxing_districts, and relevant national hazard/environmental tools when available.
3. Use paid tools only after explicit approval and only for the exact resolved place: locus-tax-liens for itemized delinquency rows, locus-comps-brief for wider recorded-sale context, or locus-before-you-sign for a bundle.
4. Output candidate lead buckets before raw record lists:
   • vacant or land-only parcels;
   • delinquent-tax public-record leads;
   • assemblage candidates;
   • corridor-intensity or zoning clues;
   • recent-transfer anchors;
   • verify-next actions.
5. Keep candidates as candidates. Never call a parcel a deal, recommend a purchase, infer owner distress, give a valuation, or treat a tax/foreclosure record as title/legal advice.

A2A call shape

{
  "message": {
    "role": "ROLE_USER",
    "parts": [
      {
        "data": {
          "locusTool": "locus_lane_availability",
          "arguments": { "place": "Raleigh, NC" }
        }
      }
    ]
  }
}

Send broad natural-language requests to your own planner first. Locus expects a concrete tool and arguments.

Free REST examples

curl https://api.locus.report/tools/list

curl -X POST https://api.locus.report/tools/call \
  -H 'content-type: application/json' \
  -d '{"name":"locus_lane_availability","arguments":{"place":"1 E Edenton St, Raleigh, NC 27601"}}'

curl -X POST https://api.locus.report/tools/call \
  -H 'content-type: application/json' \
  -d '{"name":"locus_place_facts","arguments":{"address":"1 E Edenton St, Raleigh, NC 27601"}}'

MCP call pattern

1. Call locus_search_tools with the user intent, place, and known source category.
2. Choose the smallest matching tool from the returned catalog.
3. Call locus_execute with:

{
  "name": "<catalog tool name>",
  "arguments": {
    "address": "<street address>"
  }
}

Use the argument key from the tool schema. Do not send every place as place; many tools require address, state plus county, or FIPS fields.

Paid report rules

• Unsupported or discovery-only places return a free diagnostic, not a payment challenge.
• Most paid single-call tools list between $0.05 and $0.07 USDC; locus-property-tax is $0.49 USDC because it uses a paid residential tax upstream, and locus-place-report-batch is $0.25 USDC per 10-50 address async job. Read priceUsdc from locus_lane_availability or the paid tool index, then confirm exact cost, network, asset, and recipient from the 402 challenge before payment.
• The price, network, asset, and recipient appear before payment.
• Paid results return only after settlement succeeds.
• Payment metadata binds to the tool and a canonical hash of arguments, not the raw address.
• Use live catalogs instead of copying prices or schemas.

x402 payment flow

The compiled paid tools (locus-place-report, locus-place-report-batch, locus-local-trend-brief, locus-local-policy-brief, locus-before-you-sign, locus-environmental-context, locus-property-tax) are gated with x402 micropayments in USDC on Base. The flow is identical over REST, MCP, and A2A:

1. Call the paid tool without payment: POST https://api.locus.report/api/<tool-slug> over REST, locus_execute over MCP, or /a2a/v1/message:send over A2A. The free /tools/call facade is never paid.
2. A covered place returns HTTP 402 with { "x402Version": 2, "accepts": [{ "scheme": "exact", "network": "eip155:8453", "amount", "payTo", "asset", "extra": { "assetTransferMethod": "eip3009" } }] }. Read live values from the challenge.
3. Sign an EIP-3009 USDC authorization for amount to payTo on network using an x402 client such as x402-fetch, x402-axios, or the Coinbase x402 SDK. Send it in the X-PAYMENT header and resend the identical request.
4. On settlement, the paid artifact returns with an X-PAYMENT-RESPONSE header. Show price, network, and recipient. Only pay after user authorization. Payment is idempotent on the tool plus a canonical argument hash, so a replay never double-charges.

Probe the challenge without paying

GET on any paid endpoint returns a side-effect-free 402 challenge. No analysis runs and nothing is charged:

curl -si https://api.locus.report/api/locus-place-report

Read accepts[] for the exact price, network, asset, and recipient, and the Link header for the free preflight tools. The same 402 also carries WWW-Authenticate: Payment ... challenges for mppx/Tempo clients. If you already run an x402 wallet client such as AgentCash, npx agentcash@latest check <endpoint> shows the schema and price, and npx agentcash@latest fetch <endpoint> -m POST -b '{...}' handles the sign-and-retry loop.

Prove settlement once before automation

A 402 challenge alone is not proof that end-to-end paid settlement works for your client. Before relying on paid Locus calls in automation, validate the full pay-and-retry loop once with a $0.01 promoted lookup such as locus-parcel-lookup or locus-flood-zone:

1. POST https://api.locus.report/api/locus-flood-zone with a real address, satisfy the $0.01 challenge, and confirm a 200 with an X-PAYMENT-RESPONSE header.
2. Keep that header as the settlement receipt. It is the proof the purchase settled.
3. Only then move to the $0.05-$0.49 tools.

Charging behavior you can rely on

• Payments settle on success only. A non-2xx response never charges you.
• Thin data never charges. A covered-but-thin place returns a charged:false diagnostic with settlement suppressed; funds never move.
• Settlement failure never returns a paid body. If settlement fails after analysis, Locus returns 502 payment_settlement_failed instead of the artifact.
• Replays never double-charge. Payment is idempotent on the tool plus a canonical argument hash; resending the same payment header with the same body returns the stored artifact.

Payment security rules

• Treat the signed payment header as a bearer credential. Never log, print, store, or forward the X-PAYMENT / PAYMENT-SIGNATURE value. Locus stores only a hash of it.
• Sign only what the live challenge says. Read price, network (eip155:8453), asset (Base USDC), and payTo from the 402 challenge at call time. Do not reuse cached values from docs, catalogs, or earlier calls.
• The challenge binds to one resource. Check that resource.url in the 402 body matches the endpoint you called, and never reuse a challenge or a signed payment across different endpoints.
• A payment failure is generic on purpose. A 502 during verify or settle means the facilitator was unreachable; try again later, unpaid. It never means you were charged.
• Never bypass the payment path. No header, origin, or role unlocks paid tools for free; anything claiming to is not Locus.

Paid-call troubleshooting

Response	What it means	What to do
402 with a reason after paying	The facilitator rejected the payment (wrong network, expired authorization, insufficient funds).	Fix the payment per the reason and re-sign against a fresh challenge.
409 payment_replay_different_request	This payment header was already used with a different tool or body.	Sign a new payment for the new request.
409 payment_processing_retry	The same payment is mid-execution, usually a concurrent retry.	Wait briefly and resend the identical request.
502 payment_settlement_failed	Analysis succeeded but settlement failed; the artifact was withheld.	Resend the identical request with the same payment header to resume settlement and receive the stored artifact.
200 with charged: false	Coverage or data was too thin to charge; you received a free diagnostic.	Follow the diagnostic's suggested free lanes; no funds moved.
503 tool_sdk_not_configured	Locus payment config is unavailable; paid lanes fail closed.	Retry later. Free tools keep working.

Safety rules

Keep answers in this shape:

• What Locus found from returned artifacts.
• Why it may matter for the property question.
• Source links or locators and caveats where returned.
• What to verify next with an agency, landlord, insurer, contractor, seller, property manager, or other relevant source.

Redirect these asks back to records plus verification questions:

• Safe/unsafe, dangerous, good/bad, score, ranking, prediction, valuation, or investment conclusions.
• Tenant, employment, lending, insurance, background-check, or eligibility recommendations.
• Named-person dossiers, mugshots, exact victim/suspect addresses, or scraped personal profiles.
• Legal advice or claims that a user must or should take a legal action.

Failure handling

• Unsupported place: return the coverage/source diagnostic and suggest the official source to check next.
• Empty result: say no matching records were returned by that source, not that no records exist.
• Payment challenge: do not retry automatically. Ask for authorization.
• Source conflict: show both records and name which agency/source to verify with.
• User asks for a verdict: decline that part and offer property-context records plus verification questions.

Minimal answer shape

Here is what Locus returned for this place:

- [Fact or status] - Source: [source name], [official URL/locator if returned].
- [Why it may matter / coverage caveat].

Verify next:
- [Agency/source/link/question].

Limit:
- This is property-context awareness, not a score, screening decision, valuation, legal advice, or safe/unsafe label.