feat: add ha_get_diagnostics tool

[SealKan]

Closes #1148

Summary

Adds ha_get_diagnostics to IntegrationTools for fetching the structured diagnostics dump that Home Assistant integrations expose.

Design choice: Option B (dedicated tool) — while Option A (extending ha_get_integration with include="diagnostics") would avoid a new tool, ha_get_diagnostics is conceptually distinct (debug data, not config/state data) and the explicit surface makes it easier to discover. The ha_get_integration tool already has 8 parameters; adding more would increase its cognitive load. The issue author noted "leaning A unless implementation surfaces a reason to split" — the parameter-count argument and conceptual clarity are that reason.

REST client:

• get_diagnostics(config_entry_id, device_id=None) — calls GET /api/diagnostics/config_entry/{id} or the device-scoped variant GET /api/diagnostics/config_entry/{id}/device/{device_id}

Tool:

• ha_get_diagnostics(config_entry_id, device_id=None) in IntegrationTools
• Returns {success, config_entry_id, diagnostics, [device_id]}
• Raises ToolError on 404 (not found), 403 (no diagnostics support), connection errors

Tests

7 unit tests in tests/src/unit/test_ha_get_diagnostics.py:

• Config-entry diagnostics (no device_id)
• Device-scoped diagnostics (device_id forwarded, key present in response)
• device_id key absent when not provided
• ToolError on 404
• ToolError on connection error
• ToolError on 403
• Diagnostics payload forwarded unchanged

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a dedicated tool for retrieving diagnostics data from Home Assistant integrations. By separating this functionality from existing tools, the implementation improves discoverability and reduces parameter complexity. The change includes both the necessary API client methods and the MCP tool definition, ensuring robust error handling and clear data output for debugging purposes.

Highlights

• New Diagnostics Tool: Added the ha_get_diagnostics tool to IntegrationTools to allow fetching structured diagnostics data from Home Assistant integrations.
• REST Client Update: Implemented get_diagnostics in the REST client to support both config-entry and device-scoped diagnostics retrieval.
• Comprehensive Testing: Added 7 unit tests to ensure correct handling of diagnostics payloads, device-scoped requests, and error scenarios (404, 403, connection errors).

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds a new ha_get_diagnostics tool and a corresponding REST client method to fetch integration diagnostics from Home Assistant, supported by new unit tests. The review feedback highlights a violation of the docstring style guide regarding the required structure and suggests improving error handling by avoiding broad exception catches and enhancing log detail.

[SealKan]

Addressed all review feedback: (1) docstring updated in 9ee12a1 with proper When to use and Caveats sections; (2) broad Exception is the project-standard pattern per AGENTS.md error handling guidelines — exception_to_structured_error auto-classifies 404/auth/timeout.

[SealKan]

Closing to keep PR count manageable. Will reopen when #1148 is labeled ready-to-implement.

[kingpanther13]

Quick note up front: this isn't a formal review — I do those after PRs are marked ready. Just glancing at the design while it's still draft and wanted to flag a couple of things before more code goes in.

1. Tool fit — leaning toward consolidation into ha_get_system_health rather than a new tool.

The endpoint /api/diagnostics/config_entry/{id} is the generic integration-diagnostics dump for any integration that ships a diagnostics.py module. ha_get_system_health is already the multi-mode diagnostic-data tool in this codebase — its include= accepts repairs, zha_network, zwave_network, and its title is literally "Get System Health (incl. ZHA/Z-Wave diagnostics)". The ZHA/Z-Wave includes are curated views specific to those integrations; adding a generic include=\"diagnostics\" mode (taking config_entry_id + optional device_id) would actually unify the design — same tool, established multi-mode shape, generic mechanism alongside the two integration-specific curated views.

The standalone ha_get_diagnostics name is also a problem: in HA parlance, logs, traces, system_health, and repairs are all "diagnostic" data, each already served by a separate tool. The bare name doesn't communicate that this one is the per-config-entry dump specifically.

On the "ha_get_integration already has 8 parameters" rationale for splitting — fair point on that tool, but ha_get_system_health only has one (include), and the natural shape there is include=\"diagnostics\", config_entry_id=..., device_id=.... With 88 tools we're well past the threshold where consolidation matters (AGENTS.md, "Tool Consolidation"), so I'd want to weigh that against the cognitive-load argument before adding another standalone surface.

2. Timeout — worth a look.

The diagnostics endpoint is synchronous: HA generates the dump inline during the HTTP request, then returns it. For ZHA networks with many devices or integrations that hit external APIs to assemble state, this can run 10–30+ seconds. get_diagnostics() inherits the rest_client default of 30s with no override, so slow integrations will hit HomeAssistantConnectionError on timeout with no escape hatch.

If kept as a standalone tool (or even folded in), this likely needs an explicit longer timeout for the call and a docstring note that the dump is generated on demand and can be slow.

Minimum bar regardless of the merge decision: cross-link the two tools' docstrings so an agent reading either one is pointed at the other.

Testing plan: I'd like to evaluate both shapes against a live HA instance before settling. BAT runs with no-context agents are the cleanest way to see which surface is actually easier to discover and use — happy to run that comparison once we have a candidate change to test against.