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

Describes behavior when paused vs unpaused, fire-and-forget nature, no confirmation, UDP silent drops, and need for verification. No annotations so description carries full burden.

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?

Well-structured with labeled sections, front-loaded purpose. Slightly verbose but every sentence 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?

Covers purpose, usage, prerequisites, failure modes, transport, return value, and verification steps. Complete for a no-param tool with no output schema.

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?

No parameters; schema coverage 100%. Description adds no param info but baseline for 0 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?

Description clearly states 'Step emulation forward by exactly one frame' with specific verb and resource, distinguishing it from sibling tools like pause toggle and reset.

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 tells when to use (frame-precise tasks) and when not (long jumps prefer save/load), with prerequisite to ensure paused state and reference to 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 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?

Without annotations, the description fully discloses no side effects (pure read), error on timeout, contentless state message, and exact return format. Exceeds typical 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?

Well-structured with PURPOSE, USAGE, BEHAVIOR, RETURNS sections. Every sentence is necessary and concise.

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, the description thoroughly explains return values, error states, and integration with sibling tools. Complete for reliable agent use.

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?

No parameters, so schema provides no parameter info. Description adds value by detailing output format, compensating for absence of parameters.

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?

Description clearly states the tool reports playing/paused state, loaded system, game basename, and CRC32. It uses a specific verb and resource, and distinguishes from retroarch_get_config.

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 scenarios (after ping, before pause_toggle, before frame_advance, to confirm commands) and when not to use (use retroarch_get_config for settings).

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?

Fully details destructive behavior (replaces all state), fire-and-forget nature, silent failures, and transport requirements. No annotations provided, so description carries full burden and excels.

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?

Well-structured with headings, front-loaded purpose, and every sentence adds value. Length is justified given 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?

Covers all aspects: purpose, usage, behavior, verification, transport. No output schema, but description compensates fully.

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?

No parameters exist, but description clearly communicates that behavior relies on the currently-selected slot. Schema has 100% coverage, and description adds necessary context.

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 restores emulator state from the currently-selected save slot. It uses specific verbs and resources, and distinguishes from siblings like 'retroarch_load_state_slot' and 'retroarch_reset'.

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 provides when to use (undo sequence, start from baseline) and when not to use (specific slot without pointer change), along with alternative tools and verification methods.

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 behavioral traits: 'DESTRUCTIVE TO LIVE STATE: replaces ALL current emulator state... Anything not previously snapshotted is lost.' It also covers transport requirements, reply behavior vs. siblings, error handling (UDP timeout), and constraints on state file compatibility.

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 labeled sections (PURPOSE, USAGE, BEHAVIOR, RETURNS). It is front-loaded with purpose and usage, every sentence adds distinct value, and there is no redundancy despite comprehensive coverage.

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 complexity of the tool (emulator state manipulation, no output schema), the description is remarkably complete. It explains return value format, error conditions (UDP timeout, missing state file), transport details, and dependencies (same ROM/core). No obvious gaps remain.

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% for the single parameter 'slot'. The description adds meaning beyond the schema by noting standard range (0-9), that the NCI doesn't enforce upper bound, that out-of-range slots silently no-op, and that the call does not change the current-slot pointer.

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 'PURPOSE: Load state from an explicitly-named save slot number, without modifying RetroArch's currently-selected slot pointer.' This clearly identifies the verb (load), resource (save slot), and behavior (no pointer change), differentiating it from sibling retroarch_load_state_current.

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 'USAGE' guidance: 'Use to load from a specific slot when you don't want to disturb the current-slot pointer... For loading from the currently-selected slot, use retroarch_load_state_current — semantically distinct.' It clearly states when to use this tool and when to use an alternative.

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?

Despite no annotations, description fully discloses behavior: it is fire-and-forget with no UDP acknowledgment, packets can be silently dropped, and it requires network_cmd_enable in config. It also explains that the return line only confirms the UDP datagram was sent, not that RetroArch acted on it.

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?

Description is well-organized with labeled sections (PURPOSE, USAGE, BEHAVIOR, RETURNS) and is front-loaded with the core purpose. While it is lengthy, every sentence serves a purpose; minor verbosity is acceptable given the need to explain fire-and-forget semantics and usage patterns.

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 parameterless tool with no output schema, the description covers all necessary context: purpose, correct usage sequence, behavioral limitations, transport requirements, and return value meaning. It is fully self-contained and leaves no ambiguity for an AI agent.

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?

No parameters exist, so description adds no parameter-specific info. Baseline for 0 parameters is 4, and description fulfills that without needing to elaborate.

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?

Description clearly states 'Toggle RetroArch's pause state — pause if running, unpause if paused.', which is a specific verb-resource combination. It distinguishes from siblings like retroarch_get_status and retroarch_frame_advance by explaining when to use them in conjunction.

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 instructs to use retroarch_get_status first to check current state before toggling, and explains that calling toggle when state is unknown will flip it to the opposite state. Also recommends pairing with retroarch_frame_advance and defines fire-and-forget nature.

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 no side effects, transport details (UDP, config requirement), timeout, and error conditions. No 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?

Well-structured with labeled sections. Every sentence serves a purpose; no redundancy. Front-loaded with 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?

Given zero parameters and no output schema, the description compensates fully by explaining return value, error scenarios, and configuration dependency. Complete for an agent to use 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?

No parameters exist, so description naturally has high coverage. Adds value by detailing the return format and version string example, beyond 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?

Clearly states the tool verifies connectivity and returns the RetroArch version string. Distinguishes from siblings by noting that retroarch_get_status should be used later to confirm game loaded.

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 instructs to call at start-of-session before other tools, and suggests retroarch_get_status for game confirmation. Provides clear when-to-use and when-not-to-rely 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, description discloses side effects (pure read), transport (NCI over UDP), error conditions (no memory map, invalid address/length, timeout), and behavior of returning fewer bytes across region boundaries. Explains two distinct memory APIs.

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?

Well-structured with labeled sections (PURPOSE, USAGE, BEHAVIOR) and front-loaded. Slightly verbose but all information is relevant and necessary for a complex 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?

No output schema, but description explains return format, transport, errors, and relationship to siblings. Complete for a read tool with complex constraints. Leaves no major gaps.

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 description adds core-specific address examples and distinguishes address spaces from read_ram. For length, reiterates cap and chunking. Provides context beyond 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?

Clearly states it reads up to 4096 bytes from emulated memory via the libretro core's system memory map and returns a hex dump. Differentiates from sibling retroarch_read_ram which uses CHEEVOS address space.

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 describes when to use this tool (preferred when core has memory map) versus fallback to retroarch_read_ram. Provides pairing instructions with retroarch_write_memory and workflow for memory hunting. Advises chunking for larger reads.

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: no side effects (pure read), transport details (NCI over UDP), configuration requirement (network_cmd_enable = true), behavior during pause/run, error conditions, and potential to return fewer bytes at region boundaries. This is comprehensive.

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 clear sections (PURPOSE, USAGE, BEHAVIOR, RETURNS). Every sentence adds value, though some sentences could be merged for brevity without losing clarity.

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, the description includes return format. It covers purpose, usage, behavior, parameter nuances, and compares with sibling tool. No important context is missing, making it fully self-contained.

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?

Though schema coverage is 100%, the description adds significant context: explains CHEEVOS addresses vs. system memory map, provides examples (SNES WRAM), and clarifies the length cap rationale. This enriches the schema's minimal descriptions.

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 up to 4096 bytes from emulated memory via the CHEEVOS address space and returns a hex dump. It distinguishes from sibling retroarch_read_memory by explaining the two distinct memory APIs, making the purpose precise and differentiated.

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 states this is a fallback when retroarch_read_memory returns 'no memory map defined' and that it pairs with retroarch_write_ram. Also advises that read_memory is preferred when the core advertises a memory map, providing clear when-to-use and 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?

Annotations are absent, so description bears full burden. It details destructiveness, fire-and-forget nature, silent UDP drops, persistence of cart-internal state, and lack of acknowledgment. Completely transparent.

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, RETURNS) and front-loaded with key information. However, it is somewhat verbose with some redundant elaboration, earning a 4 rather than 5.

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 covers purpose, usage guidelines, behavioral details, transport requirements, follow-up verification, and return confirmation. It is fully complete for a fire-and-forget 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?

No parameters exist, so baseline is 4. The description does not need to add parameter meaning, and the schema coverage is 100%. No additional info required.

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 'soft-reset the running game — equivalent to pressing the console's reset button', uses a specific verb-resource combination, and distinguishes from power cycle and load state tools.

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 provides when to use ('start fresh from the game's reset vector') and when not ('to return to a specific known-good point... use retroarch_load_state_current or retroarch_load_state_slot'), and recommends follow-up verification 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 fully discloses destructive behavior (overwrites slot file), fire-and-forget nature (no confirmation), UDP silent drops, and state file ROM/core binding. It also explains transport and return value limitations. This is exceptionally transparent.

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 labeled sections (PURPOSE, USAGE, BEHAVIOR, TRANSPORT, RETURNS). Every sentence adds value, though some redundancy could be trimmed. Still, it is effectively organized and 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?

Given no parameters and no output schema, the description covers all necessary context: purpose, usage context, behavioral caveats, transport details, and return value. It references sibling tools and explains limitations, making it fully self-contained.

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 zero parameters (100% coverage). The description explains why no parameters are needed (saves to current slot), adding context beyond the schema. A score of 4 is appropriate as the baseline is 4 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 clearly states the action ('Save the entire emulator state'), the target resource ('RetroArch's currently-selected save slot'), and distinguishes from siblings like retroarch_load_state_current and slot navigation tools. The scope is specific and 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?

Explicitly describes when to use (rollback, bookmarking, repro states) and when not to use, with clear alternatives: path-based I/O requires BizHawk/mGBA, targeting a specific slot requires prior slot pointer manipulation. The guidance is comprehensive and actionable.

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?

The description thoroughly explains behavioral traits: writes a new timestamped PNG without overwriting, fire-and-forget without acknowledgment, silent packet drops if RetroArch is not listening, and silent failures. It also covers transport and configuration requirements, compensating for the lack of annotations.

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

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

The description is well-structured with labeled sections (PURPOSE, USAGE, IMPORTANT, etc.) and front-loaded with the purpose. However, it is somewhat verbose with some repetition (e.g., fire-and-forget explained twice), which slightly reduces conciseness.

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 is highly complete. It covers purpose, usage, behavior, return value, transport details, and configuration requirements, leaving no critical gaps for an AI agent.

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 zero parameters, and the description clarifies that no path argument is needed because RetroArch manages its own directory. This explains the absence of parameters and adds value beyond the schema, which is fully covered.

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 captures a PNG screenshot of the current emulator display and saves it to RetroArch's configured directory. It specifies the action, resource, and destination, and distinguishes itself from typical screenshot tools by noting it does not accept a path argument.

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 usage contexts: capturing game state for inspection, sequence documentation, or verifying fire-and-forget commands. It advises pausing/advancing frames or loading a state first. It does not explicitly list when not to use it, but the context is 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 covers behavioral traits: mutates pointer, wraps/clamps, fire-and-forget UDP with no acknowledgment, silent drop, no effect on emulator memory, and transport configuration. This exceeds the disclosure requirement.

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 structured with clear sections (PURPOSE, USAGE, BEHAVIOR, TRANSPORT, RETURNS), front-loads key information, and every sentence provides essential detail 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 (fire-and-forget UDP, no confirmation, client-side tracking needed), the description covers all necessary context including transport requirements, failure modes, and verification steps. No output schema exists, but return value is explained.

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 no parameters (coverage 100%). The description adds extensive behavioral context beyond the empty schema, explaining the tool's operation, return value, and side effects, compensating fully for the lack of parameter details.

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 verb (decrement) and resource (RetroArch's current save slot pointer), and distinguishes from the sibling tool retroarch_state_slot_plus. It also mentions related tools for context.

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 identifies as counterpart to retroarch_state_slot_plus, explains when to combine with save/load current slot tools, and directs to retroarch_load_state_slot for loading without changing the pointer. Provides clear guidance on client-side tracking and verification steps.

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?

Discloses mutation of internal pointer, wrap/clamp behavior, fire-and-forget nature with no confirmation, silent drops when RetroArch not listening, and need to track slot client-side. No annotations provided, so description fully covers behavioral traits.

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?

Description is well-structured with labeled sections (PURPOSE, USAGE, BEHAVIOR, RETURNS) and front-loaded key info. Every sentence adds value, no redundancy. Length is appropriate for 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?

Highly complete given the tool's complexity: covers usage scenarios, behavioral caveats, transport details, return value, and workarounds for limitations. No output schema, but description adequately explains what the tool returns and its meaning.

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?

Input schema has no parameters, so schema coverage is 100%. Description adds meaning by explaining that the tool takes no parameters and operates on the current slot pointer statefully. While schema already conveys no params, description clarifies the lack of parameters is intentional and explains the operation.

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 tool increments RetroArch's current save slot pointer by 1. Uses specific verb 'increment' and resource 'save slot pointer'. Distinguishes from sibling retroarch_state_slot_minus by mentioning it walks backwards.

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 (combine with save/load current for targeting specific slot), when not to use (use retroarch_load_state_slot for loading without pointer change), and alternatives (pair with minus, walk from known position). Also mentions limitations like no direct set or query.

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 provided, so description carries full burden. It discloses destructive overwrite, hardcore mode disable, return count with possible partial writes, and transport details. This is comprehensive.

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?

Description is well-structured with clear sections and front-loaded purpose. While lengthy, each part serves a purpose; could be slightly condensed but still 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 complexity of two memory APIs, destructive behavior, size limits, and transport protocol, the description is thorough. It explains return format, fallback, rollback necessity, and error conditions.

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?

Input schema has 100% coverage; both parameters are described. Description adds context about sequential writing, NCI line limit, address space differences, and behavior on read-only boundaries, which is valuable beyond 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 it writes a byte sequence to emulated memory via the libretro core's system memory map, distinguishing it from retroarch_write_ram and specifying use cases like cheats and debug pokes.

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 advises when to use this tool (preferred when core has memory map) and when to fall back to retroarch_write_ram. Also mentions maximum byte limit and rollback via retroarch_save_state_current.

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 destructive behavior, fire-and-forget nature (no acknowledgment), disabling of hardcore mode, UDP silent drops, and the need for verification. This is comprehensive.

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-organized with clear sections (PURPOSE, USAGE, BEHAVIOR, RETURNS) and front-loaded critical info. It could be slightly more concise, but the detail is necessary for a complex 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 the tool complexity, 100% schema coverage, and no output schema, the description covers all necessary aspects: address space distinction, size limits, verification steps, sibling tool relationships, and transport details. It is 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?

Schema coverage is 100% with good descriptions, but the description adds important context: address space caveats for 'address' and the lack of acknowledgment for 'bytes'. This extra value justifies a 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?

The description clearly states it writes a byte sequence to emulated memory via the CHEEVOS address space, distinguishing it from retroarch_write_memory which uses the core memory map. The purpose is specific and 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 explains when to use this tool as a fallback when retroarch_write_memory returns 'no memory map defined', and lists prerequisites and follow-up actions (e.g., verify with retroarch_read_ram, create rollback point).

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