@velinussage/locus-agent-skill 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +74 -0
  2. package/package.json +13 -2
  3. package/skill/locus-agent-tools/SKILL.md +242 -60
package/README.md ADDED
@@ -0,0 +1,74 @@
1
+ # @velinussage/locus-agent-skill
2
+
3
+ [![skills.sh](https://skills.sh/b/velinussage/locus-agent-skill)](https://skills.sh/velinussage/locus-agent-skill)
4
+
5
+ Install the Locus agent skill for agents that need cited property and local-government context over MCP, REST, A2A, free tools, and x402 paid reports.
6
+
7
+ Locus returns awareness and verification steps, not a verdict. Do not use it to score, rank, screen, value, predict, or label a person, property, block, or neighborhood as safe or unsafe.
8
+
9
+ ## Install with this package
10
+
11
+ ```bash
12
+ npx @velinussage/locus-agent-skill add
13
+ ```
14
+
15
+ By default this writes `locus-agent-tools/SKILL.md` to `$CODEX_HOME/skills` or `~/.codex/skills`.
16
+
17
+ Options:
18
+
19
+ ```bash
20
+ npx @velinussage/locus-agent-skill add --target ./skills
21
+ npx @velinussage/locus-agent-skill add --target ./skills --force
22
+ npx @velinussage/locus-agent-skill --print
23
+ ```
24
+
25
+ ## Install with GitHub CLI
26
+
27
+ ```bash
28
+ gh skill install velinussage/locus-agent-skill locus-agent-tools
29
+ ```
30
+
31
+ Preview first:
32
+
33
+ ```bash
34
+ gh skill preview velinussage/locus-agent-skill locus-agent-tools
35
+ ```
36
+
37
+ ## Install with skills.sh
38
+
39
+ The same skill is also available from the public GitHub repo through the open `skills` CLI:
40
+
41
+ ```bash
42
+ npx skills add velinussage/locus-agent-skill --skill locus-agent-tools
43
+ ```
44
+
45
+ Useful variants:
46
+
47
+ ```bash
48
+ npx skills add velinussage/locus-agent-skill --skill locus-agent-tools -g
49
+ npx skills add velinussage/locus-agent-skill --skill locus-agent-tools -a claude-code -a codex
50
+ npx skills use velinussage/locus-agent-skill --skill locus-agent-tools
51
+ ```
52
+
53
+ ## Connect to Locus MCP
54
+
55
+ ```json
56
+ {
57
+ "mcpServers": {
58
+ "locus": {
59
+ "type": "http",
60
+ "url": "https://mcp.locus.report/mcp"
61
+ }
62
+ }
63
+ }
64
+ ```
65
+
66
+ ## What the skill teaches agents
67
+
68
+ - 19 national free tools work for any geocodable US address.
69
+ - `locus_place_facts` is the best first call when supported.
70
+ - `locus_lane_availability` shows national, local, varies, not-covered, and degraded lanes before payment.
71
+ - Free tools stay read-only and cited.
72
+ - Paid tools use x402 and require explicit user authorization.
73
+
74
+ Docs: <https://docs.locus.report/skill.md>
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@velinussage/locus-agent-skill",
3
- "version": "0.1.0",
4
- "description": "Install the Locus agent skill for MCP, free tools, and x402-paid property-context workflows.",
3
+ "version": "0.1.2",
4
+ "description": "Install the Locus agent skill with npx or skills.sh for MCP, free tools, and x402-paid property-context workflows.",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "locus-agent-skill": "bin/locus-agent-skill.js"
@@ -14,10 +14,21 @@
14
14
  "test": "node --test test/*.test.mjs",
15
15
  "pack:check": "npm pack --dry-run"
16
16
  },
17
+ "repository": {
18
+ "type": "git",
19
+ "url": "git+https://github.com/velinussage/locus.git",
20
+ "directory": "packages/locus-agent-skill"
21
+ },
22
+ "homepage": "https://docs.locus.report/skill.md",
23
+ "bugs": {
24
+ "url": "https://github.com/velinussage/locus/issues"
25
+ },
17
26
  "keywords": [
18
27
  "locus",
19
28
  "mcp",
20
29
  "x402",
30
+ "skills",
31
+ "skills.sh",
21
32
  "real-estate",
22
33
  "agent-tools",
23
34
  "public-records"
package/skill/locus-agent-tools/SKILL.md CHANGED
@@ -1,17 +1,33 @@
1
1
  ---
2
2
  name: locus-agent-tools
3
- description: Use when an agent needs to connect to Locus over MCP, REST, A2A, AgentCash, x402, or free tools for cited property and local-government context. Triggers include Locus MCP, mcp.locus.report, locus free tools, locus_execute, locus_search_tools, x402 Locus reports, real-estate due diligence, coverage preflight, lane availability, source-card checks, parcel/zoning/flood/permit/tax/policy context, and address-first public-record workflows.
3
+ preamble-tier: 1
4
+ version: 1.3.0
5
+ description: Use when an agent needs to connect to Locus over MCP, A2A, or REST for property and local-government context.
6
+ triggers:
7
+ - locus agent tools
8
+ - mcp or rest for locus
9
+ - a2a locus
10
+ allowed-tools: Bash Read AskUserQuestion
11
+ license: MIT
4
12
  ---
5
13
 
6
- # Locus Agent Tools
14
+ # Locus Agent Capabilities
7
15
 
8
- Use Locus when a place-based workflow needs cited public-record context: taxes, parcels, zoning, flood, environmental records, permits, development activity, transportation projects, local policy, source coverage, or monitoring. Locus returns awareness and verification steps, not a verdict.
16
+ 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`](https://github.com/velinussage/locus/blob/main/docs/AGENT_CAPABILITIES.md).
9
17
 
10
- Do not use Locus to score, rank, screen, value, predict, or label a person, property, block, or neighborhood as safe or unsafe.
18
+ 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.
19
+
20
+ ## What to remember first
21
+
22
+ - **19 national tools work for any US address, for free, with no payment or coverage check needed.** Use them for rural addresses too, including flood zone, flood gauges, FEMA events, NOAA storms, radon, wildfire risk, cleanup sites, toxic releases, water systems, representatives, governing districts, fair-market rents, nearby places, ordinance leads, and data-center/source-discovery prompts.
23
+ - **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.
24
+ - **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.
25
+ - **Use `locus_lane_availability` before paid calls.** It maps national, local, varies, not-covered, and degraded lanes, then gives per-paid-tool buy recommendations.
26
+ - **Do not memorize paid prices from this skill.** 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.
11
27
 
12
28
  ## Quick connect
13
29
 
14
- Install this skill in Codex-style agents with:
30
+ Install this skill in Codex-style agents:
15
31
 
16
32
  ```bash
17
33
  npx @velinussage/locus-agent-skill add
@@ -30,66 +46,193 @@ Remote MCP server:
30
46
  }
31
47
  ```
32
48
 
33
- Authoritative live discovery:
49
+ A2A and REST discovery:
34
50
 
35
- - MCP catalog: <https://mcp.locus.report/catalog>
36
- - Free REST catalog: <https://api.locus.report/tools/list>
37
- - Paid tool index: <https://api.locus.report/.well-known/ai-tool/index.json>
38
- - A2A Agent Card: <https://api.locus.report/.well-known/agent-card.json>
39
- - API base: <https://api.locus.report>
51
+ - [Agent Card](https://api.locus.report/.well-known/agent-card.json) - A2A skills and message endpoint.
52
+ - [Free tool catalog](https://api.locus.report/tools/list) - free tool schemas, descriptions, and read-only metadata.
53
+ - [Paid tool index](https://api.locus.report/.well-known/ai-tool/index.json) - current prices, schemas, and manifests.
54
+ - [MCP catalog](https://mcp.locus.report/catalog) - searchable tool catalog.
55
+ - [API base](https://api.locus.report) - health and discovery links.
40
56
 
41
57
  The live catalogs are authoritative for tool names, schemas, prices, and endpoints. Do not copy stale tool definitions into prompts.
42
58
 
43
- ## MCP tool pattern
59
+ ## Two coverage tools, know the difference
44
60
 
45
- The remote MCP server exposes two tools:
61
+ - **`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.
62
+ - **`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.
63
+ - **`locus_coverage_map {}`** returns the whole registry view. Use it when an agent needs breadth, not one address.
46
64
 
47
- 1. `locus_search_tools` — search the live catalog across free and paid capabilities.
48
- 2. `locus_execute` — run one selected catalog tool by exact name.
65
+ ## Workflow
49
66
 
50
- Use this loop:
67
+ 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.
68
+ 2. **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.
69
+ 3. **For local depth, check availability for the exact place.** Call `locus_lane_availability { "place": "<ZIP or address>" }`, then call only the lanes it marks `available`. For `varies`, call the free tool once and let its returned coverage/status decide.
70
+ 4. **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.
71
+ 5. **Ground every fact.** Answer only from returned artifacts. Include source names, links or locators, fetched timestamps where present, and caveats.
72
+ 6. **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.
51
73
 
52
- ```text
53
- place + user goal
54
- -> search the live catalog
55
- -> choose the smallest useful tool
56
- -> run free coverage/source diagnostics before paid analysis
57
- -> execute one tool
58
- -> answer only from returned artifacts
59
- -> show caveats and verify-next steps
60
- ```
74
+ ## Reading `locus_lane_availability`
61
75
 
62
- Example discovery call:
76
+ `locus_lane_availability` returns a top-level result with `place`, `resolved`, `jurisdiction`, `lanes`, `buyRecommendations`, `recommendedCallOrder`, `relatedTools`, and `warnings`.
77
+
78
+ Statuses and buckets:
79
+
80
+ - **`lanes.national[]`** - free national or metadata tools. These are usable for any resolved US address.
81
+ - **`lanes.local[]`** - tools with wired sources here, including paid national bundles when applicable.
82
+ - **`lanes.varies[]`** - source may resolve. Call the free tool to confirm before relying on it or paying.
83
+ - **`lanes.notCovered[]`** - skip it. Tell the user this lane is not wired and offer `locus_request_coverage`.
84
+ - **`lanes.degraded[]`** - upstream source is temporarily failing or reduced. Use the suggested fallback.
85
+ - **`buyRecommendations[]`** - paid tool guidance with `priceUsdc`, `substanceHere`, `rationale`, endpoint, and manifest.
86
+
87
+ Trimmed response example for a rural Montana ZIP:
63
88
 
64
89
  ```json
65
90
  {
66
- "query": "coverage parcel flood zoning permits Raleigh address",
67
- "tier": "all",
68
- "limit": 8
91
+ "ok": true,
92
+ "tool": "locus_lane_availability",
93
+ "result": {
94
+ "place": "59047",
95
+ "resolved": true,
96
+ "jurisdiction": {
97
+ "jurisdictionId": "us-mt-park",
98
+ "displayName": "Park County, MT",
99
+ "stack": { "state": "MT", "county": "Park County" }
100
+ },
101
+ "lanes": {
102
+ "national": [
103
+ { "tool": "locus_flood_zone", "what": "FEMA flood-zone designation at the point", "access": "free" },
104
+ { "tool": "locus_radon_zone", "what": "EPA radon zone for the county", "access": "free" },
105
+ { "tool": "locus_wildfire_risk", "what": "FEMA NRI wildfire risk rating", "access": "free" },
106
+ { "tool": "locus_representatives", "what": "Cited state + federal officials for the point", "access": "free" }
107
+ ],
108
+ "varies": [
109
+ { "tool": "locus_zoning", "access": "free", "why": "point zoning may resolve; rich coverage only in wired counties" }
110
+ ],
111
+ "notCovered": [
112
+ { "tool": "locus_place_facts", "access": "free", "why": "needs a wired parcel backbone", "requestTool": "locus_request_coverage" }
113
+ ],
114
+ "degraded": [
115
+ { "tool": "locus_housing_stock", "access": "free", "why": "upstream Census geocoder is failing" }
116
+ ]
117
+ },
118
+ "buyRecommendations": [
119
+ { "slug": "locus-place-report", "priceUsdc": "0.05", "substanceHere": "low", "rationale": "Coverage varies. Confirm the free component lanes first." },
120
+ { "slug": "locus-environmental-context", "priceUsdc": "0.05", "substanceHere": "medium", "rationale": "Wired national EPA/SDWIS sources resolve here." }
121
+ ],
122
+ "warnings": [
123
+ "Not covered does not mean no records exist. It only means Locus has no wired source yet."
124
+ ]
125
+ }
69
126
  }
70
127
  ```
71
128
 
72
- Example execution call:
129
+ A paid tool flagged not covered returns a free diagnostic, never a payment challenge.
130
+
131
+ ## Free tools by question, arguments, and output
132
+
133
+ 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.
134
+
135
+ ### Start here and coverage
136
+
137
+ | The question | Tool | Exact arguments | What it returns |
138
+ |---|---|---|---|
139
+ | 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. |
140
+ | 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. |
141
+ | What is the whole coverage registry? | `locus_coverage_map` | `{}` | Registry-level coverage inventory for tools and jurisdictions. |
142
+ | Request coverage for a missing place | `locus_request_coverage` | `{ "place": "Park County, MT" }` | Acknowledgement and demand signal. No records. |
143
+ | 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. |
144
+ | Verify a citation URL | `locus_verify_citation` | `{ "sourceUrl": "https://...", "recordId": "optional", "jurisdiction": "optional" }` | Whether a citation matches a known source card, with provenance context. |
145
+ | What policy sources govern here? | `locus_policy_sources` | `{ "place": "Raleigh, NC" }` | State, county, city policy-source list, legal geographies, source links. |
146
+ | Read aggregate coverage demand | `locus_coverage_demand` | `{}` | Aggregate requested-coverage demand, not place records. |
147
+
148
+ ### Best first call for supported address context
149
+
150
+ | The question | Tool | Exact arguments | What it returns |
151
+ |---|---|---|---|
152
+ | 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. |
153
+ | 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. |
154
+ | Multiple caller-supplied parcels | `locus_parcel_set` | `{ "addresses": ["addr 1", "addr 2"] }` | Normalized facts for up to 25 supplied addresses in an assemblage. |
155
+
156
+ ### 19 national free content tools
157
+
158
+ 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.
159
+
160
+ | The question | Tool | Exact arguments | What it returns |
161
+ |---|---|---|---|
162
+ | 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. |
163
+ | Nearby flood gauges | `locus_flood_gauges` | `{ "address": "...", "radiusMeters": 20000 }` | Nearby USGS/NWS gauges, latest stage/flow observations when available, threshold metadata, source links. |
164
+ | Governing districts | `locus_governing_districts` | `{ "address": "..." }` | Congressional, state senate, state house, county, municipality, and other governing geographies when resolved. |
165
+ | Representatives | `locus_representatives` | `{ "address": "..." }` | Cited federal and state officials for the address, districts, party/office/contact links where available. |
166
+ | Wildfire risk | `locus_wildfire_risk` | `{ "address": "..." }` | FEMA NRI tract-level wildfire rating, score, expected annual loss fields where returned, provenance, caveats. |
167
+ | 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. |
168
+ | 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. |
169
+ | Toxic releases | `locus_toxic_releases` | `{ "state": "MT", "county": "Park County" }` | EPA TRI facilities for the county, chemical-release reporting fields where available, profile links. |
170
+ | 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. |
171
+ | 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. |
172
+ | Public water systems | `locus_water_systems` | `{ "state": "MT", "county": "Park County" }` | Active public water systems serving the county, PWSIDs, SDWIS/ECHO links. |
173
+ | 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. |
174
+ | 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`. |
175
+ | 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. |
176
+ | HUD fair-market rents | `locus_fair_market_rents` | `{ "stateFips": "30", "countyFips3": "067", "year": 2026 }` | HUD FMR values by bedroom count and county/FIPS basis. |
177
+ | Nearby places and amenities | `locus_nearby_places` | `{ "address": "...", "radiusMeters": 800 }` | OpenStreetMap nearby amenities/places with categories, distance, and OSM provenance. |
178
+ | 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 watch leads for large projects, data centers, utility/water/planning sources. |
179
+ | 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. |
180
+ | Coastal county catalog | `locus_coastal_county_catalog` | `{}` or `{ "county": "new-hanover-nc" }` | Catalog of supported coastal source packs, overlays, source leads, and limitations. |
181
+
182
+ Temporarily degraded national tools may appear in `lanes.degraded`, such as `locus_regulated_facility_compliance` or `locus_housing_stock`. If degraded, use the suggested fallback from lane availability.
183
+
184
+ ### Local or coverage-dependent free tools
185
+
186
+ | The question | Tool | Exact arguments | What it returns |
187
+ |---|---|---|---|
188
+ | 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. |
189
+ | Development or rezoning nearby | `locus_development_cases` | `{ "address": "...", "radiusMeters": 1500 }` | Nearby development/rezoning case records, statuses, dates, identifiers, citations where wired. |
190
+ | Public capital projects nearby | `locus_capital_projects` | `{ "address": "...", "radiusMeters": 1609 }` | Government capital projects, public works, assessments where wired, with project ids and source links. |
191
+ | 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. |
192
+ | Transportation projects and traffic counts | `locus_transportation_context` | `{ "address": "...", "radiusMeters": 2000 }` | State DOT funded projects, traffic-count stations, routes, statuses where wired. |
193
+ | Transit stops and routes | `locus_transit_context` | `{ "address": "...", "radiusMeters": 400 }` | Transit stops, routes, shelter/ADA fields, headways where supported. |
194
+ | Recent nearby parcel transfers | `locus_parcel_transfers` | `{ "address": "...", "radiusMeters": 1500, "monthsBack": 12 }` | Recorded sales/transfers near the point where parcel-sale sources are wired. |
195
+ | Property-tax rates | `locus_property_tax_rates` | `{ "place": "Wake County, NC" }` | Adopted rate components and jurisdiction basis where wired. |
196
+ | Property-tax estimate | `locus_property_tax_estimate` | `{ "address": "..." }` | Estimated annual property tax from assessed value and rates where wired. Not a valuation. |
197
+ | Tax calendar | `locus_tax_calendar` | `{ "county": "Wake" }` | Appeal/payment/revaluation calendar for supported counties. |
198
+ | 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. |
199
+ | Local legislation preview | `locus_local_legislation` | `{ "address": "..." }` | Recent property-relevant legislation preview, status labels, source attribution. Not legal advice. |
200
+ | 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. |
201
+ | 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. |
202
+ | ACS housing stock | `locus_housing_stock` | `{ "address": "..." }` | Census tract housing units, tenure, median rent/value, year built when upstream is healthy. |
203
+ | EPA facility compliance | `locus_regulated_facility_compliance` | `{ "address": "...", "radiusMeters": 5000 }` | EPA ECHO facility compliance and inspection/enforcement summary when upstream is healthy. |
204
+
205
+ ## Worked example: address to free tools to answer
206
+
207
+ User: *"What should I know about 600 E 4th St, Charlotte, NC 28202?"*
208
+
209
+ 1. Call `locus_lane_availability { "place": "600 E 4th St, Charlotte, NC 28202" }`.
210
+ 2. If `locus_place_facts` is available, call `locus_place_facts { "address": "600 E 4th St, Charlotte, NC 28202" }` first.
211
+ 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.
212
+ 4. Skip not-covered lanes and say so. Offer `locus_request_coverage` for missing local lanes.
213
+ 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.
214
+
215
+ ## A2A call shape
73
216
 
74
217
  ```json
75
218
  {
76
- "name": "locus_lane_availability",
77
- "arguments": {
78
- "place": "1 E Edenton St, Raleigh, NC 27601"
219
+ "message": {
220
+ "role": "ROLE_USER",
221
+ "parts": [
222
+ {
223
+ "data": {
224
+ "locusTool": "locus_lane_availability",
225
+ "arguments": { "place": "Raleigh, NC" }
226
+ }
227
+ }
228
+ ]
79
229
  }
80
230
  }
81
231
  ```
82
232
 
83
- ## Free tools first
84
-
85
- Prefer free tools for discovery, coverage, source-card status, citation provenance, policy-source checks, parcel diagnostics, environmental preflights, and not-covered responses. Useful starting points:
233
+ Send broad natural-language requests to your own planner first. Locus expects a concrete tool and arguments.
86
234
 
87
- - `locus_lane_availability` — per-address preflight showing which lanes and paid tools can return data here, with buy signals.
88
- - `locus_coverage_check` — coverage status for one place.
89
- - `locus_coverage_map` — registry-level coverage map.
90
- - `locus_source_card_status` / citation and provenance tools — source health and evidence diagnostics.
91
-
92
- Free REST fallback:
235
+ ## Free REST examples
93
236
 
94
237
  ```bash
95
238
  curl https://api.locus.report/tools/list
@@ -97,31 +240,55 @@ curl https://api.locus.report/tools/list
97
240
  curl -X POST https://api.locus.report/tools/call \
98
241
  -H 'content-type: application/json' \
99
242
  -d '{"name":"locus_lane_availability","arguments":{"place":"1 E Edenton St, Raleigh, NC 27601"}}'
243
+
244
+ curl -X POST https://api.locus.report/tools/call \
245
+ -H 'content-type: application/json' \
246
+ -d '{"name":"locus_place_facts","arguments":{"address":"1 E Edenton St, Raleigh, NC 27601"}}'
247
+ ```
248
+
249
+ ## MCP call pattern
250
+
251
+ 1. Call `locus_search_tools` with the user intent, place, and known source category.
252
+ 2. Choose the smallest matching tool from the returned catalog.
253
+ 3. Call `locus_execute` with:
254
+
255
+ ```json
256
+ {
257
+ "name": "<catalog tool name>",
258
+ "arguments": {
259
+ "address": "<street address>"
260
+ }
261
+ }
100
262
  ```
101
263
 
102
- Free tools are read-only or bounded participation endpoints. They do not return full paid briefs or compiled place reports.
264
+ 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.
103
265
 
104
- ## Paid tools and x402
266
+ ## Paid report rules
105
267
 
106
- Paid tools include place reports, local trend briefs, local policy briefs, before-you-sign bundles, and environmental context products. Use the paid tool index for current names, schemas, prices, and manifests.
268
+ - Unsupported or discovery-only places return a free diagnostic, not a payment challenge.
269
+ - Do not rely on remembered price ranges. 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.
270
+ - The price, network, asset, and recipient appear before payment.
271
+ - Paid results return only after settlement succeeds.
272
+ - Payment metadata binds to the tool and a canonical hash of arguments, not the raw address.
273
+ - Use live catalogs instead of copying prices or schemas.
107
274
 
108
- When a paid call returns an x402 challenge:
275
+ ## x402 payment flow
109
276
 
110
- - Show the user the tool name, price, chain/network, asset, recipient, and what will be generated.
111
- - Do not auto-pay or retry automatically.
112
- - Retry only after explicit user authorization and wallet/payment context.
113
- - Preserve settlement proof and any returned report headers or artifact URLs.
277
+ The compiled paid tools (`locus-place-report`, `locus-local-trend-brief`, `locus-local-policy-brief`, `locus-before-you-sign`, `locus-environmental-context`) are gated with x402 micropayments in USDC on Base. The flow is identical over REST, MCP, and A2A:
114
278
 
115
- Unsupported or discovery-only places should return free diagnostics instead of a silent charge.
279
+ 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.
280
+ 2. A covered place returns **HTTP 402** with `{ "x402Version": 2, "accepts": [{ "scheme": "exact", "network", "maxAmountRequired", "payTo", "asset", "extra": { "assetTransferMethod": "eip3009" } }] }`. Read live values from the challenge.
281
+ 3. Sign an EIP-3009 USDC authorization for `maxAmountRequired` 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.
282
+ 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.
116
283
 
117
- ## Answer boundaries
284
+ ## Safety rules
118
285
 
119
286
  Keep answers in this shape:
120
287
 
121
- - What Locus returned from cited artifacts.
288
+ - What Locus found from returned artifacts.
122
289
  - Why it may matter for the property question.
123
- - Source names, official URLs or locators, fetched timestamps, and caveats when returned.
124
- - What to verify next with an agency, landlord, insurer, contractor, seller, property manager, counsel, or another relevant source.
290
+ - Source links or locators and caveats where returned.
291
+ - What to verify next with an agency, landlord, insurer, contractor, seller, property manager, or other relevant source.
125
292
 
126
293
  Redirect these asks back to records plus verification questions:
127
294
 
@@ -132,8 +299,23 @@ Redirect these asks back to records plus verification questions:
132
299
 
133
300
  ## Failure handling
134
301
 
135
- - Unsupported place: return the diagnostic and name coverage or source gaps.
136
- - Empty result: say no matching records were returned by that source, not that no records exist.
137
- - Source conflict: show both records and name the agency/source to verify with.
138
- - Payment challenge: ask for authorization before retrying.
139
- - User asks for a verdict: decline that part and offer property-context records plus verification questions.
302
+ - **Unsupported place:** return the coverage/source diagnostic and suggest the official source to check next.
303
+ - **Empty result:** say no matching records were returned by that source, not that no records exist.
304
+ - **Payment challenge:** do not retry automatically. Ask for authorization.
305
+ - **Source conflict:** show both records and name which agency/source to verify with.
306
+ - **User asks for a verdict:** decline that part and offer property-context records plus verification questions.
307
+
308
+ ## Minimal answer shape
309
+
310
+ ```text
311
+ Here is what Locus returned for this place:
312
+
313
+ - [Fact or status] - Source: [source name], [official URL/locator if returned].
314
+ - [Why it may matter / coverage caveat].
315
+
316
+ Verify next:
317
+ - [Agency/source/link/question].
318
+
319
+ Limit:
320
+ - This is property-context awareness, not a score, screening decision, valuation, legal advice, or safe/unsafe label.
321
+ ```