Skip to main content
Glama
Fistacho

ha-nexus-agent

by Fistacho
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Submit an options flow step

integrations_submit_options_flow_step
Destructive

Submit user input for a Home Assistant options-flow step to advance the form or apply new options to an existing config entry.

Instructions

Submit a step of an options flow.

Calls POST /api/config/config_entries/options/flow/{flow_id} with user_input. What this does depends entirely on the integration domain: an intermediate step just advances the form, while the step that finishes the flow applies the new options to the existing config entry, replacing its previous options. HA does not signal in advance which step is the last one, so any submitted step — not only a visibly "final" one — can be the one that overwrites the options.

Use when: providing the values an options-flow step asked for. Not for: reading the current step without submitting — there is no separate "get options flow" tool; call integrations_start_options_flow again to restart it; cancelling a flow before it finishes — use integrations_abort_options_flow. Returns: the next step (form), a step with errors, or the entry's updated result. The returned step's last_step field is True only when the integration explicitly declares this is the final step, and None otherwise — most integrations leave it None even on their actual last step, so None does not mean more steps remain. Errors: raises httpx.HTTPStatusError if flow_id is unknown or expired. Limits: any submitted step, not only a visibly "final" one, may overwrite the entry's previous options; the integration may reach an external device or cloud service while validating the submitted values.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
flow_idYesFlow id from `integrations_start_options_flow`.
user_inputYesAnswers for the current step, matching the fields in the flow's `data_schema`.

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 / flow_id / description
      Added value: +"Flow id from `integrations_start_options_flow`."
    • addedInput schema / properties / user_input / description
      Added value: +"Answers for the current step, matching the fields in the flow's `data_schema`."
  2. Addedv0.4.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantial context: any submitted step may overwrite previous options, Home Assistant does not signal in advance which step is final, and integrations may reach external devices or cloud services while validating. It also describes return shapes and the error condition for unknown or expired flow IDs.

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 and front-loaded, with clear Use/Not for/Returns/Errors/Limits sections. It is somewhat long and repeats the warning that any submitted step may overwrite options, which slightly reduces conciseness.

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 destructive, open-world options-flow submission tool with an output schema, the description covers purpose, alternatives, return values, errors, and overwrite risks thoroughly. An agent has enough context to call it correctly and understand the consequences.

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%, and the schema already documents both `flow_id` and `user_input`, including that `user_input` must match the flow's `data_schema`. The description reinforces but does not meaningfully extend parameter semantics beyond that baseline.

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: 'Submit a step of an options flow,' and explicitly names the API endpoint. It distinguishes the tool from siblings by naming `integrations_start_options_flow` and `integrations_abort_options_flow`, and explains that its effect depends on the integration domain.

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 'Use when' and 'Not for' sections, including the alternative for cancelling (`integrations_abort_options_flow`) and the warning that there is no separate get-current-step tool. This leaves no ambiguity about when to invoke this tool versus restarting or aborting a flow.

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