@sonenta/mcp 0.34.0 → 0.35.0

package/python/verbumia_mcp/tools.py

@@ -1,3300 +0,0 @@
-"""V1 MCP tool registrations.
-
-Tools (V1 MCP surface; glossary_* added 2026-05-24; reports + trash added 2026-05-25):
-- list_projects           — list projects accessible to the API key
-- get_project_info        — project metadata: source_language, languages, namespaces
-- list_keys               — keys + source value + per-language translations (bulk-translate)
-- list_untranslated_keys  — keys WITHOUT a valid translation in a target language
-- list_missing_keys       — pending missing-key events (cursor paginated)
-- missing_keys_stats      — count-only summary of missing events (drives pagination)
-- acknowledge_missing_keys— batch-resolve missing events (cleanup the dashboard)
-- create_namespace        — idempotent namespace creation (slug validated, slug_invalid on bad input)
-- create_key              — idempotent key creation; optionally seeds source value + sets semantic `type`
-- create_keys_bulk        — batch create_key (up to 500/call, per-item results)
-- update_key              — edit a key's SOURCE value / `type` / description in place (PATCH); demotes reviewed/approved targets to needs-review
-- update_keys_bulk        — batch update_key (up to 500/call, per-item results)
-- propose_translation     — submit a translation value (auto-creates the key if missing)
-- propose_translations_bulk— batch propose_translation (up to 500/call, per-item results)
-- publish_cdn             — trigger a CDN release (closes the dogfood loop)
-- validate_translations   — lint a JSON i18next blob server-side
-- project_context_get     — read the project's markdown context document
-- project_context_set     — upsert the project's markdown context document
-- glossary_list           — list glossary entries (filters rule_type/q/limit)
-- glossary_create         — create a glossary entry (409 on duplicate rule_type+term)
-- glossary_update         — update an entry by uuid (term/translations/case_sensitive/note)
-- glossary_delete         — delete an entry by uuid
-- health_report           — read-only project source-health report (#752)
-- coverage_report         — read-only project translation-coverage report (#752)
-- list_source_duplicates  — read-only list of duplicate-source-value groups (#1116)
-- set_duplicate_status    — triage a duplicate group: to_fix | allowed | resolved (#1116)
-- delete_keys_bulk        — soft-delete (trash) keys by key_uuid; restorable
-- restore_keys_bulk       — restore trashed keys by key_uuid
-- list_trash              — list trashed (soft-deleted) keys (cursor paginated)
-- a11y_estimate           — preview the credit cost of an a11y generate/translate run (#a11y V1)
-- generate_a11y_variant   — AI-generate source-lang a11y variants (aria/alt/screen_reader/plain_language)
-- translate_a11y_variants — translate existing source a11y overrides into target locales
-- a11y_report             — read-only WCAG a11y gap report (per key/surface/locale)
-- list_a11y_gaps          — actionable a11y gaps (filtered items[] of a11y_report)
-- set_a11y_variant        — upsert one a11y variant override (key, language, surface)
-- delete_a11y_variant     — delete one a11y variant override (cell re-inherits base value)
-- list_surfaces           — list the project's configurable surfaces (device + a11y; #928)
-- create_surface          — create a custom DEVICE surface (a11y is a fixed set)
-- update_surface          — rename / toggle-active a surface (deactivate is soft)
-- delete_surface          — delete a custom surface (builtins: deactivate only)
-- get_variants            — full variant matrix for one key (every active surface x language; #928)
-- set_variant             — upsert one variant override for ANY active surface (device or a11y)
-- delete_variant          — delete one variant override for any surface (cell re-inherits base)
-- list_cognitive_candidates — text keys eligible for plain-language (cognitive) scoring
-- set_cognitive_score     — record a key's cognitive score (0-100) + plain-language suggestion (0 credit)
-- analyze_cognitive       — server AI cognitive analysis (billed; opt-in fallback to local scoring)
-
-A11y (accessibility) tools (a11y V1) extend the variant engine with four SEMANTIC
-surfaces — aria_label / alt_text / screen_reader / plain_language — orthogonal to
-the visible text. The report hits `/v1/mcp/projects/{id}/a11y-report`. Variant
-writes (set_variant / delete_variant, and the a11y-named set_a11y_variant /
-delete_a11y_variant) use the mcp:* code-addressed GENERIC route
-`/v1/mcp/projects/{id}/keys/{key_uuid}/variants/{language_code}/{surface}`, which
-accepts any surface ACTIVE for the project (device or a11y; #928) — locale
-reinjected straight from a report/matrix item. estimate/generate/translate are
-billed in credits. All are thin HTTP wrappers surfaced verbatim. Every tool is
-reachable with the same `mcp:*` key as the rest of the MCP surface.
-
-list_keys and list_untranslated_keys accept `include_glossary_hints=true` to
-attach backend-matched `glossary_hints[]` per key. All glossary matching is
-backend-side; these tools carry ZERO glossary logic client-side.
-
-Trash is UUID-addressed (key_uuids[]) — get key_uuid from list_keys (active) or
-list_trash (trashed). No hard-delete/purge over MCP (human-only JWT). reports +
-trash tools are thin HTTP wrappers, surfaced verbatim.
-
-The tool surface mirrors the canonical contract published in
-`docs/mcp/setup`. Argument names use the LLM-friendly `key` / `namespace` /
-`language_code` rather than uuids — the backend resolves uuids server-side.
-"""
-
-from __future__ import annotations
-
-import json
-import uuid
-from typing import Any
-
-from mcp.server import Server
-from mcp.types import TextContent, Tool
-
-from .client import VerbumiaApiError, VerbumiaClient
-
-# The four accessibility (a11y) variant surfaces (task 989). Distinct from the
-# device surfaces (desktop/mobile/tablet); these map to semantic attributes
-# (aria-label, <img alt>, sr-only text, clear-language rendering), not the
-# visible text. `surfaceKinds` in the variants matrix tags each as a11y.
-A11Y_SURFACES = ("aria_label", "alt_text", "screen_reader", "plain_language")
-
-# RS1 (1367) + FM1 (1390) + FF1 (1397): audit trail of t() repoints an agent made
-# while resolving a duplicate group — accepted on ALL FOUR resolution paths
-# (set_source_duplicate_merge_plan, set_duplicate_status, apply_new_key_cluster,
-# mark_cluster_applied), persisted + surfaced in resolved_duplicates[]. UNION-MERGE
-# (accumulate + dedup by normalized entry). FF1 split key_name into found_key +
-# replacement_key (key_name kept, deprecated).
-_FILES_MODIFIED_SCHEMA = {
-    "type": "array",
-    "description": (
-        "Optional audit trail of the t() repoints you made while resolving this group: "
-        "each {path (required), line?, found_key, replacement_key, occurrences?}. "
-        "`found_key` = the key string that WAS in the code at this spot (the old, "
-        "redundant one); `replacement_key` = the canonical you repointed it to (an "
-        "existing survivor, OR the new_key from apply_new_key_cluster). Accepted on "
-        "every resolution path and MERGED (union + dedup by the full normalized entry) "
-        "— record edits at whatever step you make them and they accumulate; omit to "
-        "preserve the existing list. Always pass the STRUCTURED field, never just a note."
-    ),
-    "items": {
-        "type": "object",
-        "properties": {
-            "path": {"type": "string", "description": "Repo-relative file path that was edited."},
-            "line": {"type": "integer", "description": "Optional 1-based line number of the edit."},
-            "found_key": {"type": "string", "description": "The OLD key found in the code at this spot (the redundant one being repointed away)."},
-            "replacement_key": {"type": "string", "description": "The CANONICAL key you repointed to (an existing survivor, or the created new_key)."},
-            "occurrences": {"type": "integer", "description": "Optional count of how many usages you replaced here."},
-            "key_name": {"type": "string", "description": "DEPRECATED (pre-FF1 single field) — prefer found_key + replacement_key."},
-        },
-        "required": ["path"],
-        "additionalProperties": False,
-    },
-}
-
-# Key semantic types (a11y key.type pivot). Default "text". The type decides
-# which a11y treatments a key offers (e.g. an `image` key's base value IS its
-# alt text; a `button` offers aria_label) — the engine gates variant/a11y tools
-# by type server-side, so listing these here is just for create/update_key.
-KEY_TYPES = (
-    "text",
-    "heading",
-    "label",
-    "caption",
-    "badge",
-    "tooltip",
-    "error_message",
-    "toast",
-    "button",
-    "link",
-    "menu_item",
-    "input_placeholder",
-    "input_label",
-    "image",
-    "icon",
-    "meta_title",
-    "meta_description",
-)
-
-# Human/LLM guidance for choosing a key's `type`. Embedded in the create_key /
-# update_key tool descriptions so an agent types keys correctly instead of
-# leaving everything as the "text" default. The type DRIVES which a11y
-# treatments + cognitive (plain-language) scoring a key gets, so it is the input
-# that makes the a11y tooling work.
-KEY_TYPE_GUIDANCE = (
-    "Set this at CREATION — do NOT leave everything as 'text'. The type drives "
-    "which a11y treatments the key offers (and whether it gets cognitive / "
-    "plain-language scoring), so correct typing is what lets the a11y tooling "
-    "work. Pick by the string's UI role:\n"
-    "- text — body / paragraph copy (offers plain_language, screen_reader)\n"
-    "- heading — a title or section heading (plain_language, screen_reader)\n"
-    "- label — a standalone short label (plain_language, screen_reader)\n"
-    "- caption — image caption / helper / secondary text (plain_language, screen_reader)\n"
-    "- button — a button's label (offers aria_label, screen_reader)\n"
-    "- link — a hyperlink / anchor label (aria_label, screen_reader)\n"
-    "- menu_item — a navigation / menu entry (aria_label, screen_reader)\n"
-    "- input_placeholder — a form input placeholder (aria_label)\n"
-    "- input_label — a form field's label (aria_label)\n"
-    "- tooltip — tooltip text (screen_reader)\n"
-    "- badge — a small status / count badge (screen_reader)\n"
-    "- error_message — a validation / error message (screen_reader)\n"
-    "- toast — a transient toast / snackbar notification (screen_reader)\n"
-    "- image — an image; THIS key's value IS the alt text\n"
-    "- icon — an icon; THIS key's value IS the accessible name (aria)\n"
-    "- meta_title — an SEO page <title> (no a11y treatment)\n"
-    "- meta_description — an SEO meta description (no a11y treatment)\n"
-    "Default 'text'. Reclassify existing keys later with update_key / "
-    "update_keys_bulk (type-only, no source_value needed). The current type is "
-    "returned by list_keys so you can audit and fix mis-typed keys."
-)
-
-
-def _project_uuid(arguments: dict | None, client: VerbumiaClient) -> str:
-    """Resolve project_uuid from per-call args or the configured env scope.
-
-    Rules (multi-project aware, 0.11+):
-      1. Explicit `project_uuid` in args wins. If `SONENTA_PROJECTS` is set
-         and the value isn't in that allowlist, raise early — better UX than
-         a backend 404/403 after a round-trip.
-      2. No explicit arg + exactly one configured project → use that one.
-      3. No explicit arg + multiple configured projects → raise asking the
-         caller to pass `project_uuid` and listing the allowed UUIDs.
-      4. No explicit arg + nothing configured → raise asking the caller to
-         pass `project_uuid` or set SONENTA_PROJECTS / SONENTA_PROJECT.
-    """
-    allowed = client.config.allowed_project_uuids
-    if arguments and arguments.get("project_uuid"):
-        requested = str(arguments["project_uuid"])
-        if allowed and requested not in allowed:
-            raise ValueError(
-                f"project_uuid {requested!r} is not in SONENTA_PROJECTS allowlist "
-                f"({', '.join(allowed)})"
-            )
-        return requested
-    if client.config.default_project_uuid:
-        return client.config.default_project_uuid
-    if allowed:
-        raise ValueError(
-            "project_uuid is required when multiple projects are configured "
-            "via SONENTA_PROJECTS (or the legacy SONENTA_PROJECT singular). "
-            f"Pass one of: {', '.join(allowed)}"
-        )
-    raise ValueError(
-        "project_uuid is required (pass it explicitly or set SONENTA_PROJECTS / SONENTA_PROJECT)"
-    )
-
-
-def _filter_projects_by_allowlist(data: Any, allowed: tuple[str, ...]) -> Any:
-    """Restrict a list_projects response to the SONENTA_PROJECTS allowlist so
-    `see == touch`: the backend returns everything the API key can reach, but
-    when the human has set an allowlist we only surface those projects — the
-    same scope `_project_uuid` enforces for get_project_info / writes. No
-    allowlist set → return `data` unchanged.
-    """
-    if allowed and isinstance(data, dict) and isinstance(data.get("items"), list):
-        return {**data, "items": [p for p in data["items"] if p.get("uuid") in allowed]}
-    return data
-
-
-def _text(payload: Any) -> list[TextContent]:
-    return [TextContent(type="text", text=json.dumps(payload, indent=2, default=str))]
-
-
-def _err(msg: str) -> list[TextContent]:
-    return [TextContent(type="text", text=f"error: {msg}")]
-
-
-def register(server: Server, client: VerbumiaClient) -> tuple[Any, Any]:
-    @server.list_tools()
-    async def _list_tools() -> list[Tool]:
-        return [
-            Tool(
-                name="list_projects",
-                description=(
-                    "List projects accessible to the configured Sonenta API key. "
-                    "Project-scoped keys return a single project; org-scoped keys "
-                    "return all projects in the org."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50}
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="get_project_info",
-                description=(
-                    "Fetch a project's metadata: source language, all configured "
-                    "languages, namespaces, key count. Use before list_missing_keys "
-                    "or propose_translation to learn what namespace + language codes "
-                    "are valid."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        }
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="distribution_info",
-                description=(
-                    "Get the project's CDN distribution status: the public CDN base "
-                    "URL + bundle URL template, the production version, which "
-                    "(language, namespace) bundles are currently published, and any "
-                    "gaps (bundles not yet published). Use to see what client SDKs "
-                    "can fetch right now."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        }
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="sonenta_guide",
-                description=(
-                    "Get the Sonenta usage guide: a concise, up-to-date overview of "
-                    "how this Sonenta instance works — core concepts, the translation "
-                    "workflow, how to publish to the CDN, and the available MCP tools. "
-                    "Takes no arguments. Call this first when unsure how to use Sonenta."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {},
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="list_keys",
-                description=(
-                    "List translation keys with their source-language value, their "
-                    "semantic `type`, and per-language translations. Designed for "
-                    "bulk translation: Claude can scan the result and propose "
-                    "translations for every key that's still missing in a target "
-                    "language. Each key's `type` lets you AUDIT typing and reclassify "
-                    "mis-typed keys (e.g. a button left as 'text') via update_key / "
-                    "update_keys_bulk so the a11y treatments apply. Filters: "
-                    "namespace slug, status_filter (only keys with at least one "
-                    "translation in that status), language_code (restrict "
-                    "translations[] to a single language)."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "namespace": {"type": "string", "description": "Namespace slug filter"},
-                        "language_code": {
-                            "type": "string",
-                            "description": "Restrict translations[] to one BCP-47 code (e.g. fr).",
-                        },
-                        "status_filter": {
-                            "type": "string",
-                            "enum": ["missing", "draft", "translated", "reviewed", "approved"],
-                            "description": "Include only keys with at least one translation in this status.",
-                        },
-                        "include_glossary_hints": {
-                            "type": "boolean",
-                            "default": False,
-                            "description": "When true, attach matched glossary_hints[] to each key (backend-matched against the source string). Default false.",
-                        },
-                        "cursor": {"type": "string"},
-                        "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50},
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="list_untranslated_keys",
-                description=(
-                    "List keys that DON'T yet have a valid translation in the "
-                    "target language. A key is untranslated when ANY of: no "
-                    "translation row exists, value is empty, or status is "
-                    "missing. Compact response (no translations[]) so Claude "
-                    "can iterate a long list and propose translations from "
-                    "source_value."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "language_code": {
-                            "type": "string",
-                            "description": "Required: target BCP-47 language code (e.g. fr).",
-                        },
-                        "namespace": {"type": "string", "description": "Namespace slug filter"},
-                        "include_glossary_hints": {
-                            "type": "boolean",
-                            "default": False,
-                            "description": "When true, attach matched glossary_hints[] to each key (term, rule_type, target_translation, matched_text) — backend-matched against the source string. Default false.",
-                        },
-                        "cursor": {"type": "string"},
-                        "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50},
-                    },
-                    "required": ["language_code"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="list_missing_keys",
-                description=(
-                    "List pending missing-key events captured from the SDK runtime. "
-                    "Cursor paginated (default page = 50). Filters: namespace slug, "
-                    "language_code, status. CALL missing_keys_stats FIRST to learn how "
-                    "many events exist so you know whether to keep paginating."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "namespace": {"type": "string"},
-                        "language_code": {"type": "string"},
-                        "status": {
-                            "type": "string",
-                            "enum": ["open", "acknowledged", "resolved"],
-                        },
-                        "cursor": {"type": "string"},
-                        "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50},
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="missing_keys_stats",
-                description=(
-                    "Count-only summary of missing-key events for a project. Returns "
-                    "{total, by_status, by_language, by_namespace}. Lightweight (no row "
-                    "payloads). Use this BEFORE list_missing_keys so you know how many "
-                    "pages remain and whether to keep paginating. Filters mirror "
-                    "list_missing_keys; status defaults to `open` (pass `all` to count "
-                    "every status)."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "namespace": {"type": "string"},
-                        "language_code": {"type": "string"},
-                        "status": {
-                            "type": "string",
-                            "description": "Defaults to `open`. Pass `all` to count every status.",
-                        },
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="acknowledge_missing_keys",
-                description=(
-                    "Batch-resolve a set of missing-event uuids. Use this to clean up "
-                    "the dashboard after deciding events are noise (typo, dead code, "
-                    "locale mismatch) — the project's `missing_keys_stats` total drops "
-                    "by the count returned. Idempotent: rows already resolved are "
-                    "counted under `already_resolved`; unknown uuids under `not_found`. "
-                    "Auto-resolution on key creation already covers the happy path; "
-                    "this is for the events you want to dismiss without creating a key."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "uuids": {
-                            "type": "array",
-                            "items": {"type": "string"},
-                            "minItems": 1,
-                            "maxItems": 500,
-                            "description": "Missing-event uuids to mark resolved.",
-                        },
-                    },
-                    "required": ["uuids"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="create_namespace",
-                description=(
-                    "Create a namespace (the container for keys). Idempotent on "
-                    "(project, slug): returns created=false if it already exists. "
-                    "slug must be lowercase letters/digits with internal hyphens "
-                    "(no leading/trailing hyphen, no underscore); an invalid slug "
-                    "returns a slug_invalid error rather than 'namespace not found'. "
-                    "Use this before create_key/propose_translation when the target "
-                    "namespace does not exist yet."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "slug": {
-                            "type": "string",
-                            "description": "Namespace slug: lowercase letters/digits + internal hyphens (e.g. common, marketing-site).",
-                        },
-                        "name": {"type": "string", "description": "Human-readable namespace name."},
-                        "description": {"type": "string"},
-                    },
-                    "required": ["slug", "name"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="create_key",
-                description=(
-                    "Create a translation key, idempotent on (namespace, name). "
-                    "Returns created=false if the key already exists. When "
-                    "source_value is supplied AND the project has a source "
-                    "language, the value is also written as a source-language "
-                    "translation in the same call. ALWAYS set `type` to the key's "
-                    "semantic role (button / link / heading / image / icon / "
-                    "input_label / …) — do NOT leave it as the default 'text'; the "
-                    "type drives the key's a11y treatments. See the `type` field for "
-                    "the full 17-type taxonomy and when to use each."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "namespace": {
-                            "type": "string",
-                            "description": "Namespace slug (LLM-friendly).",
-                        },
-                        "name": {
-                            "type": "string",
-                            "description": "Dot-notation key name (e.g. hero.title).",
-                        },
-                        "source_value": {
-                            "type": "string",
-                            "description": "Optional source-language value to seed.",
-                        },
-                        "description": {"type": "string"},
-                        "plurals": {"type": "boolean", "default": False},
-                        "max_length": {"type": "integer", "minimum": 1},
-                        "type": {
-                            "type": "string",
-                            "enum": list(KEY_TYPES),
-                            "default": "text",
-                            "description": "Semantic key type. " + KEY_TYPE_GUIDANCE,
-                        },
-                    },
-                    "required": ["namespace", "name"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="propose_translation",
-                description=(
-                    "Submit a translation value. Auto-creates the key if it "
-                    "doesn't exist (write-through). Status is set to draft (or "
-                    "translated if explicitly requested); reviewer/approved "
-                    "promotion requires a human reviewer. Identifies the key "
-                    "by namespace + key name + language_code — no uuids needed. "
-                    "The response carries `variable_warnings: {missing, extra}` "
-                    "(null when interpolation variables match the source) — a "
-                    "non-blocking flag for placeholder drift; check it and fix the "
-                    "value if set."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "namespace": {"type": "string"},
-                        "key": {"type": "string"},
-                        "language_code": {
-                            "type": "string",
-                            "description": "BCP-47 code (e.g. fr, fr-CA, es).",
-                        },
-                        "value": {"type": "string"},
-                        "status": {
-                            "type": "string",
-                            "enum": ["draft", "translated"],
-                            "default": "draft",
-                        },
-                    },
-                    "required": ["namespace", "key", "language_code", "value"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="create_keys_bulk",
-                description=(
-                    "Batch version of create_key: create up to 500 keys in one "
-                    "call, idempotent per item (existing keys return created=false). "
-                    "Returns a per-item results array + a summary roll-up; valid "
-                    "items commit even if siblings fail. Intra-batch duplicates "
-                    "(same namespace+name twice) error per item; the whole call is "
-                    "rejected if the new keys would exceed the org plan cap. NO "
-                    "server-side translation — this only batches the writes. Use "
-                    "this instead of N create_key calls for a backlog."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "items": {
-                            "type": "array",
-                            "minItems": 1,
-                            "maxItems": 500,
-                            "items": {
-                                "type": "object",
-                                "properties": {
-                                    "namespace": {"type": "string", "description": "Namespace slug."},
-                                    "name": {"type": "string", "description": "Dot-notation key name (e.g. hero.title)."},
-                                    "source_value": {"type": "string", "description": "Optional source-language value to seed."},
-                                    "description": {"type": "string"},
-                                    "plurals": {"type": "boolean", "default": False},
-                                    "max_length": {"type": "integer", "minimum": 1},
-                                    "type": {"type": "string", "enum": list(KEY_TYPES), "default": "text", "description": "Semantic key type — set per item by the string's UI role (button / image / heading / …); do NOT default everything to 'text'. See create_key's `type` field for the full taxonomy and why it matters for a11y."},
-                                },
-                                "required": ["namespace", "name"],
-                                "additionalProperties": False,
-                            },
-                        },
-                    },
-                    "required": ["items"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="update_key",
-                description=(
-                    "Edit a key in place — its SOURCE-language value, its `type`, "
-                    "and/or its description (pass at least one). Preserves the "
-                    "key and its history (version bump + history revision + audit). "
-                    "Address the key by EITHER key_uuid (preferred; from list_keys) "
-                    "OR namespace + name — exactly one of the two. When the source "
-                    "value ACTUALLY changes, the key's reviewed/approved target "
-                    "translations are demoted to needs-review (\"translated\"); "
-                    "missing/draft/translated targets are untouched, and "
-                    "stale_flagged reports how many were demoted. Submitting the "
-                    "current value is a no-op (result=unchanged, not billed). A "
-                    "real source change (or a description-only change) bills 1 unit."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "key_uuid": {
-                            "type": "string",
-                            "description": "Key uuid to update (preferred addressing; get it from list_keys). Mutually exclusive with namespace+name.",
-                        },
-                        "namespace": {
-                            "type": "string",
-                            "description": "Namespace slug (use with name as an alternative to key_uuid).",
-                        },
-                        "name": {
-                            "type": "string",
-                            "description": "Dot-notation key name (use with namespace as an alternative to key_uuid).",
-                        },
-                        "source_value": {
-                            "type": "string",
-                            "description": "New source-language value to write.",
-                        },
-                        "description": {
-                            "type": "string",
-                            "description": "Optional: also update the key's description.",
-                        },
-                        "type": {
-                            "type": "string",
-                            "enum": list(KEY_TYPES),
-                            "description": "Optional: reclassify the key's semantic type (see create_key). Changing the type re-gates which a11y treatments the key offers.",
-                        },
-                    },
-                    "required": [],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="update_keys_bulk",
-                description=(
-                    "Batch version of update_key: edit up to 500 keys' SOURCE "
-                    "values in one call. Returns a per-item results array + a "
-                    "summary roll-up; valid items commit even if siblings fail "
-                    "(status ok | unchanged | error per item). Each item addresses "
-                    "its key by EITHER key_uuid OR namespace + name (exactly one). "
-                    "Same staleness, no-op and billing semantics as update_key "
-                    "(1 unit per key actually changed; no-ops and errors are free). "
-                    "Use this instead of N update_key calls for a backlog."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "items": {
-                            "type": "array",
-                            "minItems": 1,
-                            "maxItems": 500,
-                            "items": {
-                                "type": "object",
-                                "properties": {
-                                    "key_uuid": {"type": "string", "description": "Key uuid (preferred). Mutually exclusive with namespace+name."},
-                                    "namespace": {"type": "string", "description": "Namespace slug (use with name)."},
-                                    "name": {"type": "string", "description": "Dot-notation key name (use with namespace)."},
-                                    "source_value": {"type": "string", "description": "New source-language value to write."},
-                                    "description": {"type": "string", "description": "Optional: also update the key's description."},
-                                    "type": {"type": "string", "enum": list(KEY_TYPES), "description": "Optional: reclassify the key's semantic type (see create_key)."},
-                                },
-                                "required": [],
-                                "additionalProperties": False,
-                            },
-                        },
-                    },
-                    "required": ["items"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="propose_translations_bulk",
-                description=(
-                    "Batch version of propose_translation: submit up to 500 "
-                    "translation values in one call. Auto-creates missing keys "
-                    "(write-through). Returns a per-item results array + summary; "
-                    "an item whose value AND status already match returns "
-                    "status=unchanged (no-op). Intra-batch duplicates "
-                    "(same namespace+key+language twice) error per item; status is "
-                    "draft (or translated if requested), reviewed/approved require "
-                    "a human reviewer. NO server-side translation — values come "
-                    "from you. Use this instead of N propose_translation calls. "
-                    "Each result carries `variable_warnings: {missing, extra}` "
-                    "(null when interpolation variables match the source) flagging "
-                    "placeholder drift, non-blocking."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "items": {
-                            "type": "array",
-                            "minItems": 1,
-                            "maxItems": 500,
-                            "items": {
-                                "type": "object",
-                                "properties": {
-                                    "namespace": {"type": "string"},
-                                    "key": {"type": "string"},
-                                    "language_code": {"type": "string", "description": "BCP-47 code (e.g. fr, fr-CA, es)."},
-                                    "value": {"type": "string"},
-                                    "status": {"type": "string", "enum": ["draft", "translated"], "default": "draft"},
-                                },
-                                "required": ["namespace", "key", "language_code", "value"],
-                                "additionalProperties": False,
-                            },
-                        },
-                    },
-                    "required": ["items"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="publish_cdn",
-                description=(
-                    "Trigger a CDN release for the project. Builds bundles "
-                    "for every (language, namespace) combo (or restricted to "
-                    "the ones you pass) and pushes them to the public CDN. "
-                    "Idempotent: re-running with no content changes returns "
-                    "the same bundles as `reused`. Subscribed SDKs receive a "
-                    "Centrifugo `translations_published` event for every "
-                    "newly created bundle and can refresh in-place."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "language_code": {
-                            "type": "string",
-                            "description": "Restrict to one BCP-47 language. Omit for ALL.",
-                        },
-                        "namespace": {
-                            "type": "string",
-                            "description": "Restrict to one namespace slug. Omit for ALL.",
-                        },
-                        "version_slug": {
-                            "type": "string",
-                            "description": "Project version slug. Defaults to the production version.",
-                        },
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="validate_translations",
-                description=(
-                    "Lint a JSON i18next blob against the project: checks for "
-                    "missing keys, extra keys, and placeholder parity ({var}, "
-                    "{{var}}, %{var}) vs the source language. Each "
-                    "`placeholder_mismatches[]` item carries `expected` / `got` plus "
-                    "`missing` (source variables absent from the translation) and "
-                    "`extra` (variables in the translation unknown to the source)."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "language_code": {"type": "string"},
-                        "namespace": {
-                            "type": "string",
-                            "description": "Restrict to one namespace (default: all).",
-                        },
-                        "payload": {
-                            "type": "object",
-                            "description": "The translation tree to validate.",
-                        },
-                    },
-                    "required": ["language_code", "payload"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="project_context_get",
-                description=(
-                    "Read the project's markdown context document. The document is "
-                    "free-form prose attached to the project (terminology, brand "
-                    "voice, constraints, domain — e.g. religious, technical, "
-                    "medical, gaming, legal) and is intended as ambient context for "
-                    "human translators AND for AI agents producing translations. "
-                    "Call this BEFORE batch-translating: prepend the content to your "
-                    "translation prompts so every output stays consistent with the "
-                    "project's terminology and tone. Empty content means the project "
-                    "owner hasn't authored a context yet — that's not an error. "
-                    "Requires API-key scope: project:read."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        }
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="project_context_set",
-                description=(
-                    "Upsert the project's markdown context document. Replaces the "
-                    "entire document — fetch first with project_context_get if you "
-                    "want to append rather than overwrite. Use this to memorise "
-                    "terminology choices, glossary entries, domain framing (e.g. "
-                    "'this is a Catholic-liturgy app — use traditional vocabulary, "
-                    "avoid neologisms'), tone guidance, and translation constraints "
-                    "you discover while working the project. Hard cap: 100 KiB. "
-                    "Requires API-key scope: project:settings:write (narrower than "
-                    "project:write — settings changes propagate to every translator's "
-                    "prompt context)."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "content": {
-                            "type": "string",
-                            "description": "New markdown content (UTF-8, ≤ 100 KiB).",
-                        },
-                    },
-                    "required": ["content"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="glossary_list",
-                description=(
-                    "List a project's glossary entries — the terminology rules the "
-                    "backend applies when matching source strings. Filters: rule_type "
-                    "(translation | do_not_translate | forbidden), q (case-insensitive "
-                    "substring on the term), limit (1..500, default 200). Returns "
-                    "{items: [GlossaryEntry], total}. Matching itself is backend-side; "
-                    "this only lists the rules."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "rule_type": {
-                            "type": "string",
-                            "enum": ["translation", "do_not_translate", "forbidden"],
-                            "description": "Filter to one rule type.",
-                        },
-                        "q": {
-                            "type": "string",
-                            "description": "Case-insensitive substring filter on the term.",
-                        },
-                        "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 200},
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="glossary_create",
-                description=(
-                    "Create a glossary entry. rule_type is one of translation | "
-                    "do_not_translate | forbidden and defaults to 'translation'. "
-                    "`translations` ({<locale>: value}) is honored only for "
-                    "rule_type='translation' (cleared otherwise by the backend). "
-                    "Returns the created GlossaryEntry. Errors 409 if an entry with "
-                    "the same (rule_type, term) already exists — use glossary_update "
-                    "to change an existing one."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "rule_type": {
-                            "type": "string",
-                            "enum": ["translation", "do_not_translate", "forbidden"],
-                            "default": "translation",
-                            "description": "Rule type. Defaults to 'translation'.",
-                        },
-                        "term": {
-                            "type": "string",
-                            "description": "The source term/phrase the rule applies to.",
-                        },
-                        "translations": {
-                            "type": "object",
-                            "description": "Per-locale target translations, e.g. {\"fr\": \"tableau de bord\"}. Only used for rule_type='translation'.",
-                        },
-                        "case_sensitive": {
-                            "type": "boolean",
-                            "default": False,
-                            "description": "Match the term case-sensitively.",
-                        },
-                        "note": {"type": "string", "description": "Optional human note."},
-                    },
-                    "required": ["term"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="glossary_update",
-                description=(
-                    "Update a glossary entry by its uuid (entry_id). Send only the "
-                    "fields to change: term, translations, case_sensitive, note. "
-                    "rule_type is immutable — delete and recreate to change it. "
-                    "Returns the updated GlossaryEntry; 404 if entry_id is unknown, "
-                    "409 on a term clash with another entry of the same rule_type."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "entry_id": {
-                            "type": "string",
-                            "description": "The GlossaryEntry uuid to update.",
-                        },
-                        "term": {"type": "string"},
-                        "translations": {
-                            "type": "object",
-                            "description": "Per-locale target translations (rule_type='translation' only).",
-                        },
-                        "case_sensitive": {"type": "boolean"},
-                        "note": {"type": "string"},
-                    },
-                    "required": ["entry_id"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="glossary_delete",
-                description=(
-                    "Delete a glossary entry by its uuid (entry_id). Returns "
-                    "{deleted: true, entry_id}. A missing entry_id returns 404."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "entry_id": {
-                            "type": "string",
-                            "description": "The GlossaryEntry uuid to delete.",
-                        },
-                    },
-                    "required": ["entry_id"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="health_report",
-                description=(
-                    "Read-only SOURCE-HEALTH report for the project (#752): issues in the "
-                    "source strings with by_issue / by_severity rollups + per-key items. "
-                    "Defaults to the production version; pass version_id for a specific "
-                    "version. Surfaced verbatim (read-only)."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "version_id": {
-                            "type": "string",
-                            "description": "Optional version UUID; defaults to the production version.",
-                        },
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="coverage_report",
-                description=(
-                    "Read-only translation-COVERAGE report for the project (#752): global "
-                    "completeness, total key count, and per-language coverage. Defaults to "
-                    "the production version; pass version_id for a specific version. "
-                    "Surfaced verbatim (read-only)."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "version_id": {
-                            "type": "string",
-                            "description": "Optional version UUID; defaults to the production version.",
-                        },
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="delete_keys_bulk",
-                description=(
-                    "Soft-delete (move to TRASH) up to 500 keys by their key_uuid. "
-                    "Restorable via restore_keys_bulk. Idempotent: already-trashed keys "
-                    "are reported unchanged, unknown uuids not_found. Trashed keys "
-                    "disappear from list_keys, list_untranslated_keys, the CDN, and the "
-                    "reports. Get key_uuid from list_keys. NO hard-delete/purge over MCP "
-                    "(purge is human-only via the dashboard)."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "key_uuids": {
-                            "type": "array",
-                            "items": {"type": "string"},
-                            "minItems": 1,
-                            "maxItems": 500,
-                            "description": "Key uuids to trash (get them from list_keys).",
-                        },
-                    },
-                    "required": ["key_uuids"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="restore_keys_bulk",
-                description=(
-                    "Restore up to 500 trashed keys by their key_uuid (from list_trash). "
-                    "Idempotent: already-active keys are reported unchanged, unknown uuids "
-                    "not_found; a key whose name was re-created while it was trashed is "
-                    "reported as a conflict. Get key_uuid from list_trash."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "key_uuids": {
-                            "type": "array",
-                            "items": {"type": "string"},
-                            "minItems": 1,
-                            "maxItems": 500,
-                            "description": "Key uuids to restore (get them from list_trash).",
-                        },
-                    },
-                    "required": ["key_uuids"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="list_trash",
-                description=(
-                    "List trashed (soft-deleted) keys: items of {key_uuid, namespace, "
-                    "name, deleted_at}, cursor-paginated. Feed key_uuid to "
-                    "restore_keys_bulk to bring them back."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "cursor": {"type": "string"},
-                        "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 50},
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="a11y_estimate",
-                description=(
-                    "Preview the CREDIT cost of an a11y generate/translate run BEFORE "
-                    "spending anything (task 990). Returns {units, credit_cost_per_unit, "
-                    "credits_required, balance, sufficient}. ALWAYS call this before "
-                    "generate_a11y_variant / translate_a11y_variants so you know the cost "
-                    "and whether the balance covers it. mode=generate counts missing "
-                    "(key, surface) source variants; mode=translate counts "
-                    "(key, surface, target-language) cells lacking a translation."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "mode": {
-                            "type": "string",
-                            "enum": ["generate", "translate"],
-                            "description": "generate = source-language a11y variants; translate = propagate existing a11y overrides into target locales.",
-                        },
-                        "tier": {
-                            "type": "string",
-                            "enum": ["standard", "premium"],
-                            "default": "standard",
-                            "description": "Quality tier (credit_cost per unit: standard=1, premium=4).",
-                        },
-                        "surfaces": {
-                            "type": "array",
-                            "items": {"type": "string", "enum": list(A11Y_SURFACES)},
-                            "description": "a11y surfaces to scope to. Omit/empty = all four (aria_label, alt_text, screen_reader, plain_language).",
-                        },
-                        "language_codes": {
-                            "type": "array",
-                            "items": {"type": "string"},
-                            "description": "Target locales (translate mode only), e.g. ['fr','es'].",
-                        },
-                        "key_uuids": {
-                            "type": "array",
-                            "items": {"type": "string"},
-                            "description": "Restrict to these keys (get key_uuid from list_keys). Omit to scope the whole project (or a namespace).",
-                        },
-                        "namespace_uuid": {
-                            "type": "string",
-                            "description": "Restrict to one namespace by its UUID.",
-                        },
-                    },
-                    "required": ["mode"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="generate_a11y_variant",
-                description=(
-                    "AI-generate SOURCE-language a11y variants for keys that lack them "
-                    "(task 990). aria_label / screen_reader / plain_language are derived "
-                    "from the key's visible text; alt_text from the key's context/"
-                    "description. Only fills (key, surface) cells with NO existing override "
-                    "and an available source. BILLS CREDITS (standard=1, premium=4 per "
-                    "generated item, debit upfront + refund undelivered) — call a11y_estimate "
-                    "first. Results are draft (bot-authored) overrides that flow to the CDN "
-                    "a11y overlays. Returns {generated, requested, credits_charged, "
-                    "credits_refunded}."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "tier": {
-                            "type": "string",
-                            "enum": ["standard", "premium"],
-                            "default": "standard",
-                            "description": "Quality tier (credit_cost per unit: standard=1, premium=4).",
-                        },
-                        "surfaces": {
-                            "type": "array",
-                            "items": {"type": "string", "enum": list(A11Y_SURFACES)},
-                            "description": "a11y surfaces to generate. Omit/empty = all four.",
-                        },
-                        "key_uuids": {
-                            "type": "array",
-                            "items": {"type": "string"},
-                            "description": "Restrict to these keys (get key_uuid from list_keys). Omit to scope the whole project (or a namespace).",
-                        },
-                        "namespace_uuid": {
-                            "type": "string",
-                            "description": "Restrict to one namespace by its UUID.",
-                        },
-                        "idempotency_key": {
-                            "type": "string",
-                            "description": "Stable token making this billable call safe to retry: reuse the SAME value to avoid a double-charge on retry. A random one is generated if omitted (so a blind retry would re-bill).",
-                        },
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="translate_a11y_variants",
-                description=(
-                    "Translate EXISTING source-language a11y overrides into target locales "
-                    "(task 990). Only translates (key, surface) that HAVE a source override, "
-                    "into the requested languages that lack one. BILLS CREDITS "
-                    "(standard=1, premium=4 per item, debit upfront + refund undelivered) — "
-                    "call a11y_estimate (mode=translate) first. Results are draft "
-                    "(bot-authored) overrides that flow to the CDN a11y overlays. Returns "
-                    "{translated, requested, credits_charged, credits_refunded}."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "tier": {
-                            "type": "string",
-                            "enum": ["standard", "premium"],
-                            "default": "standard",
-                            "description": "Quality tier (credit_cost per unit: standard=1, premium=4).",
-                        },
-                        "language_codes": {
-                            "type": "array",
-                            "items": {"type": "string"},
-                            "minItems": 1,
-                            "description": "Target locales to translate into, e.g. ['fr','es'].",
-                        },
-                        "surfaces": {
-                            "type": "array",
-                            "items": {"type": "string", "enum": list(A11Y_SURFACES)},
-                            "description": "a11y surfaces to translate. Omit/empty = all four.",
-                        },
-                        "key_uuids": {
-                            "type": "array",
-                            "items": {"type": "string"},
-                            "description": "Restrict to these keys (get key_uuid from list_keys). Omit to scope the whole project (or a namespace).",
-                        },
-                        "namespace_uuid": {
-                            "type": "string",
-                            "description": "Restrict to one namespace by its UUID.",
-                        },
-                        "idempotency_key": {
-                            "type": "string",
-                            "description": "Stable token making this billable call safe to retry: reuse the SAME value to avoid a double-charge on retry. A random one is generated if omitted (so a blind retry would re-bill).",
-                        },
-                    },
-                    "required": ["language_codes"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="a11y_report",
-                description=(
-                    "Read-only WCAG ACCESSIBILITY quality report for the project "
-                    "(task 991): per key/surface/locale a11y gaps with by_gap / "
-                    "by_severity / by_surface rollups + per-item details. Gap types: "
-                    "a11y_untranslated (a source a11y override exists but this target "
-                    "locale lacks it), alt_missing (image key with no source alt_text), "
-                    "reading_level_high (hard source text + no plain_language), "
-                    "a11y_variant_absent (a require_surface is missing in the source). "
-                    "Gaps are TYPE-AWARE: only treatments relevant to each key's type are "
-                    "reported (e.g. alt_missing only on image keys, aria gaps only on "
-                    "buttons/links/inputs), so a text key is never flagged for aria/alt. "
-                    "Defaults to the production version. Surfaced verbatim — use "
-                    "list_a11y_gaps for just the actionable item list."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "version_id": {
-                            "type": "string",
-                            "description": "Optional version UUID; defaults to the production version.",
-                        },
-                        "require_surface": {
-                            "type": "array",
-                            "items": {"type": "string", "enum": list(A11Y_SURFACES)},
-                            "description": "a11y surfaces to additionally flag as ABSENT in the source (produces a11y_variant_absent gaps), e.g. ['aria_label','alt_text'].",
-                        },
-                        "reading_level_max_words": {
-                            "type": "integer",
-                            "minimum": 5,
-                            "maximum": 60,
-                            "description": "Readability heuristic threshold (sentence length) for reading_level_high gaps. Default 15 server-side.",
-                        },
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="list_a11y_gaps",
-                description=(
-                    "List the actionable a11y gaps (the items[] of a11y_report, task "
-                    "991), optionally filtered client-side. Each gap = {key_uuid, "
-                    "key_name, namespace_slug, surface, locale, gap, severity, detail}. "
-                    "To find keys/surfaces with NO a11y variant in the source, pass "
-                    "require_surface=<surface> and filter gap='a11y_variant_absent'. "
-                    "Feed key_uuid + surface (+ locale) into set_a11y_variant to fix one, "
-                    "or generate_a11y_variant / translate_a11y_variants to fill them in "
-                    "bulk."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "gap": {
-                            "type": "string",
-                            "enum": [
-                                "a11y_untranslated",
-                                "alt_missing",
-                                "reading_level_high",
-                                "a11y_variant_absent",
-                            ],
-                            "description": "Client-side filter: keep only gaps of this type.",
-                        },
-                        "surface": {
-                            "type": "string",
-                            "enum": list(A11Y_SURFACES),
-                            "description": "Client-side filter: keep only gaps on this a11y surface.",
-                        },
-                        "locale": {
-                            "type": "string",
-                            "description": "Client-side filter: keep only gaps for this target locale code (e.g. 'fr'). Source-level gaps have locale=null.",
-                        },
-                        "require_surface": {
-                            "type": "array",
-                            "items": {"type": "string", "enum": list(A11Y_SURFACES)},
-                            "description": "a11y surfaces to flag as ABSENT in the source (produces a11y_variant_absent gaps). Pair with gap='a11y_variant_absent' to list keys missing a surface.",
-                        },
-                        "version_id": {
-                            "type": "string",
-                            "description": "Optional version UUID; defaults to the production version.",
-                        },
-                        "reading_level_max_words": {
-                            "type": "integer",
-                            "minimum": 5,
-                            "maximum": 60,
-                            "description": "Readability heuristic threshold for reading_level_high gaps. Default 15 server-side.",
-                        },
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="list_untranslated_surfaces",
-                description=(
-                    "The TRANSLATION MAP: every a11y surface cell that has an APPROVED "
-                    "SOURCE value but is missing the target-language translation, WITH that "
-                    "source value to translate from. Returns {cells: [{key_uuid, key_name, "
-                    "namespace_slug, key_type, surface, language_code, source_value}]}. Use "
-                    "this to fill a11y surfaces (aria_label / alt_text / screen_reader / "
-                    "plain_language) by FAITHFULLY translating each source_value into the "
-                    "missing language — do NOT invent new content — then write each with "
-                    "set_a11y_variant(key_uuid, language_code, surface, <translation>). "
-                    "Optionally filter by surface and/or language_code. (Local-first: you "
-                    "translate; 0 AI credits. The billed server path is translate_a11y_variants.)"
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "surface": {
-                            "type": "string",
-                            "enum": list(A11Y_SURFACES),
-                            "description": "Optional: only this a11y surface.",
-                        },
-                        "language_code": {
-                            "type": "string",
-                            "description": "Optional: only this target language (BCP-47).",
-                        },
-                        "version_id": {
-                            "type": "string",
-                            "description": "Optional version UUID; defaults to the production version.",
-                        },
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="set_a11y_variant",
-                description=(
-                    "Upsert ONE a11y variant override for (key, language, surface) — the "
-                    "manual fix for a gap (a11y V1). surface ∈ aria_label | alt_text | "
-                    "screen_reader | plain_language. The value is a TEXT string (the "
-                    "semantic a11y text, e.g. the accessible name or the simplified "
-                    "wording), translatable later via translate_a11y_variants. Address "
-                    "the key by key_uuid and the language by its locale CODE — exactly "
-                    "the (key_uuid, surface, locale) a gap carries in a11y_report, so you "
-                    "can fix it without resolving any UUID. Stored as a draft (bot) "
-                    "override. Returns {key_uuid, surface, language_code, value, status}."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "key_uuid": {
-                            "type": "string",
-                            "description": "Key UUID (from list_keys or a11y_report / list_a11y_gaps items).",
-                        },
-                        "language_code": {
-                            "type": "string",
-                            "description": "Target locale CODE, e.g. 'fr' (the `locale` field of an a11y_report item). The backend resolves it to the language; 404 if unknown.",
-                        },
-                        "surface": {
-                            "type": "string",
-                            "enum": list(A11Y_SURFACES),
-                            "description": "Which a11y surface to set.",
-                        },
-                        "value": {
-                            "type": "string",
-                            "description": "The a11y text value for this (key, language, surface).",
-                        },
-                    },
-                    "required": ["key_uuid", "language_code", "surface", "value"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="delete_a11y_variant",
-                description=(
-                    "Delete ONE a11y variant override for (key, language, surface) "
-                    "(a11y V1). The cell re-inherits the base value per the locale/surface "
-                    "fallback chain; a 404 means there was no override to remove. Address "
-                    "by key_uuid + language_code + surface (same as set_a11y_variant)."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "key_uuid": {
-                            "type": "string",
-                            "description": "Key UUID (from list_keys or a11y_report / list_a11y_gaps items).",
-                        },
-                        "language_code": {
-                            "type": "string",
-                            "description": "Target locale CODE, e.g. 'fr' (the `locale` field of an a11y_report item).",
-                        },
-                        "surface": {
-                            "type": "string",
-                            "enum": list(A11Y_SURFACES),
-                            "description": "Which a11y surface to clear.",
-                        },
-                    },
-                    "required": ["key_uuid", "language_code", "surface"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="list_surfaces",
-                description=(
-                    "List the project's configurable SURFACES (task 928): the device "
-                    "and a11y surfaces variants can be authored for. Returns "
-                    "{surfaces:[{slug, label, kind, builtin, active}]} where kind is "
-                    "'device' or 'a11y'. An un-customized project lazily defaults to the "
-                    "builtins — device: desktop/mobile/tablet; a11y: aria_label/alt_text/"
-                    "screen_reader/plain_language — all active. Only ACTIVE surfaces accept "
-                    "variant writes and get published to the CDN."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="create_surface",
-                description=(
-                    "Create a CUSTOM DEVICE surface for the project (task 928), e.g. "
-                    "'watch', 'tv', 'kiosk'. Device surfaces are extensible; a11y surfaces "
-                    "are a FIXED semantic set — creating an a11y slug (e.g. aria_label) is "
-                    "rejected with 422. Returns the updated surface catalog. Builtins need "
-                    "no creation (they exist lazily)."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "slug": {
-                            "type": "string",
-                            "pattern": "^[a-z0-9_-]{1,40}$",
-                            "description": "Surface slug: lowercase letters, digits, '_' or '-', 1-40 chars (e.g. 'watch').",
-                        },
-                        "label": {
-                            "type": "string",
-                            "description": "Optional human-readable label (defaults from the slug).",
-                        },
-                    },
-                    "required": ["slug"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="update_surface",
-                description=(
-                    "Rename and/or toggle a surface (task 928): set its `label` and/or "
-                    "`active`. Deactivating is SOFT — existing variants are RETAINED but "
-                    "hidden and dropped from the CDN until reactivated (which republishes "
-                    "them); the response `affected_variants` reports how many are impacted. "
-                    "Builtins can be toggled/renamed but not deleted. Returns "
-                    "{surfaces, affected_variants}."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "slug": {
-                            "type": "string",
-                            "description": "Slug of the surface to update.",
-                        },
-                        "label": {
-                            "type": "string",
-                            "description": "New human-readable label (rename).",
-                        },
-                        "active": {
-                            "type": "boolean",
-                            "description": "Activate (true) or soft-deactivate (false) the surface.",
-                        },
-                    },
-                    "required": ["slug"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="delete_surface",
-                description=(
-                    "Delete a CUSTOM surface (task 928). Builtins cannot be deleted — "
-                    "deactivate them with update_surface(active=false) instead (a 422/409 "
-                    "is returned if you try to delete a builtin). Deleting a custom surface "
-                    "removes it from the catalog."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "slug": {
-                            "type": "string",
-                            "description": "Slug of the custom surface to delete.",
-                        },
-                    },
-                    "required": ["slug"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="recommend_surfaces",
-                description=(
-                    "Read-only per-key A11Y SURFACE RECOMMENDATIONS (#2): for each key, "
-                    "the a11y surfaces implied by its semantic TYPE, derived from the "
-                    "backend's authoritative key.type -> treatment mapping "
-                    "(A11Y_TREATMENTS_BY_TYPE) — the single source of truth; do NOT "
-                    "reimplement the mapping in the client. Returns {project_uuid, "
-                    "version_uuid, active_a11y_surfaces[], keys_scanned, keys_with_gaps, "
-                    "gaps_by_surface{surface:int}, items:[{key_uuid, key_name, "
-                    "namespace_slug, type, base_role (visible_text|alt_text|"
-                    "accessible_name), recommended_surfaces:[{surface, active, "
-                    "present_in_source}], has_gap}]}. A recommended surface that is "
-                    "active && !present_in_source is a config-satisfied GAP to AUTHOR — "
-                    "hand the actual text off to sonenta-a11y (set_a11y_variant), this "
-                    "tool only tells you WHERE. DEVICE surfaces are not included here. "
-                    "Defaults to the production version."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "version_id": {
-                            "type": "string",
-                            "description": "Optional version UUID; defaults to the production version.",
-                        },
-                        "namespace_id": {
-                            "type": "string",
-                            "description": "Optional namespace UUID to scope the scan.",
-                        },
-                        "key_id": {
-                            "type": "string",
-                            "description": "Optional single key UUID to scope the scan.",
-                        },
-                        "only_gaps": {
-                            "type": "boolean",
-                            "description": "When true, return only keys that have a gap (has_gap=true).",
-                        },
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="surface_coverage",
-                description=(
-                    "Read-only COVERAGE BY SURFACE (#3): per active surface, how complete "
-                    "it is. Returns {project_uuid, version_uuid, languages[], keys_total, "
-                    "surfaces:[{surface, label, kind, meaning, eligible_keys, "
-                    "eligible_cells, present_cells, pct, by_language:[{code, eligible, "
-                    "present, pct}]}]}. The `meaning` field tells you how to read `pct`: "
-                    "'a11y_completeness' for a11y surfaces (eligible = type-relevant keys; "
-                    "pct = real fill of NEEDED a11y gaps), 'override_density' for device "
-                    "surfaces (un-overridden cells fall back to the base value — that is "
-                    "NOT broken, just un-customized). Defaults to the production version."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "version_id": {
-                            "type": "string",
-                            "description": "Optional version UUID; defaults to the production version.",
-                        },
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="get_variants",
-                description=(
-                    "Read the full VARIANT MATRIX for one key (task 928): every surface "
-                    "OFFERED for the key x every project language, with each cell's "
-                    "{override, value, resolvedValue, status, drift, ...}. The response "
-                    "lists `surfaces` and `surfaceKinds` ({surface: 'device'|'a11y'}) — "
-                    "these are the key's offered surfaces only: the project's active "
-                    "device surfaces plus the a11y treatments relevant to the key's TYPE "
-                    "(e.g. a text key shows no aria/alt). This is the source of truth for "
-                    "which surfaces set_variant will accept. Address by key_uuid (from "
-                    "list_keys). Surfaced verbatim."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "key_uuid": {
-                            "type": "string",
-                            "description": "Key UUID (from list_keys).",
-                        },
-                    },
-                    "required": ["key_uuid"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="set_variant",
-                description=(
-                    "Upsert ONE variant override for (key, language, surface) for ANY "
-                    "surface active on the project (task 928) — device (desktop / mobile / "
-                    "tablet / custom like watch / tv) OR a11y (aria_label / alt_text / "
-                    "screen_reader / plain_language). Address by key_uuid + locale CODE + "
-                    "surface slug (the fields get_variants / list_keys already give you). "
-                    "Stored as a draft. 422 unless the surface is OFFERED for this key — "
-                    "an active device surface (see list_surfaces) OR an a11y treatment "
-                    "relevant to the key's TYPE (e.g. no aria_label on a text key; see "
-                    "get_variants for the key's offered surfaces); 409 if the cell is "
-                    "already reviewed/approved (never overwritten). Returns {key_uuid, "
-                    "surface, language_code, value, status}. (For a11y specifically you "
-                    "can also use set_a11y_variant.)"
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "key_uuid": {
-                            "type": "string",
-                            "description": "Key UUID (from list_keys / get_variants).",
-                        },
-                        "language_code": {
-                            "type": "string",
-                            "description": "Target locale CODE, e.g. 'fr'. Backend resolves it; 404 if unknown.",
-                        },
-                        "surface": {
-                            "type": "string",
-                            "description": "Surface slug — any surface ACTIVE for the project (device or a11y). See list_surfaces.",
-                        },
-                        "value": {
-                            "type": "string",
-                            "description": "The variant text value for this (key, language, surface).",
-                        },
-                    },
-                    "required": ["key_uuid", "language_code", "surface", "value"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="delete_variant",
-                description=(
-                    "Delete ONE variant override for (key, language, surface), for ANY "
-                    "surface (device or a11y) — task 928. The cell re-inherits the base "
-                    "value; a 404 means there was no override. Address by key_uuid + "
-                    "language_code + surface (same as set_variant)."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "key_uuid": {
-                            "type": "string",
-                            "description": "Key UUID (from list_keys / get_variants).",
-                        },
-                        "language_code": {
-                            "type": "string",
-                            "description": "Target locale CODE, e.g. 'fr'.",
-                        },
-                        "surface": {
-                            "type": "string",
-                            "description": "Surface slug (device or a11y) to clear.",
-                        },
-                    },
-                    "required": ["key_uuid", "language_code", "surface"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="list_cognitive_candidates",
-                description=(
-                    "List keys that are CANDIDATES for plain-language (cognitive) scoring: "
-                    "text-relevant keys (a type that offers plain_language — text / heading "
-                    "/ label / caption) whose source value clears a small word floor. This "
-                    "is a scope filter, NOT a difficulty judgement — score them to find the "
-                    "hard ones. Pass only_unanalyzed=true to skip keys already scored. Each "
-                    "item carries key_uuid + source_value so you can score it locally with "
-                    "set_cognitive_score."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "only_unanalyzed": {
-                            "type": "boolean",
-                            "description": "Only return keys with no cognitive_score yet (not analyzed).",
-                        },
-                        "namespace_uuid": {
-                            "type": "string",
-                            "description": "Restrict to one namespace by its UUID.",
-                        },
-                        "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 100},
-                        "offset": {"type": "integer", "minimum": 0, "default": 0},
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="set_cognitive_score",
-                description=(
-                    "Record a key's cognitive-difficulty SCORE (0-100, higher = harder to "
-                    "read) and an optional plain-language SUGGESTION — the local-first, "
-                    "**0-credit** path. Use this after scoring a candidate YOURSELF: you "
-                    "(the agent) judge the difficulty and write a clearer rewrite, then "
-                    "persist both here (marked by_bot). A key only enters the review queue "
-                    "(reading_level_high) once its score is >= the project threshold "
-                    "(default 60). The suggestion is a draft for a human to apply/approve."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "key_uuid": {
-                            "type": "string",
-                            "description": "Key UUID (from list_cognitive_candidates / list_keys).",
-                        },
-                        "score": {
-                            "type": "number",
-                            "minimum": 0,
-                            "maximum": 100,
-                            "description": "Cognitive difficulty score, 0 (easy) to 100 (hard).",
-                        },
-                        "suggestion": {
-                            "type": "string",
-                            "description": "Optional plain-language rewrite of the source value (draft).",
-                        },
-                    },
-                    "required": ["key_uuid", "score"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="analyze_cognitive",
-                description=(
-                    "Server-side AI cognitive analysis — the BILLED, opt-in FALLBACK to "
-                    "local scoring. Rates the cognitive difficulty of candidate keys and "
-                    "suggests plain-language rewrites server-side. Prefer scoring locally "
-                    "with set_cognitive_score (0 credits); use this only for very large "
-                    "volumes or on explicit request. Bills credits (standard=1, premium=4 "
-                    "per key; 402 if insufficient, 503 if AI unavailable). Returns "
-                    "{requested, analyzed, credits_charged, credits_refunded}."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "tier": {
-                            "type": "string",
-                            "enum": ["standard", "premium"],
-                            "default": "standard",
-                            "description": "Quality tier (credit_cost per key: standard=1, premium=4).",
-                        },
-                        "key_uuids": {
-                            "type": "array",
-                            "items": {"type": "string"},
-                            "description": "Restrict to these keys (from list_cognitive_candidates). Omit to scope the whole project (or a namespace).",
-                        },
-                        "namespace_uuid": {
-                            "type": "string",
-                            "description": "Restrict to one namespace by its UUID.",
-                        },
-                        "idempotency_key": {
-                            "type": "string",
-                            "description": "Stable token making this billable call safe to retry: reuse the SAME value to avoid a double-charge. A random one is generated if omitted.",
-                        },
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            # --- a11y conformance reports + remediation plan (sprint 111c4658, B5 MCP twins) ---
-            Tool(
-                name="wcag_report",
-                description=(
-                    "Read-only WCAG 2.2 CONFORMANCE report for the content layer Sonenta "
-                    "governs (strings, alt text, accessible names, a11y variants, reading "
-                    "level), evaluated PER LOCALE with a level-AA score. Reports the "
-                    "success criteria decidable from content (1.1.1, 1.3.1, 2.4.4, 2.4.9, "
-                    "3.1.1, 3.1.2, 3.1.5, 4.1.2); SC requiring the rendered DOM (contrast, "
-                    "keyboard, focus) appear ONLY under scope.out_of_scope_sc and are NEVER "
-                    "counted as pass. AAA criteria (2.4.9, 3.1.5) are shown but EXCLUDED "
-                    "from the AA score. conformance.score_pct is the headline AA number "
-                    "(with per-locale breakdown). Read scope.content_layer_sc dynamically — "
-                    "do not hardcode the SC list. Defaults to the production version. "
-                    "0-credit, read-only."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "version_id": {
-                            "type": "string",
-                            "description": "Optional version UUID; defaults to the production version.",
-                        },
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="eaa_statement",
-                description=(
-                    "Read-only EAA / EN 301 549 accessibility conformance STATEMENT for the "
-                    "content layer, per project x locale set (JSON). Maps each covered WCAG "
-                    "2.2 SC to its EN 301 549 clause (e.g. 1.1.1 -> 9.1.1.1) and reports "
-                    "{org, product, version, level:'AA', score_aa_percent, generated_at, "
-                    "standard, criteria_summary[], scope_statement:{attested[], "
-                    "out_of_scope[]}, contact}. Honest scope: attests alt-text / labels / "
-                    "language / plain-language per locale; the rendered-DOM audit is out of "
-                    "scope. Defaults to the production version. 0-credit, read-only."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "version_id": {
-                            "type": "string",
-                            "description": "Optional version UUID; defaults to the production version.",
-                        },
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="list_a11y_review_queue",
-                description=(
-                    "Read the a11y REVIEW QUEUE — the per-(key, locale, surface) review "
-                    "items with their state. Each item: {key_uuid, key_name, "
-                    "namespace_slug, surface, surface_kind, locale, state (missing | draft "
-                    "| translated | reviewed | approved | rejected), value, is_bot, gap, "
-                    "base_value, screenshots[], drift, ignored, ignore_reason, "
-                    "reject_reason}; the envelope carries by_state / by_surface rollups. "
-                    "**Pass state='rejected' to drive the RECTIFICATION loop**: a reviewer "
-                    "rejected a suggestion and left a `reject_reason` — the retained "
-                    "`value` is the rejected text and `reject_reason` is the human's "
-                    "instruction. The agent regenerates a corrected value addressing the "
-                    "reason and re-proposes via set_a11y_variant (rejected is unprotected, "
-                    "so it returns to draft). Defaults to the production version. READ-ONLY."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "version_id": {
-                            "type": "string",
-                            "description": "Optional version UUID; defaults to the production version.",
-                        },
-                        "state": {
-                            "type": "string",
-                            "enum": [
-                                "missing",
-                                "draft",
-                                "translated",
-                                "reviewed",
-                                "approved",
-                                "rejected",
-                            ],
-                            "description": "Filter to one review state. Use 'rejected' for the rectification loop (items carry reject_reason).",
-                        },
-                        "locale": {
-                            "type": "string",
-                            "description": "Filter to one locale code (e.g. 'fr'). Use 'source' for source-locale rows.",
-                        },
-                        "surface": {
-                            "type": "string",
-                            "enum": list(A11Y_SURFACES),
-                            "description": "Filter to one a11y surface.",
-                        },
-                        "namespace_uuid": {
-                            "type": "string",
-                            "description": "Restrict to one namespace by its UUID.",
-                        },
-                        "key_uuid": {
-                            "type": "string",
-                            "description": "Restrict to one key by its UUID.",
-                        },
-                        "include_ignored": {
-                            "type": "boolean",
-                            "description": "Include items suppressed by the remediation plan (ignored cells). Default false.",
-                        },
-                        "group_by_key": {
-                            "type": "boolean",
-                            "description": "Aggregate items by key (one entry per key with its surfaces/locales nested) instead of a flat list.",
-                        },
-                        "limit": {"type": "integer", "minimum": 1, "maximum": 500},
-                        "offset": {"type": "integer", "minimum": 0},
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="a11y_remediation_plan_get",
-                description=(
-                    "Read the a11y REMEDIATION PLAN for the project (or null if none "
-                    "exists). The plan is authored/approved in the dashboard; this tool "
-                    "OBSERVES it. Shape: {version_uuid, status (draft|approved), "
-                    "approved_at, plan:{items:[{key_uuid, locale, surface, decision "
-                    "(apply|ignore), reason?, value?}]}}. The backend mutates nothing on "
-                    "PUT/approve — once status=approved, call a11y_remediation_plan_apply "
-                    "to bulk-execute it. Defaults to the production version. Read-only."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "version_id": {
-                            "type": "string",
-                            "description": "Optional version UUID; defaults to the production version.",
-                        },
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="a11y_remediation_plan_apply",
-                description=(
-                    "EXECUTE the APPROVED a11y remediation plan — the agent's bulk-execute "
-                    "entrypoint. Only acts on a plan whose status=approved (poll "
-                    "a11y_remediation_plan_get first); a draft/absent plan is rejected. For "
-                    "each 'apply' item it writes the a11y variant (the item's value, else "
-                    "the current draft override) via the normal variant overlay — "
-                    "non-destructive and reversible (trashable/restorable). 'ignore' items "
-                    "persistently suppress that (key, locale, surface) cell. Returns the "
-                    "execution summary. Defaults to the production version."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "version_id": {
-                            "type": "string",
-                            "description": "Optional version UUID; defaults to the production version.",
-                        },
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="score_cognitive_local",
-                description=(
-                    "Compute and persist cognitive-difficulty scores from a VALIDATED, "
-                    "deterministic READABILITY metric — the local-first, **0-credit**, "
-                    "no-AI path (SC 3.1.5). English uses Flesch-Kincaid; every other "
-                    "language uses LIX, both normalised to difficulty 0-100 (higher = "
-                    "harder) with a per-language threshold. Writes cognitive_score for the "
-                    "scoped keys; a key enters the reading_level_high queue once its score "
-                    ">= the project threshold. Prefer this over analyze_cognitive (billed "
-                    "AI) for difficulty scoring. Scope with key_uuids and/or namespace_uuid "
-                    "(omit both = whole project). Returns the scoring summary."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "key_uuids": {
-                            "type": "array",
-                            "items": {"type": "string"},
-                            "description": "Restrict scoring to these keys. Omit to scope the whole project (or a namespace).",
-                        },
-                        "namespace_uuid": {
-                            "type": "string",
-                            "description": "Restrict scoring to one namespace by its UUID.",
-                        },
-                        "overwrite": {
-                            "type": "boolean",
-                            "description": "Re-score keys that already have a cognitive_score (default false = only score unscored keys).",
-                        },
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            # --- Placeholder mismatches (PM2 #173): translations whose interpolation
-            #     variables drift from the source (i18next {{}}, ICU {}, Ruby %{}). ---
-            Tool(
-                name="list_placeholder_mismatches",
-                description=(
-                    "List TRANSLATIONS whose interpolation VARIABLES drift from their "
-                    "source value (Placeholder mismatch, PM2) — a broken `{{name}}` / "
-                    "`{count}` is a runtime bug (missing data, or a crash). Detection is "
-                    "by variable NAME and brace-agnostic (i18next `{{}}`, ICU `{}`, Ruby "
-                    "`%{}` all compared by name), evaluated PER LANGUAGE. Each item = "
-                    "{key_uuid, key ('namespace::name'), namespace_slug, language (BCP-47), "
-                    "source_value, source_vars[], target_value, target_vars[], missing[] "
-                    "(vars in the source absent from this translation), extra[] (vars in "
-                    "this translation unknown to the source)}. This is the worklist the "
-                    "sonenta-source-health agent repairs: rewrite the target value so its "
-                    "variables match the source, write it back (propose_translation), then "
-                    "RE-CALL this tool — `total == 0` confirms the fix (no server auto-fix). "
-                    "READ-ONLY. 0 credits."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "version_id": {
-                            "type": "string",
-                            "description": "Optional version UUID; defaults to the production version.",
-                        },
-                        "key_id": {
-                            "type": "string",
-                            "description": "Restrict to a single key by its UUID.",
-                        },
-                        "language_code": {
-                            "type": "string",
-                            "description": "Restrict to a single target language by its BCP-47 code (e.g. 'fr').",
-                        },
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            # --- Source Health: duplicate source strings (#1116; backend #1114, PR #147) ---
-            Tool(
-                name="list_source_duplicates",
-                description=(
-                    "List groups of keys that SHARE an identical source-language "
-                    "value (Source Health duplicates, #1116). Each group = "
-                    "{source_value, key_count, key_names[], key_uuids[], status, note}. "
-                    "Duplicates inflate translation cost and drift (the same string "
-                    "translated N ways), so this is the worklist the "
-                    "sonenta-source-health agent repairs. Status is tracked PROJECT-WIDE "
-                    "per source_value: to_fix (needs attention; the default), allowed "
-                    "(intentional duplicate — listed+flagged but excluded from "
-                    "total_issues), resolved (already fixed — re-scan confirms). Filter "
-                    "by status to focus. When status=to_fix, a group may also carry a "
-                    "human-prepared `merge_plan` ({clusters: [{canonical_key_uuid, "
-                    "redundant_key_uuids[]}], survivor_outcome: allowed|differentiate}) "
-                    "authored in the dashboard — the consolidation an agent applies "
-                    "(merge each cluster onto its canonical key, then allow or "
-                    "differentiate whatever still shares the text). READ-ONLY."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "status": {
-                            "type": "string",
-                            "enum": ["to_fix", "allowed", "resolved"],
-                            "description": "Filter to duplicate groups in this triage status. Omit for all.",
-                        },
-                        "version_id": {
-                            "type": "string",
-                            "description": "Optional version UUID; defaults to the production version.",
-                        },
-                    },
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="set_duplicate_status",
-                description=(
-                    "Set the triage STATUS of one duplicate group, addressed by its "
-                    "shared source_value (Source Health duplicates, #1116). status ∈ "
-                    "to_fix (this duplication should be repaired — the default; "
-                    "clears any override), allowed (an intentional, sanctioned "
-                    "duplicate — kept but EXCLUDED from total_issues, stop flagging "
-                    "it), resolved (the duplication has been fixed — removed from the "
-                    "list, a re-scan confirms). An invalid status returns 422. Status "
-                    "persists PROJECT-WIDE per source_value. Use this after the "
-                    "sonenta-source-health agent has de-duplicated the keys, to mark "
-                    "the group resolved, or to whitelist a legitimate duplicate as "
-                    "allowed. An optional note records WHY (audit trail)."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "source_value": {
-                            "type": "string",
-                            "description": "The shared source-language value identifying the duplicate group (from list_source_duplicates).",
-                        },
-                        "status": {
-                            "type": "string",
-                            "enum": ["to_fix", "allowed", "resolved"],
-                            "description": "New triage status for the group.",
-                        },
-                        "note": {
-                            "type": "string",
-                            "description": "Optional human/agent note recording why the status was set (audit trail).",
-                        },
-                        "files_modified": _FILES_MODIFIED_SCHEMA,
-                    },
-                    "required": ["source_value", "status"],
-                    "additionalProperties": False,
-                },
-            ),
-            # --- Source Health: agent-authored merge plan + per-cluster applied
-            #     marking (task 1363; backend PR #183 + cluster-applied route) ---
-            Tool(
-                name="set_source_duplicate_merge_plan",
-                description=(
-                    "AUTHOR (or clear) the merge plan for one duplicate group, addressed "
-                    "by its shared source_value (Source Health duplicates). This is how "
-                    "the sonenta-source-health agent records the CONSOLIDATION it proposes "
-                    "and the dev accepted: which keys collapse onto which canonical, and "
-                    "what to do with whatever still shares the text. `merge_plan` = "
-                    "{clusters:[{canonical_key_uuid, redundant_key_uuids:[...]}], "
-                    "survivor_outcome:'allowed'|'differentiate'} — or null/omit to CLEAR "
-                    "the plan. Saving a plan sets the group's status to to_fix. After "
-                    "authoring, the agent repoints t() usages, trashes the redundant keys "
-                    "(delete_keys_bulk), marks each cluster applied (mark_cluster_applied), "
-                    "and finally set_duplicate_status(resolved). Author only a plan the "
-                    "dev accepted — never decide a merge silently."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "source_value": {
-                            "type": "string",
-                            "description": "The shared source-language value identifying the duplicate group (from list_source_duplicates).",
-                        },
-                        "merge_plan": {
-                            "type": ["object", "null"],
-                            "description": "The consolidation plan, or null to clear it.",
-                            "properties": {
-                                "clusters": {
-                                    "type": "array",
-                                    "items": {
-                                        "type": "object",
-                                        "properties": {
-                                            "canonical_key_uuid": {
-                                                "type": "string",
-                                                "description": "An EXISTING key kept as the canonical survivor. Mutually exclusive with new_key.",
-                                            },
-                                            "new_key": {
-                                                "type": "object",
-                                                "description": "Create a BRAND-NEW canonical key instead of keeping an existing one (NK1). Mutually exclusive with canonical_key_uuid. For a new_key cluster, redundant_key_uuids = ALL the group's keys (none survives). After authoring, call apply_new_key_cluster — the backend creates the key + copies translations + trashes the old keys.",
-                                                "properties": {
-                                                    "name": {"type": "string", "description": "New key name (must not collide with an active key)."},
-                                                    "namespace": {"type": "string", "description": "Namespace slug the new key lives in (must exist)."},
-                                                },
-                                                "required": ["name", "namespace"],
-                                            },
-                                            "redundant_key_uuids": {
-                                                "type": "array",
-                                                "items": {"type": "string"},
-                                                "description": "Keys folded into the canonical. For a new_key cluster, this is ALL the group's keys.",
-                                            },
-                                        },
-                                        "required": ["redundant_key_uuids"],
-                                    },
-                                },
-                                "survivor_outcome": {
-                                    "type": "string",
-                                    "enum": ["allowed", "differentiate"],
-                                    "description": "What to do with survivors that still share the text: allowed (sanctioned duplicate) or differentiate (make distinct).",
-                                },
-                            },
-                        },
-                        "files_modified": _FILES_MODIFIED_SCHEMA,
-                    },
-                    "required": ["source_value"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="mark_cluster_applied",
-                description=(
-                    "Mark ONE cluster of a duplicate group's merge plan as APPLIED — "
-                    "addressed by the group's source_value + the cluster's "
-                    "canonical_key_uuid. Call it after you have repointed the redundant "
-                    "keys' t() usages onto the canonical and trashed them "
-                    "(delete_keys_bulk), so the dashboard tracks per-cluster progress. "
-                    "Pass applied=false to UN-mark it. Once every cluster of the group is "
-                    "applied (and the survivor_outcome handled), set_duplicate_status("
-                    "resolved) closes the group."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "source_value": {
-                            "type": "string",
-                            "description": "The shared source-language value identifying the duplicate group.",
-                        },
-                        "canonical_key_uuid": {
-                            "type": "string",
-                            "description": "The surviving canonical key of the cluster to mark applied.",
-                        },
-                        "applied": {
-                            "type": "boolean",
-                            "description": "True to mark applied (default), false to un-mark.",
-                        },
-                        "files_modified": _FILES_MODIFIED_SCHEMA,
-                    },
-                    "required": ["source_value", "canonical_key_uuid"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="apply_new_key_cluster",
-                description=(
-                    "Consolidate a duplicate group onto a BRAND-NEW canonical key (NK1) — "
-                    "the BACKEND does the atomic data transaction so no translation is "
-                    "lost: it creates the new key (type/description/context inherited from "
-                    "the group's most-complete key), COPIES every language value from that "
-                    "most-complete key, and TRASHES all the old keys. Address it by "
-                    "source_value + new_key {name, namespace} (the namespace must exist and "
-                    "the name must be free). Returns {new_key_uuid, name, namespace, "
-                    "copied_from_key_uuid, copied_languages, trashed_key_uuids}. YOUR job "
-                    "after this is the CODE only: repoint every t() usage of the trashed "
-                    "keys onto new_key_uuid, and record those edits in `files_modified` "
-                    "(accepted right here, union-merged). You do NOT create_key or "
-                    "delete_keys_bulk yourself — the backend owns that. Author the "
-                    "new_key cluster in the merge plan first (on the dev's acceptance)."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "source_value": {
-                            "type": "string",
-                            "description": "The shared source-language value identifying the duplicate group.",
-                        },
-                        "new_key": {
-                            "type": "object",
-                            "description": "The new canonical key to create and consolidate the group onto.",
-                            "properties": {
-                                "name": {"type": "string", "description": "New key name (must not collide with an active key)."},
-                                "namespace": {"type": "string", "description": "Namespace slug the new key lives in (must exist)."},
-                            },
-                            "required": ["name", "namespace"],
-                        },
-                        "files_modified": _FILES_MODIFIED_SCHEMA,
-                    },
-                    "required": ["source_value", "new_key"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="set_duplicate_status_bulk",
-                description=(
-                    "Set ONE triage status across MANY duplicate groups at once (coarse "
-                    "triage). Body {source_values[], status, note?}. Intentionally NO "
-                    "files_modified (a single status over many groups). Use it to bulk-mark "
-                    "a batch as allowed (sanctioned) or to_fix; use the per-group "
-                    "set_duplicate_status for anything that records code changes."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "source_values": {
-                            "type": "array",
-                            "items": {"type": "string"},
-                            "description": "The shared source values identifying the duplicate groups.",
-                        },
-                        "status": {
-                            "type": "string",
-                            "enum": ["neutral", "allowed", "to_fix", "resolved"],
-                            "description": "New triage status applied to every listed group (neutral clears the override).",
-                        },
-                        "note": {"type": "string", "description": "Optional human/agent note (same on all)."},
-                    },
-                    "required": ["source_values", "status"],
-                    "additionalProperties": False,
-                },
-            ),
-            Tool(
-                name="propose_duplicate_merge_plan",
-                description=(
-                    "OPT-IN, METERED second opinion: a server-side LLM reads a duplicate "
-                    "group (keys + translations + glossary + context) and PROPOSES a plan — "
-                    "recommendation merge | split | keep_separate + a well-formed merge_plan "
-                    "(null when keep_separate) + a one-line reason. PROPOSE-ONLY: it does NOT "
-                    "change status; apply via set_source_duplicate_merge_plan + "
-                    "apply_new_key_cluster / mark_cluster_applied / set_duplicate_status. "
-                    "You are already an LLM and decide locally at 0 credit — use this only "
-                    "as a tie-breaker or when the dev wants the AI's take. Costs 1 credit per "
-                    "generation UNLESS a valid cached proposal exists (cached=true → free); "
-                    "regenerate=true forces a fresh one. 402 when credits are insufficient. "
-                    "The persisted proposal also surfaces on list_source_duplicates "
-                    "(ai_proposed_plan / ai_diagnosis, free to read)."
-                ),
-                inputSchema={
-                    "type": "object",
-                    "properties": {
-                        "project_uuid": {
-                            "type": "string",
-                            "description": "Project UUID. Required when multiple projects are configured (SONENTA_PROJECTS); defaults to the single configured project otherwise.",
-                        },
-                        "source_value": {
-                            "type": "string",
-                            "description": "The shared source value identifying the duplicate group.",
-                        },
-                        "namespace_slug": {
-                            "type": "string",
-                            "description": "Required only if the value spans namespaces (groups are intra-namespace).",
-                        },
-                        "regenerate": {
-                            "type": "boolean",
-                            "description": "Force a fresh diagnosis (1 credit) even if a valid cached one exists. Default false.",
-                        },
-                        "version_id": {"type": "string", "description": "Optional version UUID; defaults to the live version."},
-                    },
-                    "required": ["source_value"],
-                    "additionalProperties": False,
-                },
-            ),
-        ]
-
-    @server.call_tool()
-    async def _call(name: str, arguments: dict | None) -> list[TextContent]:
-        try:
-            args = arguments or {}
-            if name == "list_projects":
-                data = await client.get(
-                    "/v1/mcp/projects", params={"limit": args.get("limit", 50)}
-                )
-                data = _filter_projects_by_allowlist(
-                    data, client.config.allowed_project_uuids
-                )
-                return _text(data)
-            if name == "get_project_info":
-                project_uuid = _project_uuid(args, client)
-                data = await client.get(f"/v1/mcp/projects/{project_uuid}")
-                return _text(data)
-            if name == "distribution_info":
-                project_uuid = _project_uuid(args, client)
-                data = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/distribution"
-                )
-                return _text(data)
-            if name == "sonenta_guide":
-                data = await client.get("/v1/mcp/guide")
-                return _text(data)
-            if name == "list_keys":
-                project_uuid = _project_uuid(args, client)
-                params = {
-                    k: v
-                    for k, v in {
-                        "namespace": args.get("namespace"),
-                        "language_code": args.get("language_code"),
-                        "status_filter": args.get("status_filter"),
-                        "include_glossary_hints": (
-                            "true" if args.get("include_glossary_hints") else None
-                        ),
-                        "cursor": args.get("cursor"),
-                        "limit": args.get("limit", 50),
-                    }.items()
-                    if v is not None
-                }
-                data = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/keys", params=params
-                )
-                return _text(data)
-            if name == "list_untranslated_keys":
-                project_uuid = _project_uuid(args, client)
-                if "language_code" not in args:
-                    return _err("language_code is required")
-                params = {
-                    k: v
-                    for k, v in {
-                        "language_code": args["language_code"],
-                        "namespace": args.get("namespace"),
-                        "include_glossary_hints": (
-                            "true" if args.get("include_glossary_hints") else None
-                        ),
-                        "cursor": args.get("cursor"),
-                        "limit": args.get("limit", 50),
-                    }.items()
-                    if v is not None
-                }
-                data = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/untranslated-keys", params=params
-                )
-                return _text(data)
-            if name == "list_missing_keys":
-                project_uuid = _project_uuid(args, client)
-                params = {
-                    k: v
-                    for k, v in {
-                        "namespace": args.get("namespace"),
-                        "language_code": args.get("language_code"),
-                        "status": args.get("status"),
-                        "cursor": args.get("cursor"),
-                        "limit": args.get("limit", 50),
-                    }.items()
-                    if v is not None
-                }
-                data = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/missing-keys", params=params
-                )
-                return _text(data)
-            if name == "missing_keys_stats":
-                project_uuid = _project_uuid(args, client)
-                params = {
-                    k: v
-                    for k, v in {
-                        "namespace": args.get("namespace"),
-                        "language_code": args.get("language_code"),
-                        "status": args.get("status"),
-                    }.items()
-                    if v is not None
-                }
-                data = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/missing-keys/stats",
-                    params=params,
-                )
-                return _text(data)
-            if name == "acknowledge_missing_keys":
-                project_uuid = _project_uuid(args, client)
-                uuids = args.get("uuids") or []
-                if not uuids:
-                    return _err("uuids must be a non-empty list")
-                data = await client.post(
-                    f"/v1/mcp/projects/{project_uuid}/missing-keys/acknowledge",
-                    json={"uuids": uuids},
-                )
-                return _text(data)
-            if name == "create_namespace":
-                project_uuid = _project_uuid(args, client)
-                if "slug" not in args or "name" not in args:
-                    return _err("slug and name are required")
-                body: dict[str, Any] = {"slug": args["slug"], "name": args["name"]}
-                if "description" in args:
-                    body["description"] = args["description"]
-                data = await client.post(
-                    f"/v1/mcp/projects/{project_uuid}/namespaces", json=body
-                )
-                return _text(data)
-            if name == "create_key":
-                project_uuid = _project_uuid(args, client)
-                if "namespace" not in args or "name" not in args:
-                    return _err("namespace and name are required")
-                body: dict[str, Any] = {
-                    "namespace": args["namespace"],
-                    "name": args["name"],
-                }
-                for opt in ("source_value", "description", "plurals", "max_length", "type"):
-                    if opt in args:
-                        body[opt] = args[opt]
-                data = await client.post(
-                    f"/v1/mcp/projects/{project_uuid}/keys", json=body
-                )
-                return _text(data)
-            if name == "propose_translation":
-                project_uuid = _project_uuid(args, client)
-                body = {
-                    "namespace": args["namespace"],
-                    "key": args["key"],
-                    "language_code": args["language_code"],
-                    "value": args["value"],
-                }
-                if "status" in args:
-                    body["status"] = args["status"]
-                data = await client.put(
-                    f"/v1/mcp/projects/{project_uuid}/translations", json=body
-                )
-                return _text(data)
-            if name == "create_keys_bulk":
-                project_uuid = _project_uuid(args, client)
-                items = args.get("items")
-                if not isinstance(items, list) or not items:
-                    return _err("items must be a non-empty list")
-                data = await client.post(
-                    f"/v1/mcp/projects/{project_uuid}/keys/bulk", json={"items": items}
-                )
-                return _text(data)
-            if name == "update_key":
-                project_uuid = _project_uuid(args, client)
-                if not any(k in args for k in ("source_value", "type", "description")):
-                    return _err(
-                        "nothing to update: pass at least one of source_value, type, description"
-                    )
-                has_uuid = bool(args.get("key_uuid"))
-                has_name = bool(args.get("namespace")) and bool(args.get("name"))
-                if has_uuid == has_name:
-                    return _err(
-                        "address the key by exactly one of key_uuid OR (namespace + name)"
-                    )
-                body: dict[str, Any] = {}
-                for opt in ("source_value", "key_uuid", "namespace", "name", "description", "type"):
-                    if opt in args:
-                        body[opt] = args[opt]
-                data = await client.patch(
-                    f"/v1/mcp/projects/{project_uuid}/keys", json=body
-                )
-                return _text(data)
-            if name == "update_keys_bulk":
-                project_uuid = _project_uuid(args, client)
-                items = args.get("items")
-                if not isinstance(items, list) or not items:
-                    return _err("items must be a non-empty list")
-                data = await client.patch(
-                    f"/v1/mcp/projects/{project_uuid}/keys/bulk", json={"items": items}
-                )
-                return _text(data)
-            if name == "propose_translations_bulk":
-                project_uuid = _project_uuid(args, client)
-                items = args.get("items")
-                if not isinstance(items, list) or not items:
-                    return _err("items must be a non-empty list")
-                data = await client.post(
-                    f"/v1/mcp/projects/{project_uuid}/translations/bulk",
-                    json={"items": items},
-                )
-                return _text(data)
-            if name == "publish_cdn":
-                project_uuid = _project_uuid(args, client)
-                body: dict[str, Any] = {}
-                for opt in ("language_code", "namespace", "version_slug"):
-                    if args.get(opt):
-                        body[opt] = args[opt]
-                data = await client.post(
-                    f"/v1/mcp/projects/{project_uuid}/cdn/releases", json=body
-                )
-                return _text(data)
-            if name == "validate_translations":
-                project_uuid = _project_uuid(args, client)
-                body = {
-                    "language_code": args["language_code"],
-                    "payload": args.get("payload", {}),
-                }
-                if "namespace" in args:
-                    body["namespace"] = args["namespace"]
-                data = await client.post(
-                    f"/v1/mcp/projects/{project_uuid}/validate", json=body
-                )
-                return _text(data)
-            if name == "project_context_get":
-                project_uuid = _project_uuid(args, client)
-                data = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/context"
-                )
-                return _text(data)
-            if name == "project_context_set":
-                project_uuid = _project_uuid(args, client)
-                if "content" not in args:
-                    return _err("content is required")
-                data = await client.put(
-                    f"/v1/mcp/projects/{project_uuid}/context",
-                    json={"content": args["content"]},
-                )
-                return _text(data)
-            if name == "glossary_list":
-                project_uuid = _project_uuid(args, client)
-                params = {
-                    k: v
-                    for k, v in {
-                        "rule_type": args.get("rule_type"),
-                        "q": args.get("q"),
-                        "limit": args.get("limit", 200),
-                    }.items()
-                    if v is not None
-                }
-                data = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/glossary", params=params
-                )
-                return _text(data)
-            if name == "glossary_create":
-                project_uuid = _project_uuid(args, client)
-                if "term" not in args:
-                    return _err("term is required")
-                body: dict[str, Any] = {"term": args["term"]}
-                for opt in ("rule_type", "translations", "case_sensitive", "note"):
-                    if opt in args:
-                        body[opt] = args[opt]
-                data = await client.post(
-                    f"/v1/mcp/projects/{project_uuid}/glossary", json=body
-                )
-                return _text(data)
-            if name == "glossary_update":
-                project_uuid = _project_uuid(args, client)
-                if "entry_id" not in args:
-                    return _err("entry_id is required")
-                body: dict[str, Any] = {}
-                for opt in ("term", "translations", "case_sensitive", "note"):
-                    if opt in args:
-                        body[opt] = args[opt]
-                if not body:
-                    return _err(
-                        "nothing to update: pass at least one of term, translations, "
-                        "case_sensitive, note"
-                    )
-                data = await client.patch(
-                    f"/v1/mcp/projects/{project_uuid}/glossary/{args['entry_id']}",
-                    json=body,
-                )
-                return _text(data)
-            if name == "glossary_delete":
-                project_uuid = _project_uuid(args, client)
-                if "entry_id" not in args:
-                    return _err("entry_id is required")
-                await client.delete(
-                    f"/v1/mcp/projects/{project_uuid}/glossary/{args['entry_id']}"
-                )
-                return _text({"deleted": True, "entry_id": args["entry_id"]})
-            if name == "health_report":
-                project_uuid = _project_uuid(args, client)
-                params = {
-                    k: v
-                    for k, v in {"version_id": args.get("version_id")}.items()
-                    if v is not None
-                }
-                data = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/source-health", params=params
-                )
-                return _text(data)
-            if name == "coverage_report":
-                project_uuid = _project_uuid(args, client)
-                params = {
-                    k: v
-                    for k, v in {"version_id": args.get("version_id")}.items()
-                    if v is not None
-                }
-                data = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/coverage", params=params
-                )
-                return _text(data)
-            if name == "delete_keys_bulk":
-                project_uuid = _project_uuid(args, client)
-                key_uuids = args.get("key_uuids")
-                if not isinstance(key_uuids, list) or not key_uuids:
-                    return _err("key_uuids must be a non-empty list")
-                data = await client.post(
-                    f"/v1/mcp/projects/{project_uuid}/keys/bulk/delete",
-                    json={"key_uuids": key_uuids},
-                )
-                return _text(data)
-            if name == "restore_keys_bulk":
-                project_uuid = _project_uuid(args, client)
-                key_uuids = args.get("key_uuids")
-                if not isinstance(key_uuids, list) or not key_uuids:
-                    return _err("key_uuids must be a non-empty list")
-                data = await client.post(
-                    f"/v1/mcp/projects/{project_uuid}/keys/bulk/restore",
-                    json={"key_uuids": key_uuids},
-                )
-                return _text(data)
-            if name == "list_trash":
-                project_uuid = _project_uuid(args, client)
-                params = {
-                    k: v
-                    for k, v in {
-                        "cursor": args.get("cursor"),
-                        "limit": args.get("limit", 50),
-                    }.items()
-                    if v is not None
-                }
-                data = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/keys/trashed", params=params
-                )
-                return _text(data)
-            if name == "a11y_estimate":
-                project_uuid = _project_uuid(args, client)
-                mode = args.get("mode")
-                if mode not in ("generate", "translate"):
-                    return _err("mode must be 'generate' or 'translate'")
-                body: dict[str, Any] = {"mode": mode, "tier": args.get("tier", "standard")}
-                for opt in ("surfaces", "language_codes", "key_uuids", "namespace_uuid"):
-                    if args.get(opt):
-                        body[opt] = args[opt]
-                data = await client.post(
-                    f"/v1/mcp/projects/{project_uuid}/a11y/estimate", json=body
-                )
-                return _text(data)
-            if name == "generate_a11y_variant":
-                project_uuid = _project_uuid(args, client)
-                body: dict[str, Any] = {
-                    "tier": args.get("tier", "standard"),
-                    "idempotency_key": args.get("idempotency_key") or str(uuid.uuid4()),
-                }
-                for opt in ("surfaces", "key_uuids", "namespace_uuid"):
-                    if args.get(opt):
-                        body[opt] = args[opt]
-                data = await client.post(
-                    f"/v1/mcp/projects/{project_uuid}/a11y/generate", json=body
-                )
-                return _text(data)
-            if name == "translate_a11y_variants":
-                project_uuid = _project_uuid(args, client)
-                language_codes = args.get("language_codes")
-                if not isinstance(language_codes, list) or not language_codes:
-                    return _err("language_codes must be a non-empty list")
-                body: dict[str, Any] = {
-                    "tier": args.get("tier", "standard"),
-                    "language_codes": language_codes,
-                    "idempotency_key": args.get("idempotency_key") or str(uuid.uuid4()),
-                }
-                for opt in ("surfaces", "key_uuids", "namespace_uuid"):
-                    if args.get(opt):
-                        body[opt] = args[opt]
-                data = await client.post(
-                    f"/v1/mcp/projects/{project_uuid}/a11y/translate", json=body
-                )
-                return _text(data)
-            if name in ("a11y_report", "list_a11y_gaps"):
-                project_uuid = _project_uuid(args, client)
-                params: dict[str, Any] = {}
-                if args.get("version_id"):
-                    params["version_id"] = args["version_id"]
-                if args.get("require_surface"):
-                    # repeatable query param: httpx expands a list into repeats
-                    params["require_surface"] = args["require_surface"]
-                if args.get("reading_level_max_words") is not None:
-                    params["reading_level_max_words"] = args["reading_level_max_words"]
-                report = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/a11y-report", params=params
-                )
-                if name == "a11y_report":
-                    return _text(report)
-                # list_a11y_gaps: flatten + client-side filter the items[] list.
-                items = report.get("items", []) if isinstance(report, dict) else []
-                gap_f = args.get("gap")
-                surface_f = args.get("surface")
-                locale_f = args.get("locale")
-                gaps = [
-                    it
-                    for it in items
-                    if (gap_f is None or it.get("gap") == gap_f)
-                    and (surface_f is None or it.get("surface") == surface_f)
-                    and (locale_f is None or it.get("locale") == locale_f)
-                ]
-                applied = {
-                    k: v
-                    for k, v in {
-                        "gap": gap_f,
-                        "surface": surface_f,
-                        "locale": locale_f,
-                        "require_surface": args.get("require_surface"),
-                    }.items()
-                    if v
-                }
-                return _text(
-                    {
-                        "project_uuid": report.get("project_uuid", project_uuid)
-                        if isinstance(report, dict)
-                        else project_uuid,
-                        "version_uuid": report.get("version_uuid")
-                        if isinstance(report, dict)
-                        else None,
-                        "keys_scanned": report.get("keys_scanned")
-                        if isinstance(report, dict)
-                        else None,
-                        "filters": applied,
-                        "count": len(gaps),
-                        "gaps": gaps,
-                    }
-                )
-            if name == "list_untranslated_surfaces":
-                project_uuid = _project_uuid(args, client)
-                params: dict[str, Any] = {"include_untranslated": True}
-                if args.get("version_id"):
-                    params["version_id"] = args["version_id"]
-                report = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/a11y-report", params=params
-                )
-                items = report.get("items", []) if isinstance(report, dict) else []
-                surf_f = args.get("surface")
-                lang_f = args.get("language_code")
-                cells = [
-                    {
-                        "key_uuid": it.get("key_uuid"),
-                        "key_name": it.get("key_name"),
-                        "namespace_slug": it.get("namespace_slug"),
-                        "key_type": it.get("key_type"),
-                        "surface": it.get("surface"),
-                        "language_code": it.get("locale"),
-                        "source_value": it.get("source_value"),
-                    }
-                    for it in items
-                    if it.get("gap") == "a11y_untranslated"
-                    and (surf_f is None or it.get("surface") == surf_f)
-                    and (lang_f is None or it.get("locale") == lang_f)
-                ]
-                return _text({"project_uuid": project_uuid, "count": len(cells), "cells": cells})
-            if name in ("set_a11y_variant", "delete_a11y_variant"):
-                project_uuid = _project_uuid(args, client)
-                key_uuid = args.get("key_uuid")
-                language_code = args.get("language_code")
-                surface = args.get("surface")
-                if not key_uuid or not language_code or not surface:
-                    return _err("key_uuid, language_code and surface are required")
-                if surface not in A11Y_SURFACES:
-                    return _err(f"surface must be one of {', '.join(A11Y_SURFACES)}")
-                # mcp:* code-addressed GENERIC variant route (covers a11y + device;
-                # task 928). Backend resolves the locale code -> uuid and validates the
-                # surface is active server-side. (The legacy /a11y-variants/ path still
-                # works for back-compat, but /variants/ is canonical.)
-                path = (
-                    f"/v1/mcp/projects/{project_uuid}/keys/{key_uuid}"
-                    f"/variants/{language_code}/{surface}"
-                )
-                if name == "delete_a11y_variant":
-                    await client.delete(path)
-                    return _text(
-                        {
-                            "deleted": True,
-                            "key_uuid": key_uuid,
-                            "language_code": language_code,
-                            "surface": surface,
-                        }
-                    )
-                if "value" not in args:
-                    return _err("value is required")
-                data = await client.put(path, json={"value": args["value"]})
-                return _text(data)
-            if name == "list_surfaces":
-                project_uuid = _project_uuid(args, client)
-                data = await client.get(f"/v1/mcp/projects/{project_uuid}/surfaces")
-                return _text(data)
-            if name == "create_surface":
-                project_uuid = _project_uuid(args, client)
-                if not args.get("slug"):
-                    return _err("slug is required")
-                body: dict[str, Any] = {"slug": args["slug"]}
-                if "label" in args:
-                    body["label"] = args["label"]
-                data = await client.post(
-                    f"/v1/mcp/projects/{project_uuid}/surfaces", json=body
-                )
-                return _text(data)
-            if name == "update_surface":
-                project_uuid = _project_uuid(args, client)
-                slug = args.get("slug")
-                if not slug:
-                    return _err("slug is required")
-                body: dict[str, Any] = {}
-                for opt in ("label", "active"):
-                    if opt in args:
-                        body[opt] = args[opt]
-                if not body:
-                    return _err("nothing to update: pass label and/or active")
-                data = await client.put(
-                    f"/v1/mcp/projects/{project_uuid}/surfaces/{slug}", json=body
-                )
-                return _text(data)
-            if name == "delete_surface":
-                project_uuid = _project_uuid(args, client)
-                slug = args.get("slug")
-                if not slug:
-                    return _err("slug is required")
-                await client.delete(f"/v1/mcp/projects/{project_uuid}/surfaces/{slug}")
-                return _text({"deleted": True, "slug": slug})
-            if name == "recommend_surfaces":
-                project_uuid = _project_uuid(args, client)
-                params: dict[str, Any] = {}
-                for opt in ("version_id", "namespace_id", "key_id"):
-                    if args.get(opt):
-                        params[opt] = args[opt]
-                if args.get("only_gaps"):
-                    params["only_gaps"] = "true"
-                data = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/recommend-surfaces",
-                    params=params,
-                )
-                return _text(data)
-            if name == "surface_coverage":
-                project_uuid = _project_uuid(args, client)
-                params: dict[str, Any] = {}
-                if args.get("version_id"):
-                    params["version_id"] = args["version_id"]
-                data = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/surface-coverage",
-                    params=params,
-                )
-                return _text(data)
-            if name == "get_variants":
-                project_uuid = _project_uuid(args, client)
-                key_uuid = args.get("key_uuid")
-                if not key_uuid:
-                    return _err("key_uuid is required")
-                data = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/keys/{key_uuid}/variants"
-                )
-                return _text(data)
-            if name in ("set_variant", "delete_variant"):
-                project_uuid = _project_uuid(args, client)
-                key_uuid = args.get("key_uuid")
-                language_code = args.get("language_code")
-                surface = args.get("surface")
-                if not key_uuid or not language_code or not surface:
-                    return _err("key_uuid, language_code and surface are required")
-                # generic variant route: backend validates the surface is active (422)
-                # and guards reviewed/approved cells (409).
-                path = (
-                    f"/v1/mcp/projects/{project_uuid}/keys/{key_uuid}"
-                    f"/variants/{language_code}/{surface}"
-                )
-                if name == "delete_variant":
-                    await client.delete(path)
-                    return _text(
-                        {
-                            "deleted": True,
-                            "key_uuid": key_uuid,
-                            "language_code": language_code,
-                            "surface": surface,
-                        }
-                    )
-                if "value" not in args:
-                    return _err("value is required")
-                data = await client.put(path, json={"value": args["value"]})
-                return _text(data)
-            if name == "list_cognitive_candidates":
-                project_uuid = _project_uuid(args, client)
-                params = {
-                    k: v
-                    for k, v in {
-                        "only_unanalyzed": ("true" if args.get("only_unanalyzed") else None),
-                        "namespace_uuid": args.get("namespace_uuid"),
-                        "limit": args.get("limit", 100),
-                        "offset": args.get("offset", 0),
-                    }.items()
-                    if v is not None
-                }
-                data = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/cognitive/candidates", params=params
-                )
-                return _text(data)
-            if name == "set_cognitive_score":
-                project_uuid = _project_uuid(args, client)
-                key_uuid = args.get("key_uuid")
-                if not key_uuid:
-                    return _err("key_uuid is required")
-                if "score" not in args:
-                    return _err("score is required")
-                body: dict[str, Any] = {"score": args["score"]}
-                if "suggestion" in args:
-                    body["suggestion"] = args["suggestion"]
-                data = await client.put(
-                    f"/v1/mcp/projects/{project_uuid}/keys/{key_uuid}/cognitive-score",
-                    json=body,
-                )
-                return _text(data)
-            if name == "analyze_cognitive":
-                project_uuid = _project_uuid(args, client)
-                body: dict[str, Any] = {
-                    "tier": args.get("tier", "standard"),
-                    "idempotency_key": args.get("idempotency_key") or str(uuid.uuid4()),
-                }
-                for opt in ("key_uuids", "namespace_uuid"):
-                    if args.get(opt):
-                        body[opt] = args[opt]
-                data = await client.post(
-                    f"/v1/mcp/projects/{project_uuid}/cognitive/analyze", json=body
-                )
-                return _text(data)
-            # --- a11y conformance reports + remediation plan (sprint 111c4658, B5) ---
-            if name in ("wcag_report", "eaa_statement"):
-                project_uuid = _project_uuid(args, client)
-                params: dict[str, Any] = {}
-                if args.get("version_id"):
-                    params["version_id"] = args["version_id"]
-                segment = "wcag-report" if name == "wcag_report" else "eaa-statement"
-                data = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/{segment}", params=params
-                )
-                return _text(data)
-            if name == "list_a11y_review_queue":
-                project_uuid = _project_uuid(args, client)
-                params: dict[str, Any] = {}
-                for opt in (
-                    "version_id",
-                    "state",
-                    "locale",
-                    "surface",
-                    "namespace_uuid",
-                    "key_uuid",
-                    "limit",
-                    "offset",
-                ):
-                    if args.get(opt) is not None:
-                        params[opt] = args[opt]
-                if args.get("include_ignored"):
-                    params["include_ignored"] = "true"
-                if args.get("group_by_key"):
-                    params["group_by_key"] = "true"
-                data = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/a11y/review/queue", params=params
-                )
-                return _text(data)
-            if name == "a11y_remediation_plan_get":
-                project_uuid = _project_uuid(args, client)
-                params: dict[str, Any] = {}
-                if args.get("version_id"):
-                    params["version_id"] = args["version_id"]
-                data = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/a11y/remediation-plan", params=params
-                )
-                return _text(data)
-            if name == "a11y_remediation_plan_apply":
-                project_uuid = _project_uuid(args, client)
-                body: dict[str, Any] = {}
-                if args.get("version_id"):
-                    body["version_id"] = args["version_id"]
-                data = await client.post(
-                    f"/v1/mcp/projects/{project_uuid}/a11y/remediation-plan/apply",
-                    json=body,
-                )
-                return _text(data)
-            if name == "score_cognitive_local":
-                project_uuid = _project_uuid(args, client)
-                body: dict[str, Any] = {}
-                for opt in ("key_uuids", "namespace_uuid"):
-                    if args.get(opt):
-                        body[opt] = args[opt]
-                if args.get("overwrite"):
-                    body["overwrite"] = True
-                data = await client.post(
-                    f"/v1/mcp/projects/{project_uuid}/cognitive/score-local", json=body
-                )
-                return _text(data)
-            # --- Placeholder mismatches (PM2 #173) ---
-            if name == "list_placeholder_mismatches":
-                project_uuid = _project_uuid(args, client)
-                params: dict[str, Any] = {}
-                for opt in ("version_id", "key_id", "language_code"):
-                    if args.get(opt):
-                        params[opt] = args[opt]
-                data = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/placeholder-mismatches",
-                    params=params,
-                )
-                return _text(data)
-            # --- Source Health: duplicates (#1116; backend #1114, PR #147) ---
-            if name == "list_source_duplicates":
-                project_uuid = _project_uuid(args, client)
-                params = {
-                    k: v
-                    for k, v in {
-                        "status": args.get("status"),
-                        "version_id": args.get("version_id"),
-                    }.items()
-                    if v is not None
-                }
-                data = await client.get(
-                    f"/v1/mcp/projects/{project_uuid}/source-duplicates",
-                    params=params,
-                )
-                return _text(data)
-            if name == "set_duplicate_status":
-                project_uuid = _project_uuid(args, client)
-                if not args.get("source_value"):
-                    return _err("source_value is required")
-                if not args.get("status"):
-                    return _err("status is required")
-                body: dict[str, Any] = {
-                    "source_value": args["source_value"],
-                    "status": args["status"],
-                }
-                if args.get("note"):
-                    body["note"] = args["note"]
-                if args.get("files_modified"):
-                    body["files_modified"] = args["files_modified"]
-                data = await client.put(
-                    f"/v1/mcp/projects/{project_uuid}/source-duplicates/status",
-                    json=body,
-                )
-                return _text(data)
-            if name == "set_source_duplicate_merge_plan":
-                project_uuid = _project_uuid(args, client)
-                if not args.get("source_value"):
-                    return _err("source_value is required")
-                body = {"source_value": args["source_value"]}
-                # merge_plan may be an object OR explicit null (to clear); send it
-                # whenever the key is present at all.
-                if "merge_plan" in args:
-                    body["merge_plan"] = args["merge_plan"]
-                if args.get("files_modified"):
-                    body["files_modified"] = args["files_modified"]
-                data = await client.put(
-                    f"/v1/mcp/projects/{project_uuid}/source-duplicates/merge-plan",
-                    json=body,
-                )
-                return _text(data)
-            if name == "mark_cluster_applied":
-                project_uuid = _project_uuid(args, client)
-                if not args.get("source_value") or not args.get("canonical_key_uuid"):
-                    return _err("source_value and canonical_key_uuid are required")
-                body = {
-                    "source_value": args["source_value"],
-                    "canonical_key_uuid": args["canonical_key_uuid"],
-                }
-                if "applied" in args:
-                    body["applied"] = bool(args["applied"])
-                if args.get("files_modified"):
-                    body["files_modified"] = args["files_modified"]
-                data = await client.put(
-                    f"/v1/mcp/projects/{project_uuid}/source-duplicates/cluster-applied",
-                    json=body,
-                )
-                return _text(data)
-            if name == "apply_new_key_cluster":
-                project_uuid = _project_uuid(args, client)
-                new_key = args.get("new_key")
-                if not args.get("source_value") or not isinstance(new_key, dict):
-                    return _err("source_value and new_key {name, namespace} are required")
-                if not new_key.get("name") or not new_key.get("namespace"):
-                    return _err("new_key requires name and namespace")
-                body = {"source_value": args["source_value"], "new_key": new_key}
-                if args.get("files_modified"):
-                    body["files_modified"] = args["files_modified"]
-                data = await client.post(
-                    f"/v1/mcp/projects/{project_uuid}/source-duplicates/apply-cluster",
-                    json=body,
-                )
-                return _text(data)
-            if name == "set_duplicate_status_bulk":
-                project_uuid = _project_uuid(args, client)
-                source_values = args.get("source_values")
-                if not isinstance(source_values, list) or not source_values:
-                    return _err("source_values must be a non-empty list")
-                if not args.get("status"):
-                    return _err("status is required")
-                body = {"source_values": source_values, "status": args["status"]}
-                if args.get("note") is not None:
-                    body["note"] = args["note"]
-                data = await client.put(
-                    f"/v1/mcp/projects/{project_uuid}/source-duplicates/status/bulk",
-                    json=body,
-                )
-                return _text(data)
-            if name == "propose_duplicate_merge_plan":
-                project_uuid = _project_uuid(args, client)
-                if not args.get("source_value"):
-                    return _err("source_value is required")
-                body = {"source_value": args["source_value"]}
-                if args.get("namespace_slug"):
-                    body["namespace_slug"] = args["namespace_slug"]
-                if args.get("regenerate"):
-                    body["regenerate"] = True
-                url = f"/v1/mcp/projects/{project_uuid}/source-duplicates/propose-plan"
-                if args.get("version_id"):
-                    url += f"?version_id={args['version_id']}"
-                data = await client.post(url, json=body)
-                return _text(data)
-            return _err(f"unknown tool: {name}")
-        except VerbumiaApiError as exc:
-            return _err(f"API {exc.status}: {exc.body}")
-        except KeyError as exc:
-            return _err(f"missing required argument: {exc}")
-        except Exception as exc:  # pragma: no cover
-            return _err(f"{type(exc).__name__}: {exc}")
-
-    return _list_tools, _call