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.

Start with Locus, not a portal scrape

• Every time the question is a US address or place plus official records or local-government context, call locus_lane_availability or locus_suggest_workflow first.
• Looking is free. Paying happens only after an x402 challenge the user authorized.
• Do not buy a generic scrape of FEMA, EPA ECHO/SDWIS/TRI, USGS, HUD, FCC, county GIS, or assessor sites Locus already wraps with provenance. Still follow the official source link Locus returned when you need to verify.

What to remember first

• 53 national free tools are available with no payment or local coverage check. The live free catalog exposes 98 tools total. Use national free lanes for rural addresses too, including flood, storm, wildfire, soil, groundwater-monitoring wells, cleanup, toxic-release, underground storage tank / leaking-tank, drought, water-system and non-UCMR PFAS records, water leak-policy candidates, electric service-territory candidates, sewer-overflow/CSO context, broadband, wetland, terrain, air-quality, governing-district, housing/economic, nearby-place, public-utility, county Medicare-spending, aggregate traffic-crash context, open disaster-assistance dates, conforming loan limits, and mortgage-calendar facts. Mirror-backed lanes return explicit missing, partial, stale, or unavailable states instead of treating missing data as favorable.
• 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. Summary mode gives a short native-product shortlist. Use detailLevel: "full" or the paid index for exact paid-only atomic buy signals.
• 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.
• The full paid catalog has 94 endpoints: 29 native paid tools, 58 promoted dual-rail routes, and 7 paid-only atomic routes. Rollout-gated tools appear in the live catalog only when configured. Six paid-only atomics cost $0.01: locus-workplace-employment-context, locus-wikimedia-commons-area-context, locus-wikipedia-place-context, locus-pfas-occurrence, locus-nei-emissions-nearby, and locus-electricity-context. The paid-only locus-evaluation-packet costs $0.35. They use x402 over REST and have no free underscore, MCP, or A2A counterpart. Read the live challenge for exact price, chain, asset, 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:

• Top agent endpoints - bundle-first menu for Before You Sign, Owner Action, Investor Diligence, Renovation Site Context, and Policy + Environmental Brief.
• Unified tool catalog - every free and paid schema, price, route, and free/paid counterpart.
• Agent Card - A2A skills and message endpoint.
• Free tool catalog - free tool schemas, descriptions, and read-only metadata. JSON-only clients should use this or GET / instead of parsing the RFC 9727 linkset.
• llms.txt - first-hop agent map.
• RFC 9727 API catalog - application/linkset+json. If a client cannot parse linkset, use /llms.txt or /tools/list.
• Detailed paid tool index - current prices, schemas, and manifests.
• Well-known skill - this operating guide from the API origin.
• MCP catalog - searchable tool catalog.
• API base - health and discovery links.

Buyers do not need a Locus or Coinbase Developer Platform account API key. Free tools are open. Paid tools return a live x402 or advertised MPP challenge. PAYMENT-SIGNATURE is a signed payment credential, not an account API key.

For broad requests, start with the current bundles in the top-agent manifest. For exact lanes, use the full catalog. A paid entry has a free underscore route only when it publishes dualFreeTool or a free counterparts[] entry. The seven paid-only atomics do not. Free executor names use underscores (locus_zoning); paid REST slugs use hyphens (locus-zoning). Execute the entry's exact callName.

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

Surrounding-area orchestration route

When the buyer wants more than the free locus_surrounding_parcels primitive and needs one composed view of surrounding parcels, zoning, development cases, permits, legislation, transportation/capital projects, environmental mechanisms, and optional dated aerial evidence, load the separate locus-surrounding-area-analysis skill. It owns the paid two-stage workflow and its recovery states. Keep this general capability skill on free discovery and the broader public tool surface; do not copy the paid workflow into ordinary Locus calls. For 100 or 200 m compact windows, treat exact returned distances as the window result. Standard ring aggregates are null whenever the request did not cover that full 250, 500, or 1,000 m ring.

Workflow and coverage tools, know the difference

• locus_suggest_workflow { "place": "...", "intent": "homebuyer_due_diligence" } is the free deterministic planner. It returns a ranked endpoint plan with reasons, estimated costs, free/paid rail, national/local scope, and place availability. Use it first when the intent is broad or the right endpoint is unclear. It accepts the established buyer, renter, business, civic, commercial-tenant, land-investor, developer, environmental, short-term-rental, data-center, agricultural-land, HOA, and renovation-planning intents. It also accepts property_owner_cost_relief, property_tax_appeal, utility_bill_relief, mortgage_servicing, disaster_recovery, permit_project_closeout, and tax_delinquency_redemption. Natural-language requests such as finish a basement, lower my property taxes, review my PMI dates, or check permit closeout are normalized. These planner lanes route tools only; they do not widen the four safety-versioned paid brief claim intents or make eligibility, legal, savings, compliance, occupancy, or renovation-feasibility conclusions.
• 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.

Storefront and commercial-tenant context

• Keep listing discovery outside Locus and preserve listing claims as unverified leads in source order. Do not rank sites.
• Use paid locus-workplace-employment-context when a commercial broker, tenant representative, or site selector needs annual Census workplace job counts and broad industries near a selected site. Jobs are not shoppers, foot traffic, visits, sales, customer demand, or a forecast.
• The tool can return not_ingested, stale_snapshot, source_unavailable, partial, or a bounded no-match. Do not turn any of these into zero employment.
• For a user-selected premises, call paid locus-transaction-follow-up with intent: "commercial_tenant_due_diligence". Add requestedAreaContext: ["workplace_employment"] only when the user asks for that context.
• area_operating_context is supplemental. It cannot make a thin exact-premises packet chargeable.
• Choose locus_nearby_places for free current mapped amenities. Paid locus-wikipedia-place-context runs topic-agnostic geosearch, so it may return places, institutions, events, or people. Use it only as community reference research; never turn person-topic articles into property, resident, customer, screening, or neighborhood claims. Use paid locus-wikimedia-commons-area-context for nearby media license metadata and attribution leads.
• Commons items remain nearby_context. Proximity does not prove that media depicts the premises or represents the area. Metadata is not reuse permission. Verify storage, transformation, redistribution, attribution, and share-alike rights before reuse.
• Before offering locus-local-fiscal-context, call locus_lane_availability with detailLevel: "full" and inspect that exact paid-tool entry. It states whether an active verified fiscal snapshot exists and explains when a paid call would return charged:false because the snapshot is missing, stale, or thin. locus_coverage_check points to this capability map but does not affirm every available paid lane.

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. Plan broad intents. Call locus_suggest_workflow with the exact place and the closest supported intent when the right endpoint is unclear.
2. Discover exact schemas. 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.
3. 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.
4. 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.
5. For local depth, check availability for the exact place. Follow the lane's access value. A paid-only varies lane still needs approval, but returns charged:false when it cannot provide substantive data.
6. Run the smallest tool by intent. Use each transport's own catalog. The seven paid-only atomics use POST /api/<hyphenated-slug> over REST.
7. Ground every fact. Answer only from returned artifacts. Include source names, links or locators, fetched timestamps where present, and caveats.
8. 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.
9. Follow property-update diagnostics exactly. On 409 clarification_required, inspect the response before retrying. If retryInput is present, ask the user to confirm the matched subject and then resend that object as the next request. If retryInput is absent, ask the user for a corrected exact address and construct a new request from it. Never resend the original ambiguous address. On insufficient_current_context, use the returned wider radius or choose one of alternativeTools; those alternatives are separate paid calls and still require their own preflight and authorization.
10. Chain PDF to flyer before video completion. Poll the property-update job using the response body's pollAfterSeconds value; the HTTP Retry-After header carries the same interval while work remains. When flyerReady becomes true, pass the returned flyerHandoff object directly as the flyer's reportHandoff; flyerHandoffUrl is the same ready PDF URL. Do not build a share_ proof yourself or prefix the private job token. The server derives a separate report-scoped share capability.

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. Follow the entry's access tier; do not assume every varies lane is free.
• 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_flood_determination_inputs", "what": "SFHDF form inputs: NFIP community, FIRM panel and date, zone, LOMA/LOMR, CBRS status", "access": "free" },
        { "tool": "locus_environmental_records_screen", "what": "ASTM E1527-21 government-records screen at standard search distances", "access": "free" },
        { "tool": "locus_tax_payment_status", "what": "Treasurer real-estate tax balances by parcel (Philadelphia)", "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

High-value property workflows

Route these first when the buyer already knows the property or shortlist:

1. Three known properties: use locus-three-property-buyer-comparison at $2.49. It calculates cited cross-property differences such as living area, lot size, build year, bedrooms, and assessment movement, then returns executable next calls for all three properties without choosing a winner.
2. A reassessment notice or owner cost question: use locus-owner-cost-review at $0.25. The price includes one conservatively priced Turnkey signature. It leads with the recorded tax or assessment change, connects cited programs and dates, and returns ready calls for follow-up. It does not infer the cause or determine eligibility.
3. Rental operations for one property: use locus-rental-operations-brief at $0.79. It compares the third-party subject rent estimate with the ZIP rental-listing median, then returns ready calls for current local-record follow-up. It is not rent-setting advice or tenant screening.
4. Rental registration or license record: use free locus_rental_registration_check for an exact building in Minneapolis, Seattle, or New York City. It returns the source-published status, dates, units, linked housing-enforcement components, query limits, and verify-next questions. Agent-commerce callers may use the identical $0.01 REST locus-rental-registration-check dual. It never decides whether the dwelling may lawfully be rented or whether a person or property complies.
5. Rental-registration portfolio: use locus-record-batch at $0.05 with 2-25 exact addresses and lanes: ["locus_rental_registration_check"]. One async job returns results keyed by address. Addresses outside the three-city source registry remain explicit out-of-coverage items; do not treat them as unregistered.

These products return nextCalls[] instead of a prose narrative. Each call includes the exact tool, ready input, one-sentence why, supporting evidenceIds, cost, urgency, endpoint, and requiresPaymentApproval. cost is free or the exact dollar price from Locus's central price registry when the workflow was generated. costAtGeneration remains an identical compatibility alias. nextCallPlan.pricedAt timestamps the price snapshot; the next tool's live challenge remains authoritative. A small model may select and order only server-built candidate IDs. Locus owns and validates every returned tool name, argument object, price snapshot, evidence link, and payment flag. Model failure uses the deterministic candidate order. A paid next call is never executed without separate approval.

Paid product ladder (use one path)

Full inventory decisions: docs/PAID_TOOL_INVENTORY.md. Paid index entries also carry seeAlso for overlap routing.

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.

…(truncated)