@@ -8,6 +8,30 @@ adheres to [Semantic Versioning](https://semver.org/).
 
 ### Added
 
+### Changed
+
+### Fixed
+
+## [0.6.7] - 2026-07-03
+
+### Added
+
+- **MCP `ToolAnnotations` on every tool** — all 252 tools now publish
+  `readOnlyHint` (185 read-only / 67 write-capable) and `openWorldHint`
+  on the wire, derived mechanically from the same READ / WRITE / DDL /
+  SHELL / LISTEN capability gates that already enforce access, so a
+  moved tool can never ship a stale hint. Clients like Claude Desktop
+  use these to decide which calls to auto-approve — MCPg's safety
+  classification is now visible to them, not just internal.
+  `openWorldHint` is `false` everywhere except `translate_nl_to_sql`
+  (the one tool that calls an external LLM API). `destructiveHint` is
+  deliberately left unset for write-capable tools: the MCP default
+  (true) is the cautious reading. A contract test pins the derivation
+  exhaustively: the hinted read-only set must equal the surface
+  actually reachable in read-only access mode.
+- **Prompt argument descriptions** — all 7 arguments across the 3 MCP
+  prompts (`diagnose_slow_query`, `bisect_slow_migration`,
+  `review_rls_policy`) now carry wire-visible descriptions.
 - **`mcpg --demo` / `mcpg --demo-drop`** (roadmap **17.1**) — one-shot CLI
   commands that seed / remove a small, deterministic, curated e-commerce
   demo dataset (400 customers, 120 products, 3,000 orders, 900 reviews)
@@ -36,6 +60,22 @@ adheres to [Semantic Versioning](https://semver.org/).
 
 ### Fixed
 
+- **Startup warning noise eliminated.** Running MCPg printed a wall of
+  benign pydantic `Field name "schema" ... shadows an attribute in
+  parent "BaseModel"` warnings on the first `tools/list` call (the
+  `mcp` SDK builds a pydantic model from each tool-return dataclass,
+  and `schema` — the natural name for "which Postgres schema" — collides
+  with a deprecated pydantic v1 shim). The specific message is now
+  suppressed at import time; renaming the field would have broken every
+  affected tool's JSON output shape. A contract test builds the full
+  tool surface and asserts zero shadow warnings leak.
+- **TestPyPI smoke-test race in the publish pipeline.** The
+  wait-for-indexing step polled TestPyPI's JSON API, which can report a
+  release "ready" before the PEP 503 simple index (what `pip install`
+  actually reads) catches up — observed on the v0.6.6 release, which
+  needed a manual re-run. The step now polls the simple index directly
+  and retry-wraps the install.
+
 ## [0.6.6] - 2026-07-01
 
 ### Added
 
@@ -39,7 +39,9 @@ graph queries, data movement, live ops, and more.
   `[A-Za-z_][A-Za-z0-9_]*` regex — a design constraint that means
   user input never reaches the database through string concatenation.
   Capabilities like DDL, shell, and `LISTEN/NOTIFY` are off until you
-  opt in.
+  opt in. Every tool publishes MCP `ToolAnnotations` (`readOnlyHint`,
+  `openWorldHint`) derived from those same gates, so clients can
+  auto-approve reads and gate writes without guessing.
 - **One server, broad surface.** Application data access (queries, search,
   cursors, NL→SQL) *and* DBA-grade operations (health checks, index tuning,
   EXPLAIN analysis, locks, vacuum, dumps, replicas, migrations) in a
 
@@ -51,6 +51,7 @@ them" — pick the section that matches what you're trying to do.
   retrospectives.
 - [**Progress log**](PROGRESS.md) — chronological build log.
 - Release notes:
+  [v0.6.7](release-notes-0.6.7.md) ·
   [v0.6.6](release-notes-0.6.6.md) ·
   [v0.6.5](release-notes-0.6.5.md) ·
   [v0.6.4](release-notes-0.6.4.md) ·
 
@@ -0,0 +1,85 @@
+# MCPg v0.6.7 — release notes
+
+**Released:** 2026-07-03
+**Tool surface:** **252** tools across 19 capability buckets
+**Tests:** 2741 pass (PG 14 / 15 / 16 / 17 / 18 / 19 / WarehousePG)
+**Runtime:** Python 3.14
+
+This is a **patch-level bump (0.6.6 → 0.6.7)** focused on the client
+experience: the safety classification now reaches the wire, a curated
+demo dataset gives new users a rich first five minutes, and the runtime
+moves to Python 3.14. No tool signatures changed; everything is
+backward-compatible.
+
+## Headline: MCPg's safety model is now on the wire
+
+Every one of the 252 tools now publishes **MCP `ToolAnnotations`**:
+
+- **`readOnlyHint`** — `true` for the 185 read tools, `false` for the
+  67 write-capable ones. Derived mechanically from the same
+  READ / WRITE / DDL / SHELL / LISTEN capability gates that enforce
+  access, so a tool moved between gates can never ship a stale hint.
+  A contract test pins the derivation exhaustively: the hinted
+  read-only set must equal the tool surface actually reachable in
+  read-only access mode.
+- **`openWorldHint`** — `false` everywhere except `translate_nl_to_sql`
+  (the one tool that calls an external LLM API); everything else talks
+  only to the connected PostgreSQL server.
+- `destructiveHint` is deliberately left unset for write-capable tools:
+  the MCP default (true) is the cautious reading.
+
+Clients like Claude Desktop use these hints to decide which calls to
+auto-approve — until now MCPg's "safe by default" story was internal;
+now it's visible to every MCP client. The 3 MCP prompts' arguments all
+carry wire-visible descriptions too.
+
+## Try MCPg in two minutes: the demo dataset
+
+```bash
+MCPG_DATABASE_URL=postgresql://... mcpg --demo       # seed
+MCPG_DATABASE_URL=postgresql://... mcpg --demo-drop  # remove
+```
+
+`mcpg --demo` seeds a small, deterministic, **curated** e-commerce
+dataset (400 customers, 120 products, 3,000 orders, 900 reviews) into
+an `mcpg_demo` schema — engineered so the pivotal tools all have
+something real to find on first contact: an un-indexed foreign key for
+`analyze_query_plan` / `recommend_indexes`, PII-shaped columns for
+`find_sensitive_columns`, a camelCase naming violation, searchable
+review prose, and an optional pgvector embedding column when the
+extension is installed. The seed is a single transaction, re-seeding
+refuses rather than clobbers, and `--demo-drop` only removes a schema
+carrying the MCPg ownership marker.
+
+The companion [guided tour](demo.md) is *captured, not written* — every
+output block is a real tool run against the seeded dataset, and
+integration tests pin the planted findings so the walkthrough can't
+silently rot.
+
+## Also in this release
+
+- **Runtime moves to Python 3.14** — Docker image, the full CI matrix,
+  and the publish pipeline. `requires-python` stays `>=3.12`;
+  installing on 3.12/3.13 is unchanged.
+- **Startup warning noise eliminated** — the benign pydantic
+  "Field name `schema` shadows an attribute in parent BaseModel"
+  warnings on first `tools/list` are suppressed (narrowly, by message
+  pattern), with a contract test guarding the full tool surface.
+- **Release-pipeline hardening** — the TestPyPI smoke test now polls
+  the PEP 503 simple index (what `pip install` actually reads) instead
+  of the JSON API, eliminating the propagation race that required a
+  manual re-run during the v0.6.6 release.
+
+## Upgrade
+
+```bash
+pip install --upgrade mcpg
+docker pull ghcr.io/devopam/mcpg:0.6.7   # or :latest
+```
+
+No configuration changes required.
+
+## Full changelog
+
+See [`../CHANGELOG.md`](../CHANGELOG.md) `[0.6.7]` for the complete
+itemised list.
@@ -1,6 +1,6 @@
 [project]
 name = "mcpg"
-version = "0.6.6"
+version = "0.6.7"
 description = "A production-grade PostgreSQL Model Context Protocol (MCP) server."
 readme = "README.md"
 requires-python = ">=3.12"
 
@@ -2,7 +2,7 @@
 
 import warnings
 
-__version__ = "0.6.6"
+__version__ = "0.6.7"
 
 # ``schema`` is the natural field name for "which Postgres schema" across
 # ~180 tool-return dataclasses. The ``mcp`` SDK dynamically builds a
 
@@ -13,6 +13,7 @@
 
 from mcp.server.fastmcp import Context, FastMCP
 from mcp.server.session import ServerSession
+from mcp.types import ToolAnnotations
 from pydantic import Field
 
 from mcpg import (
@@ -6401,7 +6402,9 @@ def _register_prompts(server: FastMCP[AppContext]) -> None:
             "structured reporting checklist at the end."
         ),
     )
-    def diagnose_slow_query_prompt(sql: str) -> str:
+    def diagnose_slow_query_prompt(
+        sql: Annotated[str, Field(description="The slow SQL statement to investigate, verbatim.")],
+    ) -> str:
         return mcpg_prompts._build_diagnose_slow_query(sql)
 
     # ------------------------------------------------------------------
@@ -6419,9 +6422,15 @@ def diagnose_slow_query_prompt(sql: str) -> str:
         ),
     )
     def bisect_slow_migration_prompt(
-        migration_id: str,
-        baseline_schema: str,
-        current_schema: str,
+        migration_id: Annotated[
+            str, Field(description="Identifier of the suspect migration (as tracked by the migration tool in use).")
+        ],
+        baseline_schema: Annotated[
+            str, Field(description="Schema name representing the pre-migration (known-good) state.")
+        ],
+        current_schema: Annotated[
+            str, Field(description="Schema name representing the post-migration (regressed) state.")
+        ],
     ) -> str:
         return mcpg_prompts._build_bisect_slow_migration(migration_id, baseline_schema, current_schema)
 
@@ -6440,7 +6449,10 @@ def bisect_slow_migration_prompt(
             "not apply them."
         ),
     )
-    def review_rls_policy_prompt(schema: str, table: str) -> str:
+    def review_rls_policy_prompt(
+        schema: Annotated[str, Field(description="Schema containing the table to audit.")],
+        table: Annotated[str, Field(description="Table whose row-level-security coverage should be reviewed.")],
+    ) -> str:
         return mcpg_prompts._build_review_rls_policy(schema, table)
 
 
@@ -6709,6 +6721,52 @@ async def drop_subscription(
         return result
 
 
+# Tools that reach outside the connected PostgreSQL server. Everything
+# else in MCPg talks to a closed domain (the database), so it gets
+# ``openWorldHint=False``; these are the exceptions (external LLM APIs).
+_OPEN_WORLD_TOOLS = frozenset({"translate_nl_to_sql"})
+
+
+def _apply_tool_annotations(server: FastMCP[AppContext], read_only_names: set[str]) -> None:
+    """Stamp MCP ``ToolAnnotations`` derived from the capability gates.
+
+    MCPg already classifies every tool as READ / WRITE / DDL / SHELL /
+    LISTEN via the registration gates in :func:`register_tools`; this
+    puts that classification on the wire, where clients use it to
+    decide which calls to auto-approve (``readOnlyHint``) and whether
+    the tool leaves the database's closed world (``openWorldHint``).
+    Derived, not hand-written, so a tool moved between gates can never
+    ship a stale hint. ``destructiveHint`` is deliberately left unset
+    for non-read tools: the MCP default (true) is the cautious reading,
+    and MCPg doesn't currently track per-tool destructiveness more
+    precisely than the gate does.
+
+    Uses the sync ``_tool_manager`` accessor for the same reason the
+    session-intent filter does: this runs in synchronous startup code.
+
+    Merge semantics: annotations a registration set explicitly always
+    win — the derived values only fill fields that are still ``None``.
+    (No call site passes ``annotations=`` today, but a future per-tool
+    override — e.g. ``destructiveHint=False`` on a maintenance tool —
+    must not be silently clobbered by this sweep.)
+    """
+    for tool in server._tool_manager.list_tools():
+        existing = tool.annotations
+        if existing is None:
+            tool.annotations = ToolAnnotations(
+                readOnlyHint=tool.name in read_only_names,
+                openWorldHint=tool.name in _OPEN_WORLD_TOOLS,
+            )
+            continue
+        derived: dict[str, bool] = {}
+        if existing.readOnlyHint is None:
+            derived["readOnlyHint"] = tool.name in read_only_names
+        if existing.openWorldHint is None:
+            derived["openWorldHint"] = tool.name in _OPEN_WORLD_TOOLS
+        if derived:
+            tool.annotations = existing.model_copy(update=derived)
+
+
 def register_tools(server: FastMCP[AppContext], settings: Settings) -> None:
     """Register the MCP tools permitted by the configured access mode.
 
@@ -6757,6 +6815,9 @@ def register_tools(server: FastMCP[AppContext], settings: Settings) -> None:
         _register_wait_for_lsn_reads(server)
         _register_wait_for_lsn_writes(server)
         _register_warehousepg_reads(server)
+    # Everything registered so far sits behind (at most) the READ gate —
+    # this snapshot is what ``readOnlyHint=True`` is derived from below.
+    read_only_names = {tool.name for tool in server._tool_manager.list_tools()}
     if is_permitted(settings.access_mode, Capability.WRITE):
         _register_write(server)
         _register_maintenance(server)
@@ -6788,6 +6849,8 @@ def register_tools(server: FastMCP[AppContext], settings: Settings) -> None:
     if is_permitted(settings.access_mode, Capability.LISTEN) and settings.allow_listen:
         _register_listen(server)
 
+    _apply_tool_annotations(server, read_only_names)
+
     # Session-intent surface filter (roadmap 8.8). Runs LAST so every
     # tool that would otherwise be registered has already been added —
     # we then remove whatever the configured intent doesn't allow.