Skip to main content
Glama

Get logbook entries

history_get_logbook
Read-onlyIdempotent

Fetch human-readable Home Assistant logbook entries from the last N hours, optionally filtered by entity, to review state changes and triggered automations as a narrative.

Instructions

Get human-readable logbook entries from the last N hours.

Calls GET /api/logbook/<start>, optionally filtered by entity_id, where start is now - hours.

Use when: a narrative of what happened (state changes, triggered automations) is more useful than raw state-history records. Not for: raw per-state timestamps and values for one entity — use history_get_state_history. Returns: HA's raw logbook payload — a list of {when, name, message, entity_id, ...}-shaped entries. Errors: raises httpx.HTTPStatusError if the HA API request fails. Limits: only as far back as the recorder integration has retained logbook data.

Input Schema

NameRequiredDescriptionDefault
hoursNoHow many hours back from now to fetch, e.g. 24 for one day. Default 24.
entity_idNoFull entity ID to filter to, e.g. 'light.kitchen'. Omit to return logbook entries for every entity.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.25.1
    • addedInput schema / properties / entity_id / description
      Added value: +"Full entity ID to filter to, e.g. 'light.kitchen'. Omit to return logbook entries for every entity."
    • addedInput schema / properties / hours / description
      Added value: +"How many hours back from now to fetch, e.g. 24 for one day. Default 24."
  2. First observedv0.3.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive), but the description adds genuinely non-structured behavior: the exact error type raised on API failure (`httpx.HTTPStatusError`) and the retention constraint that data only goes back as far as the recorder integration retains logbook data. It also sketches the returned payload shape.

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

Conciseness5/5

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

Front-loads the core action, then organizes supporting detail into tight 'Use when / Not for / Returns / Errors / Limits' fragments. Every line earns its place with no redundant prose.

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?

An output schema exists, yet the description still summarizes the payload shape, and it covers errors and retention limits on top of the two well-documented params. Nothing an agent needs to invoke this correctly is missing.

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 description coverage is 100%, so both `hours` and `entity_id` are already fully documented with defaults and examples. The description restates the optional entity_id filter and the `start = now - hours` derivation but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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?

States a specific verb and resource ('Get human-readable logbook entries'), gives the underlying API route, and explicitly distinguishes itself from the sibling `history_get_state_history`. An agent can select it 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 Guidelines5/5

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

Provides an explicit 'Use when' condition (narrative of state changes and triggered automations) and an explicit 'Not for' exclusion naming the alternative tool for raw per-state timestamps. This is a complete routing rule.

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