dosbox_read_memory

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.