Port OS Smart Home

group_manage

DestructiveIdempotent

Organize rooms and device groups: create, rename, change members, enable, disable, merge or delete them.

Create, delete, add/remove members, MOVE_MEMBER and rename default to providerSync BEST_EFFORT: send supported native group changes first, verify provider readback, then save Port OS intent. A provider failure falls back locally and is PARTIALLY_APPLIED. PORTOS_ONLY sends nothing; FAIL_ON_PROVIDER_ERROR fails customer intent if a required provider change fails, while retaining received provider facts. Native effects cannot be rolled back. Undeclared support is NOT_SUPPORTED with reason NOT_DECLARED and does not by itself make the result partial. OUTSIDE_PRINCIPAL means native changes are not attempted through another principal's account; the authorized Port OS change can still apply.

Read group IDs and etags with group_query first. Every reference to one group in a batch uses the same starting etag. MOVE_MEMBER takes memberEndpointId plus source and target group references with both etags; a lone add cannot implicitly displace another exclusive native group. Contradictory edits return 400; list position is not a procedural ordering mechanism. MERGE_INTO and aggregate/route enablement accept only PORTOS_ONLY. Rename does not automatically merge groups.

DELETE_GROUP can delete provider groups. Routes not confirmed retired are disabled and orphaned, so rediscovery cannot resurrect the deleted group. SET_ENABLEMENT can hide an aggregate without deleting it; SET_GROUP_ROUTE_ENABLEMENT changes one provider route's contribution locally. Obtain explicit user authorization for the exact MERGE_INTO or DELETE_GROUP targets and effects before calling.

Hue supports native group creation, deletion, membership and rename. Roborock supports room rename only; membership changes do not reshape robot maps. Sonos native group mutations are not implemented. Declared support is authoritative. Use control for device actions such as power, playback or cleaning.

Customer intent commits as one batch. Set validateOnly=true to report PLANNED or NOT_SUPPORTED dispatches without sending or writing. idempotencyKey is required otherwise: use one unique key per intended change, and reuse it only for the identical request after a lost or uncertain response. A stale etag returns PRECONDITION_FAILED; re-read and resolve the change before a new request.

Inspect status COMMITTED, PARTIALLY_SUCCEEDED or FAILED, each result's APPLIED, PARTIALLY_APPLIED or NOT_APPLIED status, and providerDispatches. Failed batches retain provider facts and report operations whose messages were sent as NOT_APPLIED without group etags; errors identify failing operations. Do not report a partial save as fully synchronized or automatically repeat native writes.

Input Schema

Name	Required	Description
`operations`	Yes	Compatible intended changes in one customer batch. Reuse each group's starting etag across its references; contradictory edits cannot be resolved by list order.
`validateOnly`	No	Validate and authorize the batch and report planned or unsupported provider dispatches without sending messages or writing.
`idempotencyKey`	No	Unique key for this intended change, at most 255 characters. Required unless validateOnly is true.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 27, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already flag destructive=true and openWorld=true, but the description goes far beyond them: it discloses that native effects cannot be rolled back, that BEST_EFFORT falls back locally as PARTIALLY_APPLIED, that OUTSIDE_PRINCIPAL suppresses native attempts, and per-provider support (Hue create/delete/membership/rename, Roborock rename only, Sonos unimplemented). It also warns that deleting routes leaves them disabled and orphaned so rediscovery cannot resurrect them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and alternatives are front-loaded, but the body is a dense wall of internal status vocabulary (NOT_SUPPORTED, NOT_DECLARED, OUTSIDE_PRINCIPAL, PARTIALLY_APPLIED) and several sentences restate what the enum descriptions in the schema already say (providerSync, enablement). The information is valuable but the phrasing is spec-leak prose rather than scannable guidance, so not every sentence earns its place.

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 9-variant, destructive, provider-syncing batch mutation this covers the essentials: authorization requirements, idempotency, etag/precondition handling, per-provider capability matrix, partial-failure semantics, and interpretation of result statuses. The output schema exists, so the added status guidance ('Do not report a partial save as fully synchronized') is interpretation help rather than duplication.

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 the schema already documents operations, etags, providerSync and idempotencyKey; baseline would be 3. The description adds cross-cutting meaning the schema does not: one starting etag shared by every reference to a group in a batch, requestId correlation over position, idempotencyKey reuse only for the identical request, and that MERGE_INTO/SET_ENABLEMENT/route enablement accept only PORTOS_ONLY.

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?

Opens with a concrete verb+resource+scope: 'Organize rooms and device groups: create, rename, change members, enable, disable, merge or delete them.' It explicitly separates itself from siblings by naming group_query for reads and control for device actions, so an agent can route without opening any 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?

States when to use it (group organization), when to use alternatives ('Use control for device actions', 'Read group IDs and etags with group_query first'), and hard prerequisites ('Obtain explicit user authorization for the exact MERGE_INTO or DELETE_GROUP targets'). It also gives the dry-run path via validateOnly and the recovery path for stale etags/idempotency reuse.

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

All Port OS Smart Home tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?