feat: convert doc tools to MCP resources and skill references

AGENTS.md

@@ -531,7 +531,7 @@ def register_<domain>_tools(mcp, client, **kwargs):
     @log_tool_usage
     async def ha_<verb>_<noun>(param: str) -> dict[str, Any]:
         """One-line summary starting with action verb."""
-        # For complex schemas, add: "Use ha_get_domain_docs('<domain>') for details."
+        # For complex schemas, add: "Use read_resource('ha://docs/domains/<domain>') for details."
 ```
 
 ### Safety Annotations
@@ -693,14 +693,14 @@ Context engineering treats LLM context as a finite resource with diminishing ret
 
 | Pattern | Example |
 |---------|---------|
-| **Docs on demand** | Tool descriptions reference `ha_get_domain_docs()` instead of embedding full documentation |
+| **Docs on demand** | Tool descriptions reference `ha://docs/domains/{domain}` resources instead of embedding full documentation |
 | **Hints in UX flow** | First tool in a workflow hints at related tools (e.g., `ha_search_entities` suggests `ha_get_state`) |
-| **Error-driven discovery** | When a tool fails, the error response hints at `ha_get_domain_docs()` for syntax help |
+| **Error-driven discovery** | When a tool fails, the error response hints at `ha://docs/` resources or the skill guidance tool for help |
 | **Layered parameters** | Required params first, optional params with sensible defaults |
 | **Focused returns** | Return essential data; let user request details via follow-up tools |
 
 **Practical examples in this codebase:**
-- `ha_config_set_helper` has minimal docstring, points to `ha_get_domain_docs()` for each helper type
+- `ha_config_set_helper` has minimal docstring, points to `ha://docs/domains/` resources for each helper type
 - Search tools return entity IDs and names; full state requires `ha_get_state`
 - Error responses include `suggestions` array guiding next steps
 
@@ -718,7 +718,7 @@ Task tool with model=haiku or model=sonnet:
 
 This reveals:
 - What the model knows from training (no need to document)
-- What gaps exist (target these with `ha_get_domain_docs()` hints)
+- What gaps exist (target these with `ha://docs/domains/` resource hints)
 - Confidence levels across model tiers (haiku vs sonnet vs opus)
 
 **Important: Fact-check model claims.** Models can hallucinate plausible-sounding syntax. Always verify against HA Core source:

README.md

@@ -138,7 +138,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **Automations** | `ha_config_get_automation`, `ha_config_set_automation`, `ha_config_remove_automation` |
 | **Scripts** | `ha_config_get_script`, `ha_config_set_script`, `ha_config_remove_script` |
 | **Helper Entities** | `ha_config_list_helpers`, `ha_config_set_helper`, `ha_config_remove_helper` |
-| **Dashboards** | `ha_config_get_dashboard`, `ha_config_set_dashboard`, `ha_config_delete_dashboard`, `ha_get_dashboard_guide`, `ha_get_card_documentation` |
+| **Dashboards** | `ha_config_get_dashboard`, `ha_config_set_dashboard`, `ha_config_delete_dashboard` + dashboard skill references |
 | **Areas & Floors** | `ha_config_list_areas`, `ha_config_set_area`, `ha_config_remove_area`, `ha_config_list_floors`, `ha_config_set_floor`, `ha_config_remove_floor` |
 | **Labels** | `ha_config_get_label`, `ha_config_set_label`, `ha_config_remove_label`, `ha_manage_entity_labels` |
 | **Zones** | `ha_get_zone`, `ha_set_zone`, `ha_remove_zone` |
@@ -154,7 +154,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **Automation Traces** | `ha_get_automation_traces` |
 | **System & Updates** | `ha_check_config`, `ha_restart`, `ha_reload_core`, `ha_get_system_info`, `ha_get_system_health`, `ha_get_updates` |
 | **Backup & Restore** | `ha_backup_create`, `ha_backup_restore` |
-| **Utility** | `ha_get_logbook`, `ha_eval_template`, `ha_get_domain_docs`, `ha_get_integration` |
+| **Utility** | `ha_get_logbook`, `ha_eval_template`, `ha_get_integration` + `ha://docs/` resources |
 
 </details>
 
@@ -173,7 +173,7 @@ Skills from `homeassistant-ai/skills` are bundled and served as [MCP resources](
 | Setting | Default | Description |
 |---------|---------|-------------|
 | `ENABLE_SKILLS` | `true` | Serve skills as MCP resources. Resources are not auto-injected into context — clients must explicitly request them. |
-| `ENABLE_SKILLS_AS_TOOLS` | `false` | Also expose skills via `list_resources`/`read_resource` tools for clients that don't support MCP resources natively. |
+| `ENABLE_SKILLS_AS_TOOLS` | `true` | Expose skills and doc resources via `list_resources`/`read_resource` tools. Resource-capable clients can set to `false` to reduce tool count. |
 
 Skills can still be installed manually for clients that prefer local skill files — see the [skills repo](https://github.com/homeassistant-ai/skills) for instructions.
 

homeassistant-addon/DOCS.md

@@ -334,7 +334,7 @@ The add-on provides 80+ MCP tools for controlling Home Assistant:
 ### Utility
 - `ha_get_logbook` - Historical events
 - `ha_eval_template` - Evaluate Jinja2 templates
-- `ha_get_domain_docs` - Domain documentation
+- Domain documentation available via `ha://docs/domains/{domain}` MCP resources
 - `ha_get_integration` - List or get integration info
 
 See the [main repository](https://github.com/homeassistant-ai/ha-mcp) for detailed tool documentation and examples.

src/ha_mcp/config.py

@@ -90,9 +90,11 @@ class Settings(BaseSettings):
     # Resources are not auto-injected — clients must explicitly request them.
     enable_skills: bool = Field(True, alias="ENABLE_SKILLS")
 
-    # Expose skills as tools (list_resources/read_resource) for clients
-    # that don't support MCP resources natively.
-    enable_skills_as_tools: bool = Field(False, alias="ENABLE_SKILLS_AS_TOOLS")
+    # Expose skills and doc resources as tools (list_resources/read_resource)
+    # for clients that don't support MCP resources natively.
+    # Defaults to True so all clients can access documentation and skills.
+    # Resource-capable clients can set to False to reduce tool count.
+    enable_skills_as_tools: bool = Field(True, alias="ENABLE_SKILLS_AS_TOOLS")
 
     @property
     def env_file_name(self) -> str:

src/ha_mcp/errors.py

@@ -137,7 +137,7 @@ class ErrorCode(StrEnum):
         "Entity domain must match the original domain",
     ],
     ErrorCode.SERVICE_NOT_FOUND: [
-        "Use ha_get_domain_docs() to see available services",
+        "Use read_resource('ha://docs/domains/{domain}') or ha_get_skill_home_assistant_best_practices for documentation",
         "Check the service name spelling",
         "Verify the domain supports this service",
     ],
@@ -148,7 +148,7 @@ class ErrorCode(StrEnum):
     ErrorCode.SERVICE_INVALID_ACTION: [
         "Check available actions for this domain",
         "Common actions: turn_on, turn_off, toggle",
-        "Use ha_get_domain_docs() for service documentation",
+        "Use read_resource('ha://docs/domains/{domain}') or ha_get_skill_home_assistant_best_practices for documentation",
     ],
     ErrorCode.SERVICE_CALL_FAILED: [
         "Check the service parameters are correct",
@@ -161,7 +161,7 @@ class ErrorCode(StrEnum):
     ],
     ErrorCode.CONFIG_INVALID: [
         "Review the configuration format",
-        "Use ha_get_domain_docs() for configuration help",
+        "Use read_resource('ha://docs/domains/{domain}') or ha_get_skill_home_assistant_best_practices for configuration help",
     ],
     ErrorCode.CONFIG_MISSING_REQUIRED_FIELDS: [
         "Check documentation for required fields",