"""Cowork-only connector tools for first-party integrations.

These tools are intentionally local-first: credentials are read from the SecretStore at
execution time and never enter prompts. OAuth-managed setup can later replace the manual
access-token fields without changing the tool surface.
"""

from __future__ import annotations

import base64
import datetime as _dt
import json
import re
from email.message import EmailMessage
from html.parser import HTMLParser
from typing import Any, Callable, Optional
from urllib.parse import quote

import aisuite as ai

from ..secrets import SecretStore
from .browser_automation import make_browser_automation_tools
from .email_tools import make_email_tools
from .tool_defs import approval_for_tool, connector_for_tool


def _meta(
    name: str, *, approval: bool = False, capabilities: Optional[list[str]] = None
):
    return ai.ToolMetadata(
        name=name,
        category="connector",
        risk_level="medium" if approval else "low",
        capabilities=capabilities or ["integration"],
        requires_approval=approval,
    )


def _schema(
    name: str, description: str, properties: dict[str, Any], required: list[str]
) -> dict[str, Any]:
    return {
        "type": "function",
        "function": {
            "name": name,
            "description": description,
            "parameters": {
                "type": "object",
                "properties": properties,
                "required": required,
            },
        },
    }


def _attach(
    fn: Callable[..., Any],
    schema: dict[str, Any],
    *,
    approval: bool = True,
    caps: Optional[list[str]] = None,
):
    name = schema["function"]["name"]
    # §36: the tool registry's read/write kind overrides the call-site flag for
    # registered tools — connector READS never gate. The explicit arg only governs
    # tools without a registry entry.
    approval = approval_for_tool(name, default=approval)
    fn.__coworker_schema__ = schema
    fn.__aisuite_tool_metadata__ = _meta(name, approval=approval, capabilities=caps)
    fn.__doc__ = schema["function"]["description"]
    return fn


def _profile(
    secrets: SecretStore, name: str, *keys: str
) -> tuple[Optional[dict[str, Any]], Optional[dict[str, str]]]:
    profile = secrets.get(f"{name}:default") or {}
    if profile.get("managed"):
        # Managed-OAuth profiles renew through the cloud broker just before
        # expiry; manual token profiles are never touched (no-op inside).
        from ..cloud import ensure_fresh_connector_token
        from ..config import load_config

        ensure_fresh_connector_token(secrets, load_config(), name)
        profile = secrets.get(f"{name}:default") or {}
    missing = [k for k in keys if not profile.get(k)]
    if missing:
        return None, {"error": f"{name} is not connected; missing {', '.join(missing)}"}
    return profile, None


def _account_profile(
    secrets: SecretStore, connector: str, account: str = "", *keys: str
) -> tuple[str, Optional[dict[str, Any]], Optional[dict[str, str]]]:
    """(account_id, profile, err) for an account-patterned connector (generic
    accounts.py layer): requested — or default — account, managed tokens
    refreshed in place. The gmail/gcal/hubspot bespoke helpers predate this."""
    from . import accounts as _accounts

    account_id, key, profile = _accounts.resolve(secrets, connector, account)
    if profile is None:
        hint = (
            f"no {connector} account matching {account!r}"
            if account
            else f"{connector} is not connected"
        )
        return "", None, {"error": hint}
    if profile.get("managed"):
        from ..cloud import ensure_fresh_connector_token
        from ..config import load_config

        ensure_fresh_connector_token(secrets, load_config(), connector, profile_key=key)
        profile = secrets.get(key) or profile
    missing = [k for k in keys if not profile.get(k)]
    if missing:
        return (
            account_id,
            None,
            {"error": f"{connector} is not connected; missing {', '.join(missing)}"},
        )
    return account_id, profile, None


def _acct_result(account_id: str, result: dict[str, Any]) -> dict[str, Any]:
    """Stamp which account served a tool call — approvals and transcripts must
    name the account once more than one is connected."""
    if isinstance(result, dict) and account_id:
        return {"account": account_id, **result}
    return result


_GEN_ACCOUNT_PROP = {
    "type": "string",
    "description": "Which connected account to use (default account when empty)",
}


def _gmail_profile(
    secrets: SecretStore, account: str = ""
) -> tuple[str, Optional[dict[str, Any]], Optional[dict[str, str]]]:
    """(email, profile, err) for the requested — or default — mailbox, with the
    managed token refreshed in place. Multi-account: `gmail:account:<email>`."""
    from . import gmail_accounts

    email, key, profile = gmail_accounts.resolve(secrets, account)
    if profile is None:
        hint = (
            f"no gmail account matching {account!r}"
            if account
            else "gmail is not connected"
        )
        return "", None, {"error": hint}
    if profile.get("managed"):
        from ..cloud import ensure_fresh_connector_token
        from ..config import load_config

        ensure_fresh_connector_token(secrets, load_config(), "gmail", profile_key=key)
        profile = secrets.get(key) or profile
    if not profile.get("access_token"):
        return "", None, {"error": f"gmail account {email} has no usable token"}
    return email, profile, None


def _gcal_profile(
    secrets: SecretStore, account: str = ""
) -> tuple[str, Optional[dict[str, Any]], Optional[dict[str, str]]]:
    """(email, profile, err) for the requested — or default — Google account,
    with the managed token refreshed in place. Multi-account:
    `google_calendar:account:<email>`."""
    from . import gcal_accounts

    email, key, profile = gcal_accounts.resolve(secrets, account)
    if profile is None:
        hint = (
            f"no google calendar account matching {account!r}"
            if account
            else "google calendar is not connected"
        )
        return "", None, {"error": hint}
    if profile.get("managed"):
        from ..cloud import ensure_fresh_connector_token
        from ..config import load_config

        ensure_fresh_connector_token(
            secrets, load_config(), "google_calendar", profile_key=key
        )
        profile = secrets.get(key) or profile
    if not profile.get("access_token"):
        return (
            "",
            None,
            {"error": f"google calendar account {email} has no usable token"},
        )
    return email, profile, None


# HubSpot-defined association type ids: note → object (v4 default associations).
_HS_NOTE_ASSOC = {"contacts": 202, "companies": 190, "deals": 214, "tickets": 228}


def _now_ms() -> int:
    from time import time

    return int(time() * 1000)


def _hubspot_profile(
    secrets: SecretStore, portal: str = ""
) -> tuple[str, str, Optional[dict[str, str]]]:
    """(portal name, bearer token, err) for the requested — or default — portal,
    with a managed token refreshed in place. Multi-portal: `hubspot:portal:<id>`."""
    from . import hubspot_portals

    hub_id, key, profile = hubspot_portals.resolve(secrets, portal)
    if profile is None:
        hint = (
            f"no hubspot portal matching {portal!r}"
            if portal
            else "hubspot is not connected"
        )
        return "", "", {"error": hint}
    if profile.get("managed"):
        from ..cloud import ensure_fresh_connector_token
        from ..config import load_config

        ensure_fresh_connector_token(secrets, load_config(), "hubspot", profile_key=key)
        profile = secrets.get(key) or profile
    # Manual private-app profiles carry `token`; managed OAuth carries
    # `access_token` (which is what the broker refresh rotates).
    token = profile.get("token") or profile.get("access_token") or ""
    if not token:
        return "", "", {"error": f"hubspot portal {hub_id} has no usable token"}
    name = str(profile.get("account") or f"portal {hub_id}")
    return name, token, None


def _hubspot_result(secrets: SecretStore, portal_name: str, result: dict) -> dict:
    """Post-process a CRM read: strip denylisted fields (model-facing policy)
    and name the portal so transcripts/approvals say where data came from.
    Stripped-value counts ride `_display` → audit; agents see nothing."""
    from . import hubspot_portals

    if not result.get("ok"):
        return result
    hidden = hubspot_portals.get_hidden_fields(secrets)
    data, removed = hubspot_portals.strip_hidden(result.get("data"), hidden)
    out = {**result, "data": data, "portal": portal_name}
    if removed:
        out["_display"] = {"hidden_fields": removed, "connector": "hubspot"}
    return out


# --- "Never show agents" enforcement (desktop tool layer, silent to agents) ----


def _gmail_filters(secrets: SecretStore) -> Optional[dict[str, list[str]]]:
    from . import gmail_accounts

    f = gmail_accounts.get_filters(secrets)
    return f if (f["senders"] or f["labels"]) else None


def _gmail_from_address(message: dict[str, Any]) -> str:
    from email.utils import parseaddr

    for h in (message.get("payload") or {}).get("headers") or []:
        if str(h.get("name", "")).lower() == "from":
            return parseaddr(str(h.get("value") or ""))[1]
    return ""


def _gmail_label_map(token: str) -> dict[str, str]:
    """Label id → name for the mailbox (names are what the user filters on)."""
    resp = _request(
        "GET",
        "https://gmail.googleapis.com/gmail/v1/users/me/labels",
        headers=_google_headers(token),
    )
    if not resp.get("ok"):
        return {}
    labels = (resp.get("data") or {}).get("labels") or []
    return {str(l.get("id") or ""): str(l.get("name") or "") for l in labels}


def _gmail_is_hidden(
    message: dict[str, Any],
    filters: dict[str, list[str]],
    label_map: dict[str, str],
) -> bool:
    from .gmail_accounts import sender_matches

    if filters["senders"] and sender_matches(
        _gmail_from_address(message), filters["senders"]
    ):
        return True
    if filters["labels"]:
        wanted = {name.lower() for name in filters["labels"]}
        for lid in message.get("labelIds") or []:
            if (
                label_map.get(str(lid), "").lower() in wanted
                or str(lid).lower() in wanted
            ):
                return True
    return False


def _request(
    method: str, url: str, *, headers=None, params=None, json=None, auth=None
) -> dict[str, Any]:
    try:
        import httpx

        with httpx.Client(timeout=30.0, follow_redirects=True) as client:
            resp = client.request(
                method, url, headers=headers, params=params, json=json, auth=auth
            )
            ctype = resp.headers.get("content-type", "")
            data: Any = resp.json() if "json" in ctype.lower() else resp.text
            if resp.status_code >= 400:
                return {"error": f"HTTP {resp.status_code}", "details": data}
            return {"ok": True, "data": data}
    except Exception as exc:
        return {"error": str(exc)}


class _TextExtractor(HTMLParser):
    _SKIP = {"script", "style", "noscript", "svg", "head"}

    def __init__(self) -> None:
        super().__init__()
        self._skip = 0
        self.parts: list[str] = []

    def handle_starttag(self, tag: str, attrs: Any) -> None:
        if tag in self._SKIP:
            self._skip += 1

    def handle_endtag(self, tag: str) -> None:
        if tag in self._SKIP and self._skip:
            self._skip -= 1

    def handle_data(self, data: str) -> None:
        if not self._skip:
            text = data.strip()
            if text:
                self.parts.append(text)


def _html_to_text(html: str) -> str:
    parser = _TextExtractor()
    try:
        parser.feed(html)
    except Exception:
        pass
    return re.sub(r"\n{3,}", "\n\n", "\n".join(parser.parts))


def _github_headers(token: str) -> dict[str, str]:
    return {
        "Authorization": f"Bearer {token}",
        "Accept": "application/vnd.github+json",
        "X-GitHub-Api-Version": "2022-11-28",
    }


def _github_base() -> str:
    import os

    return os.environ.get("GITHUB_API_URL", "https://api.github.com").rstrip("/")


def _github_auth(
    secrets: SecretStore, install: str = "", *, force: bool = False
) -> tuple[Optional[dict[str, str]], Optional[dict[str, str]]]:
    """(headers, err). A manual PAT (`github:default.token`) wins, untouched;
    a managed relay profile mints a short-lived installation token instead —
    memory-cached, never stored (github-relay-spec §4). `install` picks the
    installation by account login (pass the repo owner) or id; unknown values
    fall back to the default installation."""
    profile = secrets.get("github:default") or {}
    if profile.get("token"):
        return _github_headers(profile["token"]), None
    if profile.get("mode") == "relay":
        from ..cloud import github_installation_token
        from ..config import load_config
        from . import github_installs

        installation_id, _prof = github_installs.resolve(secrets, install)
        if not installation_id and install:
            installation_id, _prof = github_installs.resolve(secrets, "")
        if not installation_id:
            return None, {"error": "github is not connected; no App installation"}
        token = github_installation_token(
            secrets, load_config(), installation_id, force=force
        )
        if not token:
            return None, {
                "error": "github installation token unavailable "
                "(sign in to OpenWorker Cloud and retry)"
            }
        return _github_headers(token), None
    return None, {"error": "github is not connected; missing token"}


def _github_git_auth_args(secrets: SecretStore, owner: str) -> list[str]:
    """Per-invocation git auth: the token rides an HTTP header on the command
    line only — it must NEVER land in .git/config or a credential store (the
    no-token-at-rest rule; github-relay-spec §4). Empty for the tokenless case
    (public repos clone fine without auth)."""
    import base64

    headers, err = _github_auth(secrets, owner)
    if err:
        return ["-c", "credential.helper="]
    token = headers["Authorization"].split(" ", 1)[1]
    basic = base64.b64encode(f"x-access-token:{token}".encode()).decode()
    return [
        "-c",
        f"http.extraHeader=AUTHORIZATION: basic {basic}",
        "-c",
        "credential.helper=",
    ]


def _run_git(
    args: list[str], *, cwd: Any = None, timeout: int = 600
) -> tuple[str, str]:
    """(stdout, error). Never raises; the error string is capped and carries no
    auth material (git never echoes header values)."""
    import subprocess

    try:
        proc = subprocess.run(
            ["git", *args], cwd=cwd, capture_output=True, text=True, timeout=timeout
        )
    except FileNotFoundError:
        return "", "git is not installed"
    except subprocess.TimeoutExpired:
        return "", "git timed out"
    if proc.returncode != 0:
        return "", (proc.stderr or proc.stdout).strip()[-500:]
    return proc.stdout.strip(), ""


def _github_git_base() -> str:
    import os

    return os.environ.get("GITHUB_GIT_URL", "https://github.com").rstrip("/")


def _github_call(
    secrets: SecretStore, method: str, path: str, *, install: str = "", **kw: Any
) -> dict[str, Any]:
    """A GitHub API call that works on either auth path. A 401 on the managed
    path re-mints once (the cached installation token may have just expired)."""
    headers, err = _github_auth(secrets, install)
    if err:
        return err
    out = _request(method, _github_base() + path, headers=headers, **kw)
    managed = not (secrets.get("github:default") or {}).get("token")
    if managed and out.get("error") == "HTTP 401":
        headers, err = _github_auth(secrets, install, force=True)
        if err:
            return out
        out = _request(method, _github_base() + path, headers=headers, **kw)
    return out


def _google_headers(token: str) -> dict[str, str]:
    return {"Authorization": f"Bearer {token}", "Accept": "application/json"}


def _graph_headers(token: str) -> dict[str, str]:
    return {
        "Authorization": f"Bearer {token}",
        "Accept": "application/json",
        "Content-Type": "application/json",
    }


def _basic_auth(email: str, token: str) -> tuple[str, str]:
    return (email, token)


def _atlassian_base(profile: dict[str, Any]) -> str:
    return str(profile.get("base_url", "")).rstrip("/")


def _bearer_headers(token: str) -> dict[str, str]:
    return {"Authorization": f"Bearer {token}", "Accept": "application/json"}


def _gitlab_api(profile: dict[str, Any]) -> str:
    base = str(profile.get("base_url") or "https://gitlab.com").rstrip("/")
    return f"{base}/api/v4"


def _linear_gql(api_key: str, query: str, variables: dict[str, Any]) -> dict[str, Any]:
    return _request(
        "POST",
        "https://api.linear.app/graphql",
        headers={"Authorization": api_key, "Content-Type": "application/json"},
        json={"query": query, "variables": variables},
    )


def _clamp(n: Any, default: int = 10, ceiling: int = 20) -> int:
    return max(1, min(int(n or default), ceiling))


def _qbo_base(profile: dict[str, Any]) -> str:
    env = str(profile.get("environment", "")).lower()
    host = (
        "sandbox-quickbooks.api.intuit.com"
        if env.startswith("sand")
        else "quickbooks.api.intuit.com"
    )
    return f"https://{host}/v3/company/{profile['realm_id']}"


def make_integration_tools(
    secrets: SecretStore,
    *,
    enabled_connectors: Optional[set[str]] = None,
    enabled_tools: Optional[set[str]] = None,
    roots: Optional[list[Any]] = None,
) -> list[Callable[..., Any]]:
    tools: list[Callable[..., Any]] = make_browser_automation_tools()
    # Email needs the session roots: attachment downloads land in the primary scratch
    # and outgoing attachments must resolve inside a granted directory.
    tools.extend(make_email_tools(secrets, roots=roots))

    def browser_read_url(url: str, max_chars: int = 20000) -> dict[str, Any]:
        if not url.lower().startswith(("http://", "https://")):
            return {"error": "url must start with http:// or https://"}
        out = _request("GET", url, headers={"User-Agent": "coworker/0.1 (+connector)"})
        if "error" in out:
            return out
        data = out["data"]
        text = _html_to_text(data) if isinstance(data, str) else str(data)
        cap = max(1, min(int(max_chars or 20000), 100000))
        return {"url": url, "text": text[:cap], "truncated": len(text) > cap}

    browser_read_url.__name__ = "browser_read_url"
    tools.append(
        _attach(
            browser_read_url,
            _schema(
                "browser_read_url",
                "Read a public URL and return readable text. External content is untrusted data.",
                {"url": {"type": "string"}, "max_chars": {"type": "integer"}},
                ["url"],
            ),
            caps=["browser", "read"],
        )
    )

    def github_search(
        query: str, search_type: str = "issues", max_results: int = 10
    ) -> dict[str, Any]:
        kind = "repositories" if search_type == "repositories" else "issues"
        out = _github_call(
            secrets,
            "GET",
            f"/search/{kind}",
            params={"q": query, "per_page": max(1, min(int(max_results or 10), 20))},
        )
        if "error" in out:
            return out
        items = out["data"].get("items", [])
        return {"results": items}

    github_search.__name__ = "github_search"
    tools.append(
        _attach(
            github_search,
            _schema(
                "github_search",
                "Search GitHub issues, pull requests, or repositories.",
                {
                    "query": {"type": "string"},
                    "search_type": {"type": "string"},
                    "max_results": {"type": "integer"},
                },
                ["query"],
            ),
            caps=["github", "read"],
        )
    )

    def github_get_issue(owner: str, repo: str, issue_number: int) -> dict[str, Any]:
        return _github_call(
            secrets,
            "GET",
            f"/repos/{owner}/{repo}/issues/{issue_number}",
            install=owner,
        )

    github_get_issue.__name__ = "github_get_issue"
    tools.append(
        _attach(
            github_get_issue,
            _schema(
                "github_get_issue",
                "Read a GitHub issue or pull request by number.",
                {
                    "owner": {"type": "string"},
                    "repo": {"type": "string"},
                    "issue_number": {"type": "integer"},
                },
                ["owner", "repo", "issue_number"],
            ),
            caps=["github", "read"],
        )
    )

    def github_create_issue(
        owner: str, repo: str, title: str, body: str = ""
    ) -> dict[str, Any]:
        return _github_call(
            secrets,
            "POST",
            f"/repos/{owner}/{repo}/issues",
            install=owner,
            json={"title": title, "body": body},
        )

    github_create_issue.__name__ = "github_create_issue"
    tools.append(
        _attach(
            github_create_issue,
            _schema(
                "github_create_issue",
                "Create a GitHub issue. Requires user approval.",
                {
                    "owner": {"type": "string"},
                    "repo": {"type": "string"},
                    "title": {"type": "string"},
                    "body": {"type": "string"},
                },
                ["owner", "repo", "title"],
            ),
            approval=True,
            caps=["github", "write"],
        )
    )

    # Wave-1 relay write tools (github-relay-spec §8). The write ceiling is
    # enforced by what exists here: comments, reviews, issues — no push,
    # branch-delete, or repo-settings tools on any auth path.
    def github_reply(owner: str, repo: str, number: int, body: str) -> dict[str, Any]:
        return _github_call(
            secrets,
            "POST",
            f"/repos/{owner}/{repo}/issues/{number}/comments",
            install=owner,
            json={"body": body},
        )

    github_reply.__name__ = "github_reply"
    tools.append(
        _attach(
            github_reply,
            _schema(
                "github_reply",
                "Comment on a GitHub issue or pull request (as the agent's bot "
                "identity on the managed path). Requires user approval.",
                {
                    "owner": {"type": "string"},
                    "repo": {"type": "string"},
                    "number": {"type": "integer"},
                    "body": {"type": "string"},
                },
                ["owner", "repo", "number", "body"],
            ),
            approval=True,
            caps=["github", "write"],
        )
    )

    def github_review(
        owner: str, repo: str, pull_number: int, event: str = "COMMENT", body: str = ""
    ) -> dict[str, Any]:
        event = (event or "COMMENT").upper()
        if event not in ("APPROVE", "REQUEST_CHANGES", "COMMENT"):
            return {"error": "event must be APPROVE, REQUEST_CHANGES or COMMENT"}
        return _github_call(
            secrets,
            "POST",
            f"/repos/{owner}/{repo}/pulls/{pull_number}/reviews",
            install=owner,
            json={"event": event, **({"body": body} if body else {})},
        )

    github_review.__name__ = "github_review"
    tools.append(
        _attach(
            github_review,
            _schema(
                "github_review",
                "Submit a pull-request review (approve / request changes / "
                "comment). Requires user approval.",
                {
                    "owner": {"type": "string"},
                    "repo": {"type": "string"},
                    "pull_number": {"type": "integer"},
                    "event": {"type": "string"},
                    "body": {"type": "string"},
                },
                ["owner", "repo", "pull_number"],
            ),
            approval=True,
            caps=["github", "write"],
        )
    )

    def github_list_commits(
        owner: str,
        repo: str,
        since: str = "",
        until: str = "",
        author: str = "",
        max_results: int = 30,
    ) -> dict[str, Any]:
        params: dict[str, Any] = {"per_page": max(1, min(int(max_results or 30), 100))}
        if since:
            params["since"] = since
        if until:
            params["until"] = until
        if author:
            params["author"] = author
        out = _github_call(
            secrets,
            "GET",
            f"/repos/{owner}/{repo}/commits",
            install=owner,
            params=params,
        )
        if "error" in out:
            return out
        commits = [
            {
                "sha": (c.get("sha") or "")[:12],
                "author": ((c.get("commit") or {}).get("author") or {}).get("name")
                or (c.get("author") or {}).get("login", ""),
                "date": ((c.get("commit") or {}).get("author") or {}).get("date", ""),
                "message": ((c.get("commit") or {}).get("message") or "")[:500],
            }
            for c in (out["data"] if isinstance(out["data"], list) else [])
        ]
        return {"commits": commits, "count": len(commits)}

    github_list_commits.__name__ = "github_list_commits"
    tools.append(
        _attach(
            github_list_commits,
            _schema(
                "github_list_commits",
                "List a repository's commits (newest first), optionally filtered "
                "by ISO-8601 since/until dates or author — the raw material for "
                "activity summaries.",
                {
                    "owner": {"type": "string"},
                    "repo": {"type": "string"},
                    "since": {
                        "type": "string",
                        "description": "ISO-8601, e.g. 2026-07-06T00:00:00Z",
                    },
                    "until": {"type": "string"},
                    "author": {"type": "string", "description": "GitHub login"},
                    "max_results": {"type": "integer"},
                },
                ["owner", "repo"],
            ),
            approval=False,
            caps=["github", "read"],
        )
    )

    def _writable_target(
        raw: str, *, default_name: str = ""
    ) -> tuple[Any, dict[str, Any] | None]:
        """Resolve a directory inside a WRITABLE granted root — clones and pulls
        never touch anything the user hasn't shared with the session."""
        from pathlib import Path as _Path

        writable = [r.path for r in (roots or []) if r.writable]
        if not writable:
            return None, {"error": "no writable session directory to clone into"}
        path = (
            _Path(str(raw)).expanduser().resolve()
            if raw
            else (writable[0] / default_name).resolve()
        )
        if not any(path.is_relative_to(root) for root in writable):
            return None, {
                "error": f"{path} is outside the session's writable directories"
            }
        return path, None

    def github_clone(owner: str, repo: str, directory: str = "") -> dict[str, Any]:
        target, err = _writable_target(directory, default_name=repo)
        if err:
            return err
        if target.exists() and any(target.iterdir()):
            return {
                "error": f"{target} already exists and is not empty (use github_pull?)"
            }
        url = f"{_github_git_base()}/{owner}/{repo}.git"
        _out, git_err = _run_git(
            [*_github_git_auth_args(secrets, owner), "clone", url, str(target)]
        )
        if git_err:
            return {"error": f"clone failed: {git_err}"}
        # Belt and braces for the no-token-at-rest rule: header auth is
        # process-only, so nothing secret can be in the clone's config — verify.
        config = (target / ".git" / "config").read_text()
        if "AUTHORIZATION" in config or "x-access-token" in config:
            import shutil

            shutil.rmtree(target)
            return {"error": "clone aborted: credentials would have persisted"}
        head, _ = _run_git(["rev-parse", "--short", "HEAD"], cwd=target)
        return {"ok": True, "path": str(target), "head": head}

    github_clone.__name__ = "github_clone"
    tools.append(
        _attach(
            github_clone,
            _schema(
                "github_clone",
                "Clone a GitHub repository into a session folder so the agent can "
                "explore the code locally. Private repos use a short-lived token "
                "that is never written to disk. Requires user approval.",
                {
                    "owner": {"type": "string"},
                    "repo": {"type": "string"},
                    "directory": {
                        "type": "string",
                        "description": "target path inside a granted folder (default: <primary>/<repo>)",
                    },
                },
                ["owner", "repo"],
            ),
            approval=True,
            caps=["github", "read"],
        )
    )

    def github_pull(directory: str) -> dict[str, Any]:
        target, err = _writable_target(directory)
        if err:
            return err
        if not (target / ".git").exists():
            return {"error": f"{target} is not a git repository"}
        remote, git_err = _run_git(["remote", "get-url", "origin"], cwd=target)
        if git_err:
            return {"error": f"no origin remote: {git_err}"}
        m = re.search(r"[:/]([^/:]+)/([^/]+?)(?:\.git)?/?$", remote)
        owner = m.group(1) if m else ""
        _out, git_err = _run_git(
            [
                *_github_git_auth_args(secrets, owner),
                "-C",
                str(target),
                "pull",
                "--ff-only",
            ]
        )
        if git_err:
            return {"error": f"pull failed: {git_err}"}
        head, _ = _run_git(["rev-parse", "--short", "HEAD"], cwd=target)
        return {"ok": True, "path": str(target), "head": head}

    github_pull.__name__ = "github_pull"
    tools.append(
        _attach(
            github_pull,
            _schema(
                "github_pull",
                "Fast-forward an existing clone in a session folder to the latest "
                "upstream commits. Requires user approval.",
                {"directory": {"type": "string"}},
                ["directory"],
            ),
            approval=True,
            caps=["github", "read"],
        )
    )

    _ACCOUNT_PROP = {
        "type": "string",
        "description": "Mailbox email to use; omit for the default account.",
    }

    def gmail_search_messages(
        query: str, max_results: int = 10, account: str = ""
    ) -> dict[str, Any]:
        email, profile, err = _gmail_profile(secrets, account)
        if err:
            return err
        token = profile["access_token"]
        result = _request(
            "GET",
            "https://gmail.googleapis.com/gmail/v1/users/me/messages",
            headers=_google_headers(token),
            params={"q": query, "maxResults": max(1, min(int(max_results or 10), 20))},
        )
        filters = _gmail_filters(secrets)
        if result.get("ok") and filters:
            # Enforce "Never show agents" HERE, silently: matching hits are
            # omitted (no tombstone); the count rides the `_display` sidecar for
            # the user's tool card + audit — never the agent-visible content.
            data = dict(result.get("data") or {})
            label_map = _gmail_label_map(token) if filters["labels"] else {}
            kept, hidden = [], 0
            for m in data.get("messages") or []:
                meta = _request(
                    "GET",
                    f"https://gmail.googleapis.com/gmail/v1/users/me/messages/{m.get('id')}",
                    headers=_google_headers(token),
                    params={"format": "metadata", "metadataHeaders": "From"},
                )
                detail = meta.get("data") if meta.get("ok") else None
                # Fail-open on a metadata miss: ids alone reveal nothing, and
                # gmail_get_message re-enforces before any content flows.
                if isinstance(detail, dict) and _gmail_is_hidden(
                    detail, filters, label_map
                ):
                    hidden += 1
                else:
                    kept.append(m)
            if hidden:
                data["messages"] = kept
                if isinstance(data.get("resultSizeEstimate"), int):
                    data["resultSizeEstimate"] = max(
                        0, data["resultSizeEstimate"] - hidden
                    )
                result = {
                    "ok": True,
                    "data": data,
                    "_display": {"hidden_by_filters": hidden, "connector": "gmail"},
                }
        if result.get("ok"):
            result["account"] = email
        return result

    gmail_search_messages.__name__ = "gmail_search_messages"
    tools.append(
        _attach(
            gmail_search_messages,
            _schema(
                "gmail_search_messages",
                "Search Gmail messages using Gmail query syntax.",
                {
                    "query": {"type": "string"},
                    "max_results": {"type": "integer"},
                    "account": _ACCOUNT_PROP,
                },
                ["query"],
            ),
            caps=["gmail", "read"],
        )
    )

    def gmail_get_message(message_id: str, account: str = "") -> dict[str, Any]:
        email, profile, err = _gmail_profile(secrets, account)
        if err:
            return err
        token = profile["access_token"]
        result = _request(
            "GET",
            f"https://gmail.googleapis.com/gmail/v1/users/me/messages/{message_id}",
            headers=_google_headers(token),
            params={"format": "full"},
        )
        filters = _gmail_filters(secrets)
        if result.get("ok") and filters:
            data = result.get("data") or {}
            label_map = _gmail_label_map(token) if filters["labels"] else {}
            if isinstance(data, dict) and _gmail_is_hidden(data, filters, label_map):
                # Indistinguishable from a real miss — the agent must not be able
                # to tell "filtered" from "gone" (a tombstone invites probing).
                return {
                    "error": "HTTP 404",
                    "details": {"error": {"code": 404, "message": "Not Found"}},
                    "_display": {"hidden_by_filters": 1, "connector": "gmail"},
                }
        if result.get("ok"):
            result["account"] = email
        return result

    gmail_get_message.__name__ = "gmail_get_message"
    tools.append(
        _attach(
            gmail_get_message,
            _schema(
                "gmail_get_message",
                "Read a Gmail message by ID.",
                {"message_id": {"type": "string"}, "account": _ACCOUNT_PROP},
                ["message_id"],
            ),
            caps=["gmail", "read"],
        )
    )

    def gmail_send_email(
        to: str, subject: str, body: str, cc: str = "", account: str = ""
    ) -> dict[str, Any]:
        email, profile, err = _gmail_profile(secrets, account)
        if err:
            return err
        msg = EmailMessage()
        msg["To"], msg["Subject"] = to, subject
        if cc:
            msg["Cc"] = cc
        msg.set_content(body)
        raw = base64.urlsafe_b64encode(msg.as_bytes()).decode().rstrip("=")
        result = _request(
            "POST",
            "https://gmail.googleapis.com/gmail/v1/users/me/messages/send",
            headers=_google_headers(profile["access_token"]),
            json={"raw": raw},
        )
        if result.get("ok"):
            result["account"] = email
        return result

    gmail_send_email.__name__ = "gmail_send_email"
    tools.append(
        _attach(
            gmail_send_email,
            _schema(
                "gmail_send_email",
                "Send an email through Gmail. Requires user approval; the "
                "`account` argument names the sending mailbox on the approval card.",
                {
                    "to": {"type": "string"},
                    "subject": {"type": "string"},
                    "body": {"type": "string"},
                    "cc": {"type": "string"},
                    "account": _ACCOUNT_PROP,
                },
                ["to", "subject", "body"],
            ),
            approval=True,
            caps=["gmail", "write"],
        )
    )

    _CAL_ACCOUNT_PROP = {
        "type": "string",
        "description": "Google account email to use; omit for the default account.",
    }

    def _gcal_result(email: str, result: dict[str, Any]) -> dict[str, Any]:
        # Name the account on every success so approvals/transcripts say whose
        # calendar was touched (same contract as the gmail tools).
        if result.get("ok"):
            result["account"] = email
        return result

    def gcal_list_events(
        calendar_id: str = "primary",
        time_min: str = "",
        time_max: str = "",
        max_results: int = 10,
        account: str = "",
    ) -> dict[str, Any]:
        email, profile, err = _gcal_profile(secrets, account)
        if err:
            return err
        params: dict[str, Any] = {
            "singleEvents": True,
            "orderBy": "startTime",
            "maxResults": max(1, min(int(max_results or 10), 20)),
        }
        if time_min:
            params["timeMin"] = time_min
        if time_max:
            params["timeMax"] = time_max
        return _gcal_result(
            email,
            _request(
                "GET",
                f"https://www.googleapis.com/calendar/v3/calendars/{calendar_id}/events",
                headers=_google_headers(profile["access_token"]),
                params=params,
            ),
        )

    gcal_list_events.__name__ = "gcal_list_events"
    tools.append(
        _attach(
            gcal_list_events,
            _schema(
                "gcal_list_events",
                "List Google Calendar events. time_min/time_max should be RFC3339 timestamps when provided.",
                {
                    "calendar_id": {"type": "string"},
                    "time_min": {"type": "string"},
                    "time_max": {"type": "string"},
                    "max_results": {"type": "integer"},
                    "account": _CAL_ACCOUNT_PROP,
                },
                [],
            ),
            caps=["calendar", "read"],
        )
    )

    def gcal_free_busy(
        time_min: str,
        time_max: str,
        calendars: str = "primary",
        timezone: str = "UTC",
        account: str = "",
    ) -> dict[str, Any]:
        email, profile, err = _gcal_profile(secrets, account)
        if err:
            return err
        items = [
            {"id": c.strip()}
            for c in str(calendars or "primary").split(",")
            if c.strip()
        ]
        return _gcal_result(
            email,
            _request(
                "POST",
                "https://www.googleapis.com/calendar/v3/freeBusy",
                headers=_google_headers(profile["access_token"]),
                json={
                    "timeMin": time_min,
                    "timeMax": time_max,
                    "timeZone": timezone,
                    "items": items,
                },
            ),
        )

    gcal_free_busy.__name__ = "gcal_free_busy"
    tools.append(
        _attach(
            gcal_free_busy,
            _schema(
                "gcal_free_busy",
                "Look up busy intervals (availability) for one or more calendars. "
                "time_min/time_max are RFC3339 timestamps; calendars is a comma-separated list of calendar ids.",
                {
                    "time_min": {"type": "string"},
                    "time_max": {"type": "string"},
                    "calendars": {"type": "string"},
                    "timezone": {"type": "string"},
                    "account": _CAL_ACCOUNT_PROP,
                },
                ["time_min", "time_max"],
            ),
            caps=["calendar", "read"],
        )
    )

    def gcal_create_event(
        summary: str,
        start: str,
        end: str,
        calendar_id: str = "primary",
        timezone: str = "UTC",
        description: str = "",
        account: str = "",
    ) -> dict[str, Any]:
        email, profile, err = _gcal_profile(secrets, account)
        if err:
            return err
        payload = {
            "summary": summary,
            "description": description,
            "start": {"dateTime": start, "timeZone": timezone},
            "end": {"dateTime": end, "timeZone": timezone},
        }
        return _gcal_result(
            email,
            _request(
                "POST",
                f"https://www.googleapis.com/calendar/v3/calendars/{calendar_id}/events",
                headers=_google_headers(profile["access_token"]),
                json=payload,
            ),
        )

    gcal_create_event.__name__ = "gcal_create_event"
    tools.append(
        _attach(
            gcal_create_event,
            _schema(
                "gcal_create_event",
                "Create a Google Calendar event. Requires user approval.",
                {
                    "summary": {"type": "string"},
                    "start": {"type": "string"},
                    "end": {"type": "string"},
                    "calendar_id": {"type": "string"},
                    "timezone": {"type": "string"},
                    "description": {"type": "string"},
                    "account": _CAL_ACCOUNT_PROP,
                },
                ["summary", "start", "end"],
            ),
            approval=True,
            caps=["calendar", "write"],
        )
    )

    def gcal_update_event(
        event_id: str,
        calendar_id: str = "primary",
        summary: str = "",
        start: str = "",
        end: str = "",
        timezone: str = "UTC",
        description: str = "",
        account: str = "",
    ) -> dict[str, Any]:
        email, profile, err = _gcal_profile(secrets, account)
        if err:
            return err
        # PATCH semantics: only the provided fields change.
        payload: dict[str, Any] = {}
        if summary:
            payload["summary"] = summary
        if description:
            payload["description"] = description
        if start:
            payload["start"] = {"dateTime": start, "timeZone": timezone}
        if end:
            payload["end"] = {"dateTime": end, "timeZone": timezone}
        if not payload:
            return {
                "error": "nothing to update — pass summary, description, start, or end"
            }
        return _gcal_result(
            email,
            _request(
                "PATCH",
                f"https://www.googleapis.com/calendar/v3/calendars/{calendar_id}/events/{event_id}",
                headers=_google_headers(profile["access_token"]),
                json=payload,
            ),
        )

    gcal_update_event.__name__ = "gcal_update_event"
    tools.append(
        _attach(
            gcal_update_event,
            _schema(
                "gcal_update_event",
                "Update fields of a Google Calendar event (only the provided fields change). Requires user approval.",
                {
                    "event_id": {"type": "string"},
                    "calendar_id": {"type": "string"},
                    "summary": {"type": "string"},
                    "start": {"type": "string"},
                    "end": {"type": "string"},
                    "timezone": {"type": "string"},
                    "description": {"type": "string"},
                    "account": _CAL_ACCOUNT_PROP,
                },
                ["event_id"],
            ),
            approval=True,
            caps=["calendar", "write"],
        )
    )

    def gcal_delete_event(
        event_id: str, calendar_id: str = "primary", account: str = ""
    ) -> dict[str, Any]:
        email, profile, err = _gcal_profile(secrets, account)
        if err:
            return err
        return _gcal_result(
            email,
            _request(
                "DELETE",
                f"https://www.googleapis.com/calendar/v3/calendars/{calendar_id}/events/{event_id}",
                headers=_google_headers(profile["access_token"]),
            ),
        )

    gcal_delete_event.__name__ = "gcal_delete_event"
    tools.append(
        _attach(
            gcal_delete_event,
            _schema(
                "gcal_delete_event",
                "Delete a Google Calendar event. Requires user approval.",
                {
                    "event_id": {"type": "string"},
                    "calendar_id": {"type": "string"},
                    "account": _CAL_ACCOUNT_PROP,
                },
                ["event_id"],
            ),
            approval=True,
            caps=["calendar", "write"],
        )
    )

    def outlook_search_messages(
        query: str = "", max_results: int = 10, account: str = ""
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(
            secrets, "outlook", account, "access_token"
        )
        if err:
            return err
        params = {"$top": max(1, min(int(max_results or 10), 20))}
        if query:
            params["$search"] = f'"{query}"'
        return _acct_result(
            aid,
            _request(
                "GET",
                "https://graph.microsoft.com/v1.0/me/messages",
                headers=_graph_headers(profile["access_token"]),
                params=params,
            ),
        )

    outlook_search_messages.__name__ = "outlook_search_messages"
    tools.append(
        _attach(
            outlook_search_messages,
            _schema(
                "outlook_search_messages",
                "Search or list Outlook messages through Microsoft Graph.",
                {
                    "query": {"type": "string"},
                    "max_results": {"type": "integer"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                [],
            ),
            caps=["outlook", "read"],
        )
    )

    def outlook_send_mail(
        to: str, subject: str, body: str, account: str = ""
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(
            secrets, "outlook", account, "access_token"
        )
        if err:
            return err
        payload = {
            "message": {
                "subject": subject,
                "body": {"contentType": "Text", "content": body},
                "toRecipients": [{"emailAddress": {"address": to}}],
            }
        }
        return _acct_result(
            aid,
            _request(
                "POST",
                "https://graph.microsoft.com/v1.0/me/sendMail",
                headers=_graph_headers(profile["access_token"]),
                json=payload,
            ),
        )

    outlook_send_mail.__name__ = "outlook_send_mail"
    tools.append(
        _attach(
            outlook_send_mail,
            _schema(
                "outlook_send_mail",
                "Send mail through Outlook/Microsoft Graph. Requires user approval.",
                {
                    "to": {"type": "string"},
                    "subject": {"type": "string"},
                    "body": {"type": "string"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                ["to", "subject", "body"],
            ),
            approval=True,
            caps=["outlook", "write"],
        )
    )

    def outlook_list_events(
        start: str = "", end: str = "", max_results: int = 10, account: str = ""
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(
            secrets, "outlook", account, "access_token"
        )
        if err:
            return err
        # calendarView expands recurrences and takes a window; /me/events does
        # neither, so a bare call used to return arbitrary (often past) events.
        # Default window: now → +7 days.
        now = _dt.datetime.now(_dt.timezone.utc)
        fmt = "%Y-%m-%dT%H:%M:%SZ"
        return _acct_result(
            aid,
            _request(
                "GET",
                "https://graph.microsoft.com/v1.0/me/calendarView",
                headers=_graph_headers(profile["access_token"]),
                params={
                    "startDateTime": start or now.strftime(fmt),
                    "endDateTime": end or (now + _dt.timedelta(days=7)).strftime(fmt),
                    "$orderby": "start/dateTime",
                    "$top": max(1, min(int(max_results or 10), 50)),
                },
            ),
        )

    outlook_list_events.__name__ = "outlook_list_events"
    tools.append(
        _attach(
            outlook_list_events,
            _schema(
                "outlook_list_events",
                "List upcoming Outlook calendar events (recurrences expanded, ordered "
                "by start). start/end are ISO timestamps; default window is the next "
                "7 days.",
                {
                    "start": {"type": "string"},
                    "end": {"type": "string"},
                    "max_results": {"type": "integer"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                [],
            ),
            caps=["outlook", "read"],
        )
    )

    def outlook_create_event(
        subject: str,
        start: str,
        end: str,
        timezone: str = "UTC",
        body: str = "",
        attendees: str = "",
        location: str = "",
        teams_meeting: bool = False,
        account: str = "",
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(
            secrets, "outlook", account, "access_token"
        )
        if err:
            return err
        payload: dict[str, Any] = {
            "subject": subject,
            "body": {"contentType": "Text", "content": body},
            "start": {"dateTime": start, "timeZone": timezone},
            "end": {"dateTime": end, "timeZone": timezone},
        }
        if attendees:
            payload["attendees"] = [
                {"emailAddress": {"address": a.strip()}, "type": "required"}
                for a in attendees.split(",")
                if a.strip()
            ]
        if location:
            payload["location"] = {"displayName": location}
        if teams_meeting:
            payload["isOnlineMeeting"] = True
            payload["onlineMeetingProvider"] = "teamsForBusiness"
        return _acct_result(
            aid,
            _request(
                "POST",
                "https://graph.microsoft.com/v1.0/me/events",
                headers=_graph_headers(profile["access_token"]),
                json=payload,
            ),
        )

    outlook_create_event.__name__ = "outlook_create_event"
    tools.append(
        _attach(
            outlook_create_event,
            _schema(
                "outlook_create_event",
                "Create an Outlook calendar event; invites go to attendees "
                "(comma-separated emails). teams_meeting adds a Teams link. "
                "Requires user approval.",
                {
                    "subject": {"type": "string"},
                    "start": {"type": "string"},
                    "end": {"type": "string"},
                    "timezone": {"type": "string"},
                    "body": {"type": "string"},
                    "attendees": {"type": "string"},
                    "location": {"type": "string"},
                    "teams_meeting": {"type": "boolean"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                ["subject", "start", "end"],
            ),
            approval=True,
            caps=["outlook", "write"],
        )
    )

    def outlook_update_event(
        event_id: str,
        subject: str = "",
        start: str = "",
        end: str = "",
        timezone: str = "UTC",
        body: str = "",
        location: str = "",
        account: str = "",
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(
            secrets, "outlook", account, "access_token"
        )
        if err:
            return err
        # PATCH semantics: only the provided fields change.
        payload: dict[str, Any] = {}
        if subject:
            payload["subject"] = subject
        if body:
            payload["body"] = {"contentType": "Text", "content": body}
        if start:
            payload["start"] = {"dateTime": start, "timeZone": timezone}
        if end:
            payload["end"] = {"dateTime": end, "timeZone": timezone}
        if location:
            payload["location"] = {"displayName": location}
        return _acct_result(
            aid,
            _request(
                "PATCH",
                f"https://graph.microsoft.com/v1.0/me/events/{quote(event_id)}",
                headers=_graph_headers(profile["access_token"]),
                json=payload,
            ),
        )

    outlook_update_event.__name__ = "outlook_update_event"
    tools.append(
        _attach(
            outlook_update_event,
            _schema(
                "outlook_update_event",
                "Change fields of an existing Outlook calendar event (only the "
                "provided fields change). Requires user approval.",
                {
                    "event_id": {"type": "string"},
                    "subject": {"type": "string"},
                    "start": {"type": "string"},
                    "end": {"type": "string"},
                    "timezone": {"type": "string"},
                    "body": {"type": "string"},
                    "location": {"type": "string"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                ["event_id"],
            ),
            approval=True,
            caps=["outlook", "write"],
        )
    )

    def outlook_delete_event(event_id: str, account: str = "") -> dict[str, Any]:
        aid, profile, err = _account_profile(
            secrets, "outlook", account, "access_token"
        )
        if err:
            return err
        return _acct_result(
            aid,
            _request(
                "DELETE",
                f"https://graph.microsoft.com/v1.0/me/events/{quote(event_id)}",
                headers=_graph_headers(profile["access_token"]),
            ),
        )

    outlook_delete_event.__name__ = "outlook_delete_event"
    tools.append(
        _attach(
            outlook_delete_event,
            _schema(
                "outlook_delete_event",
                "Delete (cancel) an Outlook calendar event. Requires user approval.",
                {"event_id": {"type": "string"}, "account": _GEN_ACCOUNT_PROP},
                ["event_id"],
            ),
            approval=True,
            caps=["outlook", "write"],
        )
    )

    def outlook_respond_event(
        event_id: str, response: str, comment: str = "", account: str = ""
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(
            secrets, "outlook", account, "access_token"
        )
        if err:
            return err
        actions = {
            "accept": "accept",
            "decline": "decline",
            "tentative": "tentativelyAccept",
        }
        action = actions.get((response or "").strip().lower())
        if not action:
            return {"error": "response must be one of: accept, decline, tentative"}
        return _acct_result(
            aid,
            _request(
                "POST",
                f"https://graph.microsoft.com/v1.0/me/events/{quote(event_id)}/{action}",
                headers=_graph_headers(profile["access_token"]),
                json={"comment": comment, "sendResponse": True},
            ),
        )

    outlook_respond_event.__name__ = "outlook_respond_event"
    tools.append(
        _attach(
            outlook_respond_event,
            _schema(
                "outlook_respond_event",
                "Respond to an Outlook meeting invite: accept, decline, or "
                "tentative. The organizer is notified. Requires user approval.",
                {
                    "event_id": {"type": "string"},
                    "response": {"type": "string"},
                    "comment": {"type": "string"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                ["event_id", "response"],
            ),
            approval=True,
            caps=["outlook", "write"],
        )
    )

    def jira_search_issues(jql: str, max_results: int = 10) -> dict[str, Any]:
        profile, err = _profile(secrets, "jira", "base_url", "email", "api_token")
        if err:
            return err
        return _request(
            "GET",
            f"{_atlassian_base(profile)}/rest/api/3/search",
            auth=_basic_auth(profile["email"], profile["api_token"]),
            params={"jql": jql, "maxResults": max(1, min(int(max_results or 10), 20))},
        )

    jira_search_issues.__name__ = "jira_search_issues"
    tools.append(
        _attach(
            jira_search_issues,
            _schema(
                "jira_search_issues",
                "Search Jira issues using JQL.",
                {"jql": {"type": "string"}, "max_results": {"type": "integer"}},
                ["jql"],
            ),
            caps=["jira", "read"],
        )
    )

    def jira_get_issue(issue_key: str) -> dict[str, Any]:
        profile, err = _profile(secrets, "jira", "base_url", "email", "api_token")
        if err:
            return err
        return _request(
            "GET",
            f"{_atlassian_base(profile)}/rest/api/3/issue/{issue_key}",
            auth=_basic_auth(profile["email"], profile["api_token"]),
        )

    jira_get_issue.__name__ = "jira_get_issue"
    tools.append(
        _attach(
            jira_get_issue,
            _schema(
                "jira_get_issue",
                "Read a Jira issue.",
                {"issue_key": {"type": "string"}},
                ["issue_key"],
            ),
            caps=["jira", "read"],
        )
    )

    def jira_create_issue(
        project_key: str, issue_type: str, summary: str, description: str = ""
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "jira", "base_url", "email", "api_token")
        if err:
            return err
        payload = {
            "fields": {
                "project": {"key": project_key},
                "issuetype": {"name": issue_type},
                "summary": summary,
                "description": {
                    "type": "doc",
                    "version": 1,
                    "content": [
                        {
                            "type": "paragraph",
                            "content": [
                                {"type": "text", "text": description or summary}
                            ],
                        }
                    ],
                },
            }
        }
        return _request(
            "POST",
            f"{_atlassian_base(profile)}/rest/api/3/issue",
            auth=_basic_auth(profile["email"], profile["api_token"]),
            json=payload,
        )

    jira_create_issue.__name__ = "jira_create_issue"
    tools.append(
        _attach(
            jira_create_issue,
            _schema(
                "jira_create_issue",
                "Create a Jira issue. Requires user approval.",
                {
                    "project_key": {"type": "string"},
                    "issue_type": {"type": "string"},
                    "summary": {"type": "string"},
                    "description": {"type": "string"},
                },
                ["project_key", "issue_type", "summary"],
            ),
            approval=True,
            caps=["jira", "write"],
        )
    )

    def confluence_search(query: str, max_results: int = 10) -> dict[str, Any]:
        profile, err = _profile(secrets, "confluence", "base_url", "email", "api_token")
        if err:
            return err
        return _request(
            "GET",
            f"{_atlassian_base(profile)}/wiki/rest/api/search",
            auth=_basic_auth(profile["email"], profile["api_token"]),
            params={
                "cql": f'text ~ "{query}"',
                "limit": max(1, min(int(max_results or 10), 20)),
            },
        )

    confluence_search.__name__ = "confluence_search"
    tools.append(
        _attach(
            confluence_search,
            _schema(
                "confluence_search",
                "Search Confluence pages.",
                {"query": {"type": "string"}, "max_results": {"type": "integer"}},
                ["query"],
            ),
            caps=["confluence", "read"],
        )
    )

    def confluence_get_page(page_id: str) -> dict[str, Any]:
        profile, err = _profile(secrets, "confluence", "base_url", "email", "api_token")
        if err:
            return err
        return _request(
            "GET",
            f"{_atlassian_base(profile)}/wiki/rest/api/content/{page_id}",
            auth=_basic_auth(profile["email"], profile["api_token"]),
            params={"expand": "body.storage,version,space"},
        )

    confluence_get_page.__name__ = "confluence_get_page"
    tools.append(
        _attach(
            confluence_get_page,
            _schema(
                "confluence_get_page",
                "Read a Confluence page.",
                {"page_id": {"type": "string"}},
                ["page_id"],
            ),
            caps=["confluence", "read"],
        )
    )

    def confluence_create_page(
        space_key: str, title: str, body: str, parent_id: str = ""
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "confluence", "base_url", "email", "api_token")
        if err:
            return err
        payload: dict[str, Any] = {
            "type": "page",
            "title": title,
            "space": {"key": space_key},
            "body": {"storage": {"value": body, "representation": "storage"}},
        }
        if parent_id:
            payload["ancestors"] = [{"id": parent_id}]
        return _request(
            "POST",
            f"{_atlassian_base(profile)}/wiki/rest/api/content",
            auth=_basic_auth(profile["email"], profile["api_token"]),
            json=payload,
        )

    confluence_create_page.__name__ = "confluence_create_page"
    tools.append(
        _attach(
            confluence_create_page,
            _schema(
                "confluence_create_page",
                "Create a Confluence page. Body should be Confluence storage-format HTML. Requires user approval.",
                {
                    "space_key": {"type": "string"},
                    "title": {"type": "string"},
                    "body": {"type": "string"},
                    "parent_id": {"type": "string"},
                },
                ["space_key", "title", "body"],
            ),
            approval=True,
            caps=["confluence", "write"],
        )
    )

    def zendesk_search(query: str) -> dict[str, Any]:
        profile, err = _profile(secrets, "zendesk", "subdomain", "email", "api_token")
        if err:
            return err
        return _request(
            "GET",
            f"https://{profile['subdomain']}.zendesk.com/api/v2/search.json",
            auth=_basic_auth(f"{profile['email']}/token", profile["api_token"]),
            params={"query": query},
        )

    zendesk_search.__name__ = "zendesk_search"
    tools.append(
        _attach(
            zendesk_search,
            _schema(
                "zendesk_search",
                "Search Zendesk tickets/users/articles.",
                {"query": {"type": "string"}},
                ["query"],
            ),
            caps=["zendesk", "read"],
        )
    )

    def zendesk_get_ticket(ticket_id: int) -> dict[str, Any]:
        profile, err = _profile(secrets, "zendesk", "subdomain", "email", "api_token")
        if err:
            return err
        return _request(
            "GET",
            f"https://{profile['subdomain']}.zendesk.com/api/v2/tickets/{ticket_id}.json",
            auth=_basic_auth(f"{profile['email']}/token", profile["api_token"]),
        )

    zendesk_get_ticket.__name__ = "zendesk_get_ticket"
    tools.append(
        _attach(
            zendesk_get_ticket,
            _schema(
                "zendesk_get_ticket",
                "Read a Zendesk ticket.",
                {"ticket_id": {"type": "integer"}},
                ["ticket_id"],
            ),
            caps=["zendesk", "read"],
        )
    )

    def zendesk_create_ticket(
        subject: str, body: str, requester_email: str = ""
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "zendesk", "subdomain", "email", "api_token")
        if err:
            return err
        ticket: dict[str, Any] = {"subject": subject, "comment": {"body": body}}
        if requester_email:
            ticket["requester"] = {"email": requester_email}
        return _request(
            "POST",
            f"https://{profile['subdomain']}.zendesk.com/api/v2/tickets.json",
            auth=_basic_auth(f"{profile['email']}/token", profile["api_token"]),
            json={"ticket": ticket},
        )

    zendesk_create_ticket.__name__ = "zendesk_create_ticket"
    tools.append(
        _attach(
            zendesk_create_ticket,
            _schema(
                "zendesk_create_ticket",
                "Create a Zendesk ticket. Requires user approval.",
                {
                    "subject": {"type": "string"},
                    "body": {"type": "string"},
                    "requester_email": {"type": "string"},
                },
                ["subject", "body"],
            ),
            approval=True,
            caps=["zendesk", "write"],
        )
    )

    def linear_search_issues(query: str, max_results: int = 10) -> dict[str, Any]:
        profile, err = _profile(secrets, "linear", "api_key")
        if err:
            return err
        gql = (
            "query($term: String!, $first: Int!) {"
            " searchIssues(term: $term, first: $first) {"
            " nodes { identifier title url state { name } assignee { name } } } }"
        )
        return _linear_gql(
            profile["api_key"], gql, {"term": query, "first": _clamp(max_results)}
        )

    linear_search_issues.__name__ = "linear_search_issues"
    tools.append(
        _attach(
            linear_search_issues,
            _schema(
                "linear_search_issues",
                "Search Linear issues by text.",
                {"query": {"type": "string"}, "max_results": {"type": "integer"}},
                ["query"],
            ),
            caps=["linear", "read"],
        )
    )

    def linear_get_issue(issue_id: str) -> dict[str, Any]:
        profile, err = _profile(secrets, "linear", "api_key")
        if err:
            return err
        gql = (
            "query($id: String!) { issue(id: $id) {"
            " identifier title description url state { name } assignee { name }"
            " comments { nodes { body user { name } } } } }"
        )
        return _linear_gql(profile["api_key"], gql, {"id": issue_id})

    linear_get_issue.__name__ = "linear_get_issue"
    tools.append(
        _attach(
            linear_get_issue,
            _schema(
                "linear_get_issue",
                "Read a Linear issue (with comments) by ID or key like ENG-123.",
                {"issue_id": {"type": "string"}},
                ["issue_id"],
            ),
            caps=["linear", "read"],
        )
    )

    def linear_list_teams() -> dict[str, Any]:
        profile, err = _profile(secrets, "linear", "api_key")
        if err:
            return err
        return _linear_gql(
            profile["api_key"], "{ teams { nodes { id key name } } }", {}
        )

    linear_list_teams.__name__ = "linear_list_teams"
    tools.append(
        _attach(
            linear_list_teams,
            _schema(
                "linear_list_teams",
                "List Linear teams (IDs are needed to create issues).",
                {},
                [],
            ),
            caps=["linear", "read"],
        )
    )

    def linear_create_issue(
        team_id: str, title: str, description: str = ""
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "linear", "api_key")
        if err:
            return err
        gql = (
            "mutation($input: IssueCreateInput!) { issueCreate(input: $input) {"
            " success issue { identifier url } } }"
        )
        return _linear_gql(
            profile["api_key"],
            gql,
            {"input": {"teamId": team_id, "title": title, "description": description}},
        )

    linear_create_issue.__name__ = "linear_create_issue"
    tools.append(
        _attach(
            linear_create_issue,
            _schema(
                "linear_create_issue",
                "Create a Linear issue. Get team_id from linear_list_teams. Requires user approval.",
                {
                    "team_id": {"type": "string"},
                    "title": {"type": "string"},
                    "description": {"type": "string"},
                },
                ["team_id", "title"],
            ),
            approval=True,
            caps=["linear", "write"],
        )
    )

    def gitlab_search(
        query: str, scope: str = "issues", max_results: int = 10
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "gitlab", "token")
        if err:
            return err
        kind = scope if scope in ("projects", "issues", "merge_requests") else "issues"
        return _request(
            "GET",
            f"{_gitlab_api(profile)}/search",
            headers={"PRIVATE-TOKEN": profile["token"]},
            params={"scope": kind, "search": query, "per_page": _clamp(max_results)},
        )

    gitlab_search.__name__ = "gitlab_search"
    tools.append(
        _attach(
            gitlab_search,
            _schema(
                "gitlab_search",
                "Search GitLab projects, issues, or merge_requests (scope).",
                {
                    "query": {"type": "string"},
                    "scope": {"type": "string"},
                    "max_results": {"type": "integer"},
                },
                ["query"],
            ),
            caps=["gitlab", "read"],
        )
    )

    def gitlab_get_issue(project: str, issue_iid: int) -> dict[str, Any]:
        profile, err = _profile(secrets, "gitlab", "token")
        if err:
            return err
        return _request(
            "GET",
            f"{_gitlab_api(profile)}/projects/{quote(project, safe='')}/issues/{issue_iid}",
            headers={"PRIVATE-TOKEN": profile["token"]},
        )

    gitlab_get_issue.__name__ = "gitlab_get_issue"
    tools.append(
        _attach(
            gitlab_get_issue,
            _schema(
                "gitlab_get_issue",
                "Read a GitLab issue. project is an ID or full path like group/repo.",
                {"project": {"type": "string"}, "issue_iid": {"type": "integer"}},
                ["project", "issue_iid"],
            ),
            caps=["gitlab", "read"],
        )
    )

    def gitlab_get_merge_request(project: str, mr_iid: int) -> dict[str, Any]:
        profile, err = _profile(secrets, "gitlab", "token")
        if err:
            return err
        return _request(
            "GET",
            f"{_gitlab_api(profile)}/projects/{quote(project, safe='')}/merge_requests/{mr_iid}",
            headers={"PRIVATE-TOKEN": profile["token"]},
        )

    gitlab_get_merge_request.__name__ = "gitlab_get_merge_request"
    tools.append(
        _attach(
            gitlab_get_merge_request,
            _schema(
                "gitlab_get_merge_request",
                "Read a GitLab merge request. project is an ID or full path like group/repo.",
                {"project": {"type": "string"}, "mr_iid": {"type": "integer"}},
                ["project", "mr_iid"],
            ),
            caps=["gitlab", "read"],
        )
    )

    def gitlab_create_issue(
        project: str, title: str, description: str = ""
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "gitlab", "token")
        if err:
            return err
        return _request(
            "POST",
            f"{_gitlab_api(profile)}/projects/{quote(project, safe='')}/issues",
            headers={"PRIVATE-TOKEN": profile["token"]},
            json={"title": title, "description": description},
        )

    gitlab_create_issue.__name__ = "gitlab_create_issue"
    tools.append(
        _attach(
            gitlab_create_issue,
            _schema(
                "gitlab_create_issue",
                "Create a GitLab issue. Requires user approval.",
                {
                    "project": {"type": "string"},
                    "title": {"type": "string"},
                    "description": {"type": "string"},
                },
                ["project", "title"],
            ),
            approval=True,
            caps=["gitlab", "write"],
        )
    )

    def discord_list_channels(guild_id: str) -> dict[str, Any]:
        profile, err = _profile(secrets, "discord", "bot_token")
        if err:
            return err
        return _request(
            "GET",
            f"https://discord.com/api/v10/guilds/{guild_id}/channels",
            headers={"Authorization": f"Bot {profile['bot_token']}"},
        )

    discord_list_channels.__name__ = "discord_list_channels"
    tools.append(
        _attach(
            discord_list_channels,
            _schema(
                "discord_list_channels",
                "List channels in a Discord server (guild).",
                {"guild_id": {"type": "string"}},
                ["guild_id"],
            ),
            caps=["discord", "read"],
        )
    )

    def discord_read_messages(channel_id: str, max_results: int = 10) -> dict[str, Any]:
        profile, err = _profile(secrets, "discord", "bot_token")
        if err:
            return err
        return _request(
            "GET",
            f"https://discord.com/api/v10/channels/{channel_id}/messages",
            headers={"Authorization": f"Bot {profile['bot_token']}"},
            params={"limit": _clamp(max_results, ceiling=50)},
        )

    discord_read_messages.__name__ = "discord_read_messages"
    tools.append(
        _attach(
            discord_read_messages,
            _schema(
                "discord_read_messages",
                "Read recent messages from a Discord channel.",
                {"channel_id": {"type": "string"}, "max_results": {"type": "integer"}},
                ["channel_id"],
            ),
            caps=["discord", "read"],
        )
    )

    def discord_send_message(channel_id: str, content: str) -> dict[str, Any]:
        profile, err = _profile(secrets, "discord", "bot_token")
        if err:
            return err
        return _request(
            "POST",
            f"https://discord.com/api/v10/channels/{channel_id}/messages",
            headers={"Authorization": f"Bot {profile['bot_token']}"},
            json={"content": content[:2000]},
        )

    discord_send_message.__name__ = "discord_send_message"
    tools.append(
        _attach(
            discord_send_message,
            _schema(
                "discord_send_message",
                "Send a message to a Discord channel. Requires user approval.",
                {"channel_id": {"type": "string"}, "content": {"type": "string"}},
                ["channel_id", "content"],
            ),
            approval=True,
            caps=["discord", "write"],
        )
    )

    def stripe_search_customers(query: str, max_results: int = 10) -> dict[str, Any]:
        profile, err = _profile(secrets, "stripe", "api_key")
        if err:
            return err
        return _request(
            "GET",
            "https://api.stripe.com/v1/customers/search",
            headers=_bearer_headers(profile["api_key"]),
            params={"query": query, "limit": _clamp(max_results)},
        )

    stripe_search_customers.__name__ = "stripe_search_customers"
    tools.append(
        _attach(
            stripe_search_customers,
            _schema(
                "stripe_search_customers",
                "Search Stripe customers. Query uses Stripe search syntax, e.g. email:'jane@example.com' or name~'Jane'.",
                {"query": {"type": "string"}, "max_results": {"type": "integer"}},
                ["query"],
            ),
            caps=["stripe", "read"],
        )
    )

    def stripe_list_charges(
        customer_id: str = "", max_results: int = 10
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "stripe", "api_key")
        if err:
            return err
        params: dict[str, Any] = {"limit": _clamp(max_results)}
        if customer_id:
            params["customer"] = customer_id
        return _request(
            "GET",
            "https://api.stripe.com/v1/charges",
            headers=_bearer_headers(profile["api_key"]),
            params=params,
        )

    stripe_list_charges.__name__ = "stripe_list_charges"
    tools.append(
        _attach(
            stripe_list_charges,
            _schema(
                "stripe_list_charges",
                "List Stripe charges, optionally for one customer.",
                {"customer_id": {"type": "string"}, "max_results": {"type": "integer"}},
                [],
            ),
            caps=["stripe", "read"],
        )
    )

    def stripe_list_invoices(
        customer_id: str = "", max_results: int = 10
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "stripe", "api_key")
        if err:
            return err
        params: dict[str, Any] = {"limit": _clamp(max_results)}
        if customer_id:
            params["customer"] = customer_id
        return _request(
            "GET",
            "https://api.stripe.com/v1/invoices",
            headers=_bearer_headers(profile["api_key"]),
            params=params,
        )

    stripe_list_invoices.__name__ = "stripe_list_invoices"
    tools.append(
        _attach(
            stripe_list_invoices,
            _schema(
                "stripe_list_invoices",
                "List Stripe invoices, optionally for one customer.",
                {"customer_id": {"type": "string"}, "max_results": {"type": "integer"}},
                [],
            ),
            caps=["stripe", "read"],
        )
    )

    def asana_list_workspaces() -> dict[str, Any]:
        profile, err = _profile(secrets, "asana", "token")
        if err:
            return err
        return _request(
            "GET",
            "https://app.asana.com/api/1.0/workspaces",
            headers=_bearer_headers(profile["token"]),
        )

    asana_list_workspaces.__name__ = "asana_list_workspaces"
    tools.append(
        _attach(
            asana_list_workspaces,
            _schema(
                "asana_list_workspaces",
                "List Asana workspaces (GIDs are needed to search tasks).",
                {},
                [],
            ),
            caps=["asana", "read"],
        )
    )

    def asana_search_tasks(
        workspace_gid: str, query: str, max_results: int = 10
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "asana", "token")
        if err:
            return err
        return _request(
            "GET",
            f"https://app.asana.com/api/1.0/workspaces/{workspace_gid}/typeahead",
            headers=_bearer_headers(profile["token"]),
            params={
                "resource_type": "task",
                "query": query,
                "count": _clamp(max_results),
            },
        )

    asana_search_tasks.__name__ = "asana_search_tasks"
    tools.append(
        _attach(
            asana_search_tasks,
            _schema(
                "asana_search_tasks",
                "Search Asana tasks by name in a workspace. Get workspace_gid from asana_list_workspaces.",
                {
                    "workspace_gid": {"type": "string"},
                    "query": {"type": "string"},
                    "max_results": {"type": "integer"},
                },
                ["workspace_gid", "query"],
            ),
            caps=["asana", "read"],
        )
    )

    def asana_get_task(task_gid: str) -> dict[str, Any]:
        profile, err = _profile(secrets, "asana", "token")
        if err:
            return err
        return _request(
            "GET",
            f"https://app.asana.com/api/1.0/tasks/{task_gid}",
            headers=_bearer_headers(profile["token"]),
        )

    asana_get_task.__name__ = "asana_get_task"
    tools.append(
        _attach(
            asana_get_task,
            _schema(
                "asana_get_task",
                "Read an Asana task.",
                {"task_gid": {"type": "string"}},
                ["task_gid"],
            ),
            caps=["asana", "read"],
        )
    )

    def asana_create_task(
        project_gid: str, name: str, notes: str = ""
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "asana", "token")
        if err:
            return err
        return _request(
            "POST",
            "https://app.asana.com/api/1.0/tasks",
            headers=_bearer_headers(profile["token"]),
            json={"data": {"name": name, "notes": notes, "projects": [project_gid]}},
        )

    asana_create_task.__name__ = "asana_create_task"
    tools.append(
        _attach(
            asana_create_task,
            _schema(
                "asana_create_task",
                "Create an Asana task in a project. Requires user approval.",
                {
                    "project_gid": {"type": "string"},
                    "name": {"type": "string"},
                    "notes": {"type": "string"},
                },
                ["project_gid", "name"],
            ),
            approval=True,
            caps=["asana", "write"],
        )
    )

    _PORTAL_PROP = {
        "type": "string",
        "description": "Portal (hub id or name) to use; omit for the default portal.",
    }
    _HS_KINDS = ("contacts", "companies", "deals", "tickets")

    def hubspot_search(
        query: str = "",
        object_type: str = "contacts",
        max_results: int = 10,
        properties: str = "",
        filters: str = "",
        portal: str = "",
    ) -> dict[str, Any]:
        name, token, err = _hubspot_profile(secrets, portal)
        if err:
            return err
        kind = object_type if object_type in _HS_KINDS else "contacts"
        # The search API only returns HubSpot's default properties unless asked,
        # and free-text `query` never matches custom properties — so property
        # filters are the only way to select on them (e.g. an "org_type" field).
        body: dict[str, Any] = {"limit": _clamp(max_results, ceiling=100)}
        if query:
            body["query"] = query
        if properties:
            body["properties"] = [p.strip() for p in properties.split(",") if p.strip()]
        if filters:
            try:
                parsed = json.loads(filters)
            except ValueError:
                return {"error": "filters must be a JSON array of filter objects"}
            if not isinstance(parsed, list) or not all(
                isinstance(f, dict) and f.get("property") and f.get("operator")
                for f in parsed
            ):
                return {"error": "each filter needs at least 'property' and 'operator'"}
            body["filterGroups"] = [{"filters": parsed}]
        if not query and not filters:
            return {"error": "provide a query, filters, or both"}
        result = _request(
            "POST",
            f"https://api.hubapi.com/crm/v3/objects/{kind}/search",
            headers=_bearer_headers(token),
            json=body,
        )
        return _hubspot_result(secrets, name, result)

    hubspot_search.__name__ = "hubspot_search"
    tools.append(
        _attach(
            hubspot_search,
            _schema(
                "hubspot_search",
                "Search HubSpot CRM contacts, companies, deals, or tickets (object_type). "
                "Custom properties are only returned if named in `properties`, and only "
                "matchable via `filters` (free-text query searches default fields only).",
                {
                    "query": {"type": "string", "description": "Free-text search"},
                    "object_type": {"type": "string"},
                    "max_results": {"type": "integer"},
                    "properties": {
                        "type": "string",
                        "description": "Comma-separated property names to return "
                        "(include custom properties here)",
                    },
                    "filters": {
                        "type": "string",
                        "description": 'JSON array of {"property", "operator", "value"} '
                        "objects, ANDed together. Operators: EQ, NEQ, LT, LTE, GT, GTE, "
                        "CONTAINS_TOKEN, HAS_PROPERTY, NOT_HAS_PROPERTY, IN",
                    },
                    "portal": _PORTAL_PROP,
                },
                [],
            ),
            caps=["hubspot", "read"],
        )
    )

    def hubspot_get_object(
        object_type: str,
        object_id: str,
        properties: str = "",
        associations: str = "",
        portal: str = "",
    ) -> dict[str, Any]:
        name, token, err = _hubspot_profile(secrets, portal)
        if err:
            return err
        kind = object_type if object_type in _HS_KINDS else "contacts"
        params: dict[str, Any] = {}
        if properties:
            params["properties"] = properties  # API takes the comma string as-is
        if associations:
            params["associations"] = associations
        result = _request(
            "GET",
            f"https://api.hubapi.com/crm/v3/objects/{kind}/{object_id}",
            headers=_bearer_headers(token),
            params=params or None,
        )
        return _hubspot_result(secrets, name, result)

    hubspot_get_object.__name__ = "hubspot_get_object"
    tools.append(
        _attach(
            hubspot_get_object,
            _schema(
                "hubspot_get_object",
                "Read a HubSpot CRM record by ID. Custom properties are only "
                "returned if named in `properties`; pass `associations` to also get "
                "linked record ids.",
                {
                    "object_type": {"type": "string"},
                    "object_id": {"type": "string"},
                    "properties": {
                        "type": "string",
                        "description": "Comma-separated property names to return",
                    },
                    "associations": {
                        "type": "string",
                        "description": "Comma-separated object types to return "
                        "associated ids for (e.g. companies,contacts)",
                    },
                    "portal": _PORTAL_PROP,
                },
                ["object_type", "object_id"],
            ),
            caps=["hubspot", "read"],
        )
    )

    def hubspot_create_contact(
        email: str, first_name: str = "", last_name: str = "", portal: str = ""
    ) -> dict[str, Any]:
        name, token, err = _hubspot_profile(secrets, portal)
        if err:
            return err
        props = {"email": email}
        if first_name:
            props["firstname"] = first_name
        if last_name:
            props["lastname"] = last_name
        result = _request(
            "POST",
            "https://api.hubapi.com/crm/v3/objects/contacts",
            headers=_bearer_headers(token),
            json={"properties": props},
        )
        return _hubspot_result(secrets, name, result)

    hubspot_create_contact.__name__ = "hubspot_create_contact"
    tools.append(
        _attach(
            hubspot_create_contact,
            _schema(
                "hubspot_create_contact",
                "Create a HubSpot contact. Requires user approval; the `portal` "
                "argument names the portal on the approval card.",
                {
                    "email": {"type": "string"},
                    "first_name": {"type": "string"},
                    "last_name": {"type": "string"},
                    "portal": _PORTAL_PROP,
                },
                ["email"],
            ),
            approval=True,
            caps=["hubspot", "write"],
        )
    )

    def hubspot_update_object(
        object_type: str, object_id: str, properties: dict, portal: str = ""
    ) -> dict[str, Any]:
        name, token, err = _hubspot_profile(secrets, portal)
        if err:
            return err
        kind = object_type if object_type in _HS_KINDS else "contacts"
        if not isinstance(properties, dict) or not properties:
            return {"error": "properties must be a non-empty object"}
        result = _request(
            "PATCH",
            f"https://api.hubapi.com/crm/v3/objects/{kind}/{object_id}",
            headers=_bearer_headers(token),
            json={"properties": properties},
        )
        return _hubspot_result(secrets, name, result)

    hubspot_update_object.__name__ = "hubspot_update_object"
    tools.append(
        _attach(
            hubspot_update_object,
            _schema(
                "hubspot_update_object",
                "Update properties on a HubSpot CRM record (no deletes exist). "
                "Requires user approval.",
                {
                    "object_type": {"type": "string"},
                    "object_id": {"type": "string"},
                    "properties": {"type": "object"},
                    "portal": _PORTAL_PROP,
                },
                ["object_type", "object_id", "properties"],
            ),
            approval=True,
            caps=["hubspot", "write"],
        )
    )

    def hubspot_log_note(
        object_type: str, object_id: str, note: str, portal: str = ""
    ) -> dict[str, Any]:
        name, token, err = _hubspot_profile(secrets, portal)
        if err:
            return err
        kind = object_type if object_type in _HS_KINDS else "contacts"
        # Note engagement associated to the record (association type ids are
        # HubSpot-defined per object; v4 default associations handle the rest).
        result = _request(
            "POST",
            "https://api.hubapi.com/crm/v3/objects/notes",
            headers=_bearer_headers(token),
            json={
                "properties": {
                    "hs_note_body": note,
                    "hs_timestamp": _now_ms(),
                },
                "associations": [
                    {
                        "to": {"id": object_id},
                        "types": [
                            {
                                "associationCategory": "HUBSPOT_DEFINED",
                                "associationTypeId": _HS_NOTE_ASSOC[kind],
                            }
                        ],
                    }
                ],
            },
        )
        return _hubspot_result(secrets, name, result)

    hubspot_log_note.__name__ = "hubspot_log_note"
    tools.append(
        _attach(
            hubspot_log_note,
            _schema(
                "hubspot_log_note",
                "Log a note on a HubSpot record's timeline. Requires user approval.",
                {
                    "object_type": {"type": "string"},
                    "object_id": {"type": "string"},
                    "note": {"type": "string"},
                    "portal": _PORTAL_PROP,
                },
                ["object_type", "object_id", "note"],
            ),
            approval=True,
            caps=["hubspot", "write"],
        )
    )

    def hubspot_create_task(
        title: str, due: str = "", notes: str = "", portal: str = ""
    ) -> dict[str, Any]:
        name, token, err = _hubspot_profile(secrets, portal)
        if err:
            return err
        props: dict[str, Any] = {
            "hs_task_subject": title,
            "hs_task_status": "NOT_STARTED",
            "hs_timestamp": due or _now_ms(),
        }
        if notes:
            props["hs_task_body"] = notes
        result = _request(
            "POST",
            "https://api.hubapi.com/crm/v3/objects/tasks",
            headers=_bearer_headers(token),
            json={"properties": props},
        )
        return _hubspot_result(secrets, name, result)

    hubspot_create_task.__name__ = "hubspot_create_task"
    tools.append(
        _attach(
            hubspot_create_task,
            _schema(
                "hubspot_create_task",
                "Create a HubSpot task (due = epoch ms or ISO date). Requires user approval.",
                {
                    "title": {"type": "string"},
                    "due": {"type": "string"},
                    "notes": {"type": "string"},
                    "portal": _PORTAL_PROP,
                },
                ["title"],
            ),
            approval=True,
            caps=["hubspot", "write"],
        )
    )

    def _dropbox_path(path: str) -> str:
        path = (path or "").strip()
        if path and not path.startswith("/"):
            path = "/" + path
        return path

    def dropbox_search(query: str, max_results: int = 10) -> dict[str, Any]:
        profile, err = _profile(secrets, "dropbox", "access_token")
        if err:
            return err
        return _request(
            "POST",
            "https://api.dropboxapi.com/2/files/search_v2",
            headers=_bearer_headers(profile["access_token"]),
            json={"query": query, "options": {"max_results": _clamp(max_results)}},
        )

    dropbox_search.__name__ = "dropbox_search"
    tools.append(
        _attach(
            dropbox_search,
            _schema(
                "dropbox_search",
                "Search Dropbox files and folders by name/content.",
                {"query": {"type": "string"}, "max_results": {"type": "integer"}},
                ["query"],
            ),
            caps=["dropbox", "read"],
        )
    )

    def dropbox_list_folder(path: str = "") -> dict[str, Any]:
        profile, err = _profile(secrets, "dropbox", "access_token")
        if err:
            return err
        return _request(
            "POST",
            "https://api.dropboxapi.com/2/files/list_folder",
            headers=_bearer_headers(profile["access_token"]),
            json={"path": _dropbox_path(path)},
        )

    dropbox_list_folder.__name__ = "dropbox_list_folder"
    tools.append(
        _attach(
            dropbox_list_folder,
            _schema(
                "dropbox_list_folder",
                "List a Dropbox folder. Empty path is the root.",
                {"path": {"type": "string"}},
                [],
            ),
            caps=["dropbox", "read"],
        )
    )

    def dropbox_read_file(path: str, max_chars: int = 20000) -> dict[str, Any]:
        profile, err = _profile(secrets, "dropbox", "access_token")
        if err:
            return err
        out = _request(
            "POST",
            "https://content.dropboxapi.com/2/files/download",
            headers={
                "Authorization": f"Bearer {profile['access_token']}",
                "Dropbox-API-Arg": json.dumps({"path": _dropbox_path(path)}),
            },
        )
        if "error" in out:
            return out
        text = out["data"] if isinstance(out["data"], str) else str(out["data"])
        cap = max(1, min(int(max_chars or 20000), 100000))
        return {"path": path, "text": text[:cap], "truncated": len(text) > cap}

    dropbox_read_file.__name__ = "dropbox_read_file"
    tools.append(
        _attach(
            dropbox_read_file,
            _schema(
                "dropbox_read_file",
                "Read a text file from Dropbox by path.",
                {"path": {"type": "string"}, "max_chars": {"type": "integer"}},
                ["path"],
            ),
            caps=["dropbox", "read"],
        )
    )

    def box_search(query: str, max_results: int = 10) -> dict[str, Any]:
        profile, err = _profile(secrets, "box", "access_token")
        if err:
            return err
        return _request(
            "GET",
            "https://api.box.com/2.0/search",
            headers=_bearer_headers(profile["access_token"]),
            params={"query": query, "limit": _clamp(max_results)},
        )

    box_search.__name__ = "box_search"
    tools.append(
        _attach(
            box_search,
            _schema(
                "box_search",
                "Search Box files and folders.",
                {"query": {"type": "string"}, "max_results": {"type": "integer"}},
                ["query"],
            ),
            caps=["box", "read"],
        )
    )

    def box_list_folder(folder_id: str = "0") -> dict[str, Any]:
        profile, err = _profile(secrets, "box", "access_token")
        if err:
            return err
        return _request(
            "GET",
            f"https://api.box.com/2.0/folders/{folder_id}/items",
            headers=_bearer_headers(profile["access_token"]),
        )

    box_list_folder.__name__ = "box_list_folder"
    tools.append(
        _attach(
            box_list_folder,
            _schema(
                "box_list_folder",
                "List items in a Box folder. Folder '0' is the root.",
                {"folder_id": {"type": "string"}},
                [],
            ),
            caps=["box", "read"],
        )
    )

    def box_read_file(file_id: str, max_chars: int = 20000) -> dict[str, Any]:
        profile, err = _profile(secrets, "box", "access_token")
        if err:
            return err
        out = _request(
            "GET",
            f"https://api.box.com/2.0/files/{file_id}/content",
            headers=_bearer_headers(profile["access_token"]),
        )
        if "error" in out:
            return out
        text = out["data"] if isinstance(out["data"], str) else str(out["data"])
        cap = max(1, min(int(max_chars or 20000), 100000))
        return {"file_id": file_id, "text": text[:cap], "truncated": len(text) > cap}

    box_read_file.__name__ = "box_read_file"
    tools.append(
        _attach(
            box_read_file,
            _schema(
                "box_read_file",
                "Read a text file from Box by file ID.",
                {"file_id": {"type": "string"}, "max_chars": {"type": "integer"}},
                ["file_id"],
            ),
            caps=["box", "read"],
        )
    )

    def quickbooks_query(query: str, max_results: int = 10) -> dict[str, Any]:
        profile, err = _profile(secrets, "quickbooks", "access_token", "realm_id")
        if err:
            return err
        q = query.strip()
        if "maxresults" not in q.lower():
            q = f"{q} MAXRESULTS {_clamp(max_results, ceiling=100)}"
        return _request(
            "GET",
            f"{_qbo_base(profile)}/query",
            headers=_bearer_headers(profile["access_token"]),
            params={"query": q},
        )

    quickbooks_query.__name__ = "quickbooks_query"
    tools.append(
        _attach(
            quickbooks_query,
            _schema(
                "quickbooks_query",
                "Run a QuickBooks Online query, e.g. \"SELECT * FROM Invoice WHERE TotalAmt > '100'\". "
                "Entities include Customer, Invoice, Bill, Payment, Account, Vendor.",
                {"query": {"type": "string"}, "max_results": {"type": "integer"}},
                ["query"],
            ),
            caps=["quickbooks", "read"],
        )
    )

    def quickbooks_list_customers(max_results: int = 10) -> dict[str, Any]:
        profile, err = _profile(secrets, "quickbooks", "access_token", "realm_id")
        if err:
            return err
        return _request(
            "GET",
            f"{_qbo_base(profile)}/query",
            headers=_bearer_headers(profile["access_token"]),
            params={
                "query": f"SELECT * FROM Customer MAXRESULTS {_clamp(max_results)}"
            },
        )

    quickbooks_list_customers.__name__ = "quickbooks_list_customers"
    tools.append(
        _attach(
            quickbooks_list_customers,
            _schema(
                "quickbooks_list_customers",
                "List QuickBooks customers.",
                {"max_results": {"type": "integer"}},
                [],
            ),
            caps=["quickbooks", "read"],
        )
    )

    def quickbooks_list_invoices(max_results: int = 10) -> dict[str, Any]:
        profile, err = _profile(secrets, "quickbooks", "access_token", "realm_id")
        if err:
            return err
        return _request(
            "GET",
            f"{_qbo_base(profile)}/query",
            headers=_bearer_headers(profile["access_token"]),
            params={
                "query": "SELECT * FROM Invoice ORDERBY TxnDate DESC "
                f"MAXRESULTS {_clamp(max_results)}"
            },
        )

    quickbooks_list_invoices.__name__ = "quickbooks_list_invoices"
    tools.append(
        _attach(
            quickbooks_list_invoices,
            _schema(
                "quickbooks_list_invoices",
                "List recent QuickBooks invoices.",
                {"max_results": {"type": "integer"}},
                [],
            ),
            caps=["quickbooks", "read"],
        )
    )

    def quickbooks_get_report(
        report: str, start_date: str = "", end_date: str = ""
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "quickbooks", "access_token", "realm_id")
        if err:
            return err
        params: dict[str, Any] = {}
        if start_date:
            params["start_date"] = start_date
        if end_date:
            params["end_date"] = end_date
        return _request(
            "GET",
            f"{_qbo_base(profile)}/reports/{quote(report, safe='')}",
            headers=_bearer_headers(profile["access_token"]),
            params=params or None,
        )

    quickbooks_get_report.__name__ = "quickbooks_get_report"
    tools.append(
        _attach(
            quickbooks_get_report,
            _schema(
                "quickbooks_get_report",
                "Run a QuickBooks report such as ProfitAndLoss, BalanceSheet, CashFlow, "
                "AgedReceivables. Dates are YYYY-MM-DD.",
                {
                    "report": {"type": "string"},
                    "start_date": {"type": "string"},
                    "end_date": {"type": "string"},
                },
                ["report"],
            ),
            caps=["quickbooks", "read"],
        )
    )

    def whatsapp_send_message(to: str, text: str) -> dict[str, Any]:
        profile, err = _profile(secrets, "whatsapp", "access_token", "phone_number_id")
        if err:
            return err
        return _request(
            "POST",
            f"https://graph.facebook.com/v21.0/{profile['phone_number_id']}/messages",
            headers=_bearer_headers(profile["access_token"]),
            json={
                "messaging_product": "whatsapp",
                "to": to,
                "type": "text",
                "text": {"body": text[:4096]},
            },
        )

    whatsapp_send_message.__name__ = "whatsapp_send_message"
    tools.append(
        _attach(
            whatsapp_send_message,
            _schema(
                "whatsapp_send_message",
                "Send a WhatsApp text message. Only delivered if the recipient messaged "
                "this number within the last 24 hours; otherwise use "
                "whatsapp_send_template. Requires user approval.",
                {"to": {"type": "string"}, "text": {"type": "string"}},
                ["to", "text"],
            ),
            approval=True,
            caps=["whatsapp", "write"],
        )
    )

    def whatsapp_send_template(
        to: str, template_name: str, language_code: str = "en_US"
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "whatsapp", "access_token", "phone_number_id")
        if err:
            return err
        return _request(
            "POST",
            f"https://graph.facebook.com/v21.0/{profile['phone_number_id']}/messages",
            headers=_bearer_headers(profile["access_token"]),
            json={
                "messaging_product": "whatsapp",
                "to": to,
                "type": "template",
                "template": {
                    "name": template_name,
                    "language": {"code": language_code},
                },
            },
        )

    whatsapp_send_template.__name__ = "whatsapp_send_template"
    tools.append(
        _attach(
            whatsapp_send_template,
            _schema(
                "whatsapp_send_template",
                "Send a pre-approved WhatsApp template message (works outside the "
                "24-hour service window). Requires user approval.",
                {
                    "to": {"type": "string"},
                    "template_name": {"type": "string"},
                    "language_code": {"type": "string"},
                },
                ["to", "template_name"],
            ),
            approval=True,
            caps=["whatsapp", "write"],
        )
    )

    # -- notion (managed OAuth or integration token, multi-workspace) --

    def _notion_headers(profile: dict[str, Any]) -> dict[str, str]:
        return {
            "Authorization": f"Bearer {profile['access_token']}",
            "Notion-Version": "2022-06-28",
        }

    def _notion_blocks_text(blocks: list[dict]) -> str:
        """Flatten block children to readable lines (rich_text plain_text)."""
        lines = []
        for b in blocks:
            content = b.get(b.get("type", ""), {})
            texts = content.get("rich_text") or content.get("title") or []
            line = "".join(
                t.get("plain_text", "") for t in texts if isinstance(t, dict)
            )
            if line:
                lines.append(line)
        return "\n".join(lines)

    def notion_search(
        query: str, max_results: int = 10, account: str = ""
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(secrets, "notion", account, "access_token")
        if err:
            return err
        result = _request(
            "POST",
            "https://api.notion.com/v1/search",
            headers=_notion_headers(profile),
            json={"query": query, "page_size": _clamp(max_results, ceiling=100)},
        )
        return _acct_result(aid, result)

    notion_search.__name__ = "notion_search"
    tools.append(
        _attach(
            notion_search,
            _schema(
                "notion_search",
                "Search Notion pages and databases the integration can see.",
                {
                    "query": {"type": "string"},
                    "max_results": {"type": "integer"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                ["query"],
            ),
            caps=["notion", "read"],
        )
    )

    def notion_read_page(page_id: str, account: str = "") -> dict[str, Any]:
        aid, profile, err = _account_profile(secrets, "notion", account, "access_token")
        if err:
            return err
        page = _request(
            "GET",
            f"https://api.notion.com/v1/pages/{page_id}",
            headers=_notion_headers(profile),
        )
        if "error" in page:
            return _acct_result(aid, page)
        blocks = _request(
            "GET",
            f"https://api.notion.com/v1/blocks/{page_id}/children",
            headers=_notion_headers(profile),
            params={"page_size": 100},
        )
        text = (
            _notion_blocks_text((blocks.get("data") or {}).get("results") or [])
            if "error" not in blocks
            else ""
        )
        return _acct_result(
            aid,
            {
                "ok": True,
                "properties": (page.get("data") or {}).get("properties"),
                "url": (page.get("data") or {}).get("url"),
                "text": text,
            },
        )

    notion_read_page.__name__ = "notion_read_page"
    tools.append(
        _attach(
            notion_read_page,
            _schema(
                "notion_read_page",
                "Read a Notion page: properties plus its content flattened to text.",
                {"page_id": {"type": "string"}, "account": _GEN_ACCOUNT_PROP},
                ["page_id"],
            ),
            caps=["notion", "read"],
        )
    )

    def notion_query_database(
        database_id: str,
        filter_json: str = "",
        max_results: int = 10,
        account: str = "",
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(secrets, "notion", account, "access_token")
        if err:
            return err
        body: dict[str, Any] = {"page_size": _clamp(max_results, ceiling=100)}
        if filter_json:
            try:
                body["filter"] = json.loads(filter_json)
            except ValueError:
                return {"error": "filter_json must be a Notion filter object (JSON)"}
        result = _request(
            "POST",
            f"https://api.notion.com/v1/databases/{database_id}/query",
            headers=_notion_headers(profile),
            json=body,
        )
        return _acct_result(aid, result)

    notion_query_database.__name__ = "notion_query_database"
    tools.append(
        _attach(
            notion_query_database,
            _schema(
                "notion_query_database",
                "Query a Notion database, optionally with a Notion filter object.",
                {
                    "database_id": {"type": "string"},
                    "filter_json": {"type": "string"},
                    "max_results": {"type": "integer"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                ["database_id"],
            ),
            caps=["notion", "read"],
        )
    )

    def notion_create_page(
        parent_page_id: str, title: str, content: str = "", account: str = ""
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(secrets, "notion", account, "access_token")
        if err:
            return err
        children = [
            {
                "object": "block",
                "type": "paragraph",
                "paragraph": {"rich_text": [{"text": {"content": line}}]},
            }
            for line in content.splitlines()
            if line.strip()
        ]
        result = _request(
            "POST",
            "https://api.notion.com/v1/pages",
            headers=_notion_headers(profile),
            json={
                "parent": {"page_id": parent_page_id},
                "properties": {"title": {"title": [{"text": {"content": title}}]}},
                "children": children,
            },
        )
        return _acct_result(aid, result)

    notion_create_page.__name__ = "notion_create_page"
    tools.append(
        _attach(
            notion_create_page,
            _schema(
                "notion_create_page",
                "Create a Notion page under a parent page (plain-text paragraphs).",
                {
                    "parent_page_id": {"type": "string"},
                    "title": {"type": "string"},
                    "content": {"type": "string"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                ["parent_page_id", "title"],
            ),
            approval=True,
            caps=["notion", "write"],
        )
    )

    # -- attio (managed OAuth or API key, multi-workspace) --

    def attio_list_objects(account: str = "") -> dict[str, Any]:
        aid, profile, err = _account_profile(secrets, "attio", account, "access_token")
        if err:
            return err
        result = _request(
            "GET",
            "https://api.attio.com/v2/objects",
            headers=_bearer_headers(profile["access_token"]),
        )
        return _acct_result(aid, result)

    attio_list_objects.__name__ = "attio_list_objects"
    tools.append(
        _attach(
            attio_list_objects,
            _schema(
                "attio_list_objects",
                "List Attio object types (companies, people, deals, custom).",
                {"account": _GEN_ACCOUNT_PROP},
                [],
            ),
            caps=["attio", "read"],
        )
    )

    def attio_query_records(
        object_type: str,
        filter_json: str = "",
        max_results: int = 10,
        account: str = "",
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(secrets, "attio", account, "access_token")
        if err:
            return err
        body: dict[str, Any] = {"limit": _clamp(max_results, ceiling=100)}
        if filter_json:
            try:
                body["filter"] = json.loads(filter_json)
            except ValueError:
                return {"error": "filter_json must be an Attio filter object (JSON)"}
        result = _request(
            "POST",
            f"https://api.attio.com/v2/objects/{object_type}/records/query",
            headers=_bearer_headers(profile["access_token"]),
            json=body,
        )
        return _acct_result(aid, result)

    attio_query_records.__name__ = "attio_query_records"
    tools.append(
        _attach(
            attio_query_records,
            _schema(
                "attio_query_records",
                "List/filter records of an Attio object (e.g. companies, people); "
                "filter_json is an Attio filter object.",
                {
                    "object_type": {"type": "string"},
                    "filter_json": {"type": "string"},
                    "max_results": {"type": "integer"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                ["object_type"],
            ),
            caps=["attio", "read"],
        )
    )

    def attio_get_record(
        object_type: str, record_id: str, account: str = ""
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(secrets, "attio", account, "access_token")
        if err:
            return err
        result = _request(
            "GET",
            f"https://api.attio.com/v2/objects/{object_type}/records/{record_id}",
            headers=_bearer_headers(profile["access_token"]),
        )
        return _acct_result(aid, result)

    attio_get_record.__name__ = "attio_get_record"
    tools.append(
        _attach(
            attio_get_record,
            _schema(
                "attio_get_record",
                "Read one Attio record by object type and record id.",
                {
                    "object_type": {"type": "string"},
                    "record_id": {"type": "string"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                ["object_type", "record_id"],
            ),
            caps=["attio", "read"],
        )
    )

    def attio_create_note(
        parent_object: str,
        parent_record_id: str,
        title: str,
        content: str,
        account: str = "",
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(secrets, "attio", account, "access_token")
        if err:
            return err
        result = _request(
            "POST",
            "https://api.attio.com/v2/notes",
            headers=_bearer_headers(profile["access_token"]),
            json={
                "data": {
                    "parent_object": parent_object,
                    "parent_record_id": parent_record_id,
                    "title": title,
                    "format": "plaintext",
                    "content": content,
                }
            },
        )
        return _acct_result(aid, result)

    attio_create_note.__name__ = "attio_create_note"
    tools.append(
        _attach(
            attio_create_note,
            _schema(
                "attio_create_note",
                "Log a note on an Attio record (e.g. a company or person).",
                {
                    "parent_object": {"type": "string"},
                    "parent_record_id": {"type": "string"},
                    "title": {"type": "string"},
                    "content": {"type": "string"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                ["parent_object", "parent_record_id", "title", "content"],
            ),
            approval=True,
            caps=["attio", "write"],
        )
    )

    # -- product analytics: posthog / mixpanel / amplitude (manual keys, multi-account) --

    def _posthog_base(profile: dict[str, Any]) -> str:
        return str(profile.get("base_url") or "https://us.posthog.com").rstrip("/")

    def posthog_query(hogql: str, account: str = "") -> dict[str, Any]:
        aid, profile, err = _account_profile(
            secrets, "posthog", account, "api_key", "project_id"
        )
        if err:
            return err
        result = _request(
            "POST",
            f"{_posthog_base(profile)}/api/projects/{profile['project_id']}/query",
            headers=_bearer_headers(profile["api_key"]),
            json={"query": {"kind": "HogQLQuery", "query": hogql}},
        )
        return _acct_result(aid, result)

    posthog_query.__name__ = "posthog_query"
    tools.append(
        _attach(
            posthog_query,
            _schema(
                "posthog_query",
                "Run a HogQL (SQL-like) query against PostHog analytics, e.g. "
                "SELECT event, count() FROM events WHERE timestamp > now() - "
                "INTERVAL 7 DAY GROUP BY event.",
                {"hogql": {"type": "string"}, "account": _GEN_ACCOUNT_PROP},
                ["hogql"],
            ),
            caps=["posthog", "read"],
        )
    )

    def posthog_list_insights(
        query: str = "", max_results: int = 10, account: str = ""
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(
            secrets, "posthog", account, "api_key", "project_id"
        )
        if err:
            return err
        params: dict[str, Any] = {"limit": _clamp(max_results)}
        if query:
            params["search"] = query
        result = _request(
            "GET",
            f"{_posthog_base(profile)}/api/projects/{profile['project_id']}/insights",
            headers=_bearer_headers(profile["api_key"]),
            params=params,
        )
        return _acct_result(aid, result)

    posthog_list_insights.__name__ = "posthog_list_insights"
    tools.append(
        _attach(
            posthog_list_insights,
            _schema(
                "posthog_list_insights",
                "List saved PostHog insights (dashboards' building blocks).",
                {
                    "query": {"type": "string"},
                    "max_results": {"type": "integer"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                [],
            ),
            caps=["posthog", "read"],
        )
    )

    def mixpanel_segmentation(
        event: str,
        from_date: str,
        to_date: str,
        unit: str = "day",
        where: str = "",
        account: str = "",
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(
            secrets, "mixpanel", account, "username", "secret", "project_id"
        )
        if err:
            return err
        params = {
            "project_id": profile["project_id"],
            "event": event,
            "from_date": from_date,
            "to_date": to_date,
            "unit": (
                unit if unit in ("minute", "hour", "day", "week", "month") else "day"
            ),
        }
        if where:
            params["where"] = where
        result = _request(
            "GET",
            "https://mixpanel.com/api/query/segmentation",
            params=params,
            auth=(profile["username"], profile["secret"]),
        )
        return _acct_result(aid, result)

    mixpanel_segmentation.__name__ = "mixpanel_segmentation"
    tools.append(
        _attach(
            mixpanel_segmentation,
            _schema(
                "mixpanel_segmentation",
                "Mixpanel event counts over a date range (YYYY-MM-DD), optionally "
                'filtered by a `where` expression like properties["plan"]=="pro".',
                {
                    "event": {"type": "string"},
                    "from_date": {"type": "string"},
                    "to_date": {"type": "string"},
                    "unit": {"type": "string"},
                    "where": {"type": "string"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                ["event", "from_date", "to_date"],
            ),
            caps=["mixpanel", "read"],
        )
    )

    def mixpanel_top_events(max_results: int = 10, account: str = "") -> dict[str, Any]:
        aid, profile, err = _account_profile(
            secrets, "mixpanel", account, "username", "secret", "project_id"
        )
        if err:
            return err
        result = _request(
            "GET",
            "https://mixpanel.com/api/query/events/top",
            params={
                "project_id": profile["project_id"],
                "type": "general",
                "limit": _clamp(max_results, ceiling=100),
            },
            auth=(profile["username"], profile["secret"]),
        )
        return _acct_result(aid, result)

    mixpanel_top_events.__name__ = "mixpanel_top_events"
    tools.append(
        _attach(
            mixpanel_top_events,
            _schema(
                "mixpanel_top_events",
                "Today's top Mixpanel events by volume.",
                {"max_results": {"type": "integer"}, "account": _GEN_ACCOUNT_PROP},
                [],
            ),
            caps=["mixpanel", "read"],
        )
    )

    def amplitude_active_users(
        start: str, end: str, metric: str = "active", account: str = ""
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(
            secrets, "amplitude", account, "api_key", "secret_key"
        )
        if err:
            return err
        result = _request(
            "GET",
            "https://amplitude.com/api/2/users",
            params={
                "m": metric if metric in ("active", "new") else "active",
                "start": start.replace("-", ""),
                "end": end.replace("-", ""),
                "i": 1,
            },
            auth=(profile["api_key"], profile["secret_key"]),
        )
        return _acct_result(aid, result)

    amplitude_active_users.__name__ = "amplitude_active_users"
    tools.append(
        _attach(
            amplitude_active_users,
            _schema(
                "amplitude_active_users",
                "Amplitude daily active or new users between two dates (YYYYMMDD "
                "or YYYY-MM-DD).",
                {
                    "start": {"type": "string"},
                    "end": {"type": "string"},
                    "metric": {"type": "string", "description": "active | new"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                ["start", "end"],
            ),
            caps=["amplitude", "read"],
        )
    )

    def amplitude_event_totals(
        event_type: str, start: str, end: str, account: str = ""
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(
            secrets, "amplitude", account, "api_key", "secret_key"
        )
        if err:
            return err
        result = _request(
            "GET",
            "https://amplitude.com/api/2/events/segmentation",
            params={
                "e": json.dumps({"event_type": event_type}),
                "start": start.replace("-", ""),
                "end": end.replace("-", ""),
                "m": "totals",
            },
            auth=(profile["api_key"], profile["secret_key"]),
        )
        return _acct_result(aid, result)

    amplitude_event_totals.__name__ = "amplitude_event_totals"
    tools.append(
        _attach(
            amplitude_event_totals,
            _schema(
                "amplitude_event_totals",
                "Daily totals for one Amplitude event between two dates.",
                {
                    "event_type": {"type": "string"},
                    "start": {"type": "string"},
                    "end": {"type": "string"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                ["event_type", "start", "end"],
            ),
            caps=["amplitude", "read"],
        )
    )

    # -- prospecting/enrichment: apollo / hunter (manual keys, multi-account) --

    def _apollo_headers(profile: dict[str, Any]) -> dict[str, str]:
        return {"X-Api-Key": profile["api_key"], "Content-Type": "application/json"}

    def apollo_enrich_person(
        email: str = "", name: str = "", company_domain: str = "", account: str = ""
    ) -> dict[str, Any]:
        if not email and not name:
            return {"error": "provide an email, a name, or both"}
        aid, profile, err = _account_profile(secrets, "apollo", account, "api_key")
        if err:
            return err
        body: dict[str, Any] = {}
        if email:
            body["email"] = email
        if name:
            body["name"] = name
        if company_domain:
            body["domain"] = company_domain
        result = _request(
            "POST",
            "https://api.apollo.io/api/v1/people/match",
            headers=_apollo_headers(profile),
            json=body,
        )
        return _acct_result(aid, result)

    apollo_enrich_person.__name__ = "apollo_enrich_person"
    tools.append(
        _attach(
            apollo_enrich_person,
            _schema(
                "apollo_enrich_person",
                "Enrich a person from Apollo: title, company, LinkedIn, location "
                "— by email and/or name (+ optional company domain).",
                {
                    "email": {"type": "string"},
                    "name": {"type": "string"},
                    "company_domain": {"type": "string"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                [],
            ),
            caps=["apollo", "read"],
        )
    )

    def apollo_enrich_company(domain: str, account: str = "") -> dict[str, Any]:
        aid, profile, err = _account_profile(secrets, "apollo", account, "api_key")
        if err:
            return err
        result = _request(
            "GET",
            "https://api.apollo.io/api/v1/organizations/enrich",
            headers=_apollo_headers(profile),
            params={"domain": domain},
        )
        return _acct_result(aid, result)

    apollo_enrich_company.__name__ = "apollo_enrich_company"
    tools.append(
        _attach(
            apollo_enrich_company,
            _schema(
                "apollo_enrich_company",
                "Enrich a company from Apollo by domain: size, industry, funding, "
                "tech stack.",
                {"domain": {"type": "string"}, "account": _GEN_ACCOUNT_PROP},
                ["domain"],
            ),
            caps=["apollo", "read"],
        )
    )

    def apollo_search_people(
        query: str, max_results: int = 10, account: str = ""
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(secrets, "apollo", account, "api_key")
        if err:
            return err
        result = _request(
            "POST",
            "https://api.apollo.io/api/v1/mixed_people/search",
            headers=_apollo_headers(profile),
            json={"q_keywords": query, "page": 1, "per_page": _clamp(max_results)},
        )
        return _acct_result(aid, result)

    apollo_search_people.__name__ = "apollo_search_people"
    tools.append(
        _attach(
            apollo_search_people,
            _schema(
                "apollo_search_people",
                "Keyword-search people in Apollo's B2B database (e.g. 'VP "
                "engineering fintech Berlin').",
                {
                    "query": {"type": "string"},
                    "max_results": {"type": "integer"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                ["query"],
            ),
            caps=["apollo", "read"],
        )
    )

    def _hunter_get(
        profile: dict[str, Any], path: str, params: dict[str, Any]
    ) -> dict[str, Any]:
        return _request(
            "GET",
            f"https://api.hunter.io/v2/{path}",
            params={**params, "api_key": profile["api_key"]},
        )

    def hunter_domain_search(
        domain: str, max_results: int = 10, account: str = ""
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(secrets, "hunter", account, "api_key")
        if err:
            return err
        result = _hunter_get(
            profile, "domain-search", {"domain": domain, "limit": _clamp(max_results)}
        )
        return _acct_result(aid, result)

    hunter_domain_search.__name__ = "hunter_domain_search"
    tools.append(
        _attach(
            hunter_domain_search,
            _schema(
                "hunter_domain_search",
                "Find published email addresses for a company domain (Hunter).",
                {
                    "domain": {"type": "string"},
                    "max_results": {"type": "integer"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                ["domain"],
            ),
            caps=["hunter", "read"],
        )
    )

    def hunter_find_email(
        domain: str, first_name: str, last_name: str, account: str = ""
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(secrets, "hunter", account, "api_key")
        if err:
            return err
        result = _hunter_get(
            profile,
            "email-finder",
            {"domain": domain, "first_name": first_name, "last_name": last_name},
        )
        return _acct_result(aid, result)

    hunter_find_email.__name__ = "hunter_find_email"
    tools.append(
        _attach(
            hunter_find_email,
            _schema(
                "hunter_find_email",
                "Find a person's most likely email address from their name and "
                "company domain (Hunter).",
                {
                    "domain": {"type": "string"},
                    "first_name": {"type": "string"},
                    "last_name": {"type": "string"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                ["domain", "first_name", "last_name"],
            ),
            caps=["hunter", "read"],
        )
    )

    def hunter_verify_email(email: str, account: str = "") -> dict[str, Any]:
        aid, profile, err = _account_profile(secrets, "hunter", account, "api_key")
        if err:
            return err
        return _acct_result(
            aid, _hunter_get(profile, "email-verifier", {"email": email})
        )

    hunter_verify_email.__name__ = "hunter_verify_email"
    tools.append(
        _attach(
            hunter_verify_email,
            _schema(
                "hunter_verify_email",
                "Check whether an email address is deliverable (Hunter).",
                {"email": {"type": "string"}, "account": _GEN_ACCOUNT_PROP},
                ["email"],
            ),
            caps=["hunter", "read"],
        )
    )

    # --- ClickUp ------------------------------------------------------------

    _CLICKUP = "https://api.clickup.com/api/v2"

    def clickup_list_teams() -> dict[str, Any]:
        profile, err = _profile(secrets, "clickup", "api_token")
        if err:
            return err
        return _request(
            "GET", f"{_CLICKUP}/team", headers={"Authorization": profile["api_token"]}
        )

    clickup_list_teams.__name__ = "clickup_list_teams"
    tools.append(
        _attach(
            clickup_list_teams,
            _schema(
                "clickup_list_teams",
                "List ClickUp workspaces (team ids are needed to browse spaces).",
                {},
                [],
            ),
            caps=["clickup", "read"],
        )
    )

    def clickup_list_spaces(team_id: str) -> dict[str, Any]:
        profile, err = _profile(secrets, "clickup", "api_token")
        if err:
            return err
        return _request(
            "GET",
            f"{_CLICKUP}/team/{quote(team_id)}/space",
            headers={"Authorization": profile["api_token"]},
        )

    clickup_list_spaces.__name__ = "clickup_list_spaces"
    tools.append(
        _attach(
            clickup_list_spaces,
            _schema(
                "clickup_list_spaces",
                "List spaces in a ClickUp workspace.",
                {"team_id": {"type": "string"}},
                ["team_id"],
            ),
            caps=["clickup", "read"],
        )
    )

    def clickup_list_lists(space_id: str) -> dict[str, Any]:
        profile, err = _profile(secrets, "clickup", "api_token")
        if err:
            return err
        return _request(
            "GET",
            f"{_CLICKUP}/space/{quote(space_id)}/list",
            headers={"Authorization": profile["api_token"]},
        )

    clickup_list_lists.__name__ = "clickup_list_lists"
    tools.append(
        _attach(
            clickup_list_lists,
            _schema(
                "clickup_list_lists",
                "List folderless lists in a ClickUp space (list ids hold the tasks).",
                {"space_id": {"type": "string"}},
                ["space_id"],
            ),
            caps=["clickup", "read"],
        )
    )

    def clickup_list_tasks(
        list_id: str, include_closed: bool = False, max_results: int = 10
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "clickup", "api_token")
        if err:
            return err
        return _request(
            "GET",
            f"{_CLICKUP}/list/{quote(list_id)}/task",
            headers={"Authorization": profile["api_token"]},
            params={
                "include_closed": str(bool(include_closed)).lower(),
                "page": 0,
            },
        )

    clickup_list_tasks.__name__ = "clickup_list_tasks"
    tools.append(
        _attach(
            clickup_list_tasks,
            _schema(
                "clickup_list_tasks",
                "List tasks in a ClickUp list.",
                {
                    "list_id": {"type": "string"},
                    "include_closed": {"type": "boolean"},
                    "max_results": {"type": "integer"},
                },
                ["list_id"],
            ),
            caps=["clickup", "read"],
        )
    )

    def clickup_get_task(task_id: str) -> dict[str, Any]:
        profile, err = _profile(secrets, "clickup", "api_token")
        if err:
            return err
        return _request(
            "GET",
            f"{_CLICKUP}/task/{quote(task_id)}",
            headers={"Authorization": profile["api_token"]},
            params={"include_subtasks": "true"},
        )

    clickup_get_task.__name__ = "clickup_get_task"
    tools.append(
        _attach(
            clickup_get_task,
            _schema(
                "clickup_get_task",
                "Read a ClickUp task (with subtasks) by id.",
                {"task_id": {"type": "string"}},
                ["task_id"],
            ),
            caps=["clickup", "read"],
        )
    )

    def clickup_create_task(
        list_id: str, name: str, description: str = ""
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "clickup", "api_token")
        if err:
            return err
        return _request(
            "POST",
            f"{_CLICKUP}/list/{quote(list_id)}/task",
            headers={"Authorization": profile["api_token"]},
            json={"name": name, "description": description},
        )

    clickup_create_task.__name__ = "clickup_create_task"
    tools.append(
        _attach(
            clickup_create_task,
            _schema(
                "clickup_create_task",
                "Create a ClickUp task in a list. Requires user approval.",
                {
                    "list_id": {"type": "string"},
                    "name": {"type": "string"},
                    "description": {"type": "string"},
                },
                ["list_id", "name"],
            ),
            approval=True,
            caps=["clickup", "write"],
        )
    )

    def clickup_update_task(
        task_id: str, name: str = "", description: str = "", status: str = ""
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "clickup", "api_token")
        if err:
            return err
        body: dict[str, Any] = {}
        if name:
            body["name"] = name
        if description:
            body["description"] = description
        if status:
            body["status"] = status
        if not body:
            return {"error": "nothing to update: pass name, description, or status"}
        return _request(
            "PUT",
            f"{_CLICKUP}/task/{quote(task_id)}",
            headers={"Authorization": profile["api_token"]},
            json=body,
        )

    clickup_update_task.__name__ = "clickup_update_task"
    tools.append(
        _attach(
            clickup_update_task,
            _schema(
                "clickup_update_task",
                "Update a ClickUp task's name, description, or status. Requires user approval.",
                {
                    "task_id": {"type": "string"},
                    "name": {"type": "string"},
                    "description": {"type": "string"},
                    "status": {"type": "string"},
                },
                ["task_id"],
            ),
            approval=True,
            caps=["clickup", "write"],
        )
    )

    def clickup_add_comment(task_id: str, text: str) -> dict[str, Any]:
        profile, err = _profile(secrets, "clickup", "api_token")
        if err:
            return err
        return _request(
            "POST",
            f"{_CLICKUP}/task/{quote(task_id)}/comment",
            headers={"Authorization": profile["api_token"]},
            json={"comment_text": text},
        )

    clickup_add_comment.__name__ = "clickup_add_comment"
    tools.append(
        _attach(
            clickup_add_comment,
            _schema(
                "clickup_add_comment",
                "Comment on a ClickUp task. Requires user approval.",
                {"task_id": {"type": "string"}, "text": {"type": "string"}},
                ["task_id", "text"],
            ),
            approval=True,
            caps=["clickup", "write"],
        )
    )

    # --- Close --------------------------------------------------------------

    _CLOSE = "https://api.close.com/api/v1"

    def _close_auth(profile: dict[str, Any]) -> tuple[str, str]:
        # HTTP basic: API key as username, blank password.
        return (str(profile.get("api_key", "")), "")

    def close_search_leads(query: str, max_results: int = 10) -> dict[str, Any]:
        profile, err = _profile(secrets, "close", "api_key")
        if err:
            return err
        return _request(
            "GET",
            f"{_CLOSE}/lead/",
            auth=_close_auth(profile),
            params={"query": query, "_limit": _clamp(max_results)},
        )

    close_search_leads.__name__ = "close_search_leads"
    tools.append(
        _attach(
            close_search_leads,
            _schema(
                "close_search_leads",
                'Search Close leads (supports Close\'s search syntax, e.g. "status:potential acme").',
                {"query": {"type": "string"}, "max_results": {"type": "integer"}},
                ["query"],
            ),
            caps=["close", "read"],
        )
    )

    def close_get_lead(lead_id: str) -> dict[str, Any]:
        profile, err = _profile(secrets, "close", "api_key")
        if err:
            return err
        return _request(
            "GET", f"{_CLOSE}/lead/{quote(lead_id)}/", auth=_close_auth(profile)
        )

    close_get_lead.__name__ = "close_get_lead"
    tools.append(
        _attach(
            close_get_lead,
            _schema(
                "close_get_lead",
                "Read a Close lead (contacts, opportunities, addresses) by id.",
                {"lead_id": {"type": "string"}},
                ["lead_id"],
            ),
            caps=["close", "read"],
        )
    )

    def close_list_opportunities(
        lead_id: str = "", max_results: int = 10
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "close", "api_key")
        if err:
            return err
        params: dict[str, Any] = {"_limit": _clamp(max_results)}
        if lead_id:
            params["lead_id"] = lead_id
        return _request(
            "GET", f"{_CLOSE}/opportunity/", auth=_close_auth(profile), params=params
        )

    close_list_opportunities.__name__ = "close_list_opportunities"
    tools.append(
        _attach(
            close_list_opportunities,
            _schema(
                "close_list_opportunities",
                "List Close opportunities, optionally for one lead.",
                {"lead_id": {"type": "string"}, "max_results": {"type": "integer"}},
                [],
            ),
            caps=["close", "read"],
        )
    )

    def close_create_lead(
        name: str, contact_name: str = "", contact_email: str = ""
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "close", "api_key")
        if err:
            return err
        body: dict[str, Any] = {"name": name}
        if contact_name or contact_email:
            contact: dict[str, Any] = {"name": contact_name}
            if contact_email:
                contact["emails"] = [{"email": contact_email}]
            body["contacts"] = [contact]
        return _request("POST", f"{_CLOSE}/lead/", auth=_close_auth(profile), json=body)

    close_create_lead.__name__ = "close_create_lead"
    tools.append(
        _attach(
            close_create_lead,
            _schema(
                "close_create_lead",
                "Create a Close lead (company), optionally with one contact. Requires user approval.",
                {
                    "name": {"type": "string"},
                    "contact_name": {"type": "string"},
                    "contact_email": {"type": "string"},
                },
                ["name"],
            ),
            approval=True,
            caps=["close", "write"],
        )
    )

    def close_update_opportunity(
        opportunity_id: str, status_id: str = "", note: str = ""
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "close", "api_key")
        if err:
            return err
        body: dict[str, Any] = {}
        if status_id:
            body["status_id"] = status_id
        if note:
            body["note"] = note
        if not body:
            return {"error": "nothing to update: pass status_id or note"}
        return _request(
            "PUT",
            f"{_CLOSE}/opportunity/{quote(opportunity_id)}/",
            auth=_close_auth(profile),
            json=body,
        )

    close_update_opportunity.__name__ = "close_update_opportunity"
    tools.append(
        _attach(
            close_update_opportunity,
            _schema(
                "close_update_opportunity",
                "Update a Close opportunity's status or note. Requires user approval.",
                {
                    "opportunity_id": {"type": "string"},
                    "status_id": {"type": "string"},
                    "note": {"type": "string"},
                },
                ["opportunity_id"],
            ),
            approval=True,
            caps=["close", "write"],
        )
    )

    def close_log_note(lead_id: str, note: str) -> dict[str, Any]:
        profile, err = _profile(secrets, "close", "api_key")
        if err:
            return err
        return _request(
            "POST",
            f"{_CLOSE}/activity/note/",
            auth=_close_auth(profile),
            json={"lead_id": lead_id, "note": note},
        )

    close_log_note.__name__ = "close_log_note"
    tools.append(
        _attach(
            close_log_note,
            _schema(
                "close_log_note",
                "Log a note on a Close lead's timeline. Requires user approval.",
                {"lead_id": {"type": "string"}, "note": {"type": "string"}},
                ["lead_id", "note"],
            ),
            approval=True,
            caps=["close", "write"],
        )
    )

    # --- Figma --------------------------------------------------------------

    _FIGMA = "https://api.figma.com/v1"

    def _figma_headers(profile: dict[str, Any]) -> dict[str, str]:
        return {"X-Figma-Token": str(profile.get("access_token", ""))}

    def _figma_summarize(node: dict[str, Any], depth: int) -> dict[str, Any]:
        out = {
            "id": node.get("id"),
            "name": node.get("name"),
            "type": node.get("type"),
        }
        children = node.get("children") or []
        if depth > 0 and children:
            out["children"] = [_figma_summarize(c, depth - 1) for c in children]
        elif children:
            out["child_count"] = len(children)
        return out

    def figma_get_file(file_key: str) -> dict[str, Any]:
        profile, err = _profile(secrets, "figma", "access_token")
        if err:
            return err
        result = _request(
            "GET",
            f"{_FIGMA}/files/{quote(file_key)}",
            headers=_figma_headers(profile),
            params={"depth": 2},
        )
        if not result.get("ok"):
            return result
        data = result.get("data") or {}
        # The raw file tree is enormous — return pages + top-level frames only.
        doc = data.get("document") or {}
        return {
            "ok": True,
            "name": data.get("name"),
            "last_modified": data.get("lastModified"),
            "pages": [_figma_summarize(p, 1) for p in (doc.get("children") or [])],
        }

    figma_get_file.__name__ = "figma_get_file"
    tools.append(
        _attach(
            figma_get_file,
            _schema(
                "figma_get_file",
                "Read a Figma file's pages and top-level frames (file key is in the URL).",
                {"file_key": {"type": "string"}},
                ["file_key"],
            ),
            caps=["figma", "read"],
        )
    )

    def figma_get_comments(file_key: str) -> dict[str, Any]:
        profile, err = _profile(secrets, "figma", "access_token")
        if err:
            return err
        return _request(
            "GET",
            f"{_FIGMA}/files/{quote(file_key)}/comments",
            headers=_figma_headers(profile),
        )

    figma_get_comments.__name__ = "figma_get_comments"
    tools.append(
        _attach(
            figma_get_comments,
            _schema(
                "figma_get_comments",
                "List comments on a Figma file.",
                {"file_key": {"type": "string"}},
                ["file_key"],
            ),
            caps=["figma", "read"],
        )
    )

    def figma_post_comment(
        file_key: str, message: str, reply_to: str = ""
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "figma", "access_token")
        if err:
            return err
        body: dict[str, Any] = {"message": message}
        if reply_to:
            body["comment_id"] = reply_to
        return _request(
            "POST",
            f"{_FIGMA}/files/{quote(file_key)}/comments",
            headers=_figma_headers(profile),
            json=body,
        )

    figma_post_comment.__name__ = "figma_post_comment"
    tools.append(
        _attach(
            figma_post_comment,
            _schema(
                "figma_post_comment",
                "Comment on a Figma file (optionally replying to a comment). Requires user approval.",
                {
                    "file_key": {"type": "string"},
                    "message": {"type": "string"},
                    "reply_to": {"type": "string"},
                },
                ["file_key", "message"],
            ),
            approval=True,
            caps=["figma", "write"],
        )
    )

    def figma_export_images(
        file_key: str, node_ids: str, format: str = "png", scale: int = 2
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "figma", "access_token")
        if err:
            return err
        return _request(
            "GET",
            f"{_FIGMA}/images/{quote(file_key)}",
            headers=_figma_headers(profile),
            params={"ids": node_ids, "format": format, "scale": scale},
        )

    figma_export_images.__name__ = "figma_export_images"
    tools.append(
        _attach(
            figma_export_images,
            _schema(
                "figma_export_images",
                "Render Figma nodes to image URLs (node ids comma-separated; png/svg/pdf).",
                {
                    "file_key": {"type": "string"},
                    "node_ids": {"type": "string"},
                    "format": {"type": "string"},
                    "scale": {"type": "integer"},
                },
                ["file_key", "node_ids"],
            ),
            caps=["figma", "read"],
        )
    )

    # --- Google Drive (read-only; deliberately no write scope) ---------------

    _DRIVE = "https://www.googleapis.com/drive/v3"
    _DRIVE_FIELDS = "files(id,name,mimeType,modifiedTime,size,webViewLink)"
    # Google-native types export to text; everything else downloads as-is.
    _DRIVE_EXPORTS = {
        "application/vnd.google-apps.document": "text/plain",
        "application/vnd.google-apps.spreadsheet": "text/csv",
        "application/vnd.google-apps.presentation": "text/plain",
    }

    def _drive_quote(term: str) -> str:
        return term.replace("\\", "\\\\").replace("'", "\\'")

    def drive_search_files(
        query: str, max_results: int = 10, account: str = ""
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(
            secrets, "google_drive", account, "access_token"
        )
        if err:
            return err
        q = _drive_quote(query)
        return _acct_result(
            aid,
            _request(
                "GET",
                f"{_DRIVE}/files",
                headers=_google_headers(profile["access_token"]),
                params={
                    "q": f"(name contains '{q}' or fullText contains '{q}') and trashed=false",
                    "pageSize": _clamp(max_results),
                    "fields": _DRIVE_FIELDS,
                },
            ),
        )

    drive_search_files.__name__ = "drive_search_files"
    tools.append(
        _attach(
            drive_search_files,
            _schema(
                "drive_search_files",
                "Search Google Drive files by name or content.",
                {
                    "query": {"type": "string"},
                    "max_results": {"type": "integer"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                ["query"],
            ),
            caps=["google_drive", "read"],
        )
    )

    def drive_list_folder(
        folder_id: str = "root", max_results: int = 20, account: str = ""
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(
            secrets, "google_drive", account, "access_token"
        )
        if err:
            return err
        return _acct_result(
            aid,
            _request(
                "GET",
                f"{_DRIVE}/files",
                headers=_google_headers(profile["access_token"]),
                params={
                    "q": f"'{_drive_quote(folder_id)}' in parents and trashed=false",
                    "pageSize": _clamp(max_results, default=20, ceiling=50),
                    "fields": _DRIVE_FIELDS,
                },
            ),
        )

    drive_list_folder.__name__ = "drive_list_folder"
    tools.append(
        _attach(
            drive_list_folder,
            _schema(
                "drive_list_folder",
                "List a Google Drive folder's contents ('root' for My Drive).",
                {
                    "folder_id": {"type": "string"},
                    "max_results": {"type": "integer"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                [],
            ),
            caps=["google_drive", "read"],
        )
    )

    def drive_read_file(
        file_id: str, max_chars: int = 20000, account: str = ""
    ) -> dict[str, Any]:
        aid, profile, err = _account_profile(
            secrets, "google_drive", account, "access_token"
        )
        if err:
            return err
        headers = _google_headers(profile["access_token"])
        meta = _request(
            "GET",
            f"{_DRIVE}/files/{quote(file_id)}",
            headers=headers,
            params={"fields": "id,name,mimeType,size"},
        )
        if not meta.get("ok"):
            return _acct_result(aid, meta)
        info = meta.get("data") or {}
        mime = str(info.get("mimeType", ""))
        export_mime = _DRIVE_EXPORTS.get(mime)
        if export_mime:
            body = _request(
                "GET",
                f"{_DRIVE}/files/{quote(file_id)}/export",
                headers=headers,
                params={"mimeType": export_mime},
            )
        elif mime.startswith("application/vnd.google-apps"):
            return _acct_result(
                aid, {"error": f"cannot read {mime} as text", "file": info}
            )
        else:
            body = _request(
                "GET",
                f"{_DRIVE}/files/{quote(file_id)}",
                headers=headers,
                params={"alt": "media"},
            )
        if not body.get("ok"):
            return _acct_result(aid, body)
        text = body.get("data")
        if not isinstance(text, str):
            text = json.dumps(text)
        return _acct_result(
            aid,
            {
                "ok": True,
                "file": info,
                "content": text[: max(1, int(max_chars))],
                "truncated": len(text) > max_chars,
            },
        )

    drive_read_file.__name__ = "drive_read_file"
    tools.append(
        _attach(
            drive_read_file,
            _schema(
                "drive_read_file",
                "Read a Drive file as text (Docs/Sheets/Slides export; other text files download).",
                {
                    "file_id": {"type": "string"},
                    "max_chars": {"type": "integer"},
                    "account": _GEN_ACCOUNT_PROP,
                },
                ["file_id"],
            ),
            caps=["google_drive", "read"],
        )
    )

    # --- Docusign -----------------------------------------------------------

    def _docusign_ctx(
        profile: dict[str, Any],
    ) -> tuple[Optional[dict[str, Any]], Optional[dict[str, str]]]:
        """Return {token, base} — discovering and caching account_id + base_uri
        from the OAuth userinfo endpoint on first use."""
        token = str(profile.get("access_token", ""))
        account_id = profile.get("account_id")
        base_uri = profile.get("base_uri")
        if not (account_id and base_uri):
            info = _request(
                "GET",
                "https://account.docusign.com/oauth/userinfo",
                headers=_bearer_headers(token),
            )
            if not info.get("ok"):
                return None, {
                    "error": "docusign account discovery failed",
                    "details": str(info.get("details") or info.get("error")),
                }
            accounts = (info.get("data") or {}).get("accounts") or []
            chosen = next(
                (a for a in accounts if a.get("is_default")),
                accounts[0] if accounts else None,
            )
            if not chosen:
                return None, {"error": "docusign token has no accounts"}
            account_id = chosen.get("account_id")
            base_uri = chosen.get("base_uri")
            secrets.put(
                "docusign:default",
                {**profile, "account_id": account_id, "base_uri": base_uri},
            )
        return {
            "token": token,
            "base": f"{str(base_uri).rstrip('/')}/restapi/v2.1/accounts/{account_id}",
        }, None

    def docusign_list_envelopes(
        status: str = "", since_days: int = 30
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "docusign", "access_token")
        if err:
            return err
        ctx, err = _docusign_ctx(profile)
        if err:
            return err
        from datetime import datetime, timedelta, timezone

        params: dict[str, Any] = {
            "from_date": (
                datetime.now(timezone.utc) - timedelta(days=max(1, int(since_days)))
            ).strftime("%Y-%m-%dT%H:%M:%SZ")
        }
        if status:
            params["status"] = status
        return _request(
            "GET",
            f"{ctx['base']}/envelopes",
            headers=_bearer_headers(ctx["token"]),
            params=params,
        )

    docusign_list_envelopes.__name__ = "docusign_list_envelopes"
    tools.append(
        _attach(
            docusign_list_envelopes,
            _schema(
                "docusign_list_envelopes",
                "List recent Docusign envelopes, optionally by status (sent/delivered/completed/declined/voided).",
                {"status": {"type": "string"}, "since_days": {"type": "integer"}},
                [],
            ),
            caps=["docusign", "read"],
        )
    )

    def docusign_get_envelope(envelope_id: str) -> dict[str, Any]:
        profile, err = _profile(secrets, "docusign", "access_token")
        if err:
            return err
        ctx, err = _docusign_ctx(profile)
        if err:
            return err
        return _request(
            "GET",
            f"{ctx['base']}/envelopes/{quote(envelope_id)}",
            headers=_bearer_headers(ctx["token"]),
            params={"include": "recipients"},
        )

    docusign_get_envelope.__name__ = "docusign_get_envelope"
    tools.append(
        _attach(
            docusign_get_envelope,
            _schema(
                "docusign_get_envelope",
                "Read a Docusign envelope's status and per-signer progress.",
                {"envelope_id": {"type": "string"}},
                ["envelope_id"],
            ),
            caps=["docusign", "read"],
        )
    )

    def docusign_list_templates(max_results: int = 10) -> dict[str, Any]:
        profile, err = _profile(secrets, "docusign", "access_token")
        if err:
            return err
        ctx, err = _docusign_ctx(profile)
        if err:
            return err
        return _request(
            "GET",
            f"{ctx['base']}/templates",
            headers=_bearer_headers(ctx["token"]),
            params={"count": _clamp(max_results)},
        )

    docusign_list_templates.__name__ = "docusign_list_templates"
    tools.append(
        _attach(
            docusign_list_templates,
            _schema(
                "docusign_list_templates",
                "List Docusign templates (template ids are needed to send).",
                {"max_results": {"type": "integer"}},
                [],
            ),
            caps=["docusign", "read"],
        )
    )

    def docusign_send_from_template(
        template_id: str,
        recipient_email: str,
        recipient_name: str,
        role_name: str = "Signer",
        subject: str = "",
    ) -> dict[str, Any]:
        profile, err = _profile(secrets, "docusign", "access_token")
        if err:
            return err
        ctx, err = _docusign_ctx(profile)
        if err:
            return err
        body: dict[str, Any] = {
            "templateId": template_id,
            "templateRoles": [
                {
                    "email": recipient_email,
                    "name": recipient_name,
                    "roleName": role_name,
                }
            ],
            "status": "sent",
        }
        if subject:
            body["emailSubject"] = subject
        return _request(
            "POST",
            f"{ctx['base']}/envelopes",
            headers=_bearer_headers(ctx["token"]),
            json=body,
        )

    docusign_send_from_template.__name__ = "docusign_send_from_template"
    tools.append(
        _attach(
            docusign_send_from_template,
            _schema(
                "docusign_send_from_template",
                "Send a Docusign template to one signer for signature. Requires user approval.",
                {
                    "template_id": {"type": "string"},
                    "recipient_email": {"type": "string"},
                    "recipient_name": {"type": "string"},
                    "role_name": {"type": "string"},
                    "subject": {"type": "string"},
                },
                ["template_id", "recipient_email", "recipient_name"],
            ),
            approval=True,
            caps=["docusign", "write"],
        )
    )

    # --- Canva --------------------------------------------------------------

    _CANVA = "https://api.canva.com/rest/v1"

    def canva_list_designs(query: str = "", max_results: int = 10) -> dict[str, Any]:
        profile, err = _profile(secrets, "canva", "access_token")
        if err:
            return err
        params: dict[str, Any] = {"limit": _clamp(max_results)}
        if query:
            params["query"] = query
        return _request(
            "GET",
            f"{_CANVA}/designs",
            headers=_bearer_headers(profile["access_token"]),
            params=params,
        )

    canva_list_designs.__name__ = "canva_list_designs"
    tools.append(
        _attach(
            canva_list_designs,
            _schema(
                "canva_list_designs",
                "List (or text-search) Canva designs.",
                {"query": {"type": "string"}, "max_results": {"type": "integer"}},
                [],
            ),
            caps=["canva", "read"],
        )
    )

    def canva_get_design(design_id: str) -> dict[str, Any]:
        profile, err = _profile(secrets, "canva", "access_token")
        if err:
            return err
        return _request(
            "GET",
            f"{_CANVA}/designs/{quote(design_id)}",
            headers=_bearer_headers(profile["access_token"]),
        )

    canva_get_design.__name__ = "canva_get_design"
    tools.append(
        _attach(
            canva_get_design,
            _schema(
                "canva_get_design",
                "Read a Canva design's metadata (title, pages, urls).",
                {"design_id": {"type": "string"}},
                ["design_id"],
            ),
            caps=["canva", "read"],
        )
    )

    def canva_export_design(design_id: str, format: str = "pdf") -> dict[str, Any]:
        profile, err = _profile(secrets, "canva", "access_token")
        if err:
            return err
        return _request(
            "POST",
            f"{_CANVA}/exports",
            headers=_bearer_headers(profile["access_token"]),
            json={"design_id": design_id, "format": {"type": format}},
        )

    canva_export_design.__name__ = "canva_export_design"
    tools.append(
        _attach(
            canva_export_design,
            _schema(
                "canva_export_design",
                "Start rendering a Canva design to pdf/png/jpg; returns an export job to poll.",
                {"design_id": {"type": "string"}, "format": {"type": "string"}},
                ["design_id"],
            ),
            caps=["canva", "read"],
        )
    )

    def canva_get_export(export_id: str) -> dict[str, Any]:
        profile, err = _profile(secrets, "canva", "access_token")
        if err:
            return err
        return _request(
            "GET",
            f"{_CANVA}/exports/{quote(export_id)}",
            headers=_bearer_headers(profile["access_token"]),
        )

    canva_get_export.__name__ = "canva_get_export"
    tools.append(
        _attach(
            canva_get_export,
            _schema(
                "canva_get_export",
                "Check a Canva export job; returns download URLs when finished.",
                {"export_id": {"type": "string"}},
                ["export_id"],
            ),
            caps=["canva", "read"],
        )
    )

    if enabled_connectors is not None:
        tools = [
            t for t in tools if connector_for_tool(t.__name__) in enabled_connectors
        ]
    if enabled_tools is not None:
        tools = [t for t in tools if t.__name__ in enabled_tools]
    return tools