smarthome_command_plan

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

The only behavioral addition is that invocation routes through the domain-agent dispatcher under JWT, tenant, and company scope, which is useful auth/context info beyond the annotations. However, destructiveHint=true is not elaborated — the description never discloses what the action changes or what side effects it may cause. It does not contradict the annotations.

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

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

The description is compact — three lines of mechanism plus a two-item arg list — with no filler or repetition. The action name is front-loaded and the routing context earns its place as scope information. The only issue is that brevity comes at the cost of substance, which is a completeness concern, not a structure flaw.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool marked destructiveHint=true with an output schema, the description omits the one thing an agent needs: what command_plan accomplishes and what it changes. The routing/scope note is present, but with dozens of smarthome_* and domain-dispatch siblings, there is no functional description to support correct selection. Basic parameter semantics exist, but the core contract of the tool is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning; it does add one-line glosses — 'Free-text objective' for message and 'Optional JSON string of structured inputs' for inputs. This distinguishes the two params beyond their names and defaults, but stays generic: no example JSON, no expected keys, and no domain-specific guidance for command_plan. It beats an empty schema but does not fully compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description says only 'Run the smarthome domain agent action `command_plan`', which restates the tool name without explaining what a command plan does. It never states the functional outcome, such as generating or executing a smart-home command sequence. This is a near-tautology: the agent learns the mechanism (dispatcher routing) but not the purpose, and cannot distinguish it from smarthome_scene_assist or smarthome_automation_review.

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

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

No sentence addresses when to choose this tool. The description offers no alternatives, exclusions, or triggering conditions, and the routing note ('routes through the platform's domain-agent dispatcher') describes mechanics, not usage context. An agent cannot decide between this and dispatch_domain_agent or other smarthome_* siblings.

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