Skip to main content
Glama

Report Issue or Feedback

ha_report_issue
Read-onlyIdempotent

Collects Home Assistant MCP diagnostics and prepares a ready-to-file GitHub issue with logs and redacted secrets for bugs, agent feedback, or feature requests.

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

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

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv9.2.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description is consistent with that: it produces an issue_url link rather than filing on the server. Beyond the annotations it discloses that the response is LARGE and field-narrowable, that logs are embedded in issue_body but stripped from the URL to fit GitHub's limit, that secrets are redacted while error messages are kept, and that a textless call still returns diagnostics with placeholders.

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 critical constraint (use before filing, else closed in 24 hours) is front-loaded and the paragraphs are organized by decision order: what it does, when to use, what to pass, how to read the response. It runs long with some redundancy in the quoted clarifying question and the instruction pointers, but nearly every sentence carries operational value.

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 gaps that matter: report-type disambiguation, the sequencing of instructions/missing_tool_hint checks, the anonymisation obligation, and the duplicate check. Since an output schema exists, it correctly avoids enumerating return fields in prose beyond the ones that change agent behavior.

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 already 100%, so the schema carries most parameter meaning. The description still adds cross-parameter behavior the schema cannot express: `fields=` is the escape hatch for the oversized response, `report_type` drives which report text goes where, and omitting report text degrades gracefully to placeholders rather than failing.

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 first sentence names a specific verb and two concrete outputs: diagnostics collection plus a ready-to-file GitHub issue (title, body, URL). It also scopes the resource to ha-mcp itself, so an agent can immediately tell this apart from the many ha_* configuration siblings that operate on Home Assistant rather than on the MCP server.

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?

It states the trigger explicitly ('Use it before filing any GitHub issue about ha-mcp') and the consequence of skipping it ('a bug report without this report is closed after 24 hours'). It also handles ambiguity in report_type by giving the literal clarifying question to ask the user, and it names the alternative path (checking missing_tool_hint first) when a tool appears missing.

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