hass-mcp

ha_list_services

List Home Assistant services and their fields to discover available actions for automations and scripts.

Instructions

List Home Assistant services and their fields.

Input Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Implementation Reference

src/index.ts:85-95 (handler)

The MCP tool registration and handler for 'ha_list_services'. It uses an empty input schema, calls ha.listServices(), and returns the services JSON.

server.tool(
  'ha_list_services',
  'List Home Assistant services and their fields.',
  ListServicesInput.shape,
  async () => {
    const services = await ha.listServices()
    return {
      content: [{ type: 'text', text: JSON.stringify(services, null, 2) }],
    }
  },
)

src/tools.ts:17-17 (schema)
The Zod schema for ha_list_services input — an empty strict object (no parameters accepted).
```
export const ListServicesInput = z.object({}).strict()
```

src/index.ts:85-95 (registration)

Registration of the tool named 'ha_list_services' on the MCP server via server.tool().

server.tool(
  'ha_list_services',
  'List Home Assistant services and their fields.',
  ListServicesInput.shape,
  async () => {
    const services = await ha.listServices()
    return {
      content: [{ type: 'text', text: JSON.stringify(services, null, 2) }],
    }
  },
)

src/ha.ts:106-109 (helper)
The HomeAssistantClient.listServices() method that connects via WebSocket and delegates to the home-assistant-js-websocket getServices() function.
```
async listServices() {
  const connection = await this.ensureConnected()
  return await getServices(connection)
}
```

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.7May 6, 2026

TDQS

A3.8/5.0

Behavior3/5

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

No annotations are present, so the description carries the full burden. The verb 'List' implies a read-only, non-destructive operation, but it does not explicitly state that it does not modify state, what permissions might be required, or the structure of the returned data. The simple nature of the tool makes this acceptable, but it lacks explicit behavioral disclosure.

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?

The description is a single concise sentence that directly states the tool's purpose without any filler. It is appropriately sized for a simple list operation and earns its place.

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?

For a zero-parameter tool with no output schema, the description is largely complete. It specifies that the tool lists services and their fields, which communicates the scope. However, it does not mention use cases or connection to sibling tools, which could add context, but given the simplicity, a 4 is appropriate.

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?

The tool has zero parameters, and the input schema is empty, so the description does not need to explain parameter semantics. The baseline for 0 parameters is 4, and the description correctly omits param details that don't exist.

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 'List Home Assistant services and their fields' clearly states the action (List) and the resource (Home Assistant services), and it distinguishes itself from sibling tools like ha_list_states, ha_list_areas, and ha_list_devices by targeting a different domain. The mention of 'fields' adds specificity.

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

Usage Guidelines2/5

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

There is no guidance on when to use this tool versus alternatives. It does not mention related tools like ha_call_service for invoking services or ha_list_states for listing entity states. The description provides no context for selecting this tool.

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

Deploy Server