agentcheckup 0.4.0__py3-none-any.whl

agentcheckup/rules/config_rules.py

@@ -0,0 +1,180 @@
+"""Client-config rules.
+
+Most MCP incidents start here rather than in the server code: an unpinned
+``npx -y`` package that silently updates, a shell wrapper that turns every arg
+into a command, a filesystem server rooted at ``/``.
+"""
+
+from __future__ import annotations
+
+import re
+
+from ..models import Finding, ServerConfig, Severity
+from .base import config_rule
+
+SHELL_WRAPPERS = ("sh", "bash", "zsh", "cmd", "cmd.exe", "powershell", "pwsh")
+
+DANGEROUS_FLAGS = (
+    "--dangerously-skip-permissions",
+    "--yolo",
+    "--allow-all",
+    "--no-sandbox",
+    "--disable-web-security",
+)
+
+SECRET_KEY = re.compile(r"(api[_-]?key|token|secret|password|passwd|credential|private[_-]?key)", re.I)
+
+DRIVE_ROOT = re.compile(r"^[A-Za-z]:[\\/]?$")
+
+
+def _package_arg(args: list[str]) -> str | None:
+    """First positional argument, skipping flags and their values."""
+    skip_next = False
+    for arg in args:
+        if skip_next:
+            skip_next = False
+            continue
+        if arg in ("-y", "--yes", "-q", "--quiet"):
+            continue
+        if arg.startswith("-"):
+            # Flags like `--registry` take a value; treat conservatively.
+            if "=" not in arg and arg in ("--registry", "--cache", "--prefix", "--cwd"):
+                skip_next = True
+            continue
+        return arg
+    return None
+
+
+def _is_pinned(spec: str) -> bool:
+    """`pkg@1.2.3` is pinned; `pkg`, `pkg@latest`, `pkg@^1` are not."""
+    if "@" not in spec:
+        return False
+    version = spec.rsplit("@", 1)[1]
+    if not version or version in ("latest", "next", "beta", "canary"):
+        return False
+    return version[0].isdigit()
+
+
+@config_rule("AGT101", Severity.WARNING, "npx package is not version-pinned")
+def unpinned_npx(server: ServerConfig):
+    """`npx -y foo` re-resolves to the latest release on every launch.
+
+    That is a silent supply-chain dependency: the code you audited last week is
+    not necessarily the code running today.
+    """
+    if not server.command or "npx" not in server.command.lower():
+        return None
+    spec = _package_arg(server.args)
+    if spec and not _is_pinned(spec):
+        return Finding(
+            rule="AGT101",
+            severity=Severity.WARNING,
+            message=f"Server {server.name!r} runs unpinned npx package {spec!r}.",
+            tool=server.name,
+            hint=f"Pin it: npx -y {spec}@1.2.3",
+        )
+    return None
+
+
+@config_rule("AGT102", Severity.WARNING, "uvx package is not version-pinned")
+def unpinned_uvx(server: ServerConfig):
+    """Same failure mode as AGT101, on the Python side."""
+    if not server.command or "uvx" not in server.command.lower():
+        return None
+    spec = _package_arg(server.args)
+    if spec and not _is_pinned(spec):
+        return Finding(
+            rule="AGT102",
+            severity=Severity.WARNING,
+            message=f"Server {server.name!r} runs unpinned uvx package {spec!r}.",
+            tool=server.name,
+            hint=f"Pin it: uvx {spec}==1.2.3",
+        )
+    return None
+
+
+@config_rule("AGT103", Severity.WARNING, "Config wraps the server in a shell")
+def shell_wrapper(server: ServerConfig):
+    """`sh -c "..."` re-parses every argument, so any string can become a command.
+
+    It also defeats argument escaping that the client already did for you.
+    """
+    if not server.command:
+        return None
+    base = server.command.replace("\\", "/").rsplit("/", 1)[-1].lower()
+    if base in SHELL_WRAPPERS and any(a in ("-c", "/c", "/C", "-Command") for a in server.args):
+        return Finding(
+            rule="AGT103",
+            severity=Severity.WARNING,
+            message=f"Server {server.name!r} is launched through a shell wrapper ({server.command}).",
+            tool=server.name,
+            hint="Call the executable directly and pass args as a list.",
+        )
+    return None
+
+
+@config_rule("AGT104", Severity.ERROR, "Filesystem server is rooted at the volume root")
+def broad_fs_root(server: ServerConfig):
+    """Granting the filesystem root gives the agent read-write access to everything.
+
+    One prompt injection is then enough to reach SSH keys, browser profiles and
+    every other project on the machine.
+    """
+    for arg in server.args:
+        if arg == "/" or DRIVE_ROOT.match(arg):
+            return Finding(
+                rule="AGT104",
+                severity=Severity.ERROR,
+                message=f"Server {server.name!r} is granted the whole filesystem ({arg}).",
+                tool=server.name,
+                hint="Point it at a project directory instead of the volume root.",
+            )
+    return None
+
+
+@config_rule("AGT105", Severity.WARNING, "Remote server uses plain HTTP")
+def insecure_url(server: ServerConfig):
+    """Tool calls carry your data and often your credentials."""
+    if server.url and server.url.lower().startswith("http://"):
+        return Finding(
+            rule="AGT105",
+            severity=Severity.WARNING,
+            message=f"Server {server.name!r} uses an unencrypted http:// endpoint.",
+            tool=server.name,
+            hint="Use https://, or a localhost port you control.",
+        )
+    return None
+
+
+@config_rule("AGT106", Severity.ERROR, "Config passes a permission-bypass flag")
+def dangerous_flag(server: ServerConfig):
+    """These flags disable the only confirmation step between the model and your disk."""
+    joined = " ".join([server.command or "", *server.args])
+    for flag in DANGEROUS_FLAGS:
+        if flag in joined:
+            return Finding(
+                rule="AGT106",
+                severity=Severity.ERROR,
+                message=f"Server {server.name!r} is launched with {flag}.",
+                tool=server.name,
+                hint="Remove the flag and grant the narrowest permission that still works.",
+            )
+    return None
+
+
+@config_rule("AGT107", Severity.WARNING, "Credentials are stored in plaintext in the config")
+def plaintext_secret(server: ServerConfig):
+    """Config files get committed, screenshotted and shared in issues.
+
+    Reading from the environment keeps the secret out of the file.
+    """
+    hits = [k for k in server.env if SECRET_KEY.search(k)]
+    if hits:
+        return Finding(
+            rule="AGT107",
+            severity=Severity.WARNING,
+            message=f"Server {server.name!r} stores credential(s) inline: {', '.join(sorted(hits)[:5])}.",
+            tool=server.name,
+            hint="Reference an env var (e.g. ${GITHUB_TOKEN}) instead of pasting the value.",
+        )
+    return None

agentcheckup/rules/docs.py

@@ -0,0 +1,124 @@
+"""Documentation rules.
+
+Tool descriptions are not documentation for humans - they are the *prompt* the
+model reads to decide whether and how to call the tool. Treating them as an
+afterthought is the single most common reason agents pick the wrong tool.
+"""
+
+from __future__ import annotations
+
+from ..models import Finding, Severity, Tool
+from .base import tool_rule
+
+#: Phrases that indicate the description says *when not* to use the tool.
+#: Presence of any one is enough; we do not try to judge quality beyond this.
+NEGATIVE_CUES = (
+    "do not",
+    "don't",
+    "not for",
+    "instead",
+    "only when",
+    "use this when",
+    "prefer ",
+    "avoid ",
+    "not use",
+)
+
+MIN_DESCRIPTION = 40
+
+
+@tool_rule("AGT010", Severity.ERROR, "Tool has no description")
+def missing_description(tool: Tool):
+    """A tool without a description is invisible to the model.
+
+    It will still appear in the manifest and can still be called, but selection
+    becomes a coin flip against every other tool.
+    """
+    if not tool.description.strip():
+        return Finding(
+            rule="AGT010",
+            severity=Severity.ERROR,
+            message=f"Tool {tool.name!r} has no description.",
+            tool=tool.name,
+            hint="One or two sentences: what it does, and what it returns.",
+        )
+    return None
+
+
+@tool_rule("AGT011", Severity.INFO, "Tool description is too short to be useful")
+def short_description(tool: Tool):
+    """Under ~40 characters there is no room for the 'when' or the return shape."""
+    text = tool.description.strip()
+    if text and len(text) < MIN_DESCRIPTION:
+        return Finding(
+            rule="AGT011",
+            severity=Severity.INFO,
+            message=f"Tool {tool.name!r} description is {len(text)} chars.",
+            tool=tool.name,
+            hint="Aim for 80-200 chars: what it does, when to use it, what it returns.",
+        )
+    return None
+
+
+@tool_rule("AGT012", Severity.INFO, "Description never says when NOT to use the tool")
+def no_negative_guidance(tool: Tool):
+    """Disambiguation is what separates a reliable tool set from a lucky one.
+
+    When two tools overlap, the model needs an explicit boundary. One clause is
+    usually enough: "Use this only for public repos; use `get_private_repo` for
+    authenticated access."
+    """
+    text = tool.description.lower()
+    if len(text) >= MIN_DESCRIPTION and not any(cue in text for cue in NEGATIVE_CUES):
+        return Finding(
+            rule="AGT012",
+            severity=Severity.INFO,
+            message=f"Tool {tool.name!r} description gives no disambiguation clause.",
+            tool=tool.name,
+            hint='Add e.g. "Use this only when ...; prefer `other_tool` for ...".',
+        )
+    return None
+
+
+@tool_rule("AGT013", Severity.WARNING, "Input parameters are undocumented")
+def undocumented_params(tool: Tool):
+    """Each parameter is a decision the model has to make blind."""
+    props = tool.properties()
+    if not props:
+        return None
+    missing = [
+        name
+        for name, spec in props.items()
+        if not (isinstance(spec, dict) and str(spec.get("description", "")).strip())
+    ]
+    if missing:
+        preview = ", ".join(sorted(missing)[:5])
+        more = "" if len(missing) <= 5 else f" (+{len(missing) - 5} more)"
+        return Finding(
+            rule="AGT013",
+            severity=Severity.WARNING,
+            message=f"Tool {tool.name!r} has {len(missing)} parameter(s) without a description: {preview}{more}.",
+            tool=tool.name,
+            hint="Describe format and constraints, not just the type.",
+        )
+    return None
+
+
+@tool_rule("AGT014", Severity.INFO, "Description does not state the return shape")
+def no_return_shape(tool: Tool):
+    """The model plans the *next* call from what it expects back.
+
+    Saying "returns a JSON array of {id, title}" is worth more than another
+    sentence about the parameters.
+    """
+    text = tool.description.lower()
+    cues = ("return", "returns", "output", "responds", "yields", "gives back")
+    if len(text) >= MIN_DESCRIPTION and not any(c in text for c in cues):
+        return Finding(
+            rule="AGT014",
+            severity=Severity.INFO,
+            message=f"Tool {tool.name!r} description does not describe what it returns.",
+            tool=tool.name,
+            hint='Add "Returns ..." so the model can plan the next step.',
+        )
+    return None

agentcheckup/rules/injection.py

@@ -0,0 +1,127 @@
+"""Prompt-injection rules for tool descriptions.
+
+Tool descriptions are injected into the model's context verbatim. That makes
+them an *input* channel controlled by whoever wrote the server - a supply-chain
+surface that most MCP setups never audit. These rules flag the shapes that show
+up in real attacks, not hypothetical ones.
+"""
+
+from __future__ import annotations
+
+import re
+
+from ..models import Finding, Severity, Tool
+from ..tokens import has_invisible_chars
+from .base import tool_rule
+
+#: Instructions aimed at the model rather than the reader.
+OVERRIDE_PATTERNS = (
+    re.compile(r"ignore\s+(all\s+)?(the\s+)?(previous|prior|above)\s+(instructions|prompts|rules)", re.I),
+    re.compile(r"disregard\s+(all\s+)?(the\s+)?(previous|prior|above)", re.I),
+    re.compile(r"forget\s+(everything|all)\s+(above|before|you)", re.I),
+    re.compile(r"you\s+are\s+now\s+(a|an|in)\b", re.I),
+    re.compile(r"new\s+(system\s+)?instructions?\s*:", re.I),
+    re.compile(r"system\s*prompt", re.I),
+)
+
+#: Requests to keep something hidden from the human.
+CONCEALMENT_PATTERNS = (
+    re.compile(r"do\s+not\s+(tell|inform|mention|reveal)\s+(the\s+)?(user|human)", re.I),
+    re.compile(r"without\s+(telling|informing|notifying)\s+(the\s+)?user", re.I),
+    re.compile(r"(hide|conceal)\s+(this|it)\s+from", re.I),
+)
+
+#: Outbound data movement embedded in a description.
+EXFIL_PATTERNS = (
+    re.compile(r"(send|post|upload|forward|exfiltrate)\s+.{0,40}\b(to|at)\s+https?://", re.I),
+    re.compile(r"https?://[^\s]+\?[^\s]*(key|token|secret|password)=", re.I),
+)
+
+#: Tool-poisoning via markup the model may read but the reviewer skims past.
+MARKUP_PATTERNS = (
+    re.compile(r"<!--.*?-->", re.S),
+    re.compile(r"<\|[^|]*\|>"),  # chat-template control tokens
+)
+
+
+@tool_rule("AGT040", Severity.ERROR, "Description tries to override model instructions")
+def instruction_override(tool: Tool):
+    """A legitimate description never talks to the model in the imperative-about-itself.
+
+    This is the classic tool-poisoning payload: the server author (or anyone who
+    compromised the package) rewrites the agent's priorities at load time.
+    """
+    for pattern in OVERRIDE_PATTERNS:
+        match = pattern.search(tool.description)
+        if match:
+            return Finding(
+                rule="AGT040",
+                severity=Severity.ERROR,
+                message=f"Tool {tool.name!r} description contains an instruction-override phrase: {match.group(0)!r}.",
+                tool=tool.name,
+                hint="Rewrite the description to describe the tool, not to instruct the model.",
+            )
+    return None
+
+
+@tool_rule("AGT041", Severity.ERROR, "Description asks the model to hide behaviour from the user")
+def concealment(tool: Tool):
+    """Anything the model is told to hide from its user is, by definition, not auditable."""
+    for pattern in CONCEALMENT_PATTERNS:
+        match = pattern.search(tool.description)
+        if match:
+            return Finding(
+                rule="AGT041",
+                severity=Severity.ERROR,
+                message=f"Tool {tool.name!r} description contains a concealment phrase: {match.group(0)!r}.",
+                tool=tool.name,
+                hint="Remove it. There is no legitimate reason to hide a tool call from the user.",
+            )
+    return None
+
+
+@tool_rule("AGT042", Severity.WARNING, "Description embeds an outbound URL with credentials")
+def exfiltration(tool: Tool):
+    """Tool descriptions should not contain endpoints at all, let alone with tokens."""
+    for pattern in EXFIL_PATTERNS:
+        match = pattern.search(tool.description)
+        if match:
+            return Finding(
+                rule="AGT042",
+                severity=Severity.WARNING,
+                message=f"Tool {tool.name!r} description contains a suspicious outbound URL: {match.group(0)[:80]!r}.",
+                tool=tool.name,
+                hint="Endpoints belong in config, never in the model-visible description.",
+            )
+    return None
+
+
+@tool_rule("AGT043", Severity.ERROR, "Description hides text with invisible characters")
+def invisible_text(tool: Tool):
+    """Zero-width and bidi characters let a description read one way and behave another."""
+    suspects = has_invisible_chars(tool.description)
+    if suspects:
+        return Finding(
+            rule="AGT043",
+            severity=Severity.ERROR,
+            message=f"Tool {tool.name!r} description contains invisible characters: {', '.join(suspects)}.",
+            tool=tool.name,
+            hint="Strip zero-width / bidi control characters; re-save the description as plain text.",
+        )
+    return None
+
+
+@tool_rule("AGT044", Severity.WARNING, "Description hides instructions in markup")
+def markup_hidden(tool: Tool):
+    """HTML comments and chat-template tokens are invisible in most UIs."""
+    for pattern in MARKUP_PATTERNS:
+        match = pattern.search(tool.description)
+        if match:
+            return Finding(
+                rule="AGT044",
+                severity=Severity.WARNING,
+                message=f"Tool {tool.name!r} description contains markup the UI may hide: {match.group(0)[:60]!r}.",
+                tool=tool.name,
+                hint="Descriptions should be plain prose; no comments or template tokens.",
+            )
+    return None

agentcheckup/rules/naming.py

@@ -0,0 +1,100 @@
+"""Naming rules: the cheapest class of bug to catch and the easiest to fix."""
+
+from __future__ import annotations
+
+import re
+
+from ..models import Finding, Severity, Tool
+from .base import tool_rule
+
+ALLOWED = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
+SNAKE = re.compile(r"^[a-z][a-z0-9]*(_[a-z0-9]+)*$")
+
+
+@tool_rule(
+    "AGT001",
+    Severity.ERROR,
+    "Tool name is not a valid MCP identifier",
+)
+def name_charset(tool: Tool):
+    """MCP tool names must be 1-64 chars of [A-Za-z0-9_-].
+
+    Anything else is rejected by strict clients and silently mangled by others,
+    which turns into a "tool not found" bug the model cannot recover from.
+    """
+    if not tool.name:
+        return Finding(
+            rule="AGT001",
+            severity=Severity.ERROR,
+            message="Tool has an empty name.",
+            hint="Every tool needs a non-empty `name`.",
+        )
+    if not ALLOWED.match(tool.name):
+        return Finding(
+            rule="AGT001",
+            severity=Severity.ERROR,
+            message=f"Tool name {tool.name!r} contains characters outside [A-Za-z0-9_-] or exceeds 64 chars.",
+            tool=tool.name,
+            hint="Rename to something like `read_file` or `search-docs`.",
+        )
+    return None
+
+
+@tool_rule(
+    "AGT002",
+    Severity.INFO,
+    "Tool name is not snake_case",
+)
+def name_style(tool: Tool):
+    """Consistent casing measurably helps tool selection.
+
+    Models see the whole manifest at once; mixed `readFile` / `read_file` /
+    `ReadFile` makes near-duplicate names harder to disambiguate.
+    """
+    if tool.name and not SNAKE.match(tool.name):
+        return Finding(
+            rule="AGT002",
+            severity=Severity.INFO,
+            message=f"Tool name {tool.name!r} is not snake_case.",
+            tool=tool.name,
+            hint="Prefer `read_file` over `readFile` / `ReadFile`.",
+        )
+    return None
+
+
+#: Prefixes that are almost always a server/domain name rather than a verb.
+#: Deliberately a closed list: a "first segment has >= 3 chars" heuristic fires
+#: on legitimate names like ``search_docs_by_tag`` and the false positives make
+#: the whole report untrustworthy.
+SERVER_PREFIXES = frozenset(
+    {
+        "github", "gitlab", "jira", "slack", "notion", "linear", "sentry",
+        "postgres", "mysql", "sqlite", "redis", "mongo", "elastic",
+        "browser", "playwright", "chrome", "puppeteer",
+        "filesystem", "files", "fs", "shell", "docker", "k8s", "kubernetes",
+        "google", "gmail", "calendar", "drive", "aws", "s3", "azure", "gcp",
+    }
+)
+
+
+@tool_rule(
+    "AGT003",
+    Severity.INFO,
+    "Tool name encodes the server name as a prefix",
+)
+def name_redundant_prefix(tool: Tool):
+    """`github_get_issue` inside the `github` server wastes context.
+
+    The client already namespaces by server, so the prefix is pure overhead on
+    every single request.
+    """
+    head = tool.name.split("_", 1)[0].lower()
+    if tool.name.count("_") >= 2 and head in SERVER_PREFIXES:
+        return Finding(
+            rule="AGT003",
+            severity=Severity.INFO,
+            message=f"Tool name {tool.name!r} repeats the server/domain name as a prefix.",
+            tool=tool.name,
+            hint="The client already namespaces by server; drop the prefix to save context.",
+        )
+    return None

agentcheckup/rules/safety.py

@@ -0,0 +1,131 @@
+"""Safety rules.
+
+Annotations exist so a host can gate destructive tools behind a confirmation
+prompt. Missing or contradictory annotations silently disable that gate, which
+is how an agent ends up deleting production data with no dialog box.
+"""
+
+from __future__ import annotations
+
+from ..models import Finding, Severity, Tool
+from .base import tool_rule
+
+DESTRUCTIVE_VERBS = (
+    "delete", "remove", "drop", "destroy", "truncate", "purge", "wipe",
+    "kill", "terminate", "reset", "overwrite", "revoke",
+)
+
+EXEC_VERBS = ("exec", "execute", "shell", "run_command", "spawn", "eval", "system")
+
+PATH_PARAMS = ("path", "file", "dir", "directory", "folder", "root", "cwd", "glob")
+
+WRITE_VERBS = ("write", "create", "update", "edit", "patch", "put", "post", "append", "insert")
+
+
+def _looks_like(tool: Tool, verbs: tuple[str, ...]) -> str | None:
+    name = tool.name.lower()
+    for verb in verbs:
+        if name == verb or name.startswith(verb + "_") or f"_{verb}" in name:
+            return verb
+    return None
+
+
+@tool_rule("AGT030", Severity.WARNING, "Destructive tool does not declare destructiveHint")
+def destructive_without_hint(tool: Tool):
+    """Hosts cannot ask "are you sure?" for a tool that does not admit it is risky."""
+    verb = _looks_like(tool, DESTRUCTIVE_VERBS)
+    if not verb:
+        return None
+    if tool.annotations.get("destructiveHint") is True:
+        return None
+    return Finding(
+        rule="AGT030",
+        severity=Severity.WARNING,
+        message=f"Tool {tool.name!r} looks destructive (verb: {verb}) but sets no destructiveHint.",
+        tool=tool.name,
+        hint='Add "annotations": {"destructiveHint": true} so hosts can require confirmation.',
+    )
+
+
+@tool_rule("AGT031", Severity.WARNING, "readOnlyHint contradicts the tool name")
+def readonly_contradiction(tool: Tool):
+    """A wrong ``readOnlyHint: true`` is worse than no hint.
+
+    Hosts use it to skip confirmation and to allow parallel calls.
+    """
+    if tool.annotations.get("readOnlyHint") is not True:
+        return None
+    verb = _looks_like(tool, DESTRUCTIVE_VERBS + WRITE_VERBS)
+    if not verb:
+        return None
+    return Finding(
+        rule="AGT031",
+        severity=Severity.WARNING,
+        message=f"Tool {tool.name!r} declares readOnlyHint: true but its name implies '{verb}'.",
+        tool=tool.name,
+        hint="Either the name or the annotation is wrong; hosts trust the annotation.",
+    )
+
+
+@tool_rule("AGT032", Severity.ERROR, "Tool exposes unconstrained command execution")
+def unconstrained_exec(tool: Tool):
+    """An `exec`-style tool with a free-form string is remote code execution by design.
+
+    It is sometimes intentional (a local shell server), but it must be a
+    deliberate, documented decision rather than a default.
+    """
+    verb = _looks_like(tool, EXEC_VERBS)
+    if not verb:
+        return None
+    for name, spec in tool.properties().items():
+        if not isinstance(spec, dict):
+            continue
+        if spec.get("type") != "string":
+            continue
+        if not any(k in spec for k in ("enum", "pattern", "const")):
+            return Finding(
+                rule="AGT032",
+                severity=Severity.ERROR,
+                message=f"Tool {tool.name!r} executes commands from an unconstrained string param {name!r}.",
+                tool=tool.name,
+                hint="Allow-list commands via `enum`, or drop the param and expose fixed operations.",
+            )
+    return None
+
+
+@tool_rule("AGT033", Severity.INFO, "Filesystem parameter has no documented scope")
+def unscoped_path(tool: Tool):
+    """Without a stated root, the model will happily read ``/etc/shadow``.
+
+    Documenting the sandbox root is cheap and makes the boundary testable.
+    """
+    for name, spec in tool.properties().items():
+        if not isinstance(spec, dict):
+            continue
+        if not any(p in name.lower() for p in PATH_PARAMS):
+            continue
+        desc = str(spec.get("description", "")).lower()
+        if any(k in desc for k in ("root", "sandbox", "within", "relative", "base dir", "allowed")):
+            continue
+        return Finding(
+            rule="AGT033",
+            severity=Severity.INFO,
+            message=f"Tool {tool.name!r} path param {name!r} does not state its allowed root.",
+            tool=tool.name,
+            hint='Say e.g. "Relative to the sandbox root; absolute paths are rejected."',
+        )
+    return None
+
+
+@tool_rule("AGT034", Severity.INFO, "Tool declares no annotations at all")
+def no_annotations(tool: Tool):
+    """No hints means the host must assume the worst case for every call."""
+    if tool.annotations:
+        return None
+    return Finding(
+        rule="AGT034",
+        severity=Severity.INFO,
+        message=f"Tool {tool.name!r} has no annotations.",
+        tool=tool.name,
+        hint='Declare at least {"readOnlyHint": true/false} and "destructiveHint" where relevant.',
+    )