Launch a game or core

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

Beyond the annotations (which state non-read-only, non-destructive, idempotent), the description discloses that the call blocks until the target reports running, that it refuses while busy, and that rapid repeats are rate-limited. Those are the operationally important traits an agent cannot infer from the hints.

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 action and completion condition come first, then the refusal rule and its alternative, then the rate-limit note. Every sentence carries distinct operational weight with no filler.

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?

With full schema coverage, an output schema handling return values, and annotations covering safety, the description fills the remaining gaps: blocking behavior, busy-state refusal, rate limits, and destructive side effects of the alternative tool.

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 coverage is 100%, so baseline is 3, but the description adds genuine meaning the schema does not express: 'game (by ref)' vs 'system (by id)' as mutually exclusive modes, and implicitly that host is derivable from a ref. The 'or' framing clarifies an exclusion the anyOf schema leaves open.

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?

States a specific verb and two distinct modes (launch a game by ref, open a system core by id), plus the completion semantics ('wait until the MiSTer reports it running'). This distinguishes it cleanly from siblings like return_to_menu and get_status.

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?

Explicitly names the preclusion condition (refuses while anything is running), routes the conflicting case to return_to_menu, and even advises asking the user first because unsaved progress is at stake. This is exactly the when/when-not/alternative structure.

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