Location params on best_local_bid / latest_prices (zip / GPS + radius)

Thread zip/lat/lng/radius_miles through the client and both tools; friendly
guard for the zip-XOR-gps rule. Formatters surface distance, the searched
center, and the nearest-source hint when nothing is in range.

- client: best()/latest() take zip/lat/lng/radius_miles
- server: location params + docstrings (note Ohio-concentrated coverage)
- format: distance column + center/nearest rendering
- README + CHANGELOG + advisor prompt library updated
- tests: location formatting cases

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

ag_bids_mcp/format.py

@@ -73,21 +73,56 @@ def _first_last(points: list[dict], field: str):
 # ---------- best_local_bid ----------
 
 
+def _loc_suffix(d: dict) -> str:
+    """' (City, ST)' when a row/result carries city/state, else ''."""
+    city, state = d.get("city"), d.get("state")
+    if city and state:
+        return f" ({city}, {state})"
+    return f" ({state})" if state else ""
+
+
+def _mi(d) -> str:
+    return "—" if d is None else f"{d:.1f} mi"
+
+
+def _where(center: dict) -> str:
+    """Human label for a resolved center point."""
+    if center.get("source") == "zip":
+        return f"ZIP {center.get('zip')}"
+    near = f" (near {center.get('zip')})" if center.get("zip") else ""
+    return f"{center['lat']:.4f}, {center['lng']:.4f}{near}"
+
+
 def fmt_best(commodity: str, payload: dict) -> str:
     best = payload.get("best")
     today = payload.get("today")
+    center = payload.get("center")
+    radius = payload.get("radius_miles")
+    scope = f" within {radius:.0f} mi of {_where(center)}" if center else ""
+    head = f"### Best place to sell {commodity} today ({today})\n\n"
     if not best:
-        return (
-            f"### Best place to sell {commodity} today ({today})\n\n"
-            f"No current-month {commodity} bids posted across the tracked sources.\n"
-        )
-    return (
-        f"### Best place to sell {commodity} today ({today})\n\n"
-        f"**{best['source_name']}** — delivery **{best['delivery']}** — "
-        f"bid **{_bu(best['bid_cents'])}/bu** (basis {_basis(best.get('basis_cents'))}, "
-        f"futures {best.get('futures_contract') or '—'})\n\n"
-        f"_Fetched {best.get('fetched_at') or '?'}_\n"
+        if center:
+            out = head + f"No current-month {commodity} bids{scope}.\n"
+            near = payload.get("nearest")
+            if near:
+                out += (f"\nNearest tracked elevator: **{near['source_name']}**"
+                        f"{_loc_suffix(near)} — about **{_mi(near.get('distance_miles'))}** "
+                        f"away, outside the {radius:.0f} mi radius.\n")
+            return out
+        return head + f"No current-month {commodity} bids posted across the tracked sources.\n"
+    dist = best.get("distance_miles")
+    dist_txt = f" — **{_mi(dist)}** away" if dist is not None else ""
+    out = (
+        head
+        + f"**{best['source_name']}**{_loc_suffix(best)}{dist_txt} — delivery "
+        f"**{best['delivery']}** — bid **{_bu(best['bid_cents'])}/bu** "
+        f"(basis {_basis(best.get('basis_cents'))}, "
+        f"futures {best.get('futures_contract') or '—'})\n"
     )
+    if center:
+        out += f"\n_Searched{scope}._\n"
+    out += f"\n_Fetched {best.get('fetched_at') or '?'}_\n"
+    return out
 
 
 # ---------- reference price trends (USDA NASS / EIA) ----------
@@ -235,20 +270,31 @@ def fmt_inputs(payload: dict) -> str:
 
 def fmt_latest(payload: dict) -> str:
     rows = payload.get("rows") or []
+    center = payload.get("center")
+    radius = payload.get("radius_miles")
     if not rows:
-        return "### Latest prices\n\nNo rows match those filters.\n"
+        head = "### Latest prices\n\n"
+        if center:
+            return head + f"No sources within {radius:.0f} mi of {_where(center)}.\n"
+        return head + "No rows match those filters.\n"
+    title = "### Latest prices"
+    if center:
+        title += f" — within {radius:.0f} mi of {_where(center)}"
+    dist_col = " Distance |" if center else ""
+    dist_sep = " ---: |" if center else ""
     lines = [
-        "### Latest prices", "",
-        "| Source | Commodity | Delivery | Bid | Basis | Futures | Fetched |",
-        "|---|---|---|---:|---:|---|---|",
+        title, "",
+        f"| Source | Commodity | Delivery | Bid | Basis | Futures |{dist_col} Fetched |",
+        f"|---|---|---|---:|---:|---|{dist_sep}---|",
     ]
     for r in rows:
         unit_fmt = _ton if r.get("commodity_kind") == "fertilizer" else _bu
+        dist_cell = f" {_mi(r.get('distance_miles'))} |" if center else ""
         lines.append(
             f"| {r['source_name']} | {r.get('display_name') or r['commodity']} | "
             f"{r['delivery']} | {unit_fmt(r.get('bid_cents'))} | "
-            f"{_basis(r.get('basis_cents'))} | {r.get('futures_contract') or '—'} | "
-            f"{r.get('fetched_at') or '?'} |"
+            f"{_basis(r.get('basis_cents'))} | {r.get('futures_contract') or '—'} |"
+            f"{dist_cell} {r.get('fetched_at') or '?'} |"
         )
     return "\n".join(lines) + "\n"