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

The description discloses rich behavior: hard-linking unchanged files, read-only MiSTer access, retention-based removal of old snapshots, and SSH/backup_dir prerequisites. However, “Old snapshots beyond the configured number are removed” conflicts with destructiveHint=false, which says the tool is not destructive. Because the description explicitly describes deletion while the annotation marks it non-destructive, this is an annotation contradiction.

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 with the main action. Each sentence adds useful context: hard-link efficiency, read-only source access, retention behavior, and prerequisites.

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?

Given that an output schema exists and the input schema is fully described, the description provides enough operational context for an agent to understand the tool. It covers side effects, retention, and prerequisites; the remaining issue is the annotation conflict rather than missing description content.

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 100%, so the schema already documents host and dry_run thoroughly. The description mentions backup_dir, but that is a configuration prerequisite rather than a parameter, and it adds no host or dry_run semantics beyond what the schema provides.

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 resource: copying saves and save states into a dated snapshot in the configured backup folder. This is clearly distinct from siblings such as launch, get_status, and run_update.

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?

Explains the operation and prerequisites (SSH and backup_dir), giving clear context for when the tool applies. It does not explicitly state when not to use it or compare against alternatives, but no sibling tool appears to offer equivalent backup functionality.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds a real operational constraint by stating SSH is required. It also discloses that output is section-structured and that core-named sections override [MiSTer], which is behavior beyond the annotations. No failure behavior (e.g. unreachable host) is described.

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?

Three short sentences, front-loaded with what is read and how it is parsed, then the section override rule, then the SSH prerequisite. No filler and nothing repeated from the schema verbatim.

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 read-only tool with an output schema and fully documented parameters, the description covers purpose, structure, and the SSH requirement. The remaining gap is minor: it does not say what happens when a requested section or file is absent.

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 the baseline is 3, but the description earns a bump by explaining the meaning of the section parameter — [MiSTer] is global and core sections override it — which the schema only hints at with an example. It also clarifies that alternate ini files exist, complementing the file parameter's own description.

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 (read) and resource (MiSTer.ini, or an alternate ini), plus the shape of the result: parsed into sections the way MiSTer reads it. That parsing detail distinguishes it from a generic file-read tool and implicitly from the write-side sibling set_ini.

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?

It gives a prerequisite ("Needs SSH") and explains the section hierarchy so the agent knows how to scope the read, but it never names the alternative tools (set_ini for writes, get_status for hosts) or states when not to use it. Usage is inferable rather than explicit.

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

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

Annotations only declare readOnlyHint/openWorldHint; the description goes well beyond them by disclosing prerequisites (core and attract_mode require SSH), what capabilities/limitations mean, and the server-level dry_run flag that changes whether writes are executed. That is exactly the kind of context annotations cannot carry.

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?

Front-loaded with 'Start here.' and then dense, field-by-field explanation. A little run-on in the capabilities/limitations sentence, but nearly every clause conveys new semantics an agent must interpret output correctly.

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 an output schema present, the description needn't enumerate return values, and instead explains the meaning of the harder fields (capabilities, limitations, core, attract_mode, dry_run). Complete for a zero-required-param read tool; only the sibling routing 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 100% and the host parameter is documented in the schema itself, so the description adds no further syntax or format detail. Baseline 3 applies when the schema does the work.

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 names the resource (MiSTer status) and enumerates exactly what the report contains: model, current game, capabilities, limitations, core, attract_mode. That is far more specific than the name alone, though it stops short of explicitly contrasting with siblings like list_systems or get_ini.

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?

'Start here' is an explicit first-call directive, and the host note ('Omit when the call already says which (a ref does)') tells the agent precisely when the single parameter is unnecessary. No exclusion against sibling tools is stated, which keeps it below a 5.

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

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.

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds which data is exposed (readers, mappings, last-scan UID) but does not disclose whether results are cached, how many MiSTers are covered, or what happens if no card has been scanned — modest added value.

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?

A single compact sentence with no filler, and the most useful cross-reference (map_nfc_card UID default) is placed at the end where it is memorable. The grammatical fragment structure is slightly awkward but costs little space.

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?

An output schema exists, so explaining return values is redundant — yet that is essentially all the description does, leaving the action verb and usage context unaddressed. For a simple read tool that is borderline adequate, but the definition doesn't fully pull its weight alongside the structured fields.

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?

With one parameter and 100% schema description coverage, the schema already explains 'host' (MiSTer name from get_status, omit when a ref supplies it). The description contributes nothing further about the host parameter, so the baseline of 3 applies.

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 sentence is a noun-phrase fragment that enumerates what the tool surfaces (NFC readers, card-to-game mappings, last scanned card) but never states the verb — the listing action is only inferable from the title. It does distinguish content from siblings implicitly and name-checks map_nfc_card, but an agent reading the description alone has to guess that this is a read/list operation.

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?

There is no explicit when-to-use or when-not-to-use guidance. The parenthetical about map_nfc_card defaulting to the last scanned card's UID hints at a sequencing relationship, but it is oblique and doesn't tell the agent when to call list_nfc versus write_nfc_card or map_nfc_card.

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

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

Annotations already declare readOnlyHint true and openWorldHint false, so the safety profile is covered. The description still adds useful substance: the listing is scoped per MiSTer (matching the host parameter), and each entry includes indexed game counts and the running core.

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?

Two sentences, front-loaded with what is listed and what each entry contains, then the follow-up usage. There is slight density in the comma-and-parenthesis parentheticals, but no wasted words.

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 simple, side-effect-free single-parameter listing tool with an output schema, the description covers what is listed, per what host, and how the ids are used downstream. Return shape is handled by the output schema, so nothing important 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?

The single parameter has 100% schema description coverage and already explains the host/ref convention, so the schema does the work. The description does not mention the host/ref selection behavior itself, so it adds nothing to what the schema provides. That meets the baseline for fully covered schemas.

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 concrete verb and resource ('The systems each MiSTer can launch') and enumerates the categories (consoles, computers, arcade) plus what each row carries (game count, core). This makes the tool's distinct role clear relative to siblings like get_status, which reports hardware status, or search_games, which consumes the ids it produces.

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?

It tells the agent such ids are the input to search_games, and that the id can also be passed to launch(system=...) for a core with no game (e.g. a computer core). That is a concrete use case and a pointer to two specific alternatives, though it does not say when *not* to call this listing (e.g. if the system id is already known from a ref).

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description reinforces this by explaining the card is never written to and read-only cards/toys work. It also discloses a refusal path (already-mapped cards) and a prerequisite human step, which annotations cannot express. Minor gap: what happens on re-mapping to a different game or an invalid game ref is unstated.

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?

Three short sentences, each carrying distinct information: what happens, who it works with, and how to invoke it. The key constraint (no card writing) is front-loaded.

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 an output schema present, return values needn't be described, and the description covers prerequisites, card compatibility, and refusal behavior. It stops short of covering edge cases like an unknown game ref or an already-mapped card being reassigned.

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 100%, and the schema already explains that omitting uid uses the card scanned in the last 2 minutes. The description restates the omit-uid workflow but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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 concrete verb and resource (map a card to a game) plus the key mechanism: the mapping lives in Zaparoo, not on the card. That mechanism implicitly separates it from the sibling write_nfc_card, so an agent can tell the two apart without reading schemas.

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?

Gives a usable procedure ('Ask the user to scan the card on the game's MiSTer first, then call this without uid') and a condition for failure ('Refuses a card that's already mapped'). It does not explicitly name write_nfc_card as the alternative when the user does want to write to the card, leaving that inference to the agent.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful context: the records are Zaparoo's own and include games launched from the MiSTer menu (a non-obvious inclusion rule), plus that rows carry a ref. It says nothing about ordering guarantees across modes or result limits, so it adds value but stays thin.

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?

Two sentences, front-loaded with the scope, and every clause carries information (data source, menu-launch inclusion, ref for replay). The conversational phrasing ('play the last thing again') is slightly informal but not wasteful.

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 an output schema present and annotations covering read-only semantics, the description only needs to frame the data and its quirks; it does that by explaining provenance and the ref field. Minor gaps remain around mode-specific behavior and limits, but nothing blocks correct invocation.

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 75% and the schema already explains host, mode ('recent' vs 'top'), and system with examples. The description only contributes the ref/host interaction obliquely; it adds no syntax or semantics for limit or mode beyond what is structured.

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 opening clause names the resource and scope concretely ('what's been played on each MiSTer') and adds the data source ('Zaparoo's own records'). It is clearly a read/history query, distinct from launch or get_status, though it never names a sibling to contrast with.

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?

Usage is only implied: 'play the last thing again' hints at the replay workflow via launch, and the host parameter note says to omit it when a ref already identifies the host. There is no explicit statement of when to choose recent vs top, or when to prefer this over search_games.

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

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

Annotations declare destructiveHint=true; the description goes further by naming exactly what is destroyed (unsaved in-game progress) and by mandating user confirmation before the call. It also adds host-resolution behavior not covered by 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?

Two sentences, front-loaded with the action, followed by the risk warning and the default-targeting rule. Nothing is padded or repeated from the schema.

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-optional-param destructive action with an output schema and full annotations, the description covers the action, its consequence, the required user confirmation, and host defaults. Nothing an agent needs in order to call it safely 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 coverage is already 100%, so baseline is 3; the description adds genuine meaning by explaining the fallback semantics of omitting host ('acts on the one MiSTer that's running something'), which the schema itself only hints at.

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 ('end whatever is running') and destination ('back to the MiSTer menu'), which cleanly distinguishes it from write-oriented siblings like launch or run_update. The scope ('whatever is running') is unambiguous.

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?

Gives a clear precondition for calling: confirm with the user first because progress is lost. It also explains default targeting when host is omitted. It does not name an alternative tool, but there is no obvious competing sibling for this action.

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

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

Beyond the destructiveHint=true annotation, the description discloses duration (several minutes), a possible reboot at the end, the game-running refusal, and the hourly rate limit. These are exactly the behavioral traits an agent needs before invoking a destructive action.

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?

Four short sentences, front-loaded with the action, then duration/reboot, then refusal and rate-limit. Every sentence contributes distinct, useful information.

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?

Given an output schema exists and annotations cover the safety profile, the description still adds the operational context (duration, reboot, refusal, rate limit) that neither structured field provides. Nothing an agent needs to call this correctly 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 coverage is 100%, so both parameters are fully documented in the input schema, including the 'Must be true' constraint on confirm and the no-default note on host. The description adds no parameter semantics beyond what the schema already provides, so baseline 3 applies.

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 names a specific operation ('Start Update All') on a specific resource (a MiSTer's own screen) and enumerates what gets updated (cores, Main, Linux). This clearly distinguishes it from siblings like set_ini or launch.

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?

It gives clear context for when this runs (an Update All) and explicit preconditions for refusal (a game running) and a rate limit (once an hour per MiSTer). It doesn't name an alternative tool, but the sibling set makes the choice obvious.

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

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

Annotations declare readOnlyHint=false but give no reason; the description supplies that reason by disclosing the side effect — a file is written to /media/fat/screenshots. That is genuine added context beyond the structured fields. It stops short of saying what the call returns (image payload vs. path) or how the write failure is surfaced.

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?

Three short sentences, action first, side effect second, default behavior third. Nothing is padded and nothing needs re-reading.

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 zero-required-parameter tool with full schema coverage and a declared side effect, this is nearly sufficient. The one gap is the return shape — whether the agent gets image content back or just a file path — which is not covered by an output schema and is only implied by 'as an image'.

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% and the single parameter is well documented as 'MiSTer name from get_status', so baseline would be 3. The description goes slightly beyond by explaining the runtime fallback behavior when host is omitted, which the schema only gestures at with 'omit when the call already says which'.

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 resource: 'Capture what a MiSTer is showing, as an image.' No sibling tool (get_status, launch, backup_saves, etc.) overlaps with this action, and the description makes the distinction obvious without needing the schema.

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?

'Without host, uses the one MiSTer that's running something' gives a clear condition for the host-omitted call path. There are no true alternatives among siblings, so no exclusions are needed, though it never explicitly says when to prefer this over, say, inspecting state via get_status.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, so safety is covered; the description adds genuinely new behavior — that the search fans out across every MiSTer, that duplicates across hosts are returned twice with distinct refs, and what `variant` disambiguates. It stops short of noting limits or empty-result behavior.

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?

Three short, front-loaded paragraphs with no filler; the matching rule and scope come first. Some of the result-shape explanation (ref, variant) is arguably redundant given an output schema exists, but it is brief and earns its place through the cross-host duplicate caveat.

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 four-parameter read-only search with a full schema and an output schema, the description covers the non-obvious parts: multi-host fan-out, duplicate results, ref-to-host binding, and variant disambiguation. Nothing an agent needs to call and interpret it correctly 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 coverage is 100%, so the baseline is 3, but the description adds real meaning on top: 'every word must match' specifies AND-matching that the schema's 'Words in the game's name' does not, and 'optionally in one system' clarifies the system parameter's filtering role.

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 resource — 'Find games in each MiSTer's Zaparoo library by name' — and pins down matching semantics ('every word must match') plus the optional system scope. This is clearly distinguishable from siblings like list_systems or list_nfc.

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?

Usage is implied rather than stated: the mention of 'a ref for launch' hints at the search-then-launch workflow, but no alternative tool is named and no when-not condition is given. An agent must infer that this is the discovery step before launch.

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

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

Goes well beyond the annotations: it discloses the timestamped backup filename, that the change only applies on next core load, that certain keys (main, bootcore, shared_folder, debug) are refused, and that SSH is required. These are exactly the operational facts an agent needs before mutating a config file.

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?

Four short sentences, front-loaded with the main action and scope, then backup, timing, refusals and prerequisite. Every sentence carries distinct, non-redundant information.

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 mutating config tool with full annotations and an output schema, the description covers safety (backup), timing (next core load), blocked inputs and auth (SSH). Nothing an agent needs in order to invoke it correctly 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?

With 100% schema description coverage the schema already documents key, file, host, value (including null removal), dry_run and section. The description reinforces the global/per-core and remove semantics but adds no syntax or constraints beyond what the schema provides, so baseline 3 is appropriate.

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 (set/remove), resource (one MiSTer.ini setting) and scope (globally or for one core), and clarifies it preserves the rest of the file. That cleanly separates it from the read-only sibling get_ini without naming it.

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?

Clear context for when to use it: setting or removing a single key in a specific section, with the deferred-effect note. It does not explicitly point to get_ini for reading or to dry_run for previewing, so the alternative-routing guidance is implicit rather than explicit.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description reinforces this concretely ('Overwrites whatever the card held'). It also discloses behavior annotations cannot express: a blocking wait of up to a minute and a required human step. Return value detail is omitted, but an output schema exists so that is acceptable.

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?

Three short sentences, front-loaded with the action and its effect, followed by the destructive caveat and the human-in-the-loop timing. No filler and every sentence carries information an agent needs.

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 two-parameter, destructive hardware-writing tool with an output schema, the description covers purpose, side effect, precondition, and blocking behavior. The main omission is any mention of the map_nfc_card sibling, leaving the agent to infer which NFC operation to choose.

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 100%, and both parameters ('game' with ref format, 'reader' tied to list_nfc) are fully documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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 resource ('Write a game onto the NFC card') plus the physical target (reader attached to the game's MiSTer) and the outcome (tapping launches the game). It does not distinguish itself from the sibling map_nfc_card, which an agent could easily confuse with this operation.

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?

Gives clear operational context: ask the user to place the card first, and the call blocks up to a minute. That is actionable pre-call guidance. It stops short of saying when to prefer this over map_nfc_card or what to do if the card is absent at timeout.

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