Home Assistant MCP Server

Official

by homeassistant-ai

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Report Issue or Feedback

ha_report_issue

Read-onlyIdempotent

Generate diagnostics and a ready-to-file GitHub issue for ha-mcp bugs, agent feedback, or feature requests, including title, body, and submission link.

Instructions

Get diagnostics and a finished GitHub issue for a bug, agent feedback or a feature request.

Use it before filing any GitHub issue about ha-mcp: a bug report without this report is closed after 24 hours. report_type picks the kind of report; if it is unclear which, ask: "Are you reporting a bug in ha-mcp, giving feedback on how I used the tools, or requesting a feature?"

Pass the report text in the call: the server combines it with the diagnostics it collects into issue_title, issue_body (the full report with logs) and issue_url (a new-issue link with title and body filled in, log sections left out to fit GitHub's URL limit; error messages stay in, with secrets redacted). A call without text still returns diagnostics, with placeholders in the body.

The response is LARGE; fields= narrows it. Read instructions before showing anything to the user: it covers the missing-tool and known-client pre-checks, the duplicate check, the mandatory anonymisation step, and how to file the issue. Check missing_tool_hint FIRST when a tool is missing or rejects as unknown a parameter your tool list shows: a stale list (not a bug) is the usual cause.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "ha_report_issue"
  }
}

Input Schema

Name	Required	Description	Default
`title`	No	One-line summary of what broke or what is requested, for the issue title.
`fields`	No	Return only the specified top-level response keys. None = full response. Typical: 'issue_title,issue_body,issue_url,duplicate_check_urls,anonymization_guide,missing_tool_hint,known_client_issues_hint,instructions'. issue_body already embeds the relevant logs, so the raw log keys are only needed for your own analysis. Available keys: diagnostic_info, recent_logs, startup_logs, addon_logs, core_error_log, log_count, startup_log_count, formatted_report, issue_title, issue_body, issue_url, anonymization_guide, duplicate_check_urls, missing_tool_hint, known_client_issues_hint, python_upgrade_hint, instructions.
`ai_model`	No	Your own model identity, as specific as you know it. Do not invent a version.
`client_app`	No	The app and version the user runs you in, as the USER states it (usually on the app's About screen or from its --version command). Never guess it.
`tool_calls`	No	The tool call(s) that produced the problem, verbatim: name, arguments and the (shortened) response.
`description`	No	What went wrong in markdown: steps to reproduce, expected and actual behavior. For agent_behavior: what you did and what you should have done. For feature_request: what ha-mcp should do, why the user needs it, and what you tried.
`report_type`	No	'runtime_bug' when ha-mcp errored or behaved wrongly; 'agent_behavior' when the user says you used the wrong tool or worked inefficiently; 'feature_request' when the user wants ha-mcp to do something it cannot do yet.	runtime_bug
`user_prompt`	No	The user message that led to the problem, verbatim.
`user_comment`	No	The user's own words on what went wrong or what bothered them, verbatim. Ask the user for it; never write it yourself.
`tool_call_count`	No	Number of ha_* tool calls made since the issue started; determines how many log entries to include.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv9.1.2Nov 9, 2026

changedInput schema / properties / fields / description

Previous value: -"Return only the specified top-level response keys. None = full response. Typical: 'issue_title,issue_body,issue_url,duplicate_check_urls,anonymization_guide,missing_tool_hint,known_client_issues_hint,instructions'. issue_body already embeds the relevant logs, so the raw log keys are only needed for your own analysis. Available keys: diagnostic_info, recent_logs, startup_logs, addon_logs, core_error_log, log_count, startup_log_count, formatted_report, issue_title, issue_body, issue_url, anonymization_guide, duplicate_check_urls, missing_tool_hint, known_client_issues_hint, instructions."New value: +"Return only the specified top-level response keys. None = full response. Typical: 'issue_title,issue_body,issue_url,duplicate_check_urls,anonymization_guide,missing_tool_hint,known_client_issues_hint,instructions'. issue_body already embeds the relevant logs, so the raw log keys are only needed for your own analysis. Available keys: diagnostic_info, recent_logs, startup_logs, addon_logs, core_error_log, log_count, startup_log_count, formatted_report, issue_title, issue_body, issue_url, anonymization_guide, duplicate_check_urls, missing_tool_hint, known_client_issues_hint, python_upgrade_hint, instructions."

Changed4 schema fields changedv8.7.0Oct 15, 2026

changedInput schema / properties / description / description

Previous value: -"What went wrong in markdown: steps to reproduce, expected and actual behavior. For agent_behavior: what you did and what you should have done."New value: +"What went wrong in markdown: steps to reproduce, expected and actual behavior. For agent_behavior: what you did and what you should have done. For feature_request: what ha-mcp should do, why the user needs it, and what you tried."

changedInput schema / properties / report_type / description

Previous value: -"'runtime_bug' when ha-mcp errored or behaved wrongly; 'agent_behavior' when the user says you used the wrong tool or worked inefficiently."New value: +"'runtime_bug' when ha-mcp errored or behaved wrongly; 'agent_behavior' when the user says you used the wrong tool or worked inefficiently; 'feature_request' when the user wants ha-mcp to do something it cannot do yet."

changedInput schema / properties / report_type / enum

Previous value: -[
-  "runtime_bug",
-  "agent_behavior"
-]New value: +[
+  "runtime_bug",
+  "agent_behavior",
+  "feature_request"
+]

changedInput schema / properties / title / description

Previous value: -"One-line summary of what broke, for the issue title."New value: +"One-line summary of what broke or what is requested, for the issue title."

Changed10 schema fields changedv8.6.0Oct 1, 2026

addedInput schema / properties / ai_model

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Your own model identity, as specific as you know it. Do not invent a version."
+}

addedInput schema / properties / client_app

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The app and version the user runs you in, as the USER states it (usually on the app's About screen or from its --version command). Never guess it."
+}

addedInput schema / properties / description

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "What went wrong in markdown: steps to reproduce, expected and actual behavior. For agent_behavior: what you did and what you should have done."
+}

changedInput schema / properties / fields / description

Previous value: -"Return only the specified top-level response keys — the full response (both templates + logs + diagnostics, with log content repeated across the raw keys and templates) is very large. None = full response. Typical for a runtime bug: 'runtime_bug_template,suggested_title,runtime_bug_submit_url,duplicate_check_urls,anonymization_guide,instructions'; for agent feedback swap in agent_behavior_template and agent_behavior_submit_url. The templates already embed the relevant logs, so the raw log keys are only needed for your own analysis. Available keys: diagnostic_info, recent_logs, startup_logs, addon_logs, core_error_log, log_count, startup_log_count, formatted_report, runtime_bug_template, agent_behavior_template, anonymization_guide, suggested_title, runtime_bug_submit_url, agent_behavior_submit_url, duplicate_check_urls, missing_tool_hint, instructions."New value: +"Return only the specified top-level response keys. None = full response. Typical: 'issue_title,issue_body,issue_url,duplicate_check_urls,anonymization_guide,missing_tool_hint,known_client_issues_hint,instructions'. issue_body already embeds the relevant logs, so the raw log keys are only needed for your own analysis. Available keys: diagnostic_info, recent_logs, startup_logs, addon_logs, core_error_log, log_count, startup_log_count, formatted_report, issue_title, issue_body, issue_url, anonymization_guide, duplicate_check_urls, missing_tool_hint, known_client_issues_hint, instructions."

addedInput schema / properties / report_type

Added value: +{
+  "default": "runtime_bug",
+  "description": "'runtime_bug' when ha-mcp errored or behaved wrongly; 'agent_behavior' when the user says you used the wrong tool or worked inefficiently.",
+  "enum": [
+    "runtime_bug",
+    "agent_behavior"
+  ],
+  "type": "string"
+}

addedInput schema / properties / title

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "One-line summary of what broke, for the issue title."
+}

changedInput schema / properties / tool_call_count / description

Previous value: -"Number of tool calls made since the issue started. This determines how many log entries to include. Count how many ha_* tools were called from when the issue began. Default: 10. Max: 16 (limited by 200-entry log buffer: 16*4*3=192)"New value: +"Number of ha_* tool calls made since the issue started; determines how many log entries to include."

addedInput schema / properties / tool_calls

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The tool call(s) that produced the problem, verbatim: name, arguments and the (shortened) response."
+}

addedInput schema / properties / user_comment

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The user's own words on what went wrong or what bothered them, verbatim. Ask the user for it; never write it yourself."
+}

addedInput schema / properties / user_prompt

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The user message that led to the problem, verbatim."
+}

First observedv7.14.2Jul 29, 2026

TDQS

A4.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds real behavioral context beyond the annotations: the 24-hour closure rule, that the response is LARGE and fields= narrows it, that secrets are redacted, that a text-less call still returns diagnostics with placeholders, and that instructions must be read first. However, much of this is operational guidance rather than tool behavior, and the description partly shadows what the output schema already provides (issue_title, issue_body, issue_url).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose followed by prerequisites and response-shape notes in logical order. It is dense but each paragraph serves a distinct function; a few sentences (the missing_tool_hint paragraph) drift toward general agent coaching rather than this tool's contract.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 10 parameters, an output schema, and full annotation coverage, the description supplies the procedural context an agent needs (read instructions first, check missing_tool_hint, anonymise). It stops short of enumerating required inputs, but the schema and instructions key cover that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description still adds value: it says to pass the report text in the call, explains that report_type selects the kind of report, and clarifies that fields= narrows the response while issue_body already embeds the logs. That last note genuinely changes how an agent would set fields, going beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Get diagnostics and a finished GitHub issue') and enumerates the three report kinds it serves. No sibling tool in the list deals with diagnostics or issue filing, so the agent can distinguish it immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-to-use rule ('before filing any GitHub issue about ha-mcp', with the consequence that a report without it is closed after 24 hours) and an explicit disambiguation script for choosing report_type when unclear. Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server