Skip to content

Commit 71fe615

Browse files
kingpanther13claude
andcommitted
docs: add manage as approved verb for multi-modal tools
Tools like ha_manage_addon (homeassistant-ai#913) and ha_manage_custom_tool (homeassistant-ai#854) combine several operations (get/set/list/call) behind one tool. The existing verb list had no good fit — "manage" captures this pattern. Updated in all four locations: - AGENTS.md naming convention + docstring verb list - .gemini/styleguide.md naming convention + docstring verb list Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent a7ec04a commit 71fe615

2 files changed

Lines changed: 4 additions & 2 deletions

File tree

.gemini/styleguide.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ All MCP tools MUST follow `ha_<verb>_<noun>` pattern:
7171
- `ha_set_*` — create/update operations
7272
- `ha_delete_*` — remove operations
7373
- `ha_call_*` — execute operations
74+
- `ha_manage_*` — multi-modal tools combining several operations
7475

7576
Flag MEDIUM severity if tools don't follow this pattern.
7677

@@ -101,7 +102,7 @@ Flag HIGH severity if errors use plain exceptions or dict returns instead of str
101102
These rules apply to new or modified tool docstrings in the PR diff only -- not to pre-existing docstrings in unchanged files.
102103

103104
**Flag MEDIUM severity when a new or modified tool docstring:**
104-
- Does not start with an action verb (`Returns...` should be `Get...`; valid verbs: `Get`, `List`, `Search`, `Create`, `Update`, `Delete`, `Remove`, `Execute`, `Call`)
105+
- Does not start with an action verb (`Returns...` should be `Get...`; valid verbs: `Get`, `List`, `Search`, `Create`, `Update`, `Delete`, `Remove`, `Execute`, `Call`, `Manage`)
105106
- Is missing entirely or is still a placeholder
106107
- References a non-existent tool (e.g., `ha_get_domain_docs` -- the correct name is `ha_get_skill_home_assistant_best_practices`)
107108
- Embeds a full parameter schema instead of deferring to `ha_get_skill_home_assistant_best_practices`

AGENTS.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -526,6 +526,7 @@ src/ha_mcp/
526526
- `delete` — delete dashboards, config entries, or files (`ha_config_delete_dashboard`, `ha_delete_file`)
527527
- `remove` — remove registry items (`ha_remove_entity`, `ha_config_remove_area`)
528528
- `call` — execute (`ha_call_service`)
529+
- `manage` — multi-modal tools combining several operations (`ha_manage_addon`, `ha_manage_custom_tool`)
529530

530531
### Tool Structure
531532
Create `tools_<domain>.py` in `src/ha_mcp/tools/`. Registry auto-discovers it.
@@ -551,7 +552,7 @@ def register_<domain>_tools(mcp, client, **kwargs):
551552
The single-line template is the default -- extend it only where it genuinely helps.
552553

553554
**Required for every tool:**
554-
- Starts with an action verb (`Get`, `List`, `Search`, `Create`, `Update`, `Delete`, `Remove`, `Execute`, `Call`)
555+
- Starts with an action verb (`Get`, `List`, `Search`, `Create`, `Update`, `Delete`, `Remove`, `Execute`, `Call`, `Manage`)
555556
- One sentence describing what the tool does (not how)
556557

557558
**Add `RELATED TOOLS` when** the tool is a workflow entry point and the natural next step is not obvious.

0 commit comments

Comments
 (0)