Skip to main content
Glama
Sign In
Home Assistant MCP Server

Home Assistant MCP Server

by rilhia
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Get long-term statistics

get_statistics
Read-onlyIdempotent

Retrieve hourly, daily or monthly long-term statistics for Home Assistant sensors to track energy and temperature trends. List available statistic ids or return mean, min, max and sums per period.

Instructions

Long-term statistics (hourly, daily, monthly aggregates that outlive the normal history), used for energy, temperature trends and any sensor with a state class. Without statistic_ids it lists the available statistic ids, optionally filtered by query. With ids it returns mean, min, max, sum, state or change per period, plus a small summary.

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": "get_statistics"
  }
}

Input Schema

NameRequiredDescriptionDefault
endNoISO end time.
hoursNoHow far back to look when start is not given.
queryNoWhen listing, text matched against id and name.
startNoISO start time. Overrides hours.
typesNo
periodNohour
max_pointsNoMaximum periods per statistic, newest kept.
statistic_idsNoStatistic ids, usually entity ids such as sensor.energy_total. Omit to list what exists.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.1

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare a safe, idempotent read, so the description needn't restate safety. It does add genuine behavioral content beyond them: the dual list-vs-fetch mode, and since there is no output schema, the disclosure that responses carry mean/min/max/sum/state/change per period plus a small summary is valuable. Missing are any notes on data availability limits or volume of results when many ids are requested.

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?

Three tight sentences, front-loaded with the resource definition before the mode logic, and every clause carries information. The parenthetical definition is dense but earns its space by making the tool's domain unambiguous.

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 an 8-parameter, no-required-argument read tool with no output schema, the description covers what the resource is, how the two modes differ, and what the payload contains. That is sufficient for an agent to invoke it correctly without guessing.

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

Parameters3/5

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

Schema coverage is 75%, so the schema already documents most parameters; the description reinforces statistic_ids ('omit to list what exists'), query (as a listing filter) and the aggregate types by naming them. It says nothing about start/end/hours interplay beyond what the schema states, nor about max_points trimming or period granularity tradeoffs, so it does not meaningfully exceed the schema baseline.

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 names a specific resource — long-term statistics — and defines it concretely as hourly/daily/monthly aggregates that outlive normal history, used for energy and temperature trends. That definition implicitly and effectively separates it from get_history, which returns raw state history, so an agent can pick between them without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly states the two operating modes: omit statistic_ids to discover which statistics exist (optionally narrowed by query), or supply ids to fetch aggregated values. What's missing is an explicit routing statement such as 'use get_history for raw state changes' — the alternative is inferable from the 'outlive the normal history' phrasing but never named.

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