Skip to main content
Glama
Fistacho

ha-nexus-agent

by Fistacho
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Start an options flow

integrations_start_options_flow

Start an options flow for an existing Home Assistant integration config entry to change its settings through its own options schema; returns first step data and flow_id.

Instructions

Start the options flow for an existing config entry.

Calls POST /api/config/config_entries/options/flow, passing entry_id as handler — HA's options-flow API reuses the config-flow request shape and documents handler as "the entry_id" in this context. Each call creates a new, distinct flow.

Use when: changing an already-configured integration's settings through its own options UI/schema. Not for: configuring a brand-new integration — use integrations_start_config_flow. Returns: the first step: {flow_id, step_id, data_schema, errors, ...}. Pass flow_id into integrations_submit_options_flow_step. Errors: raises httpx.HTTPStatusError if entry_id does not exist or the integration has no options flow.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
entry_idYesConfig entry ID to edit, from `system_list_integrations` or `system_get_all_integrations`.
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 / entry_id / description
      Added value: +"Config entry ID to edit, from `system_list_integrations` or `system_get_all_integrations`."
    • 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.9/5.0
Behavior5/5

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

Annotations declare the safety profile (readOnly=false, idempotent=false, destructive=false), and the description adds context beyond them: each call creates a new distinct flow (reinforcing the non-idempotent trait), the flow must be continued via integrations_submit_options_flow_step, and it raises httpx.HTTPStatusError when the entry_id is invalid or no options flow exists. This is substantive 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?

Front-loads the purpose, then uses labeled sections (Use when / Not for / Returns / Errors) that each earn their place. No filler or repetition.

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?

Even though an output schema exists (so return values need not be explained), the description still provides the critical chaining hint (pass flow_id onward) and error behavior. Nothing an agent needs to call this correctly is missing.

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 coverage is 100%, so baseline is 3, but the description adds genuine semantic value by explaining that entry_id is passed as 'handler' and that HA reuses the config-flow request shape for this endpoint. It does not describe show_advanced_options, but that parameter is already documented in 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?

States a specific verb+resource ('Start the options flow for an existing config entry') and immediately distinguishes itself from the sibling it is not ('Not for: configuring a brand-new integration — use integrations_start_config_flow'). An agent can route correctly without opening either 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?

Explicit when-to-use ('changing an already-configured integration's settings through its own options UI/schema') and when-not-to-use, naming the alternative tool. The full selection condition is stated.

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