Skip to main content
Glama

Get System Overview

ha_get_overview
Read-onlyIdempotent

Retrieve a categorized Home Assistant system overview covering version, location, timezone, entity counts, and active notifications to understand your setup before querying specific entities.

Instructions

Get AI-friendly system overview with intelligent categorization.

Returns comprehensive system information at the requested detail level, including Home Assistant base_url, version, location, timezone, entity overview, and active persistent notifications (if any). Use 'minimal' (default) for most queries. Domain counts and states_summary are always complete regardless of entity pagination.

Requests whose fields= are composed only of system_info, notification, repair, or server metadata fields skip the unrelated state, service, and registry reads.

Do not use this tool to inspect a known entity or a narrow set of entities. Use ha_get_state for one entity, ha_get_entity for registry metadata, or ha_search with a domain or area filter. An unprojected overview collects system-wide state, service, and registry data and can be expensive on large Home Assistant installations.

When the ha-mcp settings-UI sidecar is running (stdio mode, e.g. Claude Desktop / Claude Code) the response carries settings_url, the local URL of the tool-configuration page; in standalone HTTP / Docker modes with an HTTP settings prefix it instead carries settings_url_hint, saying where the page is mounted and how to construct the full URL. Hand whichever is present to the user when they ask how to enable or disable tools or change server settings.

The response also carries ha_mcp_update {current, latest, update_available} (PyPI for pip/Docker, the Supervisor store for the app) — proactively tell the user when update_available is true. Omitted for the unknown version, when HA_MCP_DISABLE_UPDATE_CHECK is set, or when the update check itself failed.

mcp_client reports the MCP protocol version, client info and client capabilities this call arrived with, for diagnosing client-specific behaviour. capabilities: null means the request carried none to read, not that the client declared none.

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_get_overview"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMax total entities across all domains (default: unlimited for minimal, 200 for standard/full).
fieldsNoReturn only the specified top-level response keys to reduce response size (e.g. ["system_info", "domain_stats"]). None = full response. Available keys: success, system_summary, domain_stats, area_analysis, ai_insights, pagination, partial, warnings, device_types, service_availability, system_info, notification_count, notifications, repair_count, dismissed_repair_count, repairs, repairs_error, tool_discovery, settings_url, settings_url_hint, read_only_mode, read_only_mode_hint, ha_mcp_update, mcp_client. Note: ``settings_url`` (stdio mode), ``settings_url_hint`` (standalone HTTP/Docker mode), the ``read_only_mode`` / ``read_only_mode_hint`` pair (only while Read Only Mode is on), ``ha_mcp_update`` (when an update check applies) and ``mcp_client`` are emitted regardless of ``fields=`` projection.
offsetNoNumber of entities to skip for pagination
domainsNoFilter to specific domains (e.g. 'light,sensor' or ['light','sensor']). None = all domains.
detail_levelNo'minimal': 10 entities/domain, top-5 states; 'standard': 200 entities/page, top-10 states (use offset for more); 'full': 200 entities/page + entity_id + state + full states.minimal
include_stateNoInclude state field for entities (None = auto based on level). Full defaults to True.
include_entity_idNoInclude entity_id field for entities (None = auto based on level). Full defaults to True.
include_notificationsNoInclude active persistent notifications.
max_entities_per_domainNoOverride default entity cap per domain (minimal=10, standard/full=unlimited). 0 = no limit on entities or states.
include_dismissed_repairsNoInclude user-dismissed/ignored repairs. Dismiss or restore one with ha_manage_updates(action='ignore_repair' / 'unignore_repair').

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv9.2.0

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds substantive behavior: the fields= projection shortcut skips unrelated state/service/registry reads, domain counts and states_summary stay complete regardless of pagination, and settings_url vs settings_url_hint appear conditionally by deployment mode. It even explains that capabilities: null means the request carried none, not that the client declared none — exactly the kind of non-obvious caveat annotations cannot express.

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

Conciseness3/5

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

The first three paragraphs are front-loaded and high value (purpose, usage, projection shortcut). The trailing three paragraphs about settings_url, ha_mcp_update, and mcp_client document response fields, which is largely redundant given an output schema exists, and they bloat a tool definition an agent must parse before calling.

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?

With 10 optional parameters, an output schema, and full annotation coverage, the agent has everything it needs: cost model, detail-level guidance, projection semantics, and the do-not-use alternatives. Nothing required to invoke it correctly is missing.

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 baseline is 3; the description earns above that by adding cross-parameter semantics the schema does not: 'minimal' is the recommended default, and domain counts/states_summary remain complete no matter how entity pagination is set. It does not restate limit/offset/domains, which the schema already documents well.

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

Purpose4/5

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

States a specific verb+resource ("Get system overview") and enumerates what the overview contains: base_url, version, location, timezone, entity overview, notifications. The lead-in phrase "AI-friendly ... with intelligent categorization" is marketing filler, but the concrete enumeration rescues it. Sibling differentiation is handled in the usage paragraph rather than here.

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?

Explicitly says to use 'minimal' (default) for most queries, then names the exact non-use cases and the correct alternatives: ha_get_state for one entity, ha_get_entity for registry metadata, ha_search for domain/area filters. It also warns the unprojected overview is expensive on large installations, giving the agent a cost-based selection criterion.

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