ppsspp_write_range

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

With no annotations, the description carries full burden. It explicitly states 'DESTRUCTIVE: overwrites N bytes with no undo' and 'Direct memory write.' It also describes error conditions: 'Returns an error if address+N exceeds valid memory or any byte value is outside 0-255.' This fully discloses the tool's 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?

The description is structured into labeled sections (PURPOSE, USAGE, BEHAVIOR, RETURNS) making it highly scannable. Every sentence is informative with no redundancy. It is concise yet complete.

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

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

The description covers purpose, usage, destructive behavior, error conditions, return format, and notes encoding. Given the complexity (memory write, address range validation) it is fairly complete. A minor gap: it does not mention if the PSP emulator needs to be paused, but sibling tools ppsspp_pause/resume likely handle that. Overall, it provides sufficient context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by noting that bytes are 'base64-encoded over the wire' and specifying the return format: 'Single line "Wrote N bytes → ADDR_HEX"'. This provides semantic information beyond the schema's 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 starts with a clear purpose statement: 'Write a contiguous byte sequence to PSP memory starting at the given address.' It specifies the verb (write), resource (PSP memory), and scope (contiguous byte sequence). It also lists specific use cases like 'installing cheat tables, patching code blocks, or seeding regions,' which distinguishes it from sibling tools that write single bytes/words or read memory.

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

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

The USAGE section provides explicit use cases: 'Use for installing cheat tables, patching code blocks, or seeding regions.' This gives context for when to use the tool. However, it does not explicitly contrast with alternatives like ppsspp_write8/16/32 for single-value writes or mention when not to use it. Still, the guidance is clear and helpful.

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