Skip to main content
Glama
homeassistant-ai

Home Assistant MCP Server

Official
by homeassistant-ai
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

Get Todo

ha_get_todo
Read-onlyIdempotent

Get all todo lists from Home Assistant or retrieve items from a specific list, optionally filtered by status.

Instructions

Get todo lists or items - list all todo lists or get items from a specific list.

Without an entity_id: Lists all todo list entities in Home Assistant. With an entity_id: Gets items from that specific todo list, optionally filtered by status.

LISTING TODO LISTS (entity_id omitted): Returns all entities in the 'todo' domain, including shopping lists and any other todo-type integrations.

Each todo list includes:

  • entity_id: The unique identifier (e.g., 'todo.shopping_list')

  • friendly_name: Human-readable name

  • state: Number of incomplete items or current status

GETTING TODO ITEMS (entity_id provided): Retrieves items from the specified todo list.

Status filter values:

  • needs_action: Items that still need to be done

  • completed: Items that have been marked as done

  • None (default): Returns all items regardless of status

Item properties:

  • uid: Unique identifier for the item

  • summary: The item text/description

  • status: Current status (needs_action or completed)

  • description: Optional detailed description

  • due: Optional due date (if supported)

EXAMPLES:

  • List all todo lists: ha_get_todo()

  • Get all items: ha_get_todo("todo.shopping_list")

  • Get incomplete items: ha_get_todo("todo.shopping_list", status="needs_action")

  • Get completed items: ha_get_todo("todo.shopping_list", status="completed")

USE CASES:

  • "What todo lists do I have?"

  • "Show me my shopping list"

  • "What's on my todo list?"

  • "Show completed items"

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
statusNoFilter items by status: 'needs_action' for incomplete, 'completed' for done. Only applies when entity_id is provided.
entity_idNoTodo list entity ID (e.g., 'todo.shopping_list'). If omitted, lists all todo list entities.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Tool Definition Quality

A4.3/5.0
Behavior4/5

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

Annotations already provide readOnlyHint=true and idempotentHint=true. The description adds behavioral details: the two modes, return structures (entity_id, friendly_name, state for lists; uid, summary, status, description, due for items), and how the status filter works. No contradictions.

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 description is well-structured with headings, bullet points, and examples. It is front-loaded with a clear summary. While somewhat lengthy, every section adds value, and the structure aids readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool complexity (two modes) and high schema coverage, the description covers the tool's behavior, return structure, and common use cases. It does not rely on an output schema (though one exists) but explains return values explicitly. No critical gaps.

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 description coverage is 100%, so the baseline is 3. The description adds value by explaining the effect of each parameter (e.g., 'entity_id' lists all lists when omitted, 'status' filter values with defaults) and provides examples that clarify usage beyond the schema.

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 clearly states the tool gets todo lists or items, with two distinct modes: listing all lists (no entity_id) and getting items from a specific list (with entity_id). It is specific, uses a verb+resource structure, and distinguishes from sibling tools like ha_remove_todo_item or ha_set_todo_item.

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?

The description explicitly explains when to omit vs. provide entity_id, and optionally filter by status. It includes examples and use cases. It does not explicitly mention when not to use this tool vs. mutation siblings, but annotations (readOnlyHint=true) and the read-only nature make it clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/homeassistant-ai/ha-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server