docs: add MCP tool docstring guidelines to AGENTS.md and styleguide (homeassistant-ai#907)

* docs(agents): add Tool Docstrings guidelines and update template

Builds on the foundation laid by homeassistant-ai#752 (@julienld). Adds a structured
`### Tool Docstrings` section to AGENTS.md and updates the tool template
to show optional blocks as comments rather than a prescriptive skeleton.

Key design choices:
- Single-line template remains the default (progressive disclosure)
- Optional blocks (RELATED TOOLS, EXAMPLES, NOTE) are comments in the
  template, with guidelines on when to use each
- Explicit "What NOT to include" list to prevent over-documentation
- Corrects ha_get_domain_docs -> ha_get_skill_home_assistant_best_practices

* docs(styleguide): add MCP Tool Docstrings review section

Complements the AGENTS.md Tool Docstrings guidelines. Gives Gemini Code
Assist actionable MEDIUM-severity flags for the most common docstring
problems while explicitly excluding false positives on legitimate concise
docstrings (progressive disclosure: brief by default).

Builds on homeassistant-ai#752 (@julienld).

* fix(docs): restructure template, add remove verb, address GB findings

Finding 1: Move developer guidance comments outside the docstring
triple-quotes. Restores the original convention: docstring content
inside """, developer notes as Python comments after closing """.
This ensures the template teaches correct Python structure.

Finding 2: Add `remove` to Naming Convention and verb checklist.
13 tools use ha_remove_*/ha_config_remove_* vs 4 ha_*delete_*.
`remove` is the dominant verb for registry items but was undocumented.
Also clarifies the delete vs remove distinction inline.

Finding 3 (no change): The `# For complex schemas` in prose correctly
shows a Python comment in the function body. Removing the # would
conflate a developer note with docstring content -- explained in PR.

* fix(docs): correct delete example in Naming Convention

ha_config_delete_automation does not exist -- it was a pre-existing
error in AGENTS.md. Replaced with ha_config_delete_dashboard (real tool).
Also corrected the description: delete covers dashboards, config entries,
and files -- not just files as GB suggested (ha_config_delete_dashboard,
ha_config_delete_dashboard_resource, ha_delete_config_entry confirm this).

* fix(docs): use 'delete' in delete verb description

After introducing 'remove' as a separate verb category, describing
'delete' as 'remove dashboards...' was ambiguous. Using 'delete' in
the description eliminates the semantic overlap.

* fix(styleguide): add Remove to verb list, drop superseded Tool descriptions item

Author: Patch76

.gemini/styleguide.md

@@ -96,9 +96,24 @@ Flag HIGH severity if errors use plain exceptions or dict returns instead of str
 
 ## Code Conventions
 
-1. **Tool descriptions**: Use action verbs, keep concise
-2. **Async/await**: Use consistently for I/O operations
-3. **Type hints**: Required for all function signatures
+## MCP Tool Docstrings
+
+These rules apply to new or modified tool docstrings in the PR diff only -- not to pre-existing docstrings in unchanged files.
+
+**Flag MEDIUM severity when a new or modified tool docstring:**
+- Does not start with an action verb (`Returns...` should be `Get...`; valid verbs: `Get`, `List`, `Search`, `Create`, `Update`, `Delete`, `Remove`, `Execute`, `Call`)
+- Is missing entirely or is still a placeholder
+- References a non-existent tool (e.g., `ha_get_domain_docs` -- the correct name is `ha_get_skill_home_assistant_best_practices`)
+- Embeds a full parameter schema instead of deferring to `ha_get_skill_home_assistant_best_practices`
+- Is a workflow-entry tool but gives no hint about the next natural tool to call
+
+**Do NOT flag:**
+- Concise one-liners on straightforward tools (progressive disclosure: brief by default)
+- Missing examples on tools with obvious single-parameter calls
+- Multi-line docstrings that stay focused and on-topic
+
+1. **Async/await**: Use consistently for I/O operations
+2. **Type hints**: Required for all function signatures
 
 ## Documentation Standards
 

AGENTS.md

@@ -523,7 +523,8 @@ src/ha_mcp/
 - `list` — collections (`ha_list_areas`)
 - `search` — filtered queries (`ha_search_entities`)
 - `set` — create/update (`ha_config_set_helper`)
-- `delete` — remove (`ha_config_delete_automation`)
+- `delete` — delete dashboards, config entries, or files (`ha_config_delete_dashboard`, `ha_delete_file`)
+- `remove` — remove registry items (`ha_remove_entity`, `ha_config_remove_area`)
 - `call` — execute (`ha_call_service`)
 
 ### Tool Structure
@@ -534,10 +535,41 @@ def register_<domain>_tools(mcp, client, **kwargs):
     @mcp.tool(tags={"Category Name"}, annotations={"readOnlyHint": True, "idempotentHint": True})
     @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_skill_home_assistant_best_practices for details."
+        """<Action verb> <what this tool does -- one sentence>.
+
+        <Optional: second sentence for key behavioral distinction or modes>
+        """
+        # Add to the docstring above only when genuinely needed:
+        # RELATED TOOLS: ha_next(): why to call this after (workflow-entry tools only)
+        # EXAMPLES: ha_<verb>_<noun>("realistic_value")  -- non-obvious call patterns only
+        # NOTE / WARNING: non-obvious gotcha or destructive side-effect
+        # For complex schemas: use ha_get_skill_home_assistant_best_practices
 ```
 
+### Tool Docstrings
+
+The single-line template is the default -- extend it only where it genuinely helps.
+
+**Required for every tool:**
+- Starts with an action verb (`Get`, `List`, `Search`, `Create`, `Update`, `Delete`, `Remove`, `Execute`, `Call`)
+- One sentence describing what the tool does (not how)
+
+**Add `RELATED TOOLS` when** the tool is a workflow entry point and the natural next step is not obvious.
+Example: `ha_search_entities` hints at `ha_get_state`.
+
+**Add `EXAMPLES` when** the tool has multiple modes or non-obvious parameters.
+Omit when a single required parameter makes the call self-evident.
+
+**Add `NOTE` or `WARNING` when** there is a non-obvious gotcha, a destructive side-effect,
+or a behavioral quirk that causes silent failures if ignored.
+
+**Defer complex schemas** instead of embedding them:
+`# For complex schemas: use ha_get_skill_home_assistant_best_practices`
+
+**What NOT to include:** full parameter documentation, type descriptions already in the
+signature, HA domain internals the model already knows, or motivational prose.
+
+
 ### Tool Tags
 
 Every tool needs `tags={"Category Name"}` (native FastMCP parameter). Drives the README table, `site/src/data/tools.json`, and `homeassistant-addon/DOCS.md`. These are auto-regenerated on merge by `sync-tool-docs.yml` — no manual regeneration needed. For local testing: `python scripts/extract_tools.py`