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

Annotations already indicate this is not read-only and not destructive, so the description's added value is describing the stateful attach behavior and the goal of locating the game's data segment. It does not explain deeper behavioral consequences, such as what becomes attached or how this affects later memory operations, but it is not misleading.

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 two concise sentences with the primary action front-loaded and the useful session-discovery hint included second. It contains no filler or repeated schema content.

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 the key action and pid discovery, but the profile parameter is left unexplained and the exact state changed by attaching is not stated. An output schema exists, which reduces the need to describe return values, but the gaps around profile and attach semantics keep this from being fully 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 schema gives a clear description for pid, and the description usefully enriches it by pointing to dosbox_sessions as the way to find candidate pids. However, the profile parameter has no description in the schema and is not explained anywhere in the tool description, leaving its semantics unclear. With 50% schema coverage, the description needed to compensate but only partially does.

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: attach to a running DOSBox-X process by process ID and locate the game's data segment. It distinguishes itself from sibling tools like dosbox_launch and dosbox_sessions by focusing on an already-running process and by identifying a concrete resource (the game data segment).

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 clear context that the target must already be running and explicitly tells the agent to use dosbox_sessions to find candidate process IDs. It does not explicitly say when not to use this tool or name alternatives, but the usage context is clear enough for 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?

Though the readOnlyHint annotation already signals a safe read operation, the description adds meaningful behavioral detail beyond that: it openly discloses specific host limitations (window capture and emulator menu commands are unavailable) and frames/recordings dependency caveats. This is useful context an agent cannot infer from structured fields alone.

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 two sentences, front-loaded with the core purpose, then specific constraints, and then usage triggers. Every sentence carries information and there is 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?

With zero parameters, an output schema present, and readOnlyHint true, the description covers everything an agent needs: what this tool provides, what it does not provide, and when to invoke it. There are no missing contextual details that would prevent correct selection or invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters and schema coverage is trivially 100%, so the baseline for this dimension is 4. The description adds context about the tool's purpose without discussing parameters, but none are needed. It does not compensate for absent parameters; it doesn't need to.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific purpose: enumerating host capabilities and limitations, with concrete examples ('Guest memory works everywhere there is a backend; window capture and the emulator's own menu commands do not'). It is clearly distinct from the sibling tools, which are actionable operations (launch, capture, read memory, etc.) rather than a capabilities overview.

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: 'Call this when a tool refuses, or before planning a session that depends on frames or recordings.' This directly tells the agent when the tool should be consulted, which is exactly the kind of contextual advice the rubric rewards.

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 goes well beyond annotations by disclosing writes to multiple files, vram vs window behavior, the desktop-visible resize effect, guest slowdown cost, and the auto source's confirmation fallback. This substantially enriches the sparse readOnly/destructive hints without contradicting them.

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 wording is dense but every sentence earns its place; the most important action is front-loaded, and the source-mode explanation is directly tied to real behavioral tradeoffs. Minor awkwardness around 'with with_segment' does not undermine actual 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?

The description is complete for frame capture, source selection, output artifacts, and side effects, and an output schema exists for return values. It could be even more complete with an explicit note about when the optional pid would be needed and how capture differs from segment-only dumping, but nothing essential for calling it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75%, and the description adds real meaning beyond the schema, especially for source, where it explains exactly what each enum value means and how auto avoids saving incorrect data. It also clarifies with_segment and output naming. It does not explain pid, but that is optional and less central.

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 first sentence states a specific action ('Capture the current frame exactly and save it'), identifies the resource (the current frame), and lists the concrete output artifacts. The mention of a replayable fixture makes the tool's role distinct from view-only or memory-read 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?

The description gives strong within-tool source guidance: when to use vram, window, or auto. However, it does not explicitly say when to choose this tool over siblings such as dosbox_view_screen or dosbox_record, so an agent must infer the boundary between capturing a saveable frame and other observation workflows.

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 reveals multiple non-obvious behavioral details: the host pointer never moves, the mouse state must be rewritten continuously for duration, a single write usually loses to the game handler, and one click can advance two pages. These go well beyond the annotations and materially improve agent decision-making.

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

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

The description is compact and front-loaded: purpose, mechanism, timing behavior, and a cautionary alternative all appear in a few dense sentences without filler or repetition.

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 annotations cover safety and an output schema exists, the description provides the remaining critical context: what the tool actually alters, why duration is needed, and when to prefer a key. An agent has enough information to call this tool correctly in most DOS game scenarios.

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 80%, so the schema already documents most parameters. The description adds real semantic value for duration_seconds by explaining why the duration exists and why a single write is insufficient, and 'guest screen coordinate' reinforces x/y meaning.

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 specific verb and resource: 'Click at a guest screen coordinate' and clarifies the unusual mechanism by writing the game's own mouse state. It clearly separates this from the other input tools in the sibling list, such as dosbox_send_keys and dosbox_hold_buttons.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives useful context for using the tool and explicitly recommends 'send a key instead' for the 'click to continue' paging case. It does not offer a full when-to-use vs. when-to-avoid comparison across all sibling tools, but the guidance is concrete 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?

Given readOnlyHint and openWorldHint are already present, the description adds useful behavioral detail: it always dumps the full 64 KiB segment, captures the state at one instant, defaults to the profile's data segment, and treats segment=0x1234 as the marker-capture mechanism. It does not describe overwrite/path-creation behavior, but it does not contradict the read-only annotation because it reads guest memory and writes an output file.

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

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

Two sentences carry the full behavioral contract: the primary operation first, then the default segment behavior and special marker use. Every clause contributes semantics, so it is concise without being vague.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and readOnly/openWorld annotations, the description is nearly complete for selecting and invoking the tool: it covers the size, snapshot semantics, default segment, arbitrary segment values, and marker use. The main gap is pid, which the agent must infer refers to the target session/profile.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents path and segment, and the description adds useful segment semantics by explaining that segment=0x1234 targets any guest segment and is used for capturing a marker. The pid parameter remains undocumented in both the schema description and the tool description, keeping this from a perfect score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the operation precisely: 'Write a whole 64 KiB guest segment to a file' as a one-instant snapshot. This clearly distinguishes it from interactive memory tools like dosbox_read_memory or dosbox_write_memory by emphasizing the whole-segment file output and its analysis/fixture purpose.

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 concrete usage contexts: 'for later analysis or as a test fixture' and 'how the marker for a new profile is captured.' It does not explicitly name sibling alternatives or say when not to use it, but the intended use is easy to infer from the wording.

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?

It adds genuinely useful behavior beyond what the schema and annotations expose: firing a record action again stops that recording, actions are fired without focus, and Windows is a required platform because DOSBox-X draws its own menu elsewhere. These details are non-obvious and not available in the structured fields. The annotation flags (readOnlyHint=false, destructiveHint=false) align with the described behavior, and the description contradicts nothing.

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

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

The description is compact and efficient: the first sentence delivers the core purpose and action list, the second adds the important toggling behavior, and the third isolates platform restrictions and a pointer to a related tool. It front-loads the most important information and keeps total length short, although it duplicate the action list from the schema somewhat.

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 there is an output schema, the return format does not need to be explained, and the tool's complexity is modest—one required parameter plus an optional pid. The description is enough to perform the call correctly for the typical case, but it does omit pid semantics and does not describe whether pid must refer to a specific session or process, leaving a small but real 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?

The description adds meaning to the 'action' parameter by explaining that these are DOSBox-X menu items and that record actions toggle on/off. However, it mostly restates the list already present in the action parameter's schema description. More importantly, the 'pid' parameter has no description in the schema and none in the tool description, and at 50% schema coverage the description fails to compensate for explaining how or when the optional pid should be provided.

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 identifies a specific action: firing DOSBox-X's own menu items, and enumerates all seven supported action values. It also distinguishes itself from keystroke or focus-based input by explicitly saying it acts 'without focus and without a keystroke.' However, it does not explicitly distinguish itself from overlapping siblings like dosbox_record or dosbox_capture_screen, so an agent must infer those boundaries.

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 context is clear: it is for menu actions when keyboard/focus simulation is not appropriate, and it even notes a Windows-only restriction with a pointer to dosbox_capabilities. That said, it never explicitly says 'use this instead of X when Y' or mentions alternatives like dosbox_send_keys, dosbox_record, or dosbox_capture_screen, leaving some selection inference to the agent.

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

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

Annotations already declare readOnlyHint=true, so the safe-read nature is covered. The description adds behavioral detail beyond that: it returns zero-run candidate gaps, orders them longest first, and indicates the guest segment context. It does not cover edge cases such as 'no suitable cave found', but the existing annotation and output schema partly mitigate that.

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

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

Three short sentences, each signing significant value: what the tool does, where the supply is typically found, and how to use the result. The key behavioral constraint ('longest first') is front-loaded and the follow-up call is clearly mentioned. There is no redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For the task of finding and using a trace cave, the description is essentially complete: it explains the search target, ordering, and next action. The only missing nuance is handling the pid parameter and the absence of an explicit failure case, but these are minor because the schema and output schema clarify the interface.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 67%, with segment and bytes_needed already described in the schema. The description reinforces that bytes_needed corresponds to the amount of room the cave needs, but it does not explain the pid parameter, which has no schema description. Overall, the description adds only modest parameter-level value 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 states the exact operation: 'Find runs of zero in a guest code segment long enough to hold a trace cave.' It clearly identifies the resource (guest code segment), the condition (runs long enough), and the intended purpose (a trace cave). It also references the downstream sibling tool dosbox_install_trace, so an agent can distinguish it from read/search/memory 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?

The description provides actionable guidance: 'Padding between routines is the usual supply' tells where to look, and 'Longest first; pass one of these offsets to dosbox_install_trace' tells what to do with the result. It names the immediate sibling for the follow-up action, though it does not explicitly state when not to use this tool or describe alternative routes.

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

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

Annotations only say readOnlyHint=true and openWorldHint=true. The description adds real behavioral depth: it locates guest physical zero from the BIOS data area, walks the DOS memory chain, and reports every loaded program with segment and source path. Nothing about the description contradicts the read-only annotation.

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 two sentences, purpose-first, and the key output (segments, paths) is front-loaded. However, it repeats the the same idea twice: 'with no profile and no prior knowledge' and 'a game nobody has described yet', plus the closing sentence adds useful context but could be trimmed.

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?

There is an output schema so return values are covered, and the description explains what to do with the results (read/search memory and seed the profile). However, it is silent about how the target emulator process is selected via pid and what happens when pid is omitted, and it does not mention the likely prerequisite of an existing launched/attached process.

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 `pid` parameter has 0% schema description coverage, yet the description never explains what pid means, how to select the emulator process, or what happens when it is null. The phrase 'inside an emulator process' indirectly suggests pid is the OS process ID, but the agent is left to infer an important prerequisite in order to invoke the tool correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb + resource: find the DOS guest in an emulator process and report what is loaded in it. It further defines the output as loaded programs, load segments, and paths, and explicitly marks it as the entry point for games with no profile or prior knowledge, which differentiates it from the profile/session/launch tools in the sibling list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear when-to-use scenario: a game nobody has described yet, with no profile and no prior knowledge, and says this is the way in. It also explains how the output feeds dosbox_read_memory, dosbox_search_memory, and profile creation. It stops short of 5 because it does not explicitly name alternative tools or say when NOT to use this one.

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

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

Beyond the annotations, it reveals the tool busy-writes, explains why ("sparse writes lose to the game's own interrupt handler"), and describes the early-release behavior via stop_when and memory fields. This gives strong behavioral insight that an agent needs to understand the tool's side effects.

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 tight and front-loaded: first states the primary action, then explains why busy-writing is necessary, then clarifies how to stop early. No sentence is filler, and the key information is delivered early.

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 9-parameter surface area, the description explains the important behaviors adequately: holding, busy-writing, and stop_when release. While some optional parameter details are only implicit, the required parameter and core usage are clear enough, and an output schema exists to cover return-value expectations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 33%, and the description does not compensate for the many undocumented parameters. It only broadly mentions stop_when, leaving poll_seconds, stop_when_size, stop_when_any_of, stop_when_equals, and other semantics to be inferred from names alone.

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: "Hold mouse buttons down for a stretch of time." It also distinguishes this from related operations by explaining it is used for "anything that reads a held button" such as an action sequence, 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 gives clear context for when to use the tool: when the game or guest needs a continuous held-button signal and "sparse writes lose to the game's own interrupt handler." It does not explicitly name sibling tools like dosbox_click as alternatives, so it stops short of full exclusionary 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?

The description richly discloses behavior beyond the annotations: it patches only live memory, calls the displaced target, preserves flags, records at each hit, and says the patch dies with the emulator. It also warns about the DS-relative memory caveat and the safety behavior of expect_hex.

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 every sentence carries essential information: purpose, mechanism, lifecycle, capture format, memory caveat, and safety check. It is front-loaded with the core intent and then layers technical details without filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of code-injection tooling, the description covers the workflow, prerequisites, parameter semantics, and side effects thoroughly. The presence of an output schema removes the need to duplicate return-value details, and nothing critical for invoking the tool correctly appears missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema only gives names and short labels, but the description adds real semantics: exact capture syntax for registers, segment registers, flags, and memory addresses, plus the contract for expect_hex. This significantly reduces ambiguity about how to construct valid calls.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: it installs a trace/hook that displaces one near CALL in a running guest, routes it through a cave, and records targeted registers/memory. This clearly distinguishes it from related tools like dosbox_read_trace and dosbox_remove_trace.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear context for when to use it — watching code in a running guest without a debugger, then reading captured data via dosbox_read_trace. It also explains prerequisites like using a zero-filled cave from dosbox_find_cave, but it does not explicitly list when-not-to-use conditions or compare against other trace/read alternatives.

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 goes well beyond annotations by disclosing that a successful call means the guest is genuinely up and drivable, and that on Linux isolated=true runs on Xvfb and avoids stealing keystrokes. It also explains the return value role and startup waiting behavior, providing valuable behavioral context.

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 a few sentences long but every sentence contributes practical information. The most important action and output are front-loaded, followed by config guidance and the isolated-mode caveat. It is slightly long but justified by the tool's launch 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?

The description explains the key behavioral outcome, return value, and a platform-specific nuance. With 6 parameters and an output schema present, the schema covers most parameter details and the description fills in the operational context. It is sufficiently complete for an agent to successfully use and interpret the result, though it does not dive into all parameter edge cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is high (83%), so the baseline is 3. The description adds semantic value by explaining that the config's [autoexec] section controls execution and that AUTOTYPE is the reliable path past intro screens, which clarifies the primary parameter's use. It also reinforces isolated behavior, giving it above-baseline value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool starts DOSBox-X with a config file and attaches to it, a specific verb and resource. It differentiates from siblings by explaining that the returned process ID is the identifier other tools take, which positions it distinctly among the sibling toolset.

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 establishes when to use this tool: to launch and attach to a DOSBox-X session. It provides practical context such as the [autoexec] section and AUTOTYPE line for intro screens, but doesn't explicitly contrast with alternatives like dosbox_attach or dosbox_profiles. This is strong contextual guidance, but lacks explicit exclusions or when-not-to-use cases.

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 annotations already declare readOnlyHint=true, so the safe/read-only nature is covered. The description adds useful context beyond the annotations by explaining what a profile represents and how the returned symbols integrate with other tools, without contradicting the read-only hint.

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

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

Three concise sentences, each earning its place: the action, the profile concept, and the call-first guidance. No filler or repetition of schema details.

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 the tool's read-only purpose, the kind of data returned, and the key integration contract (symbols usable anywhere offsets are accepted). It does not spell out null/omitted behavior or unknown-profile handling, but an output schema exists and the tool is simple enough that the gap is minor.

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 0%, so the description must carry the parameter meaning. It implies the optional 'profile' selects one game profile and exposes its named offsets, but it never explicitly states what happens when the parameter is omitted or null, or that 'profile' expects a profile name from the returned list.

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 identifies a specific verb ('List') and resource ('game profiles', 'named memory offsets'), and explains what a profile describes. This clearly separates it from the mutation and session-oriented sibling tools and makes its role as a discovery tool 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 says to call this tool first and notes that the returned symbol names can be reused anywhere an offset is accepted. It gives clear when-to-use guidance, though it does not state when not to use it or point to an alternative 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?

Beyond annotations, it discloses the critical behavioral detail that the guest is not prompted to save anything first, which is essential for an agent to evaluate risk. It also clarifies the forced relationship — that by default only server-launched sessions can be killed, and force is needed for attached sessions. These details go well beyond the readOnly/destructive hints.

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

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

Three short, purposeful sentences cover the core action, the condition for force, and the critical consequence about unsaved guest state. There is no redundancy or fluff, and the most important information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is a simple, parameter-light operation with a clear safety profile; the description covers the destructive action, the force/ownership policy, and the unsaved-data consequence. Given the output schema exists and the input schema already documents both parameters, nothing else is needed for an 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 already documents both pid with a clear description and force with a clear description, achieving full schema coverage. The description adds value by clarifying the force behavior in terms of sessions the server merely attached to, h but it adds no extra pid nuances. Given the schema's high coverage, a score above baseline is still justified.

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 action, 'Close a DOSBox-X session,' which clearly identifies the tool's purpose among siblings like launch, attach, and emulator_command. The additional nuance about launched vs. attached sessions further disambiguates its operational scope.

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 clear operational context: the default applies to sessions the server launched, and the condition for using force is described directly. It does not explicitly name alternatives or state when not to use this tool, but the warning that the guest will not be asked to save implicitly tells agents to ensure saving happens elsewhere.

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 goes far beyond the readOnlyHint by explaining that a reference page is required for confirmation, that a blind scan otherwise occurs but is refused, that confirmed locations are cached, and that the tool writes <stem>.bin and <stem>.png when a stem is provided. These are consequential observable behaviors an agent needs to know.

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

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

Three paragraphs, each with a distinct job: what it is, the reference/caching constraint, and the outputs/page-flip behavior. It is longer than the minimal examples but stays dense and front-loaded; the all-caps phrase is loud but not actually redundant.

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 6-parameter tool with no required arguments, this description supplies the essential decision context: when to use it, what the reference requirement is, why the cache exists, what files are written, and how page_offset relates to page-flipping. With the output schema present, the return values need not be re-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?

Schema coverage is high (83%), so the schema does much of the work. The description adds meaningful semantics to reference (64,000-byte frame, byte-for-byte confirmation), stem (writes .bin/.png), page_offset (page-flipping games), and allow_unconfirmed (takes the unsafe blind scan). It does not add nuance for pid or expose the 'relocate' parameter by name, though schema descriptions cover those.

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, purposeful verb and resource: "Read the guest's screen straight out of the emulator's video memory." It then precisely characterizes the return (palette indices at the instant of the read) and calls out the sibling it is not, dosbox_capture_screen, making the tool 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 usage guidance: 'Prefer this over dosbox_capture_screen for anything quantitative,' with reasoning about guest-time cost and half-drawn frames. It also states the reference requirement, the refusal to guess by default, and when allow_unconfirmed is appropriate.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=true, so the non-mutating behavior is covered. The description adds useful behavioral context beyond the annotations, including segment semantics, profile symbol offsets, and format interpretations like little-endian numbers or NUL-terminated text. It does not mention authentication, side effects, or limits, but those are minor for a read-only memory 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 three sentences with a clear front-loaded action, followed by concrete addressing behavior, formats, and a motivating use case. Every sentence earns its place, and nothing feels like filler or repeated schema content.

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 output schema exists and annotations already cover read-only behavior, the description is nearly complete for calling the tool. It covers the required option, offset semantics, segment behavior, format enum, and maximum scope. The only meaningful missing context is an explicit statement about when pid needs to be set, but that does not block the common case.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents offset, segment, and length, but the description adds meaningful semantics: symbol-name offsets only apply when segment is omitted, segment values can address another program/TSR/interrupt vector table, and format values have precise meanings (little-endian integers, NUL-terminated text). This compensates well for the remaining 40% schema coverage gap, though performance on pid remains untouched.

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 bytes from guest memory and explains the two addressing modes (default data segment vs. an explicit segment). It frames the purpose as reading game state such as money or health, which makes the resource scope obvious. It does not explicitly distinguish itself from sibling read-style tools like dosbox_read_framebuffer or dosbox_dump_segment, but the action and resource are specific.

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 clear usage context: use it to read guest memory state, with offset-as-symbol when no segment is provided and any segment when segment is provided. It even calls out this is 'how to read game state.' However, it does not explicitly list alternatives or state when not to use it, such as pointing to dosbox_search_memory or dosbox_write_memory.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=true, covering the non-mutating nature. The description adds meaningful context beyond those hints by disclosing that only the most recent hit is visible and that a hit count of zero is itself a useful answer.

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

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

Two sentences, with no filler. The core action and output shape come first, and the actionable interpretation of a zero hit count follows immediately. This is efficient 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 that output schema exists, annotations cover safety, and the operation is a simple trace read, the description provides enough operating context. The main residual gap is the undocumented pid parameter, but it is optional and handle is already described in the 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?

Schema coverage is only 50%, and the description does not compensate for the undocumented pid parameter. The handle parameter does have schema-level meaning ('omit if only one is installed'), but the description itself adds no parameter-level guidance. An agent would have to infer what pid refers to.

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 uses a specific verb-resource pair: 'Read what an installed trace has recorded' and specifies exactly the returned information (most recent hit values and hit count). It also differentiates itself from siblings like dosbox_install_trace and dosbox_remove_trace by describing a read of existing recorded state.

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 clearly implies when to use it: after a trace is installed, to see whether it fired and what values were captured. Interpreting a zero hit count is also explicitly explained, which guides acting on the result. It does not explicitly name alternatives or state when not to use this tool, so it does not earn a 5.

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

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

Beyond the annotations, the description reveals a genuinely non-obvious behavior: DOSBox-X starts an OPL capture at the guest's first register write, so arming late moves the capture window rather than truncating it. This is valuable behavioral context and is consistent with the annotations' readOnlyHint=false and destructiveHint=false.

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

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

The description is compact and front-loaded: the first sentence states the action and output, the second states the tool's unique value, and the third gives the most critical timing caution. Every sentence earns its place and there is no redundant repetition of the schema or annotations.

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?

Because an output schema exists, the description does not need to detail the return value, but the tool still has six parameters and one enum option (record_video) that are only partially or inconsistently covered by the description. The core 'provide a duration and record audio' flow is well explained, but the video capture and file-location parameters could leave an agent guessing in less common invocations.

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 only 33% schema description coverage, the description partially compensates by mapping record kinds to file formats (.dro, .mid, .wav), which helps with the kind parameter. However, it ignores pid, settle_seconds, captures_directory, config's full role, and the record_video enum alternative, leaving several parameters under-explained.

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 uses a specific action ('Record the guest's sound...') and clearly names the produced artifacts (.dro, .mid, .wav), so an agent can tell this is an audio-capture tool. However, it does not differentiate it from related siblings like dosbox_capture_screen or dosbox_sample, and it omits the record_video kind that appears in the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'This is the only independent record of what a game's sound driver actually writes' gives a strong, explicit reason to use this tool over alternatives for sound-driver investigation. The early-arming warning also adds context, though it does not explicitly name sibling tools or say when not 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?

The annotations already indicate destructive=true and readOnly=false. The description adds useful process context: the call site is restored first to prevent new entries, then the cave is blanked. This goes beyond the annotations by describing the sequence and the protective safety step.

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 a single sentence with the main action front-loaded and no unnecessary repetition. The use of metaphorical terms like 'cave' introduces slight ambiguity but does not bloat the description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, and the description sufficiently exposes the destructive process and ordering. However, it does not clarify how pid relates to the target trace or what the caller should do when multiple trace handles exist, which is meaningful for a destructive 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 description does not explain pid or handle, and schema coverage is only 50% (handle is documented but pid is not). Since the description must compensate for that gap, the lack of any parameter-level meaning leaves an agent guessing about how to identify the trace to remove.

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 phrase 'Remove an installed trace' names a specific verb and resource and clearly states the core action. The additional call-site/cave detail describes what removal entails, though it does not explicitly differentiate the tool from siblings like dosbox_install_trace or dosbox_read_trace.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance about when to prefer this tool over alternatives, no mention of prerequisites, and no exclusions such as 'use dosbox_read_trace instead to inspect a trace.' The usage context is only implicit in the action named by the description.

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 adds behavioral context beyond the annotations by explaining that each row shares a coherent snapshot (no column drift), that the output is an on-disk TSV plus an entry-time segment dump, and that the dump allows offline investigation. It does not enumerate every side effect, such as pokes, but the schema already documents those and the annotations are consistent.

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 the core purpose and each major sentence contributes useful context: the semantics, the sibling contrast, the snapshot consistency guarantee, and the side outputs. The rhetorical phrase 'which is what most questions about a running program actually are' is slightly extraneous but not bloated or confusing.

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 7-parameter tool with high schema coverage and supporting annotations, the description covers the conceptual essentials: what it samples, how it differs from siblings, and what output artifacts are produced. It does not spell out duration, frequency, or pokes flow, but those are already described in the input schema and the description is strong enough for selection and initial invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 86% schema description coverage, the schema does most of the parameter-documentation work, so a baseline of 3 is appropriate. The description adds a little extra meaning by clarifying that watches can be symbols, offsets, or profile-defined watch sets and that the dump lets unreported questions be answered later, but it does not redefine the parameter contracts.

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: 'Sample a set of memory fields repeatedly and write the series as a TSV.' It then immediately distinguishes itself from dosbox_read_memory and dosbox_wait_for by positioning this tool as answering 'how it MOVES,' so an agent can tell what the tool does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit routing rule: dosbox_read_memory answers what a value is, dosbox_wait_for answers when it becomes something, and this tool answers how it moves over time. This is a genuine when-to-use vs. alternative-tool comparison, not just a vague statement of behavior.

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 adds useful behavioral context beyond the readOnlyHint and openWorldHint annotations: it states the exact memory region searched, that every hit is reported, and the output form as segment:offset. There are no hidden side effects or contradictions.

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

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

Three compact sentences each carry functional weight: the operation and result, the motivating scenario, and the input modes. No padding or repetition of schema fields.

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 gives enough context about how to call the tool, what it returns, and why it matters in the profiling workflow. The main omission is guidance on pid/limit, but since zero parameters are required, defaults plus the schema cover most invocation scenarios.

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 description explains the key text-versus-hex choice and suggests raw bytes, while the schema describes text as latin-1. However, pid and limit are not documented anywhere, and with 50% schema coverage the description should have compensated a bit more for those two unexplained 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?

The description clearly states a specific operation: searching the guest's 640 KiB conventional memory for a byte pattern and reporting each hit as a guest segment:offset. This distinguishes it from read/dump siblings by making both the resource and the hit-reporting behavior explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a concrete use case: converting a known game string or message into the segment where it lives, as the first step in profiling. It does not explicitly list alternatives or exclusions, so it falls just short of a 5, but the context is clearly conveyed.

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 rich behavior beyond the annotations: the buffered injection mechanism, no host keystrokes, paced delivery, ring capacity, and clean failure on a full ring. These facts are not visible in readOnlyHint/openWorldHint/destructiveHint and directly improve an agent's ability to use the tool safely.

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

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

Three dense sentences, each earning its place: mechanism, key vocabulary, and pacing/capacity constraints. The most important fact is front-loaded, and there is no filler or repetition.

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 an output schema, annotations, and only three parameters, the description covers the essential behaviors, constraints, key-format rules, and failure semantics. The agent has enough context to call it correctly without additional lookup.

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?

Adds meaning the schema leaves out: each array item is a single character or a named key, it enumerates valid key names, and it explains the purpose of pace_seconds. The optional pid is not explained, but since it is nullable and has a default it does not block correct use.

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?

Leads with a precise action: 'Type into the guest' by appending to its BIOS ring buffer. It also distinguishes itself from mouse/focus-dependent input tools by saying 'no window focus, no host keystrokes'.

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 clear operational guidance: send small batches, respect pacing, and interpret a full ring as the game waiting on the mouse rather than the keyboard. It does not explicitly name sibling alternatives like dosbox_click or dosbox_hold_buttons, so the guidance is strong but not fully exclusionary.

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

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

Annotations already indicate read-only and open-world behavior, so the safety profile is covered. The description additionally clarifies scope by noting it returns both attached sessions and other visible DOSBox-X windows on the machine, but it does not describe how filtering or window-title affects results. No contradiction with annotations exists.

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 a single focused sentence. It front-loads the main action and result, and every phrase ('attached sessions', 'other visible windows', 'process ids') adds value. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only listing tool, this is largely complete: it says what is listed, the scope, and an important output detail (process IDs). The output schema exists so return documentation is not needed. The main omission is that the optional window_title parameter is not mentioned, which is important for full standalone clarity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the undocumented parameter. It does not mention `window_title` at all, leaving the agent to infer whether it is for filtering, matching, or returning output. The parameter name offers some minimal hint, but not sufficient guarantees.

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 uses a specific verb ('List') and identifies the resource ('attached sessions and any other visible DOSBox-X windows on the machine'), including process IDs. This is clear and distinct from the sibling options, though it does not explicitly differentiate itself by naming an alternative tool.

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 intended use is implied: call this to enumerate sessions/windows and their process IDs. However, it does not state when to prefer this over sibling tools like dosbox_attach, dosbox_launch, or dosbox_profiles, nor does it provide explicit exclusion conditions.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds meaningful behavioral context: capturing from a window photograph without activating it implies non-exact/approximate output, and clarifying the contrast with 'exact and saved' helps set expectations. It could additionally state output format details, but the annotations already cover the key safe-read behavior.

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

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

Three sentences, all substantive, with the primary function and key differentiator front-loaded. No filler or redundant prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only view tool with two optional parameters, defaults, and only an image return value, the description gives everything an agent needs to determine when to call it and what result to expect. It even routes to the exact-frame sibling.

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 50%: max_width is thoroughly described in the schema, but pid is not. The description does not explain pid's role or when to provide it, though pid is optional with a null default and max_width is already documented. Since the missing parameter is optional and low-risk, 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 clearly identifies the action ('look at/results in the current frame as an image') and the resource (the emulator screen). It also explicitly distinguishes the tool from dosbox_capture_screen by noting this view is photographed from the window and not guaranteed to be the exact saved frame.

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 states when to use this tool ('see where the game actually is between steps') and provides the alternative condition: use dosbox_capture_screen when the frame has to be exact and saved. This gives clear decision guidance to an agent.

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

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

The description discloses important behavioral traits beyond the readOnlyHint annotation: it does not raise on timeout, it returns whether the test was satisfied and the last value seen, and it blocks. This is genuinely useful context beyond the annotations. It could add more detail about invalid offsets or poll behavior, but for a read-only operation this is solid.

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 a concise two-sentence structure: first states the core behavioral guarantee, then gives use cases, then states the return policy and timeout behavior. Every sentence stands alone and adds value without padding or restating the tool name.

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 the high-level operation, use cases, and timeout contract, and the existence of an output schema lessens the need to spell out return structure. However, the tool has 10 parameters and only 10% schema description coverage, so the description lacks essential detail on how to specify the test condition and how polling works. It is adequate for basic guidance but not fully complete for predictable invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 10%, and the description does not compensate. It says only 'satisfies a test' with a memory field, leaving equals, any_of, at_most, at_least, not_equals, size, pid, poll_seconds, and timeout_seconds semantics to inference. An agent has to guess how multiple conditions combine or whether they are exclusive. The description adds little meaning beyond what parameter titles already hint at.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource: 'Block until a memory field satisfies a test, or the timeout runs out.' It also gives concrete use examples like screen transitions, animations, and state bytes, which help distinguish it from memory reading or search tools. It does not explicitly name an alternative sibling, so it slightly under-delivers on full 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?

The description explicitly says to use this when waiting for a screen transition, animation finish, or state byte to settle, and contrasts it with guessing at sleeps. It gives clear situational guidance, but it does not explicitly say when not to use it or how it compares to alternatives like watch_frames or read_memory polling.

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 adds meaningful behavior beyond what annotations already state: it reads video memory rather than the GUI, does not slow the guest, captures distinct frames with the guest's own timings, and writes files as <stem>_NNN.png. This complements the readOnlyHint/destructiveHint flags well.

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 short, front-loaded, and has no fluff. Both the outcome and the distinctive behavior are introduced early, and each sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with seven parameters and an output schema, the description provides the core context: what it watches, when to use it, and where frames land. It does not explain the max_frames/interval cap fully, but those are already documented in the schema. It is nearly complete and trustworthy.

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 description adds a bit of parameter meaning, especially around stem by explaining the file naming convention. However, with 57% schema coverage, the description does not flesh out key parameters like pid, max_frames, or interval_seconds beyond their schema descriptions. It is adequate but not compensating significantly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific action and resource: watching the guest's video memory and returning distinct frames with their appearance timings. It also distinguishes itself from filming the screen by noting that reading video memory does not slow the guest, so it is clearly targetable among the many dosbox sibling 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?

The description explicitly says this is how to measure animations, fades, and transitions, and explains why it should be preferred over filming the window. It does not formally name alternative tools or list exclusion conditions, so it is clear but not maximally prescriptive.

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?

Even though annotations already signal a destructive, non-read-only operation, the description adds valuable behavioral detail: writes land in the running game, are not undoable, and the game may recompute a field shortly after it is written. This is exactly the kind of non-obvious runtime behavior an agent needs to know. No contradiction with 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?

Three sentences deliver the core purpose, a motivating use case, and the critical timing/durability caveat. There is no filler or repetition; every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive memory-mutation tool, the description is nearly complete: it says why to use it, what makes it dangerous, and what timing to respect. It does not explicitly state the requirement that a target session/game is already attached or running, nor mention targeting via pid. That is a minor gap and is mostly inferable from sibling tools and the 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?

The nested schema already explains offset, size, value, and hex well, but the description adds little parameter-specific detail beyond casting writes as patches to game state. It does not clarify the top-level pid, writes, or segment semantics in prose, and top-level schema description coverage is only 33%. The description is behaviorally useful but does not fully compensate for that gap.

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 target: 'Patch the game's data segment.' It then clarifies the concrete use case—setting up a state like a treasury, rank, or flag to reach a particular screen or code path. This clearly distinguishes it from the sibling read/search/memory 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 gives clear context for when the tool should be used: when a state would otherwise take hours of gameplay. It also gives timing guidance: patch where the value will be read before the game recomputes it. It does not explicitly state when-not-to-use or name alternatives, so it stops just short of perfect.

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