seattle-open-data 0.1.0__tar.gz

seattle_open_data-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Connelly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

seattle_open_data-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: seattle-open-data
+Version: 0.1.0
+Summary: Agent-friendly MCP server for Seattle Open Data (data.seattle.gov, Socrata SODA).
+Keywords: seattle,open-data,socrata,soda,mcp,agent
+Author: Brian Connelly
+Author-email: Brian Connelly <bdc@bconnelly.net>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Dist: fastmcp>=4.1.0,<4.2
+Requires-Dist: httpx>=0.28
+Requires-Dist: ijson>=3.3
+Requires-Dist: pydantic>=2
+Requires-Dist: tzdata>=2025.2
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/briandconnelly/seattle-open-data
+Project-URL: Repository, https://github.com/briandconnelly/seattle-open-data
+Project-URL: Issues, https://github.com/briandconnelly/seattle-open-data/issues
+Project-URL: Changelog, https://github.com/briandconnelly/seattle-open-data/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# seattle-open-data
+
+[![CI](https://github.com/briandconnelly/seattle-open-data/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/briandconnelly/seattle-open-data/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fbriandconnelly%2Fseattle-open-data%2Fmain%2Fpyproject.toml)](pyproject.toml)
+[![License: MIT](https://img.shields.io/github/license/briandconnelly/seattle-open-data)](LICENSE)
+
+An agent-friendly [MCP](https://modelcontextprotocol.io/) server for [Seattle Open Data](https://data.seattle.gov/) (Socrata SODA2).
+
+**Status: alpha (0.1.0).** All four tools work against the live portal, with curated guides for seven flagship datasets. See [evals/results](evals/results) for the agent evaluation.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `seattle_data_search_datasets` | Find datasets by topic |
+| `seattle_data_describe_dataset` | Columns, row count, time coverage, place fields, geo columns |
+| `seattle_data_query_dataset` | Bounded reads and aggregates (SoQL clauses or raw SoQL) |
+| `seattle_data_get_reference` | Capability summary, SoQL help, guides, error catalog |
+
+## Run
+
+```bash
+uv run seattle-open-data          # stdio
+```
+
+Claude Code:
+
+```bash
+claude mcp add seattle-open-data -- uv run --directory /path/to/seattle-open-data seattle-open-data
+```
+
+Optional: set `SOCRATA_APP_TOKEN` to use a Socrata application token. A rejected token is reported as `app_token_rejected`, never silently dropped.
+
+To build the installable MCPB bundle (needs the `mcpb` CLI): `make mcpb`.
+
+## Develop
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check && uv run ruff format --check && uv run ty check
+UPDATE_SNAPSHOTS=1 uv run pytest tests/test_contract.py   # after an intended tool-surface change
+uv run pytest --run-integration -m integration            # live tests against data.seattle.gov
+uv run python evals/run.py [--host claude|codex] <out_dir> [task_id ...]
+uv run python evals/report.py <out_dir> --answers
+```
+
+## Release
+
+Tag `vX.Y.Z` after bumping the version: the release workflow builds and smoke-tests the wheel, sdist, and `.mcpb`, publishes to PyPI after maintainer approval, and attaches all three to a GitHub Release. See [docs/releasing.md](docs/releasing.md) for the steps, the TestPyPI rehearsal, and one-time setup.
+
+## License
+
+MIT

seattle_open_data-0.1.0/README.md

@@ -0,0 +1,54 @@
+# seattle-open-data
+
+[![CI](https://github.com/briandconnelly/seattle-open-data/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/briandconnelly/seattle-open-data/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fbriandconnelly%2Fseattle-open-data%2Fmain%2Fpyproject.toml)](pyproject.toml)
+[![License: MIT](https://img.shields.io/github/license/briandconnelly/seattle-open-data)](LICENSE)
+
+An agent-friendly [MCP](https://modelcontextprotocol.io/) server for [Seattle Open Data](https://data.seattle.gov/) (Socrata SODA2).
+
+**Status: alpha (0.1.0).** All four tools work against the live portal, with curated guides for seven flagship datasets. See [evals/results](evals/results) for the agent evaluation.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `seattle_data_search_datasets` | Find datasets by topic |
+| `seattle_data_describe_dataset` | Columns, row count, time coverage, place fields, geo columns |
+| `seattle_data_query_dataset` | Bounded reads and aggregates (SoQL clauses or raw SoQL) |
+| `seattle_data_get_reference` | Capability summary, SoQL help, guides, error catalog |
+
+## Run
+
+```bash
+uv run seattle-open-data          # stdio
+```
+
+Claude Code:
+
+```bash
+claude mcp add seattle-open-data -- uv run --directory /path/to/seattle-open-data seattle-open-data
+```
+
+Optional: set `SOCRATA_APP_TOKEN` to use a Socrata application token. A rejected token is reported as `app_token_rejected`, never silently dropped.
+
+To build the installable MCPB bundle (needs the `mcpb` CLI): `make mcpb`.
+
+## Develop
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check && uv run ruff format --check && uv run ty check
+UPDATE_SNAPSHOTS=1 uv run pytest tests/test_contract.py   # after an intended tool-surface change
+uv run pytest --run-integration -m integration            # live tests against data.seattle.gov
+uv run python evals/run.py [--host claude|codex] <out_dir> [task_id ...]
+uv run python evals/report.py <out_dir> --answers
+```
+
+## Release
+
+Tag `vX.Y.Z` after bumping the version: the release workflow builds and smoke-tests the wheel, sdist, and `.mcpb`, publishes to PyPI after maintainer approval, and attaches all three to a GitHub Release. See [docs/releasing.md](docs/releasing.md) for the steps, the TestPyPI rehearsal, and one-time setup.
+
+## License
+
+MIT

seattle_open_data-0.1.0/pyproject.toml

@@ -0,0 +1,142 @@
+[project]
+name = "seattle-open-data"
+version = "0.1.0"
+description = "Agent-friendly MCP server for Seattle Open Data (data.seattle.gov, Socrata SODA)."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "seattle",
+    "open-data",
+    "socrata",
+    "soda",
+    "mcp",
+    "agent",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+]
+dependencies = [
+    "fastmcp>=4.1.0,<4.2",
+    "httpx>=0.28",
+    "ijson>=3.3",
+    "pydantic>=2",
+    "tzdata>=2025.2",
+]
+
+[[project.authors]]
+name = "Brian Connelly"
+email = "bdc@bconnelly.net"
+
+[project.urls]
+Homepage = "https://github.com/briandconnelly/seattle-open-data"
+Repository = "https://github.com/briandconnelly/seattle-open-data"
+Issues = "https://github.com/briandconnelly/seattle-open-data/issues"
+Changelog = "https://github.com/briandconnelly/seattle-open-data/blob/main/CHANGELOG.md"
+
+[project.scripts]
+seattle-open-data = "seattle_open_data.mcp.server:main"
+
+[dependency-groups]
+dev = [
+    "jsonschema>=4.26.0",
+    "prek>=0.2",
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5",
+    "ruff>=0.15",
+    "ty>=0.0.1a1",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.0,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "B",
+    "UP",
+    "SIM",
+    "PIE",
+    "RUF",
+    "PL",
+    "PT",
+    "TID",
+    "TCH",
+    "ARG",
+    "PTH",
+]
+ignore = [
+    "PLR0913",
+    "PLR0917",
+    "PLR2004",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/seattle_open_data/core/reference.py" = ["E501"]
+"src/seattle_open_data/core/guides.py" = ["E501"]
+"tests/**" = [
+    "ARG",
+    "PLR2004",
+    "S101",
+    "TC002",
+    "TC003",
+    "PT018",
+    "PLC0415",
+    "RUF002",
+    "RUF003",
+]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.ty.src]
+include = [
+    "src",
+    "tests",
+]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+]
+asyncio_mode = "auto"
+markers = [
+    "integration: live data.seattle.gov tests (skipped by default; run with --run-integration)",
+    "soda_fixture(name, overrides=None): record or replay tests/fixtures/http/<name>.json",
+]
+
+[tool.coverage.run]
+source = ["src/seattle_open_data"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+]
+show_missing = true

seattle_open_data-0.1.0/pyproject.toml.orig

@@ -0,0 +1,91 @@
+[project]
+name = "seattle-open-data"
+version = "0.1.0"
+description = "Agent-friendly MCP server for Seattle Open Data (data.seattle.gov, Socrata SODA)."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Brian Connelly", email = "bdc@bconnelly.net" },
+]
+keywords = ["seattle", "open-data", "socrata", "soda", "mcp", "agent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+]
+dependencies = [
+    "fastmcp>=4.1.0,<4.2",
+    "httpx>=0.28",
+    "ijson>=3.3",
+    "pydantic>=2",
+    "tzdata>=2025.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/briandconnelly/seattle-open-data"
+Repository = "https://github.com/briandconnelly/seattle-open-data"
+Issues = "https://github.com/briandconnelly/seattle-open-data/issues"
+Changelog = "https://github.com/briandconnelly/seattle-open-data/blob/main/CHANGELOG.md"
+
+[project.scripts]
+seattle-open-data = "seattle_open_data.mcp.server:main"
+
+[dependency-groups]
+dev = [
+    "jsonschema>=4.26.0",
+    "prek>=0.2",
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5",
+    "ruff>=0.15",
+    "ty>=0.0.1a1",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.0,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "PIE", "RUF", "PL", "PT", "TID", "TCH", "ARG", "PTH"]
+ignore = ["PLR0913", "PLR0917", "PLR2004"]
+
+[tool.ruff.lint.per-file-ignores]
+# Reference prose and worked JSON examples read better unwrapped.
+"src/seattle_open_data/core/reference.py" = ["E501"]
+"src/seattle_open_data/core/guides.py" = ["E501"]
+"tests/**" = ["ARG", "PLR2004", "S101", "TC002", "TC003", "PT018", "PLC0415", "RUF002", "RUF003"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.ty.src]
+include = ["src", "tests"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = ["-ra", "--strict-markers", "--strict-config"]
+asyncio_mode = "auto"
+markers = [
+    "integration: live data.seattle.gov tests (skipped by default; run with --run-integration)",
+    "soda_fixture(name, overrides=None): record or replay tests/fixtures/http/<name>.json",
+]
+
+[tool.coverage.run]
+source = ["src/seattle_open_data"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = ["pragma: no cover", "if TYPE_CHECKING:", "if __name__ == .__main__.:"]
+show_missing = true

seattle_open_data-0.1.0/src/seattle_open_data/__init__.py

@@ -0,0 +1,5 @@
+"""Agent-friendly MCP server for Seattle Open Data."""
+
+from importlib.metadata import version
+
+__version__ = version("seattle-open-data")

seattle_open_data-0.1.0/src/seattle_open_data/constants.py

@@ -0,0 +1,129 @@
+"""Seattle portal facts (docs/design.md: Scope).
+
+Extract a `Portal` type only when a second portal arrives.
+"""
+
+from __future__ import annotations
+
+from zoneinfo import ZoneInfo
+
+SERVER_NAME = "seattle-open-data"
+TOOL_PREFIX = "seattle_data_"
+URI_SCHEME = "seattle-data"
+
+PUBLIC_HOST = "data.seattle.gov"
+#: The Discovery API indexes Seattle under this name; `domains=data.seattle.gov` returns nothing.
+CATALOG_DOMAIN = "cos-data.seattle.gov"
+DISCOVERY_API = "https://api.us.socrata.com/api/catalog/v1"
+
+SEATTLE_TZ = ZoneInfo("America/Los_Angeles")
+
+DATASET_ID_PATTERN = r"^[a-z0-9]{4}-[a-z0-9]{4}$"
+
+SEARCH_PAGE_SIZE_MAX = 50
+QUERY_PAGE_SIZE_MAX = 500
+QUERY_LOGICAL_CAP = 10_000
+QUERY_TEXT_MAX_BYTES = 4096
+SAMPLE_ROWS_MAX = 5
+
+RESULT_BYTE_BUDGET = 24 * 1024
+TOOLS_LIST_BYTE_BUDGET = 24 * 1024
+
+CACHE_TTL_SECONDS = 3600
+
+INSTRUCTIONS_SENTINEL = "END SEATTLE OPEN DATA INSTRUCTIONS"
+
+UPSTREAM_TIMEOUT_SECONDS = 30.0
+DESCRIBE_AGGREGATE_TIMEOUT_SECONDS = 10.0
+UPSTREAM_MAX_BYTES = 8 * 1024 * 1024
+CURSOR_TTL_SECONDS = 3600
+
+#: Values publishers use instead of null in text place fields (docs/upstream-facts.md).
+PLACEHOLDER_VALUES = frozenset({"-", "UNKNOWN", "NULL", "OOJ", "FK ERROR", "X", "0", ""})
+
+#: Computed-region layers seen on Seattle datasets; label columns and dates verified 2026-10-15.
+REGION_LAYERS: dict[str, dict[str, str]] = {
+    "ru88-fbhk": {
+        "kind": "neighborhood",
+        "label_column": "name",
+        "vintage": "SPD Micro Community Policing Plan Areas, updated 2016-03-03",
+        "reliability": "ok",
+    },
+    "kuhn-3gp2": {
+        "kind": "beat",
+        "label_column": "name",
+        "vintage": "SPD Beats, updated 2015-07-17 (51 beats; current SPD beats differ)",
+        "reliability": "partial",
+        "reason": "2015 beat boundaries; current SPD beats differ.",
+    },
+    "q256-3sug": {
+        "kind": "zip",
+        "label_column": "zcta5ce10",
+        "vintage": "2010 ZIP Code Tabulation Areas (national), updated 2015-02-19",
+        "reliability": "ok",
+    },
+    "cyqu-gs94": {
+        "kind": "council_district",
+        "label_column": "c_district",
+        "vintage": "City Council Districts, updated 2015-07-20 (predates 2022 redistricting)",
+        "reliability": "unreliable",
+        "reason": "Mostly null, only districts 1-3 appear, and the boundaries predate 2022.",
+    },
+    "2day-rhn5": {
+        "kind": "census_tract",
+        "label_column": "name10",
+        "vintage": "2010 Census Tracts, updated 2015-05-16",
+        "reliability": "unreliable",
+        "reason": "Mostly null on Seattle datasets; 2010 tracts.",
+    },
+}
+
+#: Text place fields per dataset, with reliability from the 2026-10-15 probe
+#: (docs/upstream-facts.md).
+PLACE_FIELDS: dict[str, dict[str, dict[str, str]]] = {
+    "33kz-ixgy": {
+        "dispatch_neighborhood": {"kind": "neighborhood", "reliability": "ok"},
+        "dispatch_precinct": {"kind": "precinct", "reliability": "ok"},
+        "dispatch_sector": {"kind": "sector", "reliability": "ok"},
+        "dispatch_beat": {"kind": "beat", "reliability": "ok"},
+    },
+    "tazs-3rd5": {
+        "neighborhood": {
+            "kind": "neighborhood",
+            "reliability": "partial",
+            "reason": "Placeholder ('-') for nearly all offenses before 2017; 1-4% missing since. "
+            "Do not use for 2008-2016.",
+        },
+        "precinct": {"kind": "precinct", "reliability": "ok"},
+        "sector": {"kind": "sector", "reliability": "ok"},
+        "beat": {"kind": "beat", "reliability": "ok"},
+    },
+    "ppi5-g2bj": {
+        "precinct": {"kind": "precinct", "reliability": "ok"},
+        "sector": {"kind": "sector", "reliability": "ok"},
+        "beat": {"kind": "beat", "reliability": "ok"},
+    },
+    "76t5-zqzr": {
+        "originalzip": {"kind": "zip", "reliability": "ok"},
+    },
+}
+
+#: Timezone evidence per dataset column; absent means unknown, never assumed.
+TIME_EVIDENCE: dict[str, dict[str, dict[str, str]]] = {
+    "kzjm-xkqj": {
+        "datetime": {
+            "timezone": "America/Los_Angeles",
+            "evidence": "max(datetime) tracked Pacific wall-clock time when probed 2026-10-15.",
+        },
+    },
+}
+
+GEO_TYPES = frozenset({"point", "location"})
+TIME_TYPES = frozenset({"floating_timestamp", "calendar_date", "fixed_timestamp", "date"})
+
+#: Upper bound written into download_url; SODA2 accepted it when probed 2026-10-15.
+DOWNLOAD_LIMIT = 1_000_000_000
+URL_MAX_CHARS = 2048
+#: Whole-call deadlines, metadata fetch included; tool descriptions state these.
+QUERY_DEADLINE_SECONDS = 30.0
+DESCRIBE_DEADLINE_SECONDS = 30.0

seattle_open_data-0.1.0/src/seattle_open_data/core/arguments.py

@@ -0,0 +1,96 @@
+"""Cross-argument rules the JSON Schema cannot express portably (docs/design.md: Primitives).
+
+Single-field constraints (types, enums, ranges, patterns, empty strings) live in
+the published inputSchema; only combinations are checked here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from seattle_open_data.constants import QUERY_TEXT_MAX_BYTES
+from seattle_open_data.core import cursor as cursors
+from seattle_open_data.core.errors import ErrorCode, ErrorDetails, Repair, SeattleDataError
+
+CLAUSE_ARGS = ("select", "where", "group_by", "having", "order_by", "search_text", "near")
+
+
+def _provided(args: dict[str, Any]) -> list[str]:
+    return [name for name, value in args.items() if value is not None]
+
+
+def _reject(fields: list[str], reason: str, *, tool: str, repair: Repair | None = None) -> None:
+    details = (
+        ErrorDetails(field=fields[0], reason=reason)
+        if len(fields) == 1
+        else ErrorDetails(fields=fields, reason=reason)
+    )
+    raise SeattleDataError(
+        ErrorCode.INVALID_ARGUMENT,
+        f"Invalid argument combination for {tool}.",
+        details=details,
+        repair=repair,
+    )
+
+
+def check_continuation(args: dict[str, Any], *, allowed: set[str], tool: str) -> None:
+    if args.get("cursor") is None:
+        return
+    extra = sorted(set(_provided(args)) - allowed - {"cursor"})
+    if extra:
+        _reject(
+            extra,
+            "A cursor continues the original query; send only "
+            + ", ".join(sorted(allowed | {"cursor"}))
+            + ".",
+            tool=tool,
+        )
+
+
+def check_search(args: dict[str, Any]) -> None:
+    check_continuation(args, allowed={"detail", "page_size"}, tool="seattle_data_search_datasets")
+
+
+def check_query(args: dict[str, Any]) -> None:
+    tool = "seattle_data_query_dataset"
+    check_continuation(args, allowed={"dataset_id", "detail", "page_size"}, tool=tool)
+    if args.get("cursor") is not None:
+        return
+    mode = args.get("mode") or "clauses"
+    if mode == "soql":
+        if args.get("soql") is None:
+            _reject(["soql"], "mode='soql' requires soql.", tool=tool)
+        clauses = [name for name in CLAUSE_ARGS if args.get(name) is not None]
+        if clauses:
+            _reject(
+                clauses,
+                "mode='soql' runs soql verbatim; clause arguments are not allowed.",
+                tool=tool,
+            )
+        return
+    if args.get("soql") is not None:
+        _reject(["soql"], "soql requires mode='soql'.", tool=tool)
+    # Measured as a cursor stores the clauses, so the cap also bounds the cursor (≤ 6 KiB).
+    present = {n: _plain(args[n]) for n in CLAUSE_ARGS if args.get(n) is not None}
+    if len(cursors.dump(present)) > QUERY_TEXT_MAX_BYTES:
+        _reject(
+            list(present),
+            f"Clause arguments exceed {QUERY_TEXT_MAX_BYTES} bytes in total, measured as JSON.",
+            tool=tool,
+        )
+
+
+def check_reference(args: dict[str, Any]) -> None:
+    tool = "seattle_data_get_reference"
+    topic = args.get("topic") or "index"
+    if args.get("item_id") is not None and topic in ("index", "capabilities"):
+        _reject(
+            ["topic", "item_id"],
+            f"Topic '{topic}' has no items; item_id needs soql, errors, or guides.",
+            tool=tool,
+            repair=Repair(next_step="list_topics", tool=tool, arguments={}),
+        )
+
+
+def _plain(value: Any) -> Any:
+    return value.model_dump() if hasattr(value, "model_dump") else value