alloc-context 0.2.0__tar.gz → 0.2.1__tar.gz

{alloc_context-0.2.0 → alloc_context-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alloc-context
-Version: 0.2.0
+Version: 0.2.1
 Summary: Portfolio-aware crypto context for agents — holdings, market, optional allocation analysis
 License: Elastic-2.0
 Project-URL: Homepage, https://github.com/negillett/alloc-context
@@ -9,7 +9,7 @@ Project-URL: Repository, https://github.com/negillett/alloc-context
 Project-URL: Issues, https://github.com/negillett/alloc-context/issues
 Project-URL: Changelog, https://github.com/negillett/alloc-context/releases
 Project-URL: MCP Server, https://mcp.alloc-context.com/mcp
-Keywords: mcp,x402,bitcoin,ethereum,portfolio,allocation,agents,crypto,rebalance
+Keywords: mcp,x402,bitcoin,ethereum,crypto,cryptocurrency,portfolio,allocation,holdings,rebalance,coinbase,kraken,agents
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -44,6 +44,9 @@ Dynamic: license-file
 
 # AllocContext
 
+[![smithery badge](https://smithery.ai/badge/@negillett/alloc-context)](https://smithery.ai/server/@negillett/alloc-context)
+[![Glama MCP server](https://glama.ai/mcp/servers/negillett/alloc-context/badges/score.svg)](https://glama.ai/mcp/servers/negillett/alloc-context)
+
 mcp-name: io.github.negillett/alloc-context
 
 **Portfolio-aware crypto context for agents** — discover holdings, market,
@@ -110,6 +113,7 @@ Not financial advice.
 | **Discovery** | [llms.txt](https://mcp.alloc-context.com/llms.txt), [x402 manifest](https://mcp.alloc-context.com/.well-known/x402.json) |
 | **Pricing** | **$0.02** cached context/math · **$0.05** live ingest or portfolio |
 | **Payment** | x402 on Base — USDC or EURC |
+| **Market scope** | Holdings-scoped (BTC/ETH OHLC; alt quote snapshots); bridge auto-scopes from portfolio |
 
 Agents and wallets connect directly to the hosted endpoint — see
 [agent-integration.md](docs/agent-integration.md). The Cursor bridge above
@@ -128,6 +132,11 @@ combines local portfolio reads with this upstream for market context.
 | `check_allocation_bands` | Batch band checks for multiple target scenarios |
 | `get_portfolio_state` | Live NAV and holdings from Kraken or Coinbase |
 
+Market context is **holdings-scoped**: band assets (BTC/ETH) use OHLC bars; alt
+holdings (e.g. HYPE) use quote snapshots when cached. The bridge auto-scopes
+`assets` from your portfolio (symbols only upstream). See
+[context-bundle.md#market-coverage](docs/context-bundle.md#market-coverage).
+
 See [mcp.md](docs/mcp.md) for arguments, pricing, and resources.
 
 ## Self-host and development

{alloc_context-0.2.0 → alloc_context-0.2.1}/README.md

@@ -1,5 +1,8 @@
 # AllocContext
 
+[![smithery badge](https://smithery.ai/badge/@negillett/alloc-context)](https://smithery.ai/server/@negillett/alloc-context)
+[![Glama MCP server](https://glama.ai/mcp/servers/negillett/alloc-context/badges/score.svg)](https://glama.ai/mcp/servers/negillett/alloc-context)
+
 mcp-name: io.github.negillett/alloc-context
 
 **Portfolio-aware crypto context for agents** — discover holdings, market,
@@ -66,6 +69,7 @@ Not financial advice.
 | **Discovery** | [llms.txt](https://mcp.alloc-context.com/llms.txt), [x402 manifest](https://mcp.alloc-context.com/.well-known/x402.json) |
 | **Pricing** | **$0.02** cached context/math · **$0.05** live ingest or portfolio |
 | **Payment** | x402 on Base — USDC or EURC |
+| **Market scope** | Holdings-scoped (BTC/ETH OHLC; alt quote snapshots); bridge auto-scopes from portfolio |
 
 Agents and wallets connect directly to the hosted endpoint — see
 [agent-integration.md](docs/agent-integration.md). The Cursor bridge above
@@ -84,6 +88,11 @@ combines local portfolio reads with this upstream for market context.
 | `check_allocation_bands` | Batch band checks for multiple target scenarios |
 | `get_portfolio_state` | Live NAV and holdings from Kraken or Coinbase |
 
+Market context is **holdings-scoped**: band assets (BTC/ETH) use OHLC bars; alt
+holdings (e.g. HYPE) use quote snapshots when cached. The bridge auto-scopes
+`assets` from your portfolio (symbols only upstream). See
+[context-bundle.md#market-coverage](docs/context-bundle.md#market-coverage).
+
 See [mcp.md](docs/mcp.md) for arguments, pricing, and resources.
 
 ## Self-host and development

{alloc_context-0.2.0 → alloc_context-0.2.1}/alloc_context.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alloc-context
-Version: 0.2.0
+Version: 0.2.1
 Summary: Portfolio-aware crypto context for agents — holdings, market, optional allocation analysis
 License: Elastic-2.0
 Project-URL: Homepage, https://github.com/negillett/alloc-context
@@ -9,7 +9,7 @@ Project-URL: Repository, https://github.com/negillett/alloc-context
 Project-URL: Issues, https://github.com/negillett/alloc-context/issues
 Project-URL: Changelog, https://github.com/negillett/alloc-context/releases
 Project-URL: MCP Server, https://mcp.alloc-context.com/mcp
-Keywords: mcp,x402,bitcoin,ethereum,portfolio,allocation,agents,crypto,rebalance
+Keywords: mcp,x402,bitcoin,ethereum,crypto,cryptocurrency,portfolio,allocation,holdings,rebalance,coinbase,kraken,agents
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -44,6 +44,9 @@ Dynamic: license-file
 
 # AllocContext
 
+[![smithery badge](https://smithery.ai/badge/@negillett/alloc-context)](https://smithery.ai/server/@negillett/alloc-context)
+[![Glama MCP server](https://glama.ai/mcp/servers/negillett/alloc-context/badges/score.svg)](https://glama.ai/mcp/servers/negillett/alloc-context)
+
 mcp-name: io.github.negillett/alloc-context
 
 **Portfolio-aware crypto context for agents** — discover holdings, market,
@@ -110,6 +113,7 @@ Not financial advice.
 | **Discovery** | [llms.txt](https://mcp.alloc-context.com/llms.txt), [x402 manifest](https://mcp.alloc-context.com/.well-known/x402.json) |
 | **Pricing** | **$0.02** cached context/math · **$0.05** live ingest or portfolio |
 | **Payment** | x402 on Base — USDC or EURC |
+| **Market scope** | Holdings-scoped (BTC/ETH OHLC; alt quote snapshots); bridge auto-scopes from portfolio |
 
 Agents and wallets connect directly to the hosted endpoint — see
 [agent-integration.md](docs/agent-integration.md). The Cursor bridge above
@@ -128,6 +132,11 @@ combines local portfolio reads with this upstream for market context.
 | `check_allocation_bands` | Batch band checks for multiple target scenarios |
 | `get_portfolio_state` | Live NAV and holdings from Kraken or Coinbase |
 
+Market context is **holdings-scoped**: band assets (BTC/ETH) use OHLC bars; alt
+holdings (e.g. HYPE) use quote snapshots when cached. The bridge auto-scopes
+`assets` from your portfolio (symbols only upstream). See
+[context-bundle.md#market-coverage](docs/context-bundle.md#market-coverage).
+
 See [mcp.md](docs/mcp.md) for arguments, pricing, and resources.
 
 ## Self-host and development

{alloc_context-0.2.0 → alloc_context-0.2.1}/alloc_context.egg-info/SOURCES.txt

@@ -62,6 +62,7 @@ alloccontext/mcp/bazaar.py
 alloccontext/mcp/bridge.py
 alloccontext/mcp/bridge_portfolio.py
 alloccontext/mcp/contracts.py
+alloccontext/mcp/glama.py
 alloccontext/mcp/handlers.py
 alloccontext/mcp/http.py
 alloccontext/mcp/instructions.py
@@ -70,6 +71,7 @@ alloccontext/mcp/payment_middleware.py
 alloccontext/mcp/server.py
 alloccontext/mcp/setup.py
 alloccontext/mcp/staleness.py
+alloccontext/mcp/tool_fields.py
 alloccontext/mcp/upstream.py
 alloccontext/mcp/validation.py
 alloccontext/mcp/x402_bazaar_dynamic.py
@@ -117,6 +119,7 @@ tests/test_etf.py
 tests/test_exchanges_config.py
 tests/test_fear_greed.py
 tests/test_fred.py
+tests/test_glama_well_known.py
 tests/test_holdings_scoped_delta_regime.py
 tests/test_holdings_scoped_market.py
 tests/test_horizon.py

{alloc_context-0.2.0 → alloc_context-0.2.1}/alloccontext/__init__.py

@@ -1,3 +1,3 @@
 """AllocContext — portfolio-aware crypto context for agents (MCP)."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"

{alloc_context-0.2.0 → alloc_context-0.2.1}/alloccontext/mcp/bazaar.py

@@ -43,28 +43,49 @@ SERVICE_TITLE = (
 # CDP Bazaar indexes service_name (≤32 chars) and up to five tags from payments.
 BAZAAR_SERVICE_NAME = "AllocContext portfolio MCP"
 SERVICE_TAGS = (
+    "crypto",
+    "cryptocurrency",
+    "bitcoin",
     "btc",
+    "ethereum",
     "eth",
     "holdings",
     "portfolio",
-    "crypto",
-    "bitcoin",
-    "agent-tools",
-    "mcp",
+    "allocation",
+    "rebalance",
     "sentiment",
     "macro",
-    "rebalance",
-    "allocation",
+    "coinbase",
+    "kraken",
+    "agent-tools",
+    "mcp",
+    "x402",
+)
+BAZAAR_INDEX_TAGS = (
+    "crypto",
+    "cryptocurrency",
+    "portfolio",
+    "holdings",
+    "btc",
 )
-BAZAAR_INDEX_TAGS = ("btc", "eth", "portfolio", "holdings", "mcp")
 
 DISCOVERY_KEYWORD_MARKERS = (
+    "crypto",
+    "cryptocurrency",
+    "digital assets",
+    "crypto portfolio",
     "portfolio allocation",
+    "portfolio context",
     "allocation drift",
     "rebalance plan",
     "fear and greed",
     "etf flows",
     "holdings",
+    "holdings-scoped",
+    "coinbase",
+    "kraken",
+    "market context",
+    "sentiment",
 )
 
 LISTING_DESCRIPTION = (
@@ -616,9 +637,12 @@ portfolio never persist on our servers.
 
 ## Search keywords
 
-bitcoin, ethereum, btc, eth, portfolio allocation, portfolio context, holdings,
-market context, sentiment, macro calendar, etf flows, allocation drift,
-rebalance plan, fear and greed, agent tools, mcp, x402
+bitcoin, ethereum, btc, eth, crypto, cryptocurrency, digital assets, altcoin,
+stablecoin, crypto portfolio, portfolio allocation, portfolio context, holdings,
+holdings-scoped, coinbase, kraken, market context, market data, sentiment,
+macro calendar, etf flows, allocation drift, allocation bands, rebalance plan,
+fear and greed, fear greed index, nav, agent tools, ai agents, mcp, x402,
+model context protocol, context bundle
 
 ## Examples
 
@@ -673,3 +697,32 @@ def build_well_known_x402(
             },
         },
     }
+
+
+def build_mcp_server_card(*, version: str) -> dict[str, Any]:
+    """Smithery static server card (SEP-1649) — free metadata when POST /mcp is x402."""
+    return {
+        "serverInfo": {
+            "name": SERVICE_TITLE,
+            "version": version,
+            "description": LISTING_DESCRIPTION,
+        },
+        "authentication": {
+            "required": True,
+            "schemes": ["x402"],
+            "description": (
+                "x402 exact payment on Base mainnet (USDC or EURC) per tool call; "
+                "see /.well-known/x402.json for pricing."
+            ),
+        },
+        "tools": [
+            {
+                "name": spec["tool_name"],
+                "description": spec["description"],
+                "inputSchema": spec["input_schema"],
+            }
+            for spec in _MCP_TOOLS
+        ],
+        "resources": [],
+        "prompts": [],
+    }

alloc_context-0.2.1/alloccontext/mcp/glama.py

@@ -0,0 +1,51 @@
+"""Glama connector well-known metadata (/.well-known/glama.json)."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+GLAMA_CONNECTOR_SCHEMA = "https://glama.ai/mcp/schemas/connector.json"
+
+
+def _repo_glama_json_path() -> Path:
+    # alloccontext/mcp/glama.py -> repo root (glama.json lives beside pyproject.toml)
+    return Path(__file__).resolve().parents[2] / "glama.json"
+
+
+def build_glama_well_known() -> dict[str, Any]:
+    """Load glama.json for Glama ownership verification on the hosted domain."""
+    path = _repo_glama_json_path()
+    if not path.is_file():
+        msg = f"glama.json not found at {path}"
+        raise FileNotFoundError(msg)
+
+    data = json.loads(path.read_text(encoding="utf-8"))
+    maintainers: list[dict[str, str]] = []
+
+    email_override = os.environ.get("GLAMA_MAINTAINER_EMAIL", "").strip()
+    if email_override:
+        maintainers = [{"email": email_override}]
+    else:
+        connector_emails = data.get("connector_emails") or []
+        for entry in connector_emails:
+            if isinstance(entry, str) and "@" in entry:
+                maintainers.append({"email": entry})
+        if not maintainers:
+            raw = data.get("maintainers") or []
+            for entry in raw:
+                if isinstance(entry, dict) and entry.get("email"):
+                    maintainers.append({"email": str(entry["email"])})
+                elif isinstance(entry, str) and "@" in entry:
+                    maintainers.append({"email": entry})
+
+    if not maintainers:
+        msg = "glama.json maintainers must include at least one email"
+        raise ValueError(msg)
+
+    return {
+        "$schema": GLAMA_CONNECTOR_SCHEMA,
+        "maintainers": maintainers,
+    }

{alloc_context-0.2.0 → alloc_context-0.2.1}/alloccontext/mcp/http.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import contextlib
+import json
 import os
 from collections.abc import AsyncIterator
 from typing import Any
@@ -12,9 +13,11 @@ from starlette.routing import Mount, Route
 
 from alloccontext.mcp.bazaar import (
     build_llms_txt,
+    build_mcp_server_card,
     build_well_known_x402,
     resolve_public_base_url,
 )
+from alloccontext.mcp.glama import build_glama_well_known
 from alloccontext.mcp.server import create_server
 from alloccontext.mcp.x402_config import (
     CDP_FACILITATOR_URL,
@@ -119,6 +122,26 @@ def _well_known_x402(settings: X402Settings) -> JSONResponse:
     return JSONResponse(payload)
 
 
+def _well_known_mcp_server_card() -> JSONResponse:
+    public_base = resolve_public_base_url()
+    if not public_base:
+        return JSONResponse({"error": "discovery metadata unavailable"}, status_code=404)
+    from alloccontext import __version__
+
+    return JSONResponse(build_mcp_server_card(version=__version__))
+
+
+def _well_known_glama() -> JSONResponse:
+    public_base = resolve_public_base_url()
+    if not public_base:
+        return JSONResponse({"error": "discovery metadata unavailable"}, status_code=404)
+    try:
+        payload = build_glama_well_known()
+    except (FileNotFoundError, ValueError, json.JSONDecodeError) as exc:
+        return JSONResponse({"error": str(exc)}, status_code=404)
+    return JSONResponse(payload)
+
+
 def _is_loopback_host(host: str) -> bool:
     normalized = host.strip().lower()
     return normalized in {"127.0.0.1", "localhost", "::1"}
@@ -154,6 +177,8 @@ def build_http_app(
         Route("/health", _make_health_handler(config_path)),
         Route("/llms.txt", lambda req: _llms_txt(settings)),
         Route("/.well-known/x402.json", lambda req: _well_known_x402(settings)),
+        Route("/.well-known/mcp/server-card.json", lambda req: _well_known_mcp_server_card()),
+        Route("/.well-known/glama.json", lambda req: _well_known_glama()),
     ]
 
     if not settings.enabled:

{alloc_context-0.2.0 → alloc_context-0.2.1}/alloccontext/mcp/server.py

@@ -6,6 +6,26 @@ from typing import Any
 from alloccontext.config import load_config
 from alloccontext.mcp import handlers
 from alloccontext.mcp.instructions import PRODUCT_INSTRUCTIONS, REBALANCE_HINT_GUIDE
+from alloccontext.mcp.tool_fields import (
+    AllocationPct,
+    ApiKey,
+    ApiSecret,
+    AsOf,
+    Assets,
+    BandDefault,
+    BandOptional,
+    CurrentAsOf,
+    Exchange,
+    ExchangeKrakenDefault,
+    Freshness,
+    MatchMode,
+    NavUsd,
+    OptionalTargetPct,
+    PriorAsOf,
+    Scenarios,
+    Scope,
+    TargetPct,
+)
 from alloccontext.store.db import connect
 
 
@@ -78,19 +98,21 @@ def create_server(
     @mcp.tool(
         name="get_context_bundle",
         description=(
-            "Full ContextBundle JSON: portfolio holdings, market, sentiment, "
-            "macro, regime hints, and delta vs the prior saved snapshot. Optional "
-            "assets filter (default BTC, ETH). Optional target_pct and band attach "
-            "allocation_analysis (opt-in drift math). freshness=cached uses the "
-            "local ingest DB; freshness=live runs ingest first."
+            "Return the full read-only ContextBundle JSON: portfolio holdings, "
+            "market, sentiment, macro, regime hints, and delta vs the prior saved "
+            "snapshot. Use get_market_context for market-only; use get_context_at "
+            "for a historical snapshot; use get_context_delta to compare two times. "
+            "Optional target_pct and band attach allocation_analysis (opt-in drift "
+            "math). freshness=cached uses the local ingest DB; freshness=live runs "
+            "ingest first (may add latency; needs ingest API keys on the host)."
         ),
     )
     def get_context_bundle(
-        scope: str = "daily",
-        freshness: str = "cached",
-        assets: list[str] | None = None,
-        target_pct: dict[str, float] | None = None,
-        band: float | None = None,
+        scope: Scope = "daily",
+        freshness: Freshness = "cached",
+        assets: Assets = None,
+        target_pct: OptionalTargetPct = None,
+        band: BandOptional = None,
     ) -> dict[str, Any]:
         """Return the full deterministic context bundle for daily or weekly scope."""
         validated_scope = handlers.validate_scope(scope)
@@ -112,16 +134,17 @@ def create_server(
     @mcp.tool(
         name="get_market_context",
         description=(
-            "Fused market backdrop: sentiment (Fear & Greed, Kalshi), macro events, "
-            "FRED indicators, ETF flows, and market breadth. Optional assets filter "
-            "(default BTC, ETH). freshness=cached uses the local ingest DB; "
+            "Return read-only fused market backdrop: sentiment (Fear & Greed, "
+            "Kalshi), macro events, FRED indicators, ETF flows, and market breadth "
+            "(no portfolio holdings). Use get_context_bundle when you also need "
+            "holdings, delta, or regime. freshness=cached uses the local ingest DB; "
             "freshness=live runs ingest first (requires ingest API keys on the host)."
         ),
     )
     def get_market_context(
-        scope: str = "daily",
-        freshness: str = "cached",
-        assets: list[str] | None = None,
+        scope: Scope = "daily",
+        freshness: Freshness = "cached",
+        assets: Assets = None,
     ) -> dict[str, Any]:
         """Return ContextBundle subset for daily or weekly scope."""
         validated_scope = handlers.validate_scope(scope)
@@ -141,18 +164,22 @@ def create_server(
     @mcp.tool(
         name="get_rebalance_plan",
         description=(
-            "USD deltas and exchange-style move lines to reach a target BTC/ETH/CASH "
-            "split. Requires allocation_pct, target_pct, and nav_usd. Optional band "
-            "returns a band_check block alongside the plan. exchange=kraken|coinbase "
-            "adjusts move wording."
+            "Compute read-only USD deltas and suggested exchange move lines to "
+            "reach a BTC/ETH/CASH target split. Pure math — no exchange API calls. "
+            "Requires allocation_pct, target_pct, and nav_usd. Use "
+            "get_portfolio_state or get_context_bundle when you need live or cached "
+            "weights first. Use check_allocation_band for pass/fail drift only; use "
+            "check_allocation_bands for multiple scenarios. Optional band adds a "
+            "band_check block alongside the plan. exchange=kraken|coinbase adjusts "
+            "move wording only."
         ),
     )
     def get_rebalance_plan(
-        allocation_pct: dict[str, float],
-        target_pct: dict[str, float],
-        nav_usd: float,
-        exchange: str = "kraken",
-        band: float | None = None,
+        allocation_pct: AllocationPct,
+        target_pct: TargetPct,
+        nav_usd: NavUsd,
+        exchange: ExchangeKrakenDefault = "kraken",
+        band: BandOptional = None,
     ) -> dict[str, Any]:
         """Compute rebalance plan from current allocation and NAV."""
         return handlers.get_rebalance_plan(
@@ -166,18 +193,21 @@ def create_server(
     @mcp.tool(
         name="get_portfolio_state",
         description=(
-            "Live portfolio NAV, holdings[], and band weights from read-only "
-            "exchange credentials passed in the request. Optional target_pct "
-            "attaches allocation_analysis. Credentials are never stored. "
-            "Supports kraken and coinbase."
+            "Fetch live read-only portfolio NAV, holdings[], and band weights from "
+            "Kraken or Coinbase credentials passed in this call (never stored). "
+            "Requires exchange, api_key, and api_secret. Use get_context_bundle "
+            "for cached market and history without exchange keys. Optional "
+            "target_pct attaches allocation_analysis; optional band sets drift "
+            "width when target_pct is supplied. Returns an error payload on invalid "
+            "credentials or unsupported exchange — no side effects."
         ),
     )
     def get_portfolio_state(
-        exchange: str,
-        api_key: str,
-        api_secret: str,
-        target_pct: dict[str, float] | None = None,
-        band: float | None = None,
+        exchange: Exchange,
+        api_key: ApiKey,
+        api_secret: ApiSecret,
+        target_pct: OptionalTargetPct = None,
+        band: BandOptional = None,
     ) -> dict[str, Any]:
         """Fetch live portfolio state using caller-supplied read-only API keys."""
         return handlers.get_portfolio_state(
@@ -192,16 +222,19 @@ def create_server(
     @mcp.tool(
         name="check_allocation_band",
         description=(
-            "Check whether BTC/ETH/CASH band weights are outside a drift band vs "
-            "target_pct and return hint (within_band, consider_rebalance, etc.). "
-            "All three inputs are required. For bundle drift, pass target_pct on "
-            "get_context_bundle to attach allocation_analysis."
+            "Read-only drift check: are BTC/ETH/CASH band weights outside the "
+            "drift band vs target_pct? Returns rebalance_hint (within_band, "
+            "consider_rebalance, etc.). Requires allocation_pct and target_pct; "
+            "band defaults to 0.15. Single-scenario only — use check_allocation_bands "
+            "for multiple targets in one call. Use get_rebalance_plan when you need "
+            "USD move lines, not just a hint. For bundle drift, pass target_pct on "
+            "get_context_bundle to attach allocation_analysis instead."
         ),
     )
     def check_allocation_band(
-        allocation_pct: dict[str, float],
-        target_pct: dict[str, float],
-        band: float = 0.15,
+        allocation_pct: AllocationPct,
+        target_pct: TargetPct,
+        band: BandDefault = 0.15,
     ) -> dict[str, Any]:
         """Evaluate allocation drift against band width (default 0.15 = 15%)."""
         return handlers.check_band(allocation_pct, target_pct, band)
@@ -209,18 +242,20 @@ def create_server(
     @mcp.tool(
         name="get_context_at",
         description=(
-            "Load a saved ContextBundle snapshot from ingest history. "
-            "as_of is an ISO timestamp; match=at_or_before returns the latest "
-            "snapshot on or before that time."
+            "Load a read-only ContextBundle snapshot from ingest history at a "
+            "point in time. Use get_context_bundle for the latest snapshot; use "
+            "get_context_delta to compare two timestamps. Read-only; returns an "
+            "unavailable payload when no snapshot matches as_of and match. Optional "
+            "target_pct and band attach allocation_analysis to the historical bundle."
         ),
     )
     def get_context_at(
-        as_of: str,
-        scope: str = "daily",
-        match: str = "at_or_before",
-        assets: list[str] | None = None,
-        target_pct: dict[str, float] | None = None,
-        band: float | None = None,
+        as_of: AsOf,
+        scope: Scope = "daily",
+        match: MatchMode = "at_or_before",
+        assets: Assets = None,
+        target_pct: OptionalTargetPct = None,
+        band: BandOptional = None,
     ) -> dict[str, Any]:
         validated_scope = handlers.validate_scope(scope)
         if match not in ("exact", "at_or_before"):
@@ -243,15 +278,18 @@ def create_server(
     @mcp.tool(
         name="get_context_delta",
         description=(
-            "Compare two ContextBundle snapshots and return notable_shifts. "
-            "prior_as_of is required; omit current_as_of for latest live bundle."
+            "Compare two read-only ContextBundle snapshots and return "
+            "notable_shifts between them. Requires prior_as_of; omit current_as_of "
+            "to diff against the latest live bundle. Use get_context_at to load one "
+            "snapshot without diffing. Read-only; no ingest unless you combine with "
+            "a live current_as_of path."
         ),
     )
     def get_context_delta(
-        prior_as_of: str,
-        scope: str = "daily",
-        current_as_of: str | None = None,
-        assets: list[str] | None = None,
+        prior_as_of: PriorAsOf,
+        scope: Scope = "daily",
+        current_as_of: CurrentAsOf = None,
+        assets: Assets = None,
     ) -> dict[str, Any]:
         validated_scope = handlers.validate_scope(scope)
         conn = connect(config.paths.db)
@@ -270,14 +308,16 @@ def create_server(
     @mcp.tool(
         name="check_allocation_bands",
         description=(
-            "Evaluate allocation drift against multiple target_pct/band "
-            "scenarios in one call. Each scenario needs target_pct; optional "
-            "name and band (default 0.15)."
+            "Read-only batch drift check: evaluate allocation_pct against multiple "
+            "target_pct/band scenarios in one call. Each scenario requires "
+            "target_pct; optional name and band (default 0.15). Use "
+            "check_allocation_band for a single target. Use get_rebalance_plan when "
+            "you need USD move lines after identifying drift."
         ),
     )
     def check_allocation_bands(
-        allocation_pct: dict[str, float],
-        scenarios: list[dict[str, Any]],
+        allocation_pct: AllocationPct,
+        scenarios: Scenarios,
     ) -> dict[str, Any]:
         return handlers.check_allocation_bands(allocation_pct, scenarios)