[DOCS] Tool naming convention: AGENTS.md and .gemini/styleguide.md disagree

[kingpanther13]

📚 Documentation Issue

Where is the issue?

Other — contributor documentation (AGENTS.md and .gemini/styleguide.md)

What's wrong or unclear?

AGENTS.md and .gemini/styleguide.md give incongruent rules for MCP tool naming, which causes two concrete problems:

1. A contributor who follows one doc will be flagged by Gemini Code Assist when the other runs on their PR.
2. Neither doc matches the actual tool surface. A significant fraction of current tools don't fit the stated rule, and the rule's own examples contradict the rule's pattern line.

Specific incongruences:

AGENTS.md → Writing MCP Tools → Naming Convention:

• States the pattern is ha_<verb>_<noun>.
• Lists 7 verbs: get, list, search, set, delete, remove, call.
• But the examples for set, delete, and remove all show a ha_config_<verb>_<noun> form (ha_config_set_helper, ha_config_delete_dashboard, ha_config_remove_area) — i.e., config sits in the verb slot, which doesn't match the opening pattern line. So the rule line and its own examples disagree about whether a ha_config_* namespace prefix is allowed.

.gemini/styleguide.md → Tool Naming Convention:

• Says tools MUST follow ha_<verb>_<noun>.
• Lists only 6 verbs: get, list, search, set, delete, call. remove is missing.
• Flags MEDIUM severity if tools don't follow the pattern.
• Doesn't mention the ha_config_* namespace variant at all.

Result: any tool named ha_remove_* or ha_config_remove_* follows AGENTS.md but will be flagged MEDIUM by Gemini Code Assist. Any tool in the ha_config_<verb>_* family strictly violates both docs' opening pattern line but is blessed by AGENTS.md's examples.

Current state of the tool surface (86 tools audited):

• 34 strictly conforming to ha_<verb>_<noun> (e.g., ha_get_state, ha_set_entity, ha_call_service, ha_set_config_entry_helper).
• 34 in the ha_config_<verb>_<noun> family (e.g., ha_config_set_helper, ha_config_set_automation, ha_config_remove_area). Blessed by AGENTS.md examples; not by the pattern line; not mentioned in the gemini styleguide.
• ~18 exceptions using verbs outside the approved list (backup_create, backup_restore, check_config, eval_template, hacs_*, import_blueprint, install_mcp_tools, read_file, reload_core, report_issue, restart, update_device, write_file, deep_search, bulk_control). Some of these (like ha_restart, ha_reload_core, ha_report_issue) are one-off operations where forcing a get/set/call verb would read worse than the current name; those should probably stay as-is and be documented as accepted exceptions.

How should it be fixed?

Pick one of these two directions and make both docs internally consistent with each other and with the tool surface:

Option A — Update the docs to match reality. Keep the current tool names. Rewrite AGENTS.md so the rule line explicitly permits the ha_[config_]<verb>_<noun> shape (or documents ha_config_* as an accepted namespace prefix for config-management tools). Add remove to the gemini styleguide. Document a short list of accepted one-off exceptions (ha_restart, ha_reload_core, ha_report_issue, etc.) so they stop being violations-that-aren't. This is the low-churn option and probably the right one.

Option B — Update the tool names to match the rule. Rename the 34-tool ha_config_* family to strictly follow ha_<verb>_<noun> (e.g., ha_config_set_helper → ha_set_helper, ha_config_set_automation → ha_set_automation, etc.). High churn, touches every client, every doc, every test, and collides with ha_set_config_entry_helper's existing name.

Either way, after the fix:

• AGENTS.md's rule line and its examples should agree.
• AGENTS.md and .gemini/styleguide.md should use the same verb list and the same pattern.
• Accepted exceptions should be listed explicitly so Gemini Code Assist and contributors stop flagging them.

Additional context

This came up while working on #942 (hardening ha_config_set_yaml's description). The investigation exposed that ha_config_set_helper doesn't accept helper_type="template" while ha_set_config_entry_helper does — which is a separate (semantic) issue, but the naming inconsistency between the two tools made the confusion worse. This issue is specifically about the documentation vs. tool-surface drift; the helper-tool-merge question is deliberately out of scope here.

One-off tools like ha_restart, ha_reload_core, ha_report_issue, ha_check_config, and similar should be explicitly allowed as exceptions rather than renamed — those names are clearer as-is than forcing them into a ha_call_<noun> or ha_get_<noun> shape.

Additionally I'd like to add "manage" as a verb, OR alternatively add into the agents/styleguide that we can add new verbs if no other verb fits when adding new types of tools.

[github-actions]

❌ Analysis failed

An error occurred:

YOLO mode is enabled. All tool calls will be automatically approved.
YOLO mode is enabled. All tool calls will be automatically approved.
{
  "session_id": "bd6feafd-ed80-4eb0-bedb-ce4bcbce853f",
  "error": {
    "type": "FatalTurnLimitedError",
    "message": "Reached max session turns for this session. Increase the number of turns by specifying maxSessionTurns in settings.json.",
    "code": 53
  }
}[ERROR] {
  "session_id": "bd6feafd-ed80-4eb0-bedb-ce4bcbce853f",
  "error": {
    "type": "FatalTurnLimitedError",
    "message": "Reached max session turns for this session. Increase the number of turns by specifying maxSessionTurns in settings.json.",
    "code": 53
  }
}

Please check the workflow logs.

[kingpanther13]

Will need to make a new issue about ha_config_set_helper and ha_set_config_entry_helper . Even if we add the "ha_config" thing to accepted names, these two names in particular need to be changed one way or the other to avoid future confusion, or potentially even combined

[github-actions]

The tool ha_bulk_control uses the verb Control, which isn't in the current styleguide. I'll update AGENTS.md and styleguide.md to include ha_[config_]<verb>_<noun> as the standard pattern and add a list of accepted exceptions, including ha_restart, ha_bulk_control, ha_read_file, and others, to ensure they aren't flagged as violations.

🔍 Analysis

The documentation for tool naming conventions in AGENTS.md and .gemini/styleguide.md is inconsistent and does not fully reflect the actual tool surface of the project. Specifically:

1. Incongruent Rule Lines: Both documents state a strict ha_<verb>_<noun> pattern, but the codebase (and even the examples in AGENTS.md) extensively uses a ha_config_ namespace prefix (e.g., ha_config_set_helper, ha_config_remove_area).
2. Missing Verbs: remove is used by several tools (e.g., ha_remove_todo_item, ha_remove_zone) and listed in AGENTS.md, but it is missing from the primary naming convention list in .gemini/styleguide.md.
3. Accepted Exceptions: There are several "one-off" tools that use verbs outside the approved list (e.g., ha_restart, ha_reload_core, ha_report_issue, ha_bulk_control, ha_read_file) because forcing them into a get/set/call pattern would reduce clarity. These currently trigger warnings in Gemini Code Assist.
4. Internal Docstring Inconsistency: .gemini/styleguide.md lists one set of verbs for tool names but a different, expanded set for docstring starters, leading to confusion during code review.

This drift causes friction for contributors whose PRs are flagged by automated tools for following one document while violating the other, or for following established patterns in the codebase that aren't yet codified in the documentation.

🛠️ Suggested Steps

1. Update AGENTS.md to explicitly permit the ha_config_ namespace prefix and include a list of "Accepted Exceptions" for tools that don't fit the standard pattern.
2. Update .gemini/styleguide.md to match the verb list in AGENTS.md (adding remove), permit the ha_config_ prefix, and list the same set of accepted exceptions to prevent false-positive warnings during PR reviews.
3. Align the docstring verb requirements with the tool naming verbs where possible, while acknowledging that natural language descriptions can be more flexible.

📊 Technical Analysis (for maintainers)

Root Cause

The project has evolved to include config-specific tools (using ha_config_) and utility/system tools (like ha_restart) that prioritize clarity over strict adherence to the initial 6-verb pattern. However, the documentation and the automated styleguide rules were never updated to reflect these established patterns.

Affected Code

The following documentation files need alignment:

• AGENTS.md (around line 400)
• .gemini/styleguide.md (around line 70 and 110)

The actual tool surface includes approximately 34 tools with the ha_config_ prefix and ~18 tools using non-standard verbs that are currently "valid" in practice but "invalid" in documentation.

Proposed Fix

AGENTS.md alignment

--- a/AGENTS.md
+++ b/AGENTS.md
@@ -400,14 +400,26 @@
 ## Writing MCP Tools
 
 ### Naming Convention
-`ha_<verb>_<noun>`:
-- `get` — single item (`ha_get_state`)
-- `list` — collections (`ha_list_areas`)
-- `search` — filtered queries (`ha_search_entities`)
-- `set` — create/update (`ha_config_set_helper`)
-- `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`)
+Tools follow the `ha_[config_]<verb>_<noun>` pattern:
+- `get` — single item retrieval (`ha_get_state`, `ha_config_get_automation`)
+- `list` — collections (`ha_list_areas`, `ha_config_list_groups`)
+- `search` — filtered queries (`ha_search_entities`, `ha_hacs_search`)
+- `set` — create/update operations (`ha_config_set_helper`, `ha_set_zone`)
+- `delete` — delete operations (`ha_config_delete_dashboard`, `ha_delete_file`)
+- `remove` — remove registry items (`ha_remove_entity`, `ha_config_remove_area`)
+- `call` — execute operations (`ha_call_service`)
+
+**Accepted Exceptions:**
+The following tools are accepted as one-off operations where the standard pattern would be less clear:
+- `ha_restart`, `ha_reload_core`, `ha_check_config` (System management)
+- `ha_report_issue` (Diagnostic utility)
+- `ha_bulk_control` (Multi-entity operation)
+- `ha_import_blueprint`, `ha_install_mcp_tools` (External resources)
+- `ha_read_file`, `ha_write_file` (Filesystem operations)
+- `ha_hacs_*` (HACS integration namespace)
+
+**New Verbs:** Adding new verbs is permitted if no existing verb fits the operation, but should be discussed to ensure consistency across the tool surface.

.gemini/styleguide.md alignment

--- a/.gemini/styleguide.md
+++ b/.gemini/styleguide.md
@@ -69,14 +69,22 @@
 
 ## Tool Naming Convention
 
-All MCP tools MUST follow `ha_<verb>_<noun>` pattern:
+All MCP tools MUST follow `ha_[config_]<verb>_<noun>` pattern:
 
 - `ha_get_*` — single item retrieval
 - `ha_list_*` — collections
 - `ha_search_*` — filtered queries
 - `ha_set_*` — create/update operations
-- `ha_delete_*` — remove operations
+- `ha_delete_*` — delete operations
+- `ha_remove_*` — remove operations
 - `ha_call_*` — execute operations
+
+**Accepted Exceptions:**
+The following tools are exempt from strict naming pattern validation:
+`ha_restart`, `ha_reload_core`, `ha_check_config`, `ha_report_issue`, 
+`ha_bulk_control`, `ha_import_blueprint`, `ha_install_mcp_tools`, 
+`ha_read_file`, `ha_write_file`, `ha_hacs_*`, `ha_eval_template`,
+`ha_get_operation_status`, `ha_get_automation_traces`.
 
 Flag MEDIUM severity if tools don't follow this pattern.

Related Issues/PRs

• refactor(addon): move ha_config_set_yaml to dev channel only (breaking — stable toggle removed, set ENABLE_YAML_CONFIG_EDITING or use dev add-on) #942 - Investigation of ha_config_set_yaml description hardening.

---

🤖 Automated analysis by Issue Bot