Skip to main content
Glama
homeassistant-ai

Home Assistant MCP Server

Official
by homeassistant-ai
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

Report Issue or Feedback

ha_report_issue
Read-onlyIdempotent

Generate bug and feedback report templates with captured diagnostic logs, helping you file issues or agent-behavior feedback for Home Assistant.

Instructions

Get diagnostic information and templates for filing issue reports or feedback.

This tool generates templates for TWO types of reports:

  1. Runtime Bug Report - For ha-mcp errors, failures, unexpected behavior

  2. Agent Behavior Feedback - For AI agent inefficiency, wrong tool usage

IMPORTANT FOR AI AGENTS: You MUST analyze the conversation context to determine which template to present:

šŸ› Present RUNTIME BUG template if:

  • User reports an error, failure, or unexpected behavior

  • A tool returned an error or incorrect result

  • Something is broken or not working in ha-mcp

šŸ¤– Present AGENT BEHAVIOR template if:

  • User mentions YOU (the agent) used the wrong tool

  • User suggests a more efficient workflow

  • User reports YOUR inefficiency or mistakes

  • User says you should have done something differently

If unclear which type, ASK the user: "Are you reporting a bug in ha-mcp, or providing feedback on how I used the tools?"

WHEN TO USE THIS TOOL:

  • "I want to file a bug/issue/report"

  • "This isn't working"

  • "You should have used [other tool]"

  • "That was inefficient"

OUTPUT: Returns both templates plus diagnostic data. The full response is LARGE (the captured logs appear in the raw log keys AND inside each template) ā€” pass fields=... to fetch only the keys you need once you know which template applies. Key fields:

  • runtime_bug_template, agent_behavior_template ā€” pick based on context

  • recent_logs, startup_logs ā€” captured ha-mcp tool/server log entries

  • addon_logs ā€” addon container stdout/stderr (HA add-on installs only; empty string otherwise)

  • core_error_log ā€” Home Assistant error log (home-assistant.log) over REST; carries auth / integration errors that don't show in addon_logs

  • missing_tool_hint ā€” check this FIRST when the report is about a missing/unavailable tool; a stale client tool list (not a bug) is the usual cause, and refreshing the MCP connection is the fix

  • suggested_title, duplicate_check_urls, anonymization_guide

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
fieldsNoReturn 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.
tool_call_countNoNumber 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)

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Tool Definition Quality

A4.9/5.0
Behavior5/5

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

Annotations declare readOnlyHint=true and idempotentHint=true, so the agent knows it's safe. The description adds significant behavioral context: it returns large diagnostic data, includes log entries, and explains the `fields` parameter to manage response size. This goes well beyond what annotations provide.

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?

The description is well-organized with headings, bullet points, and clear sections, front-loading critical information. However, it is quite long; while every sentence is useful, some details could be trimmed without losing clarity. Still, it is structured effectively for an AI agent.

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?

Despite the tool's complexity and the presence of an output schema, the description covers all necessary context: how to choose the appropriate template, when to use the `fields` parameter, what diagnostic fields are available, and even hints about missing tools. It is fully complete for an agent to use correctly.

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

Parameters5/5

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

Schema coverage is 100% for the two parameters. The description adds substantial meaning: for `fields`, it lists all available keys and provides usage examples; for `tool_call_count`, it explains the default and maximum and the reasoning behind them. This greatly enhances understanding 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?

The description clearly states the tool generates diagnostic information and templates for filing issue reports or feedback, and it distinguishes between two specific report types (Runtime Bug Report and Agent Behavior Feedback). This sets it apart from all sibling tools, none of which are for reporting issues.

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?

The description provides explicit conditions for when to use the tool with concrete examples (e.g., 'I want to file a bug', 'This isn't working', 'You should have used [other tool]'). It also instructs the agent to ask the user for clarification if the report type is unclear, effectively guiding the agent's decision-making.

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

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/homeassistant-ai/ha-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server