Skip to main content
Glama
Fistacho

ha-nexus-agent

by Fistacho
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Start an integration config flow

integrations_start_config_flow

Initiate a new configuration flow for a Home Assistant integration, returning the first step to guide setup.

Instructions

Start a new config flow for an integration domain.

Calls POST /api/config/config_entries/flow with {"handler": handler, "show_advanced_options": show_advanced_options}; HA has no WebSocket command for this. Each call creates a new, distinct flow.

Use when: beginning to set up a new integration through the same step-by-step flow the HA UI uses. Not for: editing an already-configured entry — use integrations_start_options_flow. Returns: the first step: {flow_id, step_id, data_schema, errors, ...}. Pass flow_id into integrations_submit_config_flow_step with the user's answers. Errors: raises httpx.HTTPStatusError if handler is not a valid flow-handler domain.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
handlerYesIntegration domain to configure, e.g. 'shelly'; from `integrations_list_flow_handlers`.
show_advanced_optionsNoWhether to include the integration's advanced-options fields in the returned form. False (default) hides them.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.25.1
    • addedInput schema / properties / handler / description
      Added value: +"Integration domain to configure, e.g. 'shelly'; from `integrations_list_flow_handlers`."
    • addedInput schema / properties / show_advanced_options / description
      Added value: +"Whether to include the integration's advanced-options fields in the returned form. False (default) hides them."
  2. Addedv0.4.0

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the annotations, the description discloses that the call uses a specific REST endpoint because no WebSocket command exists, that every call creates a new distinct flow, the shape of the first returned step, and the error behavior for an invalid handler domain. These details meaningfully lower the risk of misuse.

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 front-loaded with the core action, then cleanly structured into Use when, Not for, Returns, and Errors sections. Every sentence adds operational value without filler.

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 a multi-step integration setup flow, the description covers purpose, alternatives, return shape, and error behavior. With an output schema present and 100% parameter coverage, nothing critical is missing for correct invocation.

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 100%, so the schema already documents both parameters and their meanings. The description adds the handler payload context and reinforces that handler must be a valid flow-handler domain, but it does not substantially expand parameter semantics beyond the structured fields.

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 states a specific verb and resource: 'Start a new config flow for an integration domain.' It immediately distinguishes itself from the sibling options-flow tool by naming the alternative in the 'Not for' section.

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?

It gives explicit when-to-use guidance ('beginning to set up a new integration through the same step-by-step flow the HA UI uses') and an explicit exclusion with the correct alternative ('editing an already-configured entry — use integrations_start_options_flow'). It also tells the agent what to do next by passing flow_id into integrations_submit_config_flow_step.

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