Skip to main content
Glama
homeassistant-ai

Home Assistant MCP Server

Official

Report Issue or Feedback

ha_report_issue
Read-onlyIdempotent

Collect diagnostics and generate a complete GitHub issue for ha-mcp bugs, feedback, or feature requests, including logs and report details.

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 the report is about a missing tool: a stale client tool list (not a bug) is the usual cause.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
titleNoOne-line summary of what broke or what is requested, for the issue title.
fieldsNoReturn 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.
ai_modelNoYour own model identity, as specific as you know it. Do not invent a version.
client_appNoThe 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_callsNoThe tool call(s) that produced the problem, verbatim: name, arguments and the (shortened) response.
descriptionNoWhat 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_typeNo'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_promptNoThe user message that led to the problem, verbatim.
user_commentNoThe user's own words on what went wrong or what bothered them, verbatim. Ask the user for it; never write it yourself.
tool_call_countNoNumber of ha_* tool calls made since the issue started; determines how many log entries to include.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv8.7.0
    • 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."
  2. Changed10 schema fields changedv8.6.0
    • 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."
      +}
  3. First observedv7.14.2

TDQS

A4.6/5.0
Behavior4/5

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

Adds substantial context beyond the readOnly/idempotent annotations: response size and the fields= narrowing lever, secret redaction, the GitHub URL-length truncation of log sections, and the placeholder behavior when no text is passed. It does not, however, say anything about rate limits or whether repeated calls are cached, so it stops short of a 5.

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 purpose then progressively operational detail, and every paragraph carries actionable content. It is longer than strictly necessary — the quoted clarifying question and the URL-limit aside could be trimmed — keeping it just below a 5.

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

Completeness5/5

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

For a 10-parameter, zero-required tool with an output schema, the description covers the missing pieces: it defers return-value detail to the schema, points to the `instructions` output key for the mandatory anonymisation/duplicate-check workflow, and tells the agent not to surface raw output to the user.

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 description coverage is 100%, so the baseline is 3. The description still adds value by explaining how the free-text input is consumed ('Pass the report text in the call'), what fields= narrows, and by framing report_type as a judgment call rather than a raw enum.

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?

The opening sentence states a specific verb and resource ('Get diagnostics and a finished GitHub issue') and enumerates the three supported report kinds. It is instantly distinguishable from every sibling ha_* tool, which are Home Assistant operations rather than a self-reporting/diagnostics tool.

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?

Explicit when-to-use ('Use it before filing any GitHub issue about ha-mcp') with a concrete consequence for skipping it, plus a decision prompt for the ambiguous report_type case and an ordered pre-check ('Check missing_tool_hint FIRST when the report is about a missing tool').

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

Deploy Server

Other Tools