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

With no annotations, the description carries the full burden and does so thoroughly. It discloses that the command is silently ignored when not paused, is fire-and-forget with no acknowledgment, UDP packets are silently dropped if not listening, the frame count is not reported, and the return string is only a send confirmation. This fully reveals critical behavioral traits beyond basic functionality.

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?

Though lengthy, the description is structured with labeled sections (PURPOSE, USAGE, BEHAVIOR, FIRE-AND-FORGET, Transport, RETURNS). Each sentence conveys a necessary operational detail such as pause requirement, no-ack behavior, verification methods, and configuration. The length is justified by the tool's complexity, and it is front-loaded with the core purpose.

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?

The description covers purpose, usage, behavior, return value, transport, prerequisites, and verification strategies, even referencing sibling tools for confirmation. Given the fire-and-forget nature, no output schema, and no annotations, this description is fully complete for an agent to invoke the tool correctly and verify its effect.

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 tool has zero parameters, so there is no parameter meaning to clarify. The description instead provides useful invocation context (UDP transport, network_cmd_enable requirement), which adds value, but the parameter dimension is vacuously satisfied. Baseline 4 for no params 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?

The description opens with a precise purpose: "Step emulation forward by exactly one frame." It clearly distinguishes itself from sibling tools by emphasizing frame-precise stepping and even contrasts with long jumps using save/load states. This is a specific verb+resource+outcome with strong sibling differentiation.

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?

Explicit usage contexts are given: "frame-precise input automation, animation inspection, or letting the system initialize after a reset." It states the condition "ONLY effective while emulation is paused," instructs to call retroarch_pause_toggle first after checking retroarch_get_status, and recommends alternatives for long jumps. This is exemplary when-to-use versus when-not-to-use guidance.

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?

No annotations are provided, so the description carries full burden. It states the tool is a pure read with no side effects, describes the transport (NCI over UDP, with network_cmd_enable required), and lists potential errors (non-whitelisted param, parser breakage, timeout). This is very good, though missing details on empty values or error format.

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 well-structured with clear headings (PURPOSE, USAGE, NOTE, BEHAVIOR, RETURNS) and is front-loaded with the purpose. Every sentence adds value, and it is not overly verbose.

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 the tool's simplicity (one parameter) and lack of output schema, the description covers purpose, usage, behavior, and return format. It mentions error conditions and transport requirements. Minor omission: does not specify error return format, but overall very complete.

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 input schema has 100% coverage with detailed description of the 'name' parameter, including common values and caveats. The description adds little beyond what the schema provides, only repeating some info and adding the note about screenshot_directory not being exposed. Baseline of 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?

The description clearly states the tool reads a single RetroArch config parameter via NCI's GET_CONFIG_PARAM command. It distinguishes from siblings like retroarch_get_status and retroarch_screenshot, specifying different use cases.

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 explicitly says when to use this tool (to discover paths/settings without parsing retroarch.cfg) and when not to (for run-state, use retroarch_get_status). It also notes the screenshot directory is not exposed, pointing to retroarch_screenshot.

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?

With no annotations provided, the description fully shoulders the transparency burden. It states 'No side effects — pure read of emulator status via the NCI's GET_STATUS command', explains the contentless case ('Returns 'No content loaded' (state=contentless) when RetroArch is sitting at the menu with no ROM'), and discloses error behavior on UDP timeout. This goes beyond what structured fields could convey.

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 organized with clear labels (PURPOSE, USAGE, BEHAVIOR, RETURNS) and every sentence contributes essential information. Despite its length, there is no redundancy or filler; it remains succinct while covering all necessary facets. The front-loaded purpose lets an agent quickly classify the tool.

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 there is no output schema and no annotations, the description compensates by fully specifying the return format for both loaded and contentless states, including line-by-line details. It covers prerequisites (call after ping), side effects, and error cases, making it essentially self-contained for an agent to invoke confidently.

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 tool has zero parameters, so the schema provides no semantics to enrich. The baseline for 0 params is 4. The description adds value by detailing the return payload, which is more relevant than parameter documentation for this no-arg tool.

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 opens with a clear, specific verb ('Report') and resource ('whether RetroArch is currently playing or paused, plus the loaded system, game basename, and CRC32'). It explicitly distinguishes itself from sibling tools like retroarch_get_config by stating what this tool does not do ('this tool only reports run-state and the loaded ROM identity'), making it easy for an agent to select it correctly.

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?

Provides explicit when-to-use guidance: 'Call after retroarch_ping to learn what (if anything) is loaded; before retroarch_pause_toggle to decide whether the toggle will pause or unpause; before retroarch_frame_advance (which only steps when paused); whenever you need to confirm the previous fire-and-forget control command...'. It also names an alternative for a different use case: 'For RetroArch settings (paths, flags) use retroarch_get_config instead'. This is exemplary usage guidance.

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?

With no annotations provided, the description carries full responsibility and excels. It discloses destructive impact on live state, fire-and-forget UDP behavior with no acknowledgment, silent drops when not listening, silent ignore when no save exists, and the need for follow-up verification. This goes well beyond what annotations would have provided.

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 lengthy but well-structured with PURPOSE/USAGE/BEHAVIOR/RETURNS labels. Some redundancy exists (e.g., repeated emphasis on verifying after load), but most sentences convey essential safety and operational details. It is denser than necessary but earns most of its length.

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?

Despite having no output schema, the description explicitly states the return line and its limited meaning. It covers transport configuration, prerequisites (network_cmd_enable), failure modes, and verification strategies. For a complex, side-effect-heavy tool with zero parameters, this is exceptionally complete.

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 tool has zero parameters, so the baseline is 4. The description adds semantic context by explaining that the 'currently-selected slot' is the one save_state_current targets, and how to select a specific slot via sibling tools, effectively giving meaning to the implicit parameter state. This exceeds the baseline.

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 clearly states the tool's function: restoring emulator state from RetroArch's currently-selected save slot. It distinguishes itself from siblings by explicitly contrasting with retroarch_load_state_slot and retroarch_reset, making the purpose 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?

The description provides explicit when-to-use guidance: as a counterpart to save_state_current, for undoing writes/inputs, and for starting from a known baseline. It also gives clear alternative tools for different scenarios (load_state_slot for specific slots without changing pointer, reset for fresh boot), satisfying the when/not/alternatives criteria.

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?

With no annotations provided, the description fully carries the burden. It explicitly warns 'DESTRUCTIVE TO LIVE STATE: replaces ALL current emulator state with the named slot's contents', notes ROM/core version requirements, explains that LOAD_STATE_SLOT sends a reply unlike siblings, and clarifies no-op behavior and pointer invariants. This is thorough and goes far beyond basic info.

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 longer than average, but its labeled sections (PURPOSE, USAGE, BEHAVIOR, RETURNS) make it scannable and every sentence carries meaningful information. The detail is justified by the destructive nature and the need to separate from siblings. It is concise relative to the complexity.

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 no annotations, no output schema, and a high-risk destructive operation, the description covers all needed context: purpose, usage alternatives, behavioral side effects, transport details, timeout behavior, verification advice, and return format. Nothing material is missing for an AI agent to select and invoke this tool correctly.

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 description coverage is 100% and already provides rich detail: integer, min 0, slot range 0-9, no hard upper bound, no-op outside range, and no pointer change. The description adds one useful nuance—this tool addresses by number and ignores current-slot pointer entirely—but it mostly reinforces schema content. 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?

The description starts with a clear PURPOSE: 'Load state from an explicitly-named save slot number, without modifying RetroArch's currently-selected slot pointer.' It uses a specific verb and resource, and explicitly distinguishes itself from the sibling retroarch_load_state_current. The scope and uniqueness are fully clarified.

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 USAGE section explicitly states when to use this tool ('use to load from a specific slot when you don't want to disturb the current-slot pointer') and when not to ('For loading from the currently-selected slot, use retroarch_load_state_current'). It also notes the absence of a save counterpart and suggests the alternative state_slot_plus/minus walking approach. This is exemplary guidance.

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?

With no annotations provided, the description fully discloses critical behavioral traits: it is fire-and-forget, receives no acknowledgment, silently drops UDP if not listening, and requires verification via other tools. It also states it modifies emulator run state, giving the agent a complete operational awareness.

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 well-structured with clear section headers and every section adds essential operational detail. It is longer than a minimal toggle description, but the additional length is justified by the lack of annotations and the need to explain the fire-and-forget behavior and verification steps.

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 no annotations, no output schema, and zero parameters, the description covers all essential aspects: what it does, when to use it, expected behavior, transport details, and how to verify results. It provides a complete mental model for an agent to invoke this tool correctly.

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 tool takes zero parameters, and the schema already shows no properties. The description adds no parameter-specific details because there are none to document. This aligns with the baseline for zero-parameter tools.

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 opens with a specific verb ('Toggle') and resource ('RetroArch's pause state'), explicitly stating it pauses if running and unpauses if paused. This clearly distinguishes it from siblings like retroarch_get_status or retroarch_frame_advance, which serve different purposes.

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 usage section explicitly directs when to use the tool (e.g., before memory/screenshot sequences for a stable state) and names companion tools like retroarch_get_status and retroarch_frame_advance. It also warns that the NCI exposes only a toggle, preventing incorrect use as separate pause/unpause commands.

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?

With no annotations, the description carries the full burden and does exceptionally well: it declares 'No side effects — pure liveness probe,' explains the UDP transport and prerequisite (network_cmd_enable = true), the default host/port, and the ~5-second timeout with an explicit list of error conditions (RetroArch not running, disabled commands, wrong host/port, firewall blocking).

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 organized into labeled sections (PURPOSE, USAGE, BEHAVIOR, RETURNS) and every sentence adds value—purpose, usage context, transport details, error behavior, and return format. No fluff or redundancy.

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?

The description is complete for a zero-parameter liveness probe: it covers prerequisites, default connection details, timeout and error conditions, and the exact return format with an example. Even without an output schema or annotations, the agent has everything needed to invoke and interpret the 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?

This tool has 0 parameters, so the schema coverage is 100% and the baseline is 4. The description does not need to discuss parameters and doesn't, which is appropriate. It adds no parameter information because none exists.

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 explicitly states 'Verify connectivity to RetroArch's Network Control Interface and return the running RetroArch version string,' which is a specific verb+resource. It clearly distinguishes this from sibling tools like retroarch_get_status, which confirms game loading rather than basic connectivity.

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 when-to-use guidance: 'Call once at start-of-session before issuing other tool calls.' It also names the alternative for verifying a loaded game: 'Use retroarch_get_status afterwards to confirm a game is loaded.' This fully addresses when to use and when to choose another tool.

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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses 'No side effects — pure read', transport details over UDP, behavior while paused/running, specific error conditions (no memory map, address out of range, length out of bounds, timeout), and the important nuance that RetroArch may return fewer bytes than requested when crossing memory-region boundaries.

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 well-structured with clear labels (PURPOSE, USAGE, BEHAVIOR, RETURNS) and is front-loaded with the primary purpose. It is longer than strictly necessary, and the distinction between the two memory APIs is explained twice (once in USAGE and again in a dedicated comparison section), but the redundancy is mild and each section adds value.

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 with no output schema and no annotations, the description is remarkably complete. It describes the return format, error conditions, fallback strategy, transport prerequisites, and core-specific address behavior. The only missing element might be example output, but the return format is clearly specified.

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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: it provides concrete example address spaces (SNES WRAM at 0x7E0000, GBA EWRAM at 0x02000000, Genesis 68K RAM at 0xFF0000), clarifies that addresses are system-map not CHEEVOS, and explains the 4096-byte cap is due to NCI line-length limits. This goes well beyond the baseline 3.

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 opens with a specific verb+resource statement: 'Read up to 4096 bytes from emulated memory via the libretro core's system memory map (READ_CORE_MEMORY) and return them as a hex dump.' It clearly distinguishes this tool from retroarch_read_ram by naming the alternative and explaining when each should be used.

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 USAGE section explicitly states when to use this tool versus alternatives: 'Preferred memory-read tool when the loaded core advertises a memory map (most modern cores do). If it returns 'no memory map defined', fall back to retroarch_read_ram.' It also provides a pairing recommendation with retroarch_write_memory and describes the RAM-hunt workflow, giving concrete context for use.

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?

No annotations exist, so the description carries full burden. It discloses 'No side effects — pure read', behavior when paused/running, error conditions (invalid address, length bounds, timeout), and the caveat that fewer bytes may be returned at region boundaries. Transport and config requirements are also stated.

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 long but well-structured with PURPOSE, USAGE, BEHAVIOR, API comparison, and RETURNS sections. It front-loads the core purpose and usage, and every paragraph adds necessary context for correct invocation. No fluff.

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 no output schema and no annotations, the description fully covers return format, error handling, transport details, address space differences, and edge cases. It provides enough context for an agent to decide when to use this tool and interpret results correctly.

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 schema already provides detailed parameter descriptions. The description adds extra semantic value by explaining the CHEEVOS address space distinction, cross-core non-portability of addresses, and the pairing with write_ram. This goes beyond the schema.

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 opens with a specific verb and resource: 'Read up to 4096 bytes from emulated memory via the achievement (CHEEVOS) address space (READ_CORE_RAM) and return them as a hex dump.' It clearly distinguishes from sibling retroarch_read_memory by explicitly naming the CHEEVOS space and framing this tool as a fallback.

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?

Provides explicit when-to-use guidance: 'use when retroarch_read_memory returns "no memory map defined"' and contrasts the two memory APIs, naming preferred vs fallback. Also suggests pairing with retroarch_write_ram for write-back, and warns that addresses don't carry over across cores.

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?

Without annotations, the description carries full burden. It discloses destructive nature ('triggers the loaded core's reset routine... Unsaved game progress is lost'), the soft-reset semantics versus power cycle, fire-and-forget behavior with no acknowledgement, and silent UDP drops. Also recommends verification via other tools.

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?

Structured in labeled sections (PURPOSE, USAGE, BEHAVIOR, TRANSPORT, RETURNS) with the core action first. Every sentence provides necessary operational details (reset semantics, destructive effects, verification steps, transport requirements) without redundancy.

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 the tool's complexity (missing annotations, no output schema, zero parameters), the description covers all essential aspects: transport protocol, prerequisites, return value, side effects, and verification strategy. It also cross-references sibling tools for follow-up, making it self-sufficient.

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 tool has zero parameters, so the description cannot add parameter semantics beyond the schema. However, it clarifies the return value ('Single line 'Game reset'') and that it is only a send confirmation, which is useful context. Baseline for no params is 4.

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?

Clearly states the function: 'Soft-reset the running game — equivalent to pressing the console's reset button (NOT a power cycle).' Distinguishes from power cycle and mentions alternatives like load state, so it is unambiguous and differentiated from 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?

Explicitly explains when to use: 'Use to start fresh from the game's reset vector.' Also says 'To return to a specific known-good point instead of boot, use retroarch_load_state_current or retroarch_load_state_slot...' This provides clear usage guidance and names alternative tools.

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?

With no annotations, the description carries the full burden and excels. It discloses that the tool is 'DESTRUCTIVE TO TARGET SLOT FILE', overwriting without prompt/backup, that it is fire-and-forget with no acknowledgment, that UDP packets can be silently dropped, and that state files are bound to ROM/core versions. Verification strategies are also provided.

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 long but exceptionally well-structured with labeled sections (PURPOSE, USAGE, BEHAVIOR, RETURNS). Every sentence adds critical operational detail—overwrite risk, fire-and-forget behavior, verification, transport config—making it dense 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?

The tool has no output schema, no annotations, and no parameters, so the description must fully compensate. It covers return value, failure modes, verification steps, transport prerequisites, and slot-selection mechanics. This is complete for a destructive, non-acknowledged UDP command.

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 tool has zero parameters, so the baseline is 4. The description adds essential meaning beyond the empty schema by explaining that the target is the 'currently-selected save slot' and how to select a specific slot using retroarch_state_slot_plus/minus. This is valuable semantic context absent from the schema.

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 opens with a specific verb and resource: 'Save the entire emulator state to RetroArch's currently-selected save slot (one of slots 0-9).' It clearly distinguishes the save action from sibling tools like retroarch_load_state_current and retroarch_state_slot_plus.

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?

Explicit usage guidance is provided: 'Use as a rollback point before risky writes, to bookmark interesting game states, or to share repro states.' It also explains when NOT to use it (for path-based I/O, use BizHawk/mGBA) and how to target a specific slot via sibling tools.

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?

No annotations are provided, so the description carries the full burden. It discloses fire-and-forget UDP behavior, no acknowledgement, silently dropped packets, lack of file-write confirmation, timestamped filenames, non-overwriting, and the inaccessible screenshot_directory. This is exceptionally thorough and leaves no critical ambiguity.

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?

Though long, the description is well-structured with clear labeled sections (PURPOSE, USAGE, BEHAVIOR, RETURNS) and every sentence delivers necessary operational detail. It is front-loaded with the purpose and uses formatting to enhance scannability, making the length justified.

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 the absence of annotations and output schema, this description is remarkably complete. It covers transport prerequisites, failure modes, verification strategies, and return-value semantics, and even explains how to locate the output file. It leaves no meaningful gap for an AI agent to misinterpret or misuse the 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?

With zero parameters and a 100% coverage baseline, the description still adds significant value by explicitly explaining why there is no path argument: RetroArch uses its own configured directory, not exposed via the NCI. This prevents the agent from assuming a path parameter exists and clarifies the tool's role despite the empty schema.

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 opens with a clear, specific verb and resource: 'Capture a PNG screenshot of the current emulator display and save it to RetroArch's configured screenshot directory.' It also distinguishes itself from typical screenshot tools by explicitly stating it does NOT accept a path argument, which sets it apart from any sibling tools or generic expectations.

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?

Provides explicit when-to-use guidance: for inspection, sequence documentation, or verifying visible effects of fire-and-forget commands. It explains the workflow (pause/advance/load state first) and contrasts with observation alternatives like retroarch_get_status, retroarch_read_memory, and retroarch_read_ram, making the decision boundary clear.

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?

No annotations are provided, so the description fully bears the burden. It thoroughly details behavior: renders the message, fire-and-forget (no acknowledgment), UDP silent drops, messages not queued, line breaks stripped, and transport requirements. This exceeds typical transparency expectations for a simple notification tool.

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 well-structured with labeled sections (PURPOSE, USAGE, BEHAVIOR, etc.), making it easy to scan. It is front-loaded with the purpose. Although it is lengthy, every sentence adds value and does not contain fluff. It could be slightly more concise, but overall it is effective.

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 the tool's simplicity (1 parameter, no annotations, no output schema), the description is exceptionally complete. It covers purpose, usage, behavior, limitations, transport requirements, return format, and even mentions the lack of sibling tools. An agent can fully understand how and when to use this 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?

The single parameter 'message' has 100% schema description coverage. The description adds some context beyond the schema (e.g., fire-and-forget), but the schema already covers line breaks, consecutive calls, and length. Per guidelines, baseline is 3 when coverage is high, and while the description adds value, it does not significantly elevate parameter understanding beyond what is already in the schema.

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 clearly states the tool's purpose: 'Display a single-line notification message overlaid on the RetroArch window (OSD overlay).' It specifies the verb (display), resource (notification message), and location. It also distinguishes from siblings by stating 'this is the ONLY way to push text from the agent onto the RetroArch display.'

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 provides explicit use cases: 'debug output, progress markers during long-running scripts, or to communicate with a human.' It explains when to use (cosmetic communication) and gives guidance on the fire-and-forget nature and verification steps. However, it doesn't explicitly state when NOT to use; this is implied by the context.

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?

With no annotations, the description fully discloses behavior: it mutates the pointer, wraps/clamps, is fire-and-forget with no acknowledgment, UDP packets are silently dropped, and no slot number is returned. It also notes no effect on emulator memory/run state. This is exemplary transparency for a network command tool.

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 well-structured with labeled sections (PURPOSE, USAGE, BEHAVIOR, FIRE-AND-FORGET, Transport, RETURNS) and front-loads the core purpose. However, it is somewhat verbose with minor redundancy, such as repeating that the new slot number is not reported back in both the BEHAVIOR and RETURNS sections.

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 the tool's complexity (mutating RetroArch state via UDP), the description covers all necessary context: prerequisites, exact behavior, consequences, verification methods, and return value. It also addresses the lack of an output schema by explaining what the return line means.

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 tool has zero parameters and an empty schema, so there is nothing to explain; baseline 4 applies. The description adds value by explaining the unspoken semantics of the operation itself, though no parameter-specific detail is needed.

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 begins with 'Decrement RetroArch's currently-selected save slot pointer by 1' which clearly states the verb, resource, and expected effect. It also distinguishes from siblings by naming retroarch_state_slot_plus and retroarch_load_state_slot, making the tool's unique role 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?

Explicit guidance is provided: 'Counterpart to retroarch_state_slot_plus' and 'For loading a specific slot WITHOUT changing the pointer, use retroarch_load_state_slot.' It also advises tracking the slot client-side because no direct set/query exists, giving clear context on when and how to use this tool.

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?

No annotations are provided, so the description carries the full burden. It discloses mutation of the internal pointer, wrap/clamp behavior, fire-and-forget semantics with no acknowledgment, silent UDP drops, lack of slot-number reporting, and no effect on memory/run state. This is exemplary transparency.

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 front-loaded with PURPOSE, then USAGE, BEHAVIOR, and RETURNS. Though long, every sentence addresses a distinct operational need (e.g., NCI limitations, verification strategies, return behavior), and there is no fluff.

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 no annotations, no output schema, and zero parameters, the description must be self-sufficient. It covers purpose, usage, behavioral caveats, transport, verification, and return format — complete for the complexity of a fire-and-forget UDP command.

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?

This tool has zero parameters, so the schema coverage is 100% vacuously. The baseline for 0 params is 4; the description adds no parameter-specific details because none exist, but it explains the operational semantics fully without needing parameter documentation.

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 begins with a specific verb and resource: 'Increment RetroArch's currently-selected save slot pointer by 1 (e.g. slot 3 → slot 4).' This clearly distinguishes it from siblings like retroarch_state_slot_minus and retroarch_load_state_slot.

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?

Extremely explicit usage guidance: combine with save_state_current/load_state_current, pair with state_slot_minus, and explicitly states when to use retroarch_load_state_slot instead. It also warns about the inability to set the slot directly, which is critical for correct tool selection.

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?

No annotations are provided, but the description fully discloses behavioral traits: it is DESTRUCTIVE with no undo, disables RetroArch's hardcore mode, may write fewer bytes than requested if a read-only descriptor is hit, and returns an actual byte count. This goes well beyond the basic 'writes memory' expectation and covers side effects and edge cases.

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 long but well-structured with clear PURPOSE, USAGE, BEHAVIOR, and RETURNS sections. Every section adds essential information—fallback logic, destructive side effects, return format, and error conditions—with no filler or redundancy. The structure makes it easy for an agent to parse and extract key facts quickly.

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 no output schema, the description explicitly states the return format ('Wrote N bytes → ADDR_HEX') and explains the meaning of the count. It also covers error cases, prerequisites (network_cmd_enable), the distinction between the two memory APIs, and the fact that addresses don't carry across cores. This makes the tool fully understandable without external documentation.

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 input schema already provides highly detailed descriptions for both parameters, including the 0-255 range, 1-4096 length cap, sequential write behavior, and the distinction from CHEEVOS space (100% coverage). The description adds little new parameter-specific meaning beyond the schema, mostly repeating or rephrasing the same constraints, so the 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 opens with a specific verb and resource: 'Write a byte sequence to emulated memory via the libretro core's system memory map (WRITE_CORE_MEMORY).' It clearly identifies the target memory space and distinguishes this tool from the sibling retroarch_write_ram by stating this is the 'preferred' tool when a memory map is advertised.

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?

Provides explicit usage context: 'Use for cheats, debug pokes, and game-state mutations.' It names an alternative tool (retroarch_write_ram) as a fallback and specifies a prerequisite (use retroarch_save_state_current for rollback). This makes the when-to-use vs. when-not-to-use very clear.

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?

With no annotations provided, the description carries the full burden and excels. It discloses destructive overwrites with no undo, hardcore-mode disabling, fire-and-forget semantics with no acknowledgment, silent UDP drops, input validation limits, and bypassing of MBC/mapper/DMA semantics. This level of behavioral disclosure is exceptional.

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 long but well-structured with clear PURPOSE, USAGE, BEHAVIOR, and RETURNS sections, plus a bulleted comparison of the two memory APIs. It is appropriately detailed for a complex tool. Minor redundancy in repeating 'no ack' in multiple places costs a point, but overall it earns its length.

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 the tool's complexity, no output schema, and no annotations, the description is remarkably complete. It covers purpose, alternatives, behavioral caveats, transport requirements, input validation, return format, and verification strategies. It even notes the two distinct memory APIs and address-space non-portability across cores, leaving no critical gap.

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%, but the description adds substantial meaning beyond the schema: the 4096-byte NCI line-length cap, the distinct CHEEVOS address-space interpretation, sequential write ordering, and the implication of no acknowledgment for partial writes. It also clarifies that `bytes` length maps to the protocol limit and that `address` follows CHEEVOS conventions.

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 opens with a specific verb and resource: 'Write a byte sequence to emulated memory via the achievement (CHEEVOS) address space (WRITE_CORE_RAM).' It clearly distinguishes itself from the sibling retroarch_write_memory by naming the CHEEVOS address space and its role as a fallback, making the tool's purpose 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?

The description explicitly states when to use this tool: 'use when retroarch_write_memory returns no memory map defined or the core only supports the older CHEEVOS write API.' It also contrasts the two memory APIs, advises using retroarch_save_state_current for a rollback point, and explains when to follow up with other tools. This is exemplary usage guidance.

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