data-olympus 0.4.1__tar.gz → 0.4.2__tar.gz

{data_olympus-0.4.1 → data_olympus-0.4.2}/CHANGELOG.md

@@ -12,6 +12,45 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.4.2] - 2026-07-11
+
+### Added
+
+- **`data-olympus verify` command.** New CLI subcommand that runs pass/fail
+  checks against a running instance (`--target`, `--json`, `--checks`,
+  `--token`): liveness (`/api/v1/health`), readiness (`/readyz`), a search
+  round-trip (`/api/v1/search`), and a deployment-tolerant enforcement-plane
+  probe (`/api/v1/gate/check`). Exit codes: `0` all pass, `4` a check failed,
+  `1` the target is unreachable. Used as the pre/post-release verification gate.
+- **Staged-promotion release pipeline (release engineering).** A release
+  candidate is published to a `X.Y.Z-rc.N` ghcr channel (`rc-publish.yml`),
+  deployed as a canary and verified, then promoted by re-tagging the verified
+  digest to `vX.Y.Z` byte-identically (`tag-release.yml`), with a moving-channel
+  helper (`set-channel.yml`) and project-local runbooks under `.rules/`.
+- **Glama registry score support.** Added the Glama score badge to the README
+  and documented the claimed server listing, sandbox release settings, and
+  score-maintenance checklist in `docs/glama.md`.
+- **Release security-clearance gate.** `scripts/security_alerts.py` fails a
+  release when any Dependabot or CodeQL alert is open; the release planner clears
+  every alert (fix or justified dismissal) and the cutter verifies zero open
+  before building the release candidate.
+
+### Changed
+
+- **Improved MCP tool schema metadata for registry introspection.** MCP tools
+  now expose meaningful titles, MCP annotations, and per-parameter JSON Schema
+  descriptions so registries such as Glama can score the running server's tool
+  definitions more accurately.
+
+### Fixed
+
+- **Documented the fastmcp 3.4.3 host allowlist requirement behind
+  proxies/ingress** (docs/serving.md, docs/operations.md section 3.4).
+  v0.4.1's fastmcp bump enables DNS-rebinding protection that answers 421
+  Misdirected Request for undeclared public hostnames while health probes
+  keep passing; deployments behind a reverse proxy must set
+  `FASTMCP_HTTP_ALLOWED_HOSTS`. First-class handling tracked in #139.
+
 ## [0.4.1] - 2026-07-08
 
 ### Changed

{data_olympus-0.4.1 → data_olympus-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: data-olympus
-Version: 0.4.1
+Version: 0.4.2
 Summary: Governance-grade knowledge-base format (OKF-compatible) plus CLI and single-writer MCP server
 Project-URL: Homepage, https://github.com/knaisoma/data-olympus
 Project-URL: Repository, https://github.com/knaisoma/data-olympus
@@ -45,6 +45,8 @@ Description-Content-Type: text/markdown
 
 # data-olympus
 
+[![knaisoma/data-olympus MCP server](https://glama.ai/mcp/servers/knaisoma/data-olympus/badges/score.svg)](https://glama.ai/mcp/servers/knaisoma/data-olympus)
+
 **New here? Start with [WHY.md](WHY.md).** It is the story behind the project: the
 problem we kept hitting with coding agents, what data-olympus does differently, how
 it relates to Google's Open Knowledge Format, and where our benchmarks say it is
@@ -94,6 +96,7 @@ See `docs/quickstart.md` for the full local-run walkthrough, including curl and
 - [`docs/operations.md`](docs/operations.md): production runbook — backup, upgrade, recovery playbooks (degraded/fetch-failed, history rewrite, frozen/demoted push entries, orphaned locks), and the health/alerting model.
 - [`docs/comparison.md`](docs/comparison.md): how data-olympus relates to OKF, enterprise catalogs, markdown KB tools, agent-context conventions, RAG, and ADR tooling.
 - [`docs/okf-profile.md`](docs/okf-profile.md): field-by-field OKF profile — which governance extensions are stable, which are runtime-only serving fields, and which are experimental candidates.
+- [`docs/glama.md`](docs/glama.md): Glama registry claim, release, and score-maintenance notes.
 - [`docs/enforcement.md`](docs/enforcement.md): turning the KB into a mandatory consultation gate (hooks, `kb enforce`).
 - [`benchmarks/README.md`](benchmarks/README.md): retrieval benchmark methodology and how to reproduce the numbers in `docs/comparison.md`.
 - [`SECURITY.md`](SECURITY.md): supported versions and how to report a vulnerability.

{data_olympus-0.4.1 → data_olympus-0.4.2}/README.md

@@ -1,5 +1,7 @@
 # data-olympus
 
+[![knaisoma/data-olympus MCP server](https://glama.ai/mcp/servers/knaisoma/data-olympus/badges/score.svg)](https://glama.ai/mcp/servers/knaisoma/data-olympus)
+
 **New here? Start with [WHY.md](WHY.md).** It is the story behind the project: the
 problem we kept hitting with coding agents, what data-olympus does differently, how
 it relates to Google's Open Knowledge Format, and where our benchmarks say it is
@@ -49,6 +51,7 @@ See `docs/quickstart.md` for the full local-run walkthrough, including curl and
 - [`docs/operations.md`](docs/operations.md): production runbook — backup, upgrade, recovery playbooks (degraded/fetch-failed, history rewrite, frozen/demoted push entries, orphaned locks), and the health/alerting model.
 - [`docs/comparison.md`](docs/comparison.md): how data-olympus relates to OKF, enterprise catalogs, markdown KB tools, agent-context conventions, RAG, and ADR tooling.
 - [`docs/okf-profile.md`](docs/okf-profile.md): field-by-field OKF profile — which governance extensions are stable, which are runtime-only serving fields, and which are experimental candidates.
+- [`docs/glama.md`](docs/glama.md): Glama registry claim, release, and score-maintenance notes.
 - [`docs/enforcement.md`](docs/enforcement.md): turning the KB into a mandatory consultation gate (hooks, `kb enforce`).
 - [`benchmarks/README.md`](benchmarks/README.md): retrieval benchmark methodology and how to reproduce the numbers in `docs/comparison.md`.
 - [`SECURITY.md`](SECURITY.md): supported versions and how to report a vulnerability.

{data_olympus-0.4.1 → data_olympus-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "data-olympus"
-version = "0.4.1"
+version = "0.4.2"
 description = "Governance-grade knowledge-base format (OKF-compatible) plus CLI and single-writer MCP server"
 readme = "README.md"
 requires-python = ">=3.13"

{data_olympus-0.4.1 → data_olympus-0.4.2}/src/data_olympus/cli/main.py

@@ -141,6 +141,8 @@ def build_parser() -> argparse.ArgumentParser:
     add_validity_report_subparser(sub)
     from data_olympus.cli.init_cmd import add_init_subparser
     add_init_subparser(sub)
+    from data_olympus.cli.verify_cmd import add_verify_subparser
+    add_verify_subparser(sub)
     return parser
 
 

data_olympus-0.4.2/src/data_olympus/cli/verify_cmd.py

@@ -0,0 +1,245 @@
+"""`data-olympus verify`: automated pass/fail health + functional round-trip
+checks against a running data-olympus instance. Used by hand and as the
+pre/post-release verification gate.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import httpx
+
+if TYPE_CHECKING:
+    import argparse
+
+# NOTE: declare every module-level import here in Task 1. Later tasks add
+# functions only (no new top-level imports), so ruff's E402 never fires.
+# `json` is used by run_verify (Task 4); the argparse annotations are strings.
+
+_ALL_CHECKS = ("health", "readiness", "search", "enforcement")
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    name: str
+    ok: bool
+    detail: str
+    connection_error: bool = False
+
+
+def check_health(client: httpx.Client) -> CheckResult:
+    """GET /api/v1/health: pass on 200 with degraded=false (503 = degraded)."""
+    try:
+        resp = client.get("/api/v1/health")
+    except httpx.HTTPError as exc:
+        return CheckResult("health", False, f"request failed: {exc}", connection_error=True)
+    if resp.status_code != 200:
+        return CheckResult("health", False, f"status {resp.status_code} (degraded or down)")
+    try:
+        body = resp.json()
+    except ValueError:
+        return CheckResult("health", False, "non-JSON health body")
+    if not isinstance(body, dict):
+        return CheckResult("health", False, "unexpected non-object health body")
+    if bool(body.get("degraded")):
+        return CheckResult("health", False, "health reports degraded")
+    return CheckResult("health", True, "healthy")
+
+
+def check_readiness(client: httpx.Client) -> CheckResult:
+    """GET /readyz: the k8s readiness probe target; pass on 200."""
+    try:
+        resp = client.get("/readyz")
+    except httpx.HTTPError as exc:
+        return CheckResult("readiness", False, f"request failed: {exc}", connection_error=True)
+    ok = resp.status_code == 200
+    return CheckResult("readiness", ok, "ready" if ok else f"status {resp.status_code}")
+
+
+def check_search(client: httpx.Client, probe: str) -> CheckResult:
+    """GET /api/v1/search: confirms the index answers reads with a hits list."""
+    try:
+        resp = client.get("/api/v1/search", params={"q": probe, "limit": 1})
+    except httpx.HTTPError as exc:
+        return CheckResult("search", False, f"request failed: {exc}", connection_error=True)
+    if resp.status_code != 200:
+        return CheckResult("search", False, f"status {resp.status_code}")
+    try:
+        body = resp.json()
+    except ValueError:
+        return CheckResult("search", False, "non-JSON search body")
+    if not isinstance(body, dict):
+        return CheckResult("search", False, "unexpected non-object search body")
+    hits = body.get("hits")
+    if not isinstance(hits, list):
+        return CheckResult("search", False, "response missing 'hits' list")
+    return CheckResult("search", True, f"{len(hits)} hit(s) for probe {probe!r}")
+
+
+def check_enforcement(client: httpx.Client, token: str | None = None) -> CheckResult:
+    """Probe /api/v1/gate/check. Deployment-tolerant: 404 (routes not
+    mounted) and 401/403 without a token are informational passes; a token
+    that is rejected, or a 5xx, fail."""
+    headers = {"Authorization": f"Bearer {token}"} if token else {}
+    payload = {"workspace": "data-olympus", "session_id": "verify-probe"}
+    try:
+        resp = client.post(
+            "/api/v1/gate/check", json=payload, headers=headers
+        )
+    except httpx.HTTPError as exc:
+        return CheckResult(
+            "enforcement", False, f"request failed: {exc}", connection_error=True
+        )
+    code = resp.status_code
+    if code == 200:
+        return CheckResult("enforcement", True, "enforcement plane responding")
+    if code == 404:
+        return CheckResult(
+            "enforcement", True, "enforcement routes not mounted (open deployment)"
+        )
+    if code in (401, 403):
+        if token:
+            return CheckResult(
+                "enforcement", False, f"enforcement rejected the token ({code})"
+            )
+        return CheckResult(
+            "enforcement",
+            True,
+            "enforcement active (auth required; pass --token to test round-trip)",
+        )
+    return CheckResult("enforcement", False, f"unexpected status {code}")
+
+
+def run_verify(
+    *,
+    target: str,
+    as_json: bool = False,
+    timeout: float = 10.0,
+    probe: str = "the",
+    checks: list[str] | None = None,
+    token: str | None = None,
+    client: httpx.Client | None = None,
+) -> int:
+    """Orchestrate selected checks and report results to stdout. Returns 0, 1,
+    or 4."""
+    owns_client = client is None
+    if client is None:
+        client = httpx.Client(base_url=target.rstrip("/"), timeout=timeout)
+    try:
+        selected_checks = (
+            checks if checks is not None else list(_ALL_CHECKS)
+        )
+        results = []
+        for check_name in _ALL_CHECKS:
+            if check_name not in selected_checks:
+                continue
+            if check_name == "health":
+                results.append(check_health(client))
+            elif check_name == "readiness":
+                results.append(check_readiness(client))
+            elif check_name == "search":
+                results.append(check_search(client, probe))
+            elif check_name == "enforcement":
+                results.append(check_enforcement(client, token))
+    finally:
+        if owns_client:
+            client.close()
+
+    all_ok = all(r.ok for r in results)
+    if as_json:
+        print(
+            json.dumps(
+                {
+                    "target": target,
+                    "ok": all_ok,
+                    "checks": [
+                        {"name": r.name, "ok": r.ok, "detail": r.detail}
+                        for r in results
+                    ],
+                },
+                indent=2,
+            )
+        )
+    else:
+        for r in results:
+            mark = "PASS" if r.ok else "FAIL"
+            print(f"{mark}  {r.name}: {r.detail}")
+        print(
+            f"{'ok' if all_ok else 'FAILED'}: "
+            f"{sum(r.ok for r in results)}/{len(results)} checks passed "
+            f"against {target}"
+        )
+    if all_ok:
+        return 0
+    if results and all(r.connection_error for r in results):
+        return 1
+    return 4
+
+
+def add_verify_subparser(
+    sub: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    """Wire the verify subcommand into the argparse dispatcher."""
+    p = sub.add_parser(
+        "verify",
+        help="run health + functional round-trip checks against a running instance",
+    )
+    p.add_argument(
+        "--target",
+        default=None,
+        help="base URL (default: $KB_ENDPOINT or http://localhost:8080)",
+    )
+    p.add_argument("--json", action="store_true", help="emit JSON")
+    p.add_argument(
+        "--timeout",
+        type=float,
+        default=10.0,
+        help="per-request timeout seconds",
+    )
+    p.add_argument("--probe", default="the", help="search probe term (default: the)")
+    p.add_argument(
+        "--checks",
+        default=None,
+        help="comma-separated subset to run (default: all): "
+        "health,readiness,search,enforcement",
+    )
+    p.add_argument(
+        "--token",
+        default=None,
+        help="bearer token for enforcement check (default: $KB_AUTH_TOKEN)",
+    )
+    p.set_defaults(func=_cmd_verify)
+
+
+def _cmd_verify(args: argparse.Namespace) -> int:
+    """Entry point for the verify subcommand; resolve target and call
+    run_verify."""
+    import os
+    import sys
+
+    target = args.target or os.environ.get("KB_ENDPOINT") or (
+        "http://localhost:8080"
+    )
+
+    checks = None
+    if args.checks:
+        checks = [c.strip() for c in args.checks.split(",")]
+        unknown = set(checks) - set(_ALL_CHECKS)
+        if unknown:
+            print(
+                f"error: unknown check(s): {','.join(sorted(unknown))}",
+                file=sys.stderr,
+            )
+            return 2
+
+    token = args.token or os.environ.get("KB_AUTH_TOKEN")
+
+    return run_verify(
+        target=target,
+        as_json=args.json,
+        timeout=args.timeout,
+        probe=args.probe,
+        checks=checks,
+        token=token,
+    )

{data_olympus-0.4.1 → data_olympus-0.4.2}/src/data_olympus/server.py

@@ -6,10 +6,11 @@ import contextlib
 import contextvars
 import logging
 import time
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Annotated, Any
 
 from fastmcp import FastMCP
 from fastmcp.server.middleware import Middleware
+from pydantic import Field
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -61,6 +62,170 @@ _current_principal: contextvars.ContextVar[Principal] = contextvars.ContextVar(
     "current_principal", default=LOCAL_TRUSTED
 )
 
+READ_ONLY_TOOL = {
+    "readOnlyHint": True,
+    "destructiveHint": False,
+    "idempotentHint": True,
+    "openWorldHint": False,
+}
+STATEFUL_NONDESTRUCTIVE_TOOL = {
+    "readOnlyHint": False,
+    "destructiveHint": False,
+    "idempotentHint": False,
+    "openWorldHint": False,
+}
+PROPOSAL_WRITE_TOOL = {
+    "readOnlyHint": False,
+    "destructiveHint": False,
+    "idempotentHint": False,
+    "openWorldHint": True,
+}
+PROPOSAL_EDIT_TOOL = {
+    "readOnlyHint": False,
+    "destructiveHint": True,
+    "idempotentHint": False,
+    "openWorldHint": True,
+}
+DESTRUCTIVE_WRITE_TOOL = {
+    "readOnlyHint": False,
+    "destructiveHint": True,
+    "idempotentHint": False,
+    "openWorldHint": True,
+}
+
+VerboseParam = Annotated[
+    bool,
+    Field(description="False returns the compact response; true includes all fields."),
+]
+QueryParam = Annotated[str, Field(description="Natural-language search query.")]
+LimitParam = Annotated[int, Field(description="Maximum number of results, clamped to 1..100.")]
+TierParam = Annotated[
+    str | None,
+    Field(description="Optional tier filter such as T1, T2, T3, or T4."),
+]
+RequiredTierParam = Annotated[
+    str,
+    Field(description="Required tier such as T1, T2, T3, or T4."),
+]
+CategoryParam = Annotated[
+    str | None,
+    Field(description="Optional category filter within a tier."),
+]
+StatusParam = Annotated[str | None, Field(description="Optional frontmatter status filter.")]
+InForceParam = Annotated[
+    bool,
+    Field(description="True returns only currently governing documents."),
+]
+DocTypeParam = Annotated[str | None, Field(description="Optional document type filter.")]
+AbstainParam = Annotated[
+    bool,
+    Field(description="True returns an explicit abstention when the query has no KB signal."),
+]
+IncludeExpiredParam = Annotated[
+    bool,
+    Field(description="True allows expired documents in search results."),
+]
+ValidityStateParam = Annotated[
+    str | None,
+    Field(description="Optional validity facet: expired, stale, or expiring_within:N."),
+]
+DocumentIdParam = Annotated[str, Field(description="Stable KB document id to retrieve.")]
+WorkspaceParam = Annotated[str, Field(description="Project or workspace key in the KB.")]
+ComponentParam = Annotated[
+    str | None,
+    Field(description="Optional component key under the workspace."),
+]
+RemoteUrlParam = Annotated[
+    str | None,
+    Field(description="Optional git remote URL used for matching."),
+]
+LocalFilesParam = Annotated[
+    list[dict[str, str]],
+    Field(description="Local docs to compare, each with path and content keys."),
+]
+JaccardParam = Annotated[
+    float,
+    Field(description="Similarity threshold above which a local doc is treated as duplicate."),
+]
+TextParam = Annotated[str, Field(description="Markdown memory text to propose.")]
+TagsParam = Annotated[list[str], Field(description="Short tags for the proposed memory.")]
+SourceSessionParam = Annotated[
+    str,
+    Field(description="Stable id of the agent session making the call."),
+]
+AgentIdentityParam = Annotated[
+    str,
+    Field(description="Human-readable agent identity for audit events."),
+]
+ConfidenceParam = Annotated[
+    float,
+    Field(description="Caller confidence in the proposal, from 0.0 to 1.0."),
+]
+EvidenceParam = Annotated[
+    list[str] | None,
+    Field(description="Optional supporting evidence strings, max 10 items of 500 chars each."),
+]
+TargetPathParam = Annotated[
+    str,
+    Field(description="KB-relative markdown path to create or edit."),
+]
+PostimageParam = Annotated[
+    str,
+    Field(description="Complete markdown file content after the proposed edit."),
+]
+BaseCommitParam = Annotated[str, Field(description="Git commit the proposal was based on.")]
+BaseBlobShaParam = Annotated[
+    str | None,
+    Field(description="Optional git blob sha for compare-and-swap protection."),
+]
+TargetFileHashParam = Annotated[
+    str | None,
+    Field(description="Optional content hash for compare-and-swap protection."),
+]
+ReasonParam = Annotated[str, Field(description="Short reason for the proposed change.")]
+PendingIdParam = Annotated[str, Field(description="Pending proposal id to resolve.")]
+DecisionParam = Annotated[
+    str,
+    Field(description="Resolution decision: approve or reject."),
+]
+EditedTextParam = Annotated[
+    str | None,
+    Field(description="Optional replacement postimage used when approving."),
+]
+OverrideSecretScanParam = Annotated[
+    bool,
+    Field(description="Operator override for false-positive secret-scan matches."),
+]
+SinceParam = Annotated[float | None, Field(description="Optional Unix timestamp lower bound.")]
+AgentParam = Annotated[str | None, Field(description="Optional agent_identity filter.")]
+EventStatusParam = Annotated[str | None, Field(description="Optional audit event status filter.")]
+AuditLimitParam = Annotated[int, Field(description="Maximum audit events to return.")]
+BootstrapFilesParam = Annotated[
+    list[dict[str, str]],
+    Field(description="Bootstrap files, each with target_path and postimage keys."),
+]
+TriggerParam = Annotated[
+    str,
+    Field(description="Consult trigger: explicit or prompt_hook."),
+]
+SessionIdParam = Annotated[
+    str,
+    Field(description="Agent session id checked against consult history."),
+]
+ToolNameParam = Annotated[str, Field(description="Name of the tool or command about to run.")]
+ActionPathParam = Annotated[
+    str | None,
+    Field(description="Optional path or URL affected by the pending action."),
+]
+ActionDiffParam = Annotated[
+    str,
+    Field(description="Short description or diff summary of the pending action."),
+]
+EventTypeParam = Annotated[
+    str,
+    Field(description="Client-reported event type: gate_bypass or gate_degraded."),
+]
+
 
 class MCPAuthMiddleware(Middleware):
     """Enforce principal capabilities on MCP write tools.
@@ -444,8 +609,8 @@ def build_app(
 
     app: FastMCP = FastMCP(name="data-olympus-mcp")
 
-    @app.tool()
-    def kb_health(verbose: bool = False) -> dict[str, object]:
+    @app.tool(title="KB Health", annotations=READ_ONLY_TOOL)
+    def kb_health(verbose: VerboseParam = False) -> dict[str, object]:
         """Return service health: kb_commit, index_built_at, staleness, degraded flag,
         and write-side state (pending_count, push_queue_size, last_index_*).
 
@@ -480,8 +645,8 @@ def build_app(
         )
         return shape_response(resp, verbose=verbose)
 
-    @app.tool()
-    def kb_outline(verbose: bool = False) -> dict[str, object]:
+    @app.tool(title="KB Outline", annotations=READ_ONLY_TOOL)
+    def kb_outline(verbose: VerboseParam = False) -> dict[str, object]:
         """Return the tree of tiers and categories with doc counts.
 
         verbose: kb_outline is already lean, so compact and full modes return the
@@ -489,19 +654,19 @@ def build_app(
         resp = kb_outline_fn(idx=state.idx)
         return shape_response(resp, verbose=verbose)
 
-    @app.tool()
+    @app.tool(title="KB Search", annotations=READ_ONLY_TOOL)
     def kb_search(
-        query: str,
-        limit: int = 20,
-        tier: str | None = None,
-        category: str | None = None,
-        status: str | None = None,
-        in_force: bool = False,
-        doc_type: str | None = None,
-        abstain: bool = False,
-        include_expired: bool = False,
-        validity_state: str | None = None,
-        verbose: bool = False,
+        query: QueryParam,
+        limit: LimitParam = 20,
+        tier: TierParam = None,
+        category: CategoryParam = None,
+        status: StatusParam = None,
+        in_force: InForceParam = False,
+        doc_type: DocTypeParam = None,
+        abstain: AbstainParam = False,
+        include_expired: IncludeExpiredParam = False,
+        validity_state: ValidityStateParam = None,
+        verbose: VerboseParam = False,
     ) -> dict[str, object]:
         """Full-text search across the KB.
 
@@ -555,8 +720,8 @@ def build_app(
         )
         return shape_response(resp, verbose=verbose)
 
-    @app.tool()
-    def kb_get(id: str, verbose: bool = False) -> dict[str, object]:
+    @app.tool(title="KB Get Document", annotations=READ_ONLY_TOOL)
+    def kb_get(id: DocumentIdParam, verbose: VerboseParam = False) -> dict[str, object]:
         """Retrieve a document by id (STD-U-001, ADR-002, T-NNN, etc.).
         Returns the full content markdown plus metadata.
 
@@ -582,8 +747,11 @@ def build_app(
             return {"error": "not_found", "message": str(e)}
         return shape_response(resp, verbose=verbose)
 
-    @app.tool()
-    def kb_list(tier: str, category: str | None = None, verbose: bool = False) -> dict[str, object]:
+    @app.tool(title="KB List Documents", annotations=READ_ONLY_TOOL)
+    def kb_list(
+        tier: RequiredTierParam, category: CategoryParam = None,
+        verbose: VerboseParam = False,
+    ) -> dict[str, object]:
         """List doc ids in the given tier (and optional category), ordered by id.
 
         verbose: False (default) drops per-entry `path` (fetch via kb_get(id)) and
@@ -592,11 +760,11 @@ def build_app(
         resp = kb_list_fn(idx=state.idx, tier=tier, category=category)
         return shape_response(resp, verbose=verbose)
 
-    @app.tool()
+    @app.tool(title="KB Onboarding Status", annotations=READ_ONLY_TOOL)
     def kb_onboarding_status(
-        workspace: str, component: str | None = None,
-        workspace_remote_url: str | None = None,
-        component_remote_url: str | None = None,
+        workspace: WorkspaceParam, component: ComponentParam = None,
+        workspace_remote_url: RemoteUrlParam = None,
+        component_remote_url: RemoteUrlParam = None,
     ) -> dict[str, object]:
         """Compute onboarding status for a workspace + optional component.
         State is one of: absent, partial, onboarded, rename_candidate."""
@@ -632,10 +800,10 @@ def build_app(
                     "error": "too many requests; retry later"}
         return None
 
-    @app.tool()
+    @app.tool(title="KB Cleanup Plan", annotations=READ_ONLY_TOOL)
     def kb_cleanup_plan(
-        workspace: str, local_files: list[dict[str, str]],
-        component: str | None = None, jaccard_threshold: float = 0.6,
+        workspace: WorkspaceParam, local_files: LocalFilesParam,
+        component: ComponentParam = None, jaccard_threshold: JaccardParam = 0.6,
     ) -> dict[str, object]:
         """Read-only. Classify local project-repo docs against KB content for this
         workspace/component and return thin-pointer replacements for duplicates.
@@ -657,11 +825,11 @@ def build_app(
     if not read_only:
         # Write + enforcement-write surface. A read-only replica
         # (issue #44) exposes none of these tools.
-        @app.tool()
+        @app.tool(title="KB Propose Memory", annotations=PROPOSAL_WRITE_TOOL)
         def kb_propose_memory(
-            text: str, tags: list[str], source_session: str,
-            agent_identity: str, confidence: float,
-            evidence: list[str] | None = None,
+            text: TextParam, tags: TagsParam, source_session: SourceSessionParam,
+            agent_identity: AgentIdentityParam, confidence: ConfidenceParam,
+            evidence: EvidenceParam = None,
         ) -> dict[str, object]:
             """Propose a new memory file. High confidence auto-commits and
             enqueues for push; low confidence enters the pending queue for operator
@@ -693,12 +861,13 @@ def build_app(
             )
             return resp.model_dump()
 
-        @app.tool()
+        @app.tool(title="KB Propose Edit", annotations=PROPOSAL_EDIT_TOOL)
         def kb_propose_edit(
-            target_path: str, postimage: str, base_commit: str,
-            base_blob_sha: str | None, target_file_hash: str | None,
-            reason: str, source_session: str, agent_identity: str, confidence: float,
-            evidence: list[str] | None = None,
+            target_path: TargetPathParam, postimage: PostimageParam,
+            base_commit: BaseCommitParam, base_blob_sha: BaseBlobShaParam,
+            target_file_hash: TargetFileHashParam, reason: ReasonParam,
+            source_session: SourceSessionParam, agent_identity: AgentIdentityParam,
+            confidence: ConfidenceParam, evidence: EvidenceParam = None,
         ) -> dict[str, object]:
             """Propose an edit to an existing (or new) markdown file under an
             indexed tier. High confidence auto-commits + queues for push; low
@@ -733,11 +902,13 @@ def build_app(
             )
             return resp.model_dump()
 
-        @app.tool()
+        @app.tool(title="KB Resolve Pending", annotations=DESTRUCTIVE_WRITE_TOOL)
         def kb_resolve_pending(
-            pending_id: str, decision: str, edited_text: str | None = None,
-            source_session: str = "operator-resolve", agent_identity: str = "operator",
-            override_secret_scan: bool = False,
+            pending_id: PendingIdParam, decision: DecisionParam,
+            edited_text: EditedTextParam = None,
+            source_session: SourceSessionParam = "operator-resolve",
+            agent_identity: AgentIdentityParam = "operator",
+            override_secret_scan: OverrideSecretScanParam = False,
         ) -> dict[str, object]:
             """Resolve a pending proposal: approve (optionally with edited text) or
             reject. Approval commits + enqueues for push.
@@ -769,7 +940,7 @@ def build_app(
             )
             return resp.model_dump()
 
-        @app.tool()
+        @app.tool(title="KB List Pending", annotations=READ_ONLY_TOOL)
         def kb_list_pending() -> dict[str, object]:
             """List currently pending proposals awaiting operator decision."""
             assert state.pending is not None
@@ -777,10 +948,10 @@ def build_app(
             resp = kb_list_pending_fn(pending=state.pending)
             return resp.model_dump()
 
-        @app.tool()
+        @app.tool(title="KB Audit", annotations=READ_ONLY_TOOL)
         def kb_audit(
-            since: float | None = None, agent: str | None = None,
-            status: str | None = None, limit: int = 100,
+            since: SinceParam = None, agent: AgentParam = None,
+            status: EventStatusParam = None, limit: AuditLimitParam = 100,
         ) -> dict[str, object]:
             """Return recent audit events, most-recent first. Optional filters:
             since (unix ts), agent (agent_identity), status (event status)."""
@@ -790,8 +961,8 @@ def build_app(
                               agent=agent, status=status, limit=limit)
             return resp.model_dump()
 
-        @app.tool()
-        def kb_session_recap(source_session: str) -> dict[str, object]:
+        @app.tool(title="KB Session Recap", annotations=READ_ONLY_TOOL)
+        def kb_session_recap(source_session: SourceSessionParam) -> dict[str, object]:
             """Read-only per-session write summary (issue #112 feedback loop):
             N committed, M demoted-to-pending, K rejected for source_session.
             Call this (or `kb pending`) whenever a write response indicated a
@@ -804,13 +975,13 @@ def build_app(
             resp = kb_session_recap_fn(audit_log=state.audit_log, source_session=source_session)
             return resp.model_dump()
 
-        @app.tool()
+        @app.tool(title="KB Bootstrap Project", annotations=PROPOSAL_WRITE_TOOL)
         def kb_bootstrap_project(
-            workspace: str, files: list[dict[str, str]],
-            source_session: str, agent_identity: str, confidence: float,
-            component: str | None = None,
-            workspace_remote_url: str | None = None,
-            component_remote_url: str | None = None,
+            workspace: WorkspaceParam, files: BootstrapFilesParam,
+            source_session: SourceSessionParam, agent_identity: AgentIdentityParam,
+            confidence: ConfidenceParam, component: ComponentParam = None,
+            workspace_remote_url: RemoteUrlParam = None,
+            component_remote_url: RemoteUrlParam = None,
         ) -> dict[str, object]:
             """Bootstrap a new workspace/component. Only valid when status=absent
             or partial. High confidence commits atomically; low confidence
@@ -842,10 +1013,11 @@ def build_app(
             )
             return resp.model_dump()
 
-        @app.tool()
+        @app.tool(title="KB Consult", annotations=STATEFUL_NONDESTRUCTIVE_TOOL)
         def kb_consult(
-            workspace: str, intent: str, source_session: str,
-            agent_identity: str, trigger: str = "explicit",
+            workspace: WorkspaceParam, intent: QueryParam,
+            source_session: SourceSessionParam,
+            agent_identity: AgentIdentityParam, trigger: TriggerParam = "explicit",
         ) -> dict[str, object]:
             """Record a consultation for (source_session, workspace) and return the
             governing rules for the intent. Call before code/architectural work.
@@ -876,10 +1048,11 @@ def build_app(
             )
             return resp.model_dump(exclude_none=True)
 
-        @app.tool()
+        @app.tool(title="KB Gate Check", annotations=STATEFUL_NONDESTRUCTIVE_TOOL)
         def kb_gate_check(
-            workspace: str, session_id: str, tool_name: str,
-            action_path: str | None = None, action_diff: str = "",
+            workspace: WorkspaceParam, session_id: SessionIdParam,
+            tool_name: ToolNameParam, action_path: ActionPathParam = None,
+            action_diff: ActionDiffParam = "",
         ) -> dict[str, object]:
             """Return a verdict (allow | consult_required) for a pending code action.
             Governed actions require a fresh consultation on record."""
@@ -897,9 +1070,9 @@ def build_app(
             )
             return resp.model_dump()
 
-        @app.tool()
+        @app.tool(title="KB Compliance", annotations=READ_ONLY_TOOL)
         def kb_compliance(
-            since: float | None = None, agent: str | None = None,
+            since: SinceParam = None, agent: AgentParam = None,
         ) -> dict[str, object]:
             """Aggregate enforcement events (consult / gate_*) overall and per agent."""
             if state.audit_log is None:
@@ -908,10 +1081,11 @@ def build_app(
             resp = kb_compliance_fn(audit_log=state.audit_log, since=since, agent=agent)
             return resp.model_dump()
 
-        @app.tool()
+        @app.tool(title="KB Record Event", annotations=STATEFUL_NONDESTRUCTIVE_TOOL)
         def kb_record_event(
-            event_type: str, workspace: str, agent_identity: str,
-            source_session: str, reason: str = "",
+            event_type: EventTypeParam, workspace: WorkspaceParam,
+            agent_identity: AgentIdentityParam, source_session: SourceSessionParam,
+            reason: ReasonParam = "",
         ) -> dict[str, object]:
             """Record a gate_bypass or gate_degraded enforcement event in the audit."""
             if state.audit_log is None: