Add contract coverage test and docs

Author: senseibelbi

README.md

@@ -214,7 +214,7 @@ Every successful tool invocation returns structured payloads designed for agents
 - Applicability-domain definitions, policy defaults, and remediation steps live under `metadata/` with JSON Schema validation.
 - Predictive invocations persist audit bundles that can be fetched via metadata tools.
 - Governance workflows (SME review, policy approval, publication) are documented in `docs/model_cards_and_policies.md`.
-- Response contracts live under `docs/contracts/schemas/` and are enforced before MCP responses (and predictive HTTP endpoints) are returned; upstream failover policies are summarized in `docs/contracts/endpoint-matrix.md`.
+- Response contracts live under `docs/contracts/schemas/` (see `docs/contracts/README.md`) and are enforced before MCP responses (and predictive HTTP endpoints) are returned; upstream failover policies are summarized in `docs/contracts/endpoint-matrix.md`.
 
 ### Testing & quality gates
 

docs/contracts/README.md

@@ -0,0 +1,9 @@
+# Contract Metadata
+
+All MCP tool responses are backed by JSON Schemas stored under `docs/contracts/schemas/`. Whenever you add a new tool or transport surface, follow these steps:
+
+1. **Author the schema** – drop a Draft 2020-12 schema in the appropriate namespace (e.g., `common/`, `hazard/`, `predictive/`). Favor the shared schemas in `docs/contracts/schemas/common/` when possible.
+2. **Reference it in the tool definition** – include `"responseSchemaRef": schema_ref("namespace", "file.json")` in the resource's `get_tools()` entry (or expose a concrete `outputSchema`).
+3. **Update tests if needed** – `tests/test_tool_contracts.py` enforces that every tool has either a `responseSchemaRef` or `outputSchema`, so missing contracts will fail CI automatically.
+
+This workflow keeps MCP responses stable for downstream agents and makes future schema coverage straightforward.

tests/test_tool_contracts.py

@@ -0,0 +1,30 @@
+"""Ensure every MCP tool defines a response schema/output schema."""
+
+from epacomp_tox.resources.bioactivity import BioactivityResource
+from epacomp_tox.resources.chemical import ChemicalResource
+from epacomp_tox.resources.chemical_list import ChemicalListResource
+from epacomp_tox.resources.cheminformatics import CheminformaticsResource
+from epacomp_tox.resources.exposure import ExposureResource
+from epacomp_tox.resources.hazard import HazardResource
+from epacomp_tox.resources.metadata import MetadataResource
+
+
+RESOURCE_FACTORIES = {
+    "chemical": lambda: ChemicalResource(api_key="fake"),
+    "chemical_list": lambda: ChemicalListResource(api_key="fake"),
+    "cheminformatics": lambda: CheminformaticsResource(api_key="fake"),
+    "bioactivity": lambda: BioactivityResource(api_key="fake"),
+    "exposure": lambda: ExposureResource(api_key="fake"),
+    "hazard": lambda: HazardResource(api_key="fake"),
+    "metadata": lambda: MetadataResource(api_key="fake"),
+}
+
+
+def test_all_tools_declare_response_schemas() -> None:
+    missing = []
+    for name, factory in RESOURCE_FACTORIES.items():
+        resource = factory()
+        for tool in resource.get_tools():
+            if not tool.get("responseSchemaRef") and not tool.get("outputSchema"):
+                missing.append(f"{name}:{tool['name']}")
+    assert not missing, f"Missing response schema for: {', '.join(missing)}"