starlink_reboot

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly warns that the dish will lose connectivity for 2–5 minutes, which is critical for a disruptive reboot operation. It also mentions the write-enable prerequisite, providing useful operational context beyond the raw tool name.

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 and front-loaded: it states the action, prerequisites, impact, and intended use cases in two sentences with no filler. Every sentence earns its place.

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 single-parameter reboot tool with an output schema, the description covers what the tool does, when to use it, what preconditions exist, and the most important behavioral consequence (connectivity loss). Nothing essential is missing for an agent to decide whether and how to invoke it.

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?

The schema already documents the confirm parameter with 100% coverage ya la descripción refuerza que debe ser true para ejecutar el reinicio. The description adds practical meaning by tying the confirm flag to the execution precondition, which is valuable beyond the schema's default value.

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 states a specific verb and resource ('Reboot the Starlink dish') and clearly distinguishes this from the sibling read-only tools like starlink_status and starlink_alerts. The action is unambiguous and unique among the siblings.

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?

The description gives explicit use cases: 'recover from stuck states or apply pending firmware updates.' It also states prerequisites (STARLINK_WRITE_ENABLED=true and confirm=true), though it does not explicitly list when not to use it or contrast with alternative tools.

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