feat: set openWorldHint explicitly on every MCP tool (#1879)

* feat: set openWorldHint explicitly on every MCP tool

openWorldHint defaults to true in the MCP spec, so a tool that omits it is
silently treated as open-world by clients. Only ha_manage_updates set it
explicitly, leaving the other 86 tools relying on the implicit default.

Set it explicitly on all 87 tools: true for the 8 whose output crosses a
trust boundary into an externally-authored world (HACS store search/info,
HACS download/add, the add-on store, blueprint import-from-URL, core update
checks, the in-process server self-update, and the MCP-tools component
install), false for the 79 whose domain is the local Home Assistant instance.
A tool is open-world when its output carries externally-authored content back
to the client, even when a local integration (HACS, Supervisor, HA Core)
makes the actual network call on its behalf. Clients that honor the hint can
then skip untrusted-content scrutiny on local reads and keep flagging the
genuinely external tools.

Add a test asserting every tool sets openWorldHint explicitly so new tools
can't drift back to the implicit default, document the annotation in AGENTS.md
and the styleguide alongside the other safety hints, and regenerate tools.json.

Closes #1871

* fix(annotations): mark update-embedding and external-content reads open-world

Review adoption for PR #1879:
- ha_get_overview / ha_get_system_health embed ha_mcp_update, resolved via a
  network check (update_check.get_update_info), so their output can carry
  externally-fetched release metadata -> openWorldHint: true.
- ha_get_blueprint returns imported blueprint content (author, source_url,
  inputs) that may originate from an external URL -> true.
- ha_config_list_dashboard_resources returns third-party card URLs and, with
  include_content, decoded inline JS/CSS -> true.
- ha_get_skill_guide is registered in server.py via self.mcp.tool(...) and was
  missed by the tools/ scanner: annotate it openWorldHint: false (bundled local
  docs) and extend the test to assert server-registered tools carry the hint.
- Make the presence-check regex quote-agnostic (single or double quotes).

* fix(annotations): set openWorldHint on the runtime tool-search proxies

Review adoption for PR #1879. CategorizedSearchTransform builds ha_search_tools
and the ha_call_read/write/delete proxies at runtime via ToolAnnotations(...),
which the static tools/ scan never sees, so they inherited the implicit
open-world default when ENABLE_TOOL_SEARCH=true.

- ha_search_tools -> false (searches the local tool catalog).
- ha_call_read_tool / ha_call_write_tool -> true (they dispatch read/write tools
  that include the open-world ones: HACS, add-on store, blueprint import,
  updates, server self-update).
- ha_call_delete_tool -> false (delete-category tools are all local registry
  removals; none reach an external system).
- Add a guard test asserting every ToolAnnotations(...) construction in
  categorized_search.py sets openWorldHint.

* docs: state the content-provenance clause in the AGENTS.md openWorldHint row

The row said only "Set to False when the tool's domain is the local Home
Assistant instance". Applied literally that classifies ha_get_overview,
ha_get_system_health, ha_get_blueprint and ha_config_list_dashboard_resources
as false -- contradicting the true values this PR ships.

.gemini/styleguide.md already carries the load-bearing clause: a tool is
open-world if its output carries externally-authored content back to the
client, even when a local integration makes the actual network call. Append
it here with the four examples so both docs state one rule.

* test(annotations): fail loudly when the tool scan drops a tool

The closure-form pattern @mcp.tool\(([^)]*)\) cannot span a ')', so a future
decorator whose args contain one (e.g. a title like "Get Logs (verbose)")
falls out of get_all_tools() and escapes every annotation assertion --
silently inheriting the MCP default openWorldHint=true.

Verified by injecting a paren into a closure-form title: the scan dropped to
86 tools while test_all_tools_have_open_world_hint still passed, i.e. the
tool skipped every check unnoticed. Every tool sets openWorldHint exactly
once, so assert the scanned count equals the occurrences across the tool
files; the injected drop now fails with 86 != 87. No tool triggers this today.

Also resolve module-level string constants when naming server-registered
tools: ha_get_skill_guide registers as name=SKILL_TOOL_NAME, so the
Constant-only lookup reported "<unknown>" in the failure message.

Drop two stale scanner claims while in the file: ha_set_entity and
ha_get_system_health are both class-form, so the class pattern matches them
-- neither is dropped by the closure pattern's nested-paren limit.

Author: Patch76

.gemini/styleguide.md

@@ -70,6 +70,7 @@ Verify that safety annotations match actual tool behavior:
 - Tool with `readOnlyHint: True` must NOT modify state (no writes, no service calls)
 - Tool with `destructiveHint: True` must actually delete data
 - State-changing operations should have `idempotentHint: True` only if safe to retry
+- Tool with `openWorldHint: True` must reach an external, third-party-authored world (HACS store, add-on repositories, GitHub release feeds, arbitrary import URLs); a tool whose domain is the local Home Assistant instance should use `False`. It is open-world if its output carries externally-authored content back to the client, even when a local integration (HACS, Supervisor, HA Core) makes the actual network call on its behalf
 
 Flag HIGH severity if annotation contradicts actual behavior in the implementation.
 

AGENTS.md

@@ -553,6 +553,7 @@ Every tool needs `tags={"Category Name"}` (native FastMCP parameter). Drives the
 | `readOnlyHint: True` | `False` | Tool does not modify its environment |
 | `destructiveHint: True` | `True` | Tool may perform destructive updates (only meaningful when `readOnlyHint` is false). Set to `False` for non-destructive writes (e.g., creating a record) |
 | `idempotentHint: True` | `False` | Repeated calls with same args have no additional effect (only meaningful when `readOnlyHint` is false) |
+| `openWorldHint: True` | `True` | Tool reaches an external, third-party-authored world (HACS store, add-on repositories, GitHub release feeds, arbitrary import URLs). Set to `False` when the tool's domain is the local Home Assistant instance. A tool is also open-world if its output carries externally-authored content back to the client, even when a local integration (HACS, Supervisor, HA Core) makes the actual network call on its behalf — `ha_get_overview` and `ha_get_system_health` embed the update-check field that reaches PyPI / the Supervisor store, while `ha_get_blueprint` and `ha_config_list_dashboard_resources` return externally-authored content from purely local reads. Required on every tool — the default is `true`, so an omitted value silently marks a local tool as open-world |
 
 ### Error Handling
 

src/ha_mcp/server.py

@@ -1349,6 +1349,7 @@ async def ha_get_skill_guide(
             name=SKILL_TOOL_NAME,
             description=tool_description,
             annotations={
+                "openWorldHint": False,
                 "readOnlyHint": True,
                 "idempotentHint": True,
                 "title": "Get Home Assistant Best Practices Skill Guide",

src/ha_mcp/tools/backup.py

@@ -1054,7 +1054,11 @@ def register_backup_tools(
     @mcp.tool(
         description=manage_backup_description,
         tags={"System"},
-        annotations={"destructiveHint": True, "title": "Manage Backups"},
+        annotations={
+            "openWorldHint": False,
+            "destructiveHint": True,
+            "title": "Manage Backups",
+        },
     )
     @log_tool_usage
     async def ha_manage_backup(

src/ha_mcp/tools/tools_addons.py

@@ -2572,6 +2572,7 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
     @mcp.tool(
         tags={"Add-ons"},
         annotations={
+            "openWorldHint": True,
             "idempotentHint": True,
             "readOnlyHint": True,
             "title": "Get Add-ons",
@@ -2660,6 +2661,7 @@ async def ha_get_addon(
     @mcp.tool(
         tags={"Add-ons"},
         annotations={
+            "openWorldHint": True,
             "destructiveHint": True,
             "idempotentHint": False,
             "readOnlyHint": False,

src/ha_mcp/tools/tools_areas.py

@@ -139,6 +139,7 @@ def _build_floor_create_message(
         name="ha_list_floors_areas",
         tags={"Areas & Floors"},
         annotations={
+            "openWorldHint": False,
             "idempotentHint": True,
             "readOnlyHint": True,
             "title": "List Floors and Areas",
@@ -390,6 +391,7 @@ def _floor_sort_key(floor: dict[str, Any]) -> int:
         name="ha_set_area_or_floor",
         tags={"Areas & Floors"},
         annotations={
+            "openWorldHint": False,
             "destructiveHint": True,
             "title": "Create or Update Area or Floor",
         },
@@ -640,6 +642,7 @@ async def ha_set_area_or_floor(
         name="ha_remove_area_or_floor",
         tags={"Areas & Floors"},
         annotations={
+            "openWorldHint": False,
             "destructiveHint": True,
             "idempotentHint": True,
             "title": "Remove Area or Floor",

src/ha_mcp/tools/tools_blueprints.py

@@ -76,6 +76,7 @@ def _format_blueprint_list(
         name="ha_get_blueprint",
         tags={"Blueprints"},
         annotations={
+            "openWorldHint": True,
             "idempotentHint": True,
             "readOnlyHint": True,
             "title": "Get Blueprint",
@@ -224,7 +225,11 @@ async def ha_get_blueprint(
     @tool(
         name="ha_import_blueprint",
         tags={"Blueprints"},
-        annotations={"destructiveHint": True, "title": "Import Blueprint"},
+        annotations={
+            "openWorldHint": True,
+            "destructiveHint": True,
+            "title": "Import Blueprint",
+        },
     )
     @log_tool_usage
     async def ha_import_blueprint(

src/ha_mcp/tools/tools_bug_report.py

@@ -646,6 +646,7 @@ async def _detect_component_version(self) -> str | None:
         name="ha_report_issue",
         tags={"Utilities"},
         annotations={
+            "openWorldHint": False,
             "idempotentHint": True,
             "readOnlyHint": True,
             "title": "Report Issue or Feedback",

src/ha_mcp/tools/tools_calendar.py

@@ -43,6 +43,7 @@ def __init__(self, client: Any) -> None:
         name="ha_config_get_calendar_events",
         tags={"Calendar"},
         annotations={
+            "openWorldHint": False,
             "idempotentHint": True,
             "readOnlyHint": True,
             "title": "Get Calendar Events",
@@ -282,6 +283,7 @@ def _build_set_calendar_event_error_suggestions(
         name="ha_config_set_calendar_event",
         tags={"Calendar"},
         annotations={
+            "openWorldHint": False,
             "destructiveHint": True,
             "title": "Create or Update Calendar Event",
         },
@@ -426,6 +428,7 @@ async def ha_config_set_calendar_event(
         name="ha_config_remove_calendar_event",
         tags={"Calendar"},
         annotations={
+            "openWorldHint": False,
             "destructiveHint": True,
             "idempotentHint": True,
             "title": "Remove Calendar Event",

src/ha_mcp/tools/tools_camera.py

@@ -62,6 +62,7 @@ def _check_response(response: Any, entity_id: str) -> None:
         name="ha_get_camera_image",
         tags={"Camera"},
         annotations={
+            "openWorldHint": False,
             "idempotentHint": True,
             "readOnlyHint": True,
             "title": "Get Camera Image",