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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: it does not contact PPSSPP, the default source is the server-mirrored broadcast log, and it explains that the 500-match internal cap makes total_matches a lower bound — behavioral detail absent from 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?

Front-loaded PURPOSE/USAGE/BEHAVIOR/RETURNS structure with no filler; every sentence carries load-bearing information and the most decision-relevant facts come first.

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 annotations covering safety, an output schema present, and 100% schema description coverage, the description supplies the remaining gaps (default source, truncation lower-bound semantics) and omits return-value detail that the output schema already owns.

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

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

Schema coverage is 100% and each parameter already carries a detailed description, so the baseline is 3. The USAGE line restates optional/default status but adds no syntax or format detail beyond what the schema provides.

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?

States a precise verb+resource+scope: filter a PPSSPP log file for ERROR/WARNING/CRASH lines. No sibling tool covers this surface, and the purpose is unambiguous 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?

Explicitly documents that log_path, filter, and session_id are optional and what the defaults resolve to, and the schema's filter_mode documents the 'all' vs 'any' narrowing with a concrete example. It stops short of naming when a sibling tool would be preferable, but no obvious alternative exists.

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 destructiveHint=true and readOnlyHint=false, so safety is partly covered. The description goes further by naming the protected ranges (kernel, top.prx code), the force=true escape hatch, and the partial-write error directing the agent to disassemble and inspect — meaningful operational detail beyond the 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?

Structured as PURPOSE/USAGE/BEHAVIOR/RETURNS with no filler; the critical constraint (one line per call) is front-loaded. The RETURNS line slightly duplicates the existing output schema, which is the only wasted sentence.

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 mutation tool, the description covers the force requirement, protected-range behavior, comment syntax limits, invocation loop, and error path; return values are already documented by the output schema and annotations cover the safety profile. Nothing essential to correct invocation 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 description coverage is 100%, so baseline is 3. The description adds value the schema does not: the assembler loops one line per call, ';' comments are not supported, and the partial-write/force semantics are summarized as an operational consequence rather than just a field definition.

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?

States a specific verb (assemble) plus resource (MIPS instructions) and the side effect (write resulting bytes to memory). An agent can immediately distinguish this from ppsspp_write_memory (raw bytes) and ppsspp_disassemble (reverse direction) without opening a 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 USAGE line names the required parameter triple and warns that ';' comments are unsupported and that PPSSPP assembles one line per call, so the tool loops. However, it never states when to prefer this over ppsspp_write_memory or ppsspp_run_script, and gives no exclusions or alternative routing.

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 declare the mutation/safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false); the description goes well beyond by disclosing that the job's finally block releases the session lock immediately, that the abort lands at the step boundary (~1s mid-wait), and that cancelling a finished job errors. This is exactly the operational context an agent needs and cannot get from structured fields.

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?

Sectioned PURPOSE/USAGE/BEHAVIOR/RETURNS layout is front-loaded with the essential verb and every sentence carries information: id sourcing, lock-release timing, abort granularity, and the error case. No 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?

Output schema exists so return values need not be detailed, yet the description still summarizes the return shape and directs polling to ppsspp_batch_status. Annotations plus description cover safety and side effects well; the only real gap is the unresolved required-vs-optional contradiction for batch_id.

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% (baseline 3), but the description actively contradicts the schema by instructing the agent to omit batch_id for 'survey/list mode' while the input schema marks batch_id required. A misleading claim about a required parameter can cause a failed call, which is worse than saying nothing.

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?

States a specific verb (cancel) and resource (queued or running background batch job), and implicitly distinguishes itself from ppsspp_batch_step and ppsspp_batch_status by naming them as the source of the id and the pre-check tool. An agent can route to it 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?

Gives explicit sourcing ('batch_id from ppsspp_batch_step(background=true)') and a clear guard ('check ppsspp_batch_status first if unsure'). The claimed 'omit batch_id for survey/list mode' is useful context but conflicts with the schema's required field, so guidance is not fully trustworthy.

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 declare the safety profile (readOnly/idempotent/non-destructive); the description goes further by explaining WHY it is safe — lock-free registry read, no WS transport, no per-session lock wait — which tells the agent it can be called concurrently with a batch owning the session. It also discloses eviction behavior (finished jobs beyond retention are absent).

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?

Four labeled sections (PURPOSE/USAGE/BEHAVIOR/RETURNS) with the most decision-relevant fact — what it does and that it is session-safe — front-loaded. Dense but every sentence carries operational information; no 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?

Even though an output schema exists, the description supplies the concurrency/safety model and retention eviction caveat that an agent needs to call this correctly alongside a running batch. Nothing required for correct invocation 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 100% and the schema already documents the omit-to-survey semantics, so the baseline is 3. The description earns an extra point by tying each parameter mode to a distinct return shape (single job vs. jobs array in submission order), which is meaning the schema alone does not convey.

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?

States a specific verb and resource — 'poll the state and progress of a background batch job' — and immediately scopes it with 'without touching the session'. An agent can distinguish it from ppsspp_batch_step and ppsspp_batch_cancel purely from this line.

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

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

Explicitly names where batch_id comes from (ppsspp_batch_step with background=true) and defines the no-argument survey/list mode with concrete use cases (recovering a lost batch_id, auditing background activity before touching the session). Both modes and their selection conditions are stated, not implied.

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 declare the mutation profile (readOnlyHint=false, idempotentHint=false) but the description adds substantial context beyond them: the session lock is held for the whole batch, sequences estimated >25s are rejected with BATCH_BUDGET_EXCEEDED because the client aborts at ~30s, foreground failure makes the whole call isError BATCH_STEP_FAILED, background returns a batch_id immediately, and screenshots are auto-skipped during replay. This is a rich, non-obvious behavioral disclosure.

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?

Front-loaded with PURPOSE/USAGE/ROUTING/BEHAVIOR/RETURNS headers that make it scannable, and each section earns its place given the tool's complexity. It is dense and long, but the structure keeps it navigable rather than wasteful.

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

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

Despite an existing output schema, the definition covers everything an agent needs: supported step types, budget/timeout constraints, lock behavior, failure semantics, background submission flow, and progress reporting. Nothing critical for correct invocation 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 description coverage is 100% and the schema already documents session_id, steps, on_failure, and background with detailed per-field descriptions and a discriminator. The description largely restates the defaults already present in the schema, adding only marginal framing, so baseline 3 applies.

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

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

States a specific verb ('Execute'), the resource ('ordered automation sequence'), and the exact step types (press/wait/state_probe/screenshot), plus the background variant. The ROUTING line explicitly separates it from ppsspp_step and ppsspp_batch_status, so an agent can identify it without opening any 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?

ROUTING gives explicit when-to-use routing: ordered multi-step automation goes here, single CPU-step goes to ppsspp_step, background job survey goes to ppsspp_batch_status. Alternatives and the condition selecting them are named outright.

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 discloses that the tool is mutating, that trace arms and always removes a temporary memory breakpoint and resumes, that reliable hits need CPUCore=2, that mem_remove resolves the real size via mem_list, that mem_update merges omitted booleans, that CPU set/remove return no data and are followed by a list, and that wait/trace remain lock-free. These are material behavioral traits not captured by the structured fields.

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 it is front-loaded with PURPOSE and organized into USAGE, ROUTING, BEHAVIOR, and RETURNS sections. The length is defensible for an 11-action tool, though some material repeats the schema or output schema.

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 11 actions, 13 parameters, annotations, and output schema, the description is complete. It covers action semantics, mutation behavior, condition filtering, timeout behavior, return-shape expectations, and important edge cases such as strict mem_remove and PPSSPP IR condition handling.

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 100%, so the schema already documents all 13 parameters in detail. The description adds cross-action routing and some caveats, but most parameter-specific meaning is redundant with the schema, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb-and-resource statement: it manages CPU execution breakpoints and memory watchpoints and consumes their hits. It distinguishes management, wait, trace, and stats actions, and routes execution breakpoints to set + wait, so an agent can identify what this 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 explicitly states when to use each action: persistent management, one-shot strict-wait via action='wait', and armed hit-capture via action='trace'. It also says when to use set + wait for execution breakpoints and warns against submitting step/pause/resume during a wait, giving clear alternatives and exclusions.

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?

Goes well beyond the read-only/idempotent annotations: unknown addresses return identity=null rather than failing, backtrace is silently skipped (not an error) when the CPU is running with the reason in `note`, the CPU is briefly paused for backtrace and concurrent readers block, and identity comes from a TOPX-specific KB where an empty result means 'not in tables' not 'bad address'.

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?

Header-labeled sections (PURPOSE/USAGE/BEHAVIOR/SCOPE/ROUTING/RETURNS) make it front-loaded and scannable, and each sentence carries signal. The RETURNS block is somewhat redundant given an output schema exists, costing a point.

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 so return values needn't be spelled out, yet the description still covers the non-obvious cases (null identity, skipped backtrace, ISO-specific empty results, brief CPU pause) that an agent must know to interpret responses correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that address is a crash PC/call target and that window covers instructions before/after, but the schema already documents the window count, cap, and the backtrace pause/concurrency behavior, so little is added beyond structured fields.

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?

States a specific verb+resource pack ('one-call crash-triage pack — identity + disassembly window + optional backtrace for an address') and explicitly names sibling tools in the ROUTING section, so an agent can distinguish it from ppsspp_breakpoint and ppsspp_disassemble without opening schemas.

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

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

Provides explicit when-to-use ('pass a crash PC or call target') and explicit alternatives with their selecting conditions: persistent breakpoints -> ppsspp_breakpoint, one armed hit-capture -> ppsspp_breakpoint(action="trace"), recurring sampling -> ppsspp_state_observer.

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 and destructiveHint=false, yet the description adds substantial behavior beyond that: the per-snapshot 8 MiB cap, registry cap of 4 with FIFO eviction, and critically the process-global registry shared across parallel sessions so another session can evict your snapshots. These are non-obvious operational traits that materially change how an agent should use the 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?

Four labeled sections (PURPOSE/USAGE/BEHAVIOR/RETURNS) front-load the most important information and every sentence carries payload — caps, eviction semantics, return shapes. No filler 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?

For a 7-parameter tool with annotations and an output schema, the description closes the remaining gaps: cross-action parameter requirements, registry capacity and eviction behavior, session-sharing hazards, and return payloads. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is already 100%, so the baseline is 3, but the USAGE and RETURNS blocks add call-shape meaning beyond the schema: which params belong to which action (handle required for compare/drop, session_id ignored for drop/list) and what each action returns. The clarification that compare requires the handle's exact range is genuine added semantics.

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 PURPOSE line gives a specific verb+resource with an evocative framing (“classic 'what changed?' variable-locator”) that makes the tool instantly identifiable. It is clearly distinguishable from read_memory, write_memory, and scan, which the description later references by name.

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 lays out the exact workflow (snapshot → act in game → compare) and enumerates how each of the four actions is invoked. It does not, however, state when to prefer this over overlapping siblings like scan or watch_value, so an agent gets strong invocation guidance but no exclusion criteria.

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

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

Annotations already declare readOnlyHint/idempotentHint=true and destructiveHint=false, so the safety profile is pre-covered; the description reinforces this and adds genuine context beyond structured fields by naming the underlying mechanism ('Calls memory.disasm via WebSocket'). It also confirms no memory or CPU state is modified, but adds no rate-limit or failure-mode detail.

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?

Four labeled sections (PURPOSE/USAGE/BEHAVIOR/RETURNS) with zero filler; the essential purpose leads and each line carries distinct information. Well front-loaded for fast agent scanning.

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, so the RETURNS block is a convenience rather than a necessity. Combined with full 100% schema coverage and annotations covering the safety profile, an agent has everything needed to invoke this correctly; the added WebSocket/read-only context closes the remaining gap.

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

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

Schema description coverage is 100%: the schema already documents count's default, count=0 handling, the 100 cap, the clamp note, address hex format, and session_id auto-resolution. The description only restates defaults and never adds syntax or edge-case meaning beyond the schema, so baseline 3 applies.

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

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

The description opens with a precise verb+resource: 'Disassemble N MIPS instructions at a given address.' This clearly distinguishes it from siblings like ppsspp_assemble (the inverse) and ppsspp_search_disasm (which searches rather than dumps at a fixed address).

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?

USAGE states parameter requirements ('address required; session_id optional when exactly one session is active; count optional'), which is helpful, but it never says when to prefer this tool over alternatives such as ppsspp_search_disasm or ppsspp_list_addresses. Usage is implied rather than explicitly scoped.

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 cover read-only/idempotent/non-destructive, and the description adds real behavior beyond that: a documented failure mode (CAPTURE_EMPTY) with a retry remedy, the constraint that capture is by currently-bound state only (no VRAM-address targeting), and the response shape. This is genuinely useful error/limitation disclosure.

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?

Labeled sections (PURPOSE/USAGE/BEHAVIOR/RETURNS) front-load the key information and every sentence carries weight. The only cost is some duplication of the schema's kind/level descriptions, which slightly dilutes conciseness.

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

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

With an output schema present, the description needn't detail return values, and it still summarizes structuredContent fields and the ImageContent block. Between annotations, schema, and the error guidance, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so all three parameters are already documented, including the enum and the clut/level rejection rule. The description largely restates the same semantics (no VRAM-address targeting is the only marginal addition), so baseline 3 applies.

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

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

States a specific verb+resource: dump the currently-bound GPU texture or CLUT palette as image plus metadata. It is clearly distinguishable from siblings like ppsspp_screenshot and ppsspp_gpu_record because it names GPU texture/CLUT capture as the 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?

Gives explicit per-value guidance (kind='texture' uses level for mipmap; kind='clut' requires level=0) and tells the agent what to do when capture is empty. It does not, however, name an alternative tool for related needs (e.g., screenshot), so it stops short of full when/when-not routing.

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, idempotentHint, and destructiveHint, so the description's 'READ-ONLY' label mostly repeats structured data. However, 'Pauses/resumes the CPU internally' adds a meaningful behavioral side effect beyond the annotations exceptional. This helps an agent understand why a seemingly safe read may still briefly affect execution state.

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 well-organized into PURPOSE, USAGE, BEHAVIOR, and RETURNS. Every line carries meaningful operational information without redundancy or fluff. The most important constraints are 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 the two parameters, high schema coverage, and rich annotations, the description provides everything needed to invoke the tool correctly: purpose, required inputs, a behavioral side effect, an alternative for an unsupported use case, and the return shape. Nothing essential 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 description coverage is 100%, and the expression parameter already documents supported syntax, examples, and the no-dereference caveat. The description's 'session_id + expression' adds no new semantic value beyond the schema. There is no coverage gap for the description to compensate for, so 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 opens with a specific verb and resource: 'Evaluate a debugger expression', and enumerates the accepted operand classes ('register names, hex literals, simple arithmetic'). It also separates itself from memory-reading tools by explicitly stating dereference syntax is not supported and pointing to read_u32 instead.

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' line indicates that session_id and expression are required. More importantly, the exclusion 'No '*addr' dereference syntax — read memory with read_u32 instead' gives an explicit when-not-to-use rule and names the alternative. It does not cover all possible alternatives among the many sibling tools, but the key routing edge case is handled.

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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description goes well beyond them: it discloses the session-lock scope, that a CPU it paused is resumed before returning while an already-paused CPU stays paused, and that a failing capture never leaves the game frozen — exactly the safety contract an agent needs for a state-mutating call.

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 PURPOSE/USAGE/ROUTING/BEHAVIOR/RETURNS layout is front-loaded and scannable, with the routing decision placed early. It is slightly verbose, and the RETURNS block partially duplicates the existing output schema, but each section still 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?

Given an output schema already exists, the description needn't restate return fields, yet its nullable-key contract note and behavior guarantees are relevant extras. Routing, preconditions, failure behavior, and pause/resume semantics are all covered for a short state-mutating snapshot 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?

Schema description coverage is 100% and every parameter already carries a description and default, so the baseline is 3. The description's USAGE line largely restates the schema (probes = comma-separated registry names, want_registers default true) rather than adding syntax or format detail beyond it.

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 PURPOSE line gives a specific verb+resource ('paused scene snapshot') and spells out the full sequence (pause, capture pc + registers + optional probes, resume). Siblings like ppsspp_query and ppsspp_state_observer are explicitly named as alternatives, so the agent can distinguish this tool without opening a 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 ROUTING line states exactly when to use this tool ('pause+capture+resume in one call') and names two alternatives with their triggering conditions ('cheap PC-only check -> ppsspp_query', 'recurring sampled probes -> ppsspp_state_observer'). Nothing is left to inference.

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 readOnlyHint annotation, the description reveals the output destination (output/gpu_dumps/), the binary (non-JSON) format, and the MCP pre-probe error conversion. It explicitly says READ-ONLY, which is consistent with annotations, and adds meaningful behavioral context not visible in the schema.

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

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

The description is organized into four compact labeled sections (PURPOSE, USAGE, BEHAVIOR, RETURNS) and front-loads the key facts. Every sentence carries operational value with no 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 a single-parameter tool with a rich annotation set and an existing output schema, the description covers purpose, precondition, output behavior, and return shape. An agent has enough information to invoke it correctly and understand the result without looking up additional 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% and the session_id parameter is already documented as 'Active session ID.' The description only repeats 'session_id' in USAGE without adding extra syntax, validation, or format semantics, so the baseline of 3 applies.

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

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

The description uses a specific verb and resource: 'Capture the next rendered frame's GE command stream as a binary dump file.' This clearly identifies the tool's operation and distinguishes it from sibling GPU tools like ppsspp_gpu_stats or ppsspp_screenshot.

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 the only required input, session_id, and gives an explicit precondition: the CPU must be RUNNING, with a concrete explanation of why and the resulting CPU_STATE_ERROR. It does not name alternative sibling tools, but the when-to-use condition is unambiguous.

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 readOnly/idempotent annotations, it discloses a full timeout taxonomy (expected_stall, pairing_broken, no_producer) and the escalation rule that CPU_FREEZE_SUSPECTED is demoted to WS_TIMEOUT with no-producer attribution when the frame heartbeat is silent. That is behavioral context an agent cannot get from the annotations or schema, plus an operational remedy hint (check for a modal dialog).

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?

Sectioned PURPOSE/USAGE/BEHAVIOR/ON TIMEOUT/RETURNS with the core verb front-loaded, and each block carries distinct information. The RETURNS list slightly duplicates the existing output schema, which is the only mild 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?

For a zero-arg-complexity read tool with an output schema already present, the description covers everything an agent needs: what it returns, the required CPU state, and how to interpret every failure mode. Preconditions and error semantics are fully specified.

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

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

Schema description coverage is 100% for the single session_id parameter, so the schema already documents it fully. The description restates 'USAGE: session_id' and adds a state precondition, but no format, sourcing, or scoping detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource — 'Query GPU counters — fps, vblanks per second, timing info' — and enumerates exactly which counters. An agent can distinguish it from the sibling ppsspp_gpu_record (which captures/records rather than queries) without opening either 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?

Gives a hard precondition ('The CPU must be RUNNING') and even a non-obvious secondary use ('doubles as the cheapest paused-CPU probe'), which is real when-to-use guidance. It stops short of naming alternative tools for the same data, so it falls just below the top band.

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 readOnly/idempotent/non-destructive, so the safety profile is covered; the description nonetheless adds meaningful context: the server probe never contacts PPSSPP, the session battery contacts the transport but never mutates, and it deeply explains value_status semantics, crucially warning that passed=false can mean opposite things (read-zero vs could-not-read). This is above-and-beyond disclosure, though it stops short of e.g. counter/pagination caveats.

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?

Front-loaded sectioned structure (PURPOSE/USAGE/BEHAVIOR/READING/RETURNS) with every block earning its place; the READING section is long but carries high-value disambiguation for interpreting passed vs value_status. Slightly verbose but not wasteful.

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

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

An output schema exists, yet the description still summarizes the return shape (status, version, uptime, tool_count, session_checks, overall_session_status) and explains how to interpret the fields, which is exactly what an agent needs to act on the result. Nothing required to call or interpret the tool 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 100% and the single parameter is already well documented, so baseline is 3; the description adds the enumeration of the four battery checks and clarifies that omitting session_id yields the zero-contact probe, giving more meaning than the schema 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?

States a specific verb+resource (probe server liveness/readiness plus an optional session health battery) and explicitly separates the server-level probe from the session battery, distinguishing it from siblings like ppsspp_state_observer and ppsspp_session. An agent can identify this as the health/diagnostic tool 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?

Gives explicit routing: no args for the server-level probe (no PPSSPP contact), pass session_id to also run the four-point session battery. It also names the absorbed former tool (ppsspp_smoke_test), so an agent migrating from that tool knows where it went.

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 mark it non-read-only and non-idempotent; the description adds the crucial state-machine semantics: the held state persists across calls until the next hold_buttons call, and must be explicitly cleared with an empty combination. It also warns that send_analog does not clear buttons, which prevents a realistic misuse. This is substantive behavior beyond the structured fields.

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 PURPOSE/USAGE/BEHAVIOR/RETURNS labeling front-loads the essential fact (persistent hold) and makes scanning easy. It is slightly redundant with the 100%-covered schema, listing valid button names twice across description and schema.

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 2-parameter state-mutation tool, the definition covers required inputs, the full button vocabulary, persistence semantics, and the release path, and return values are captured by the output schema plus the brief RETURNS line. Nothing needed to invoke this 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 description coverage is 100%, so both parameters and the pipe-separated name list are already documented in the schema. The description repeats the same format guidance and valid name list rather than adding new semantics, so the baseline 3 applies.

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

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

States a specific verb+resource ('Hold a combination of PSP buttons') and scope ('until a subsequent call changes the state'), which is far more specific than a tautology. It distinguishes itself from send_analog ('send_analog does NOT release buttons'), but does not directly contrast itself with the closest sibling, ppsspp_press_button (momentary vs. persistent hold) — that contrast appears only in the schema, not the description.

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?

Gives clear context for when to use it (persistent held state), how to release it (call with buttons=''), and an explicit exclusion (send_analog does not release buttons). It stops short of naming press_button as the alternative for one-shot presses in the description text, leaving part of the routing to the schema.

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 readOnly/idempotent/non-destructive, so 'READ-ONLY' is largely redundant, but the description adds genuinely new behavior: ints ≥0x1000 are returned as hex strings safe to paste into address parameters, and the exact IDA↔PPSSPP conversion arithmetic (with the v0.1.6 note that convert_address no longer exists). Those are real operational facts an agent cannot get from the 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?

Labeled PURPOSE/USAGE/CONVERSION/BEHAVIOR/RETURNS sections are front-loaded and each carries usable content; nothing is padding. It is denser than strictly needed for a one-parameter list tool — the conversion formula and version-history note are slightly tangential — but they are relevant and compact.

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 still summarizes the return shape ({sections, count, section_filter}) and the hex-string formatting of values. With safety covered by annotations, filtering, error behavior, conversion, and return content all addressed, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100% and the schema already documents the section parameter with examples, so the baseline is 3. The description adds error semantics the schema lacks: an unknown section fails with an error enumerating valid sections, which changes how an agent should recover from a bad filter.

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?

States a specific verb (list), a specific resource (address constants), and the authoritative source (addresses.yaml), plus the explicit anti-goal 'never guess hex addresses'. An agent can distinguish this from memory-map/scan/read-memory siblings without opening any 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?

Gives clear context for use (the source of truth for addresses, used before supplying address parameters) and documents the optional section filter and its error behavior. It does not explicitly name which sibling to use instead for related lookups (e.g. memory_map vs. this list), so it stops short of full routing guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context by stating that the tool reads the in-memory manifest registry loaded at startup and does not execute any script. This goes beyond the structured annotations and clarifies the side-effect-free nature.

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, front-loaded with purpose, and uses clear labeled sections (PURPOSE, USAGE, BEHAVIOR, RETURNS). Every sentence contributes useful information with no filler 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?

For a low-complexity read-only listing tool with one optional parameter and an output schema, the description is complete. It covers what the tool does, the filter options, behavioral guarantees, and the return envelope. Nothing needed for correct invocation 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 description coverage is 100%, so the input schema fully documents the category parameter and its valid values. The description repeats this information and adds a return-shape hint, but it does not provide meaningful new semantics beyond what the schema already includes.

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 ('List') and a precise resource (diagnostic scripts declared in .ppsspp-dfx/config/scripts.manifest.yaml). It is clearly distinct from sibling tools like ppsspp_run_script and ppsspp_reload_scripts, and the 'Does not execute any script' note reinforces what this tool is for.

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 explains the optional category filter and its valid values, but it does not explicitly say when to choose this tool over siblings or when not to use it. The intended use is implied rather than stated, and no alternatives are mentioned.

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, idempotentHint=true, and destructiveHint=false, so 'BEHAVIOR: READ-ONLY' is a restatement that adds no new information. The RETURNS line hints at output shape, but an output schema already exists, so nothing about side effects, session prerequisites, or failure modes is added beyond structured data.

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 PURPOSE/USAGE/BEHAVIOR/RETURNS labeling is front-loaded and scannable, and the whole description is four short lines with no prose padding. The USAGE and RETURNS lines are largely redundant with the schema and output schema, which is a small waste rather than a structural flaw.

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 single-parameter read tool, the safety profile (annotations), parameter (schema), and return shape (output schema) are all covered by structured fields, and the purpose line names the exact resource. The only real omission — routing guidance among the many memory-related siblings — is a usage-guideline gap rather than a completeness one.

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 100% and the single parameter is documented as 'Active session ID.' in the schema; 'USAGE: session_id' in the description adds no syntax, format, or validity detail. Baseline 3 applies when the schema carries the parameter semantics.

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?

States a specific verb and resource — 'Get the PPSSPP memory region map' — and enumerates the sub-regions (user/kernel/VRAM), so an agent knows it retrieves the address-space layout rather than bytes. It does not explicitly contrast itself with close siblings like ppsspp_read_memory or ppsspp_list_addresses, which is the only thing keeping it from a 5.

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?

'USAGE: session_id' merely restates the sole required parameter and gives no when-to-use, when-not-to-use, or alternative routing. An agent cannot tell from this description whether to prefer it over ppsspp_read_memory, ppsspp_list_addresses, or ppsspp_search_memory_info.

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 it is a non-readonly, non-idempotent, non-destructive mutation. The description adds genuine behavioral context beyond that: it labels itself 'STATE-CHANGE', explains that the button returns to released after the duration, and the schema notes the call blocks and the 18000-frame cap. It stops short of noting anything about concurrent input or failure modes.

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 PURPOSE/USAGE/BEHAVIOR/RETURNS structure front-loads the essentials and is easy to scan. The button enumeration is duplicated from the schema, which is mild redundancy, but overall there is little waste.

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 3-param input tool with an output schema, annotations, and full schema coverage, the description covers purpose, required inputs, mutation semantics, and duration behavior. The extra RETURNS line is redundant against the output schema, but nothing critical 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 description coverage is 100%, so the schema already documents all three parameters (including button names, duration default/cap, and blocking behavior) thoroughly. The description largely repeats the button list and default already in the schema, adding no format or syntax detail beyond it. Baseline 3 applies.

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

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

States a specific verb+resource: 'Simulate a single PSP button press for a duration.' An agent immediately knows what it does. However, it does not distinguish itself from the sibling ppsspp_hold_buttons or ppsspp_send_analog, which are plausibly related input-simulation tools, so it falls short of a 5.

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 clearly states the required parameters (session_id + button) and that duration is optional with a default, which is useful invocation guidance. But it gives no when-to-use guidance relative to alternatives like hold_buttons or send_analog, nor any prereq like requiring an active session. Usage is implied rather than routed.

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?

Goes well beyond the annotations: it discloses that threads/modules/funcs/func_scan respond while the CPU is RUNNING without a pause, that running-state PC reads are LOW trust unless safe=true, and that func_add/func_remove mutate the debugger-side function list (a nuance annotations alone would not convey). It also notes top_n=0 can produce a 700+KB payload, which is real behavioral context for an agent.

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?

Front-loaded with PURPOSE/USAGE/ROUTING/BEHAVIOR/RETURNS headers, so an agent can skim. It is dense but largely earns its length; a few clauses (e.g. the 'same as the retired ppsspp_get_pc' aside) restate what the annotation or schema already implies.

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, the description need not document return fields, and it correctly just lists {action, data, trust_level}. Given 10 actions, 8 parameters, and an enum, the routing, prerequisites, trust-level semantics, and mutation caveats together make this complete enough to call correctly.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds genuine value: top_n's default and the rationale for pass-0 (700+KB hle.func.list), the safe flag's effect on trust_level, and which actions require name/address. It stops short of explaining the output data shape per action.

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 PURPOSE line names a specific verb (aggregate queries) and enumerates the concrete resources covered — game_state, registers, backtrace, threads, modules, and HLE function-list management. Combined with the ROUTING section, an agent can distinguish this multi-action query tool from ppsspp_frame_snapshot and ppsspp_state_observer without opening any 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 ROUTING block gives explicit when-to-use-this vs when-to-use-a-sibling guidance: one-shot PC read -> query(action='register', name='pc'), pause+capture -> ppsspp_frame_snapshot, recurring probes -> ppsspp_state_observer. It also states the per-action parameter prerequisites (name for 'register', address for func_scan/func_remove) and the safe=true/false tradeoff for PC reads.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real value beyond that: read_string is ASCII-only (with a workaround for game text), MCP does no IR-encoding detection so read_u32 on JIT-IR returns raw bytes, and the size cap behavior (rejected with ARGS_INVALID). This is the substantive behavioral detail the annotations cannot express.

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?

Front-loaded with PURPOSE/USAGE/BEHAVIOR/RETURNS sections, each sentence carrying distinct load. The structured layout lets an agent extract the scoping, routing, and output-channel rules quickly without wasted 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 7-parameter read tool with an output schema, the definition covers the action enum, the address/size constraints, the ASCII-only limitation, the disassembly routing, and the RETURN shape with the three output channels. An agent has everything needed to call it correctly in one pass.

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 schema already documents every parameter in detail; baseline would be 3. The description still adds cross-parameter relationships not obvious from the schema alone (read_string is ASCII-only, read_bytes outputs to value/hex/file, chunking semantics for size). It doesn't add much beyond the schema, but the added interaction rules are genuinely useful.

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?

Opens with an explicit verb+resource ('Read memory') and immediately enumerates the three concrete actions (read_bytes/read_u32/read_string). It also distinguishes itself from siblings by routing scanning to ppsspp_scan and disassembly to ppsspp_disassemble, so an agent can place it precisely among the 37 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?

Explicit when-to-use rules: session_id optional when exactly one session is active, address must be '0x' hex, reads over 65536 bytes must be chunked. It also names the alternative destination for related work ('Memory scanning has moved to ppsspp_scan', disassembly to ppsspp_disassemble), which is exactly the sibling routing a good definition provides.

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?

Goes well past the annotations by disclosing that it re-reads the manifest, invalidates the module cache, is reversible because an unchanged file yields an equal registry, and that a tool-list-changed notification is emitted only when the exposed set actually changes. Annotations only say it is mutating, idempotent and non-destructive; this adds the observable 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?

Labeled PURPOSE/USAGE/BEHAVIOR/RETURNS sections front-load the essential information, and the conditional notification detail is packed into one dense sentence without padding. Every sentence contributes.

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 still summarizes the return shape; annotations cover the safety profile and the description adds the cache/manifest semantics and notification behavior. Nothing an agent needs to call this mutation 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?

The tool takes zero parameters (schema coverage 100%), and the description correctly states 'No parameters', so there is nothing further to document. Baseline 4 applies for a parameterless tool.

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

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

States a specific verb and resource ('reload the script manifest YAML and clear the script module cache'), which is far more than a restatement of the name. It does not, however, explicitly contrast itself with siblings like ppsspp_list_scripts or ppsspp_run_script, so an agent must infer the distinction.

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?

'USAGE: No parameters' describes invocation mechanics, not when to reach for this tool. There is no statement of when a reload is warranted (e.g., after the manifest changes) or how it relates to list_scripts/run_script, leaving usage implied rather than guided.

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?

Goes far beyond the annotations (readOnly=false, destructive=false, idempotent=false) by disclosing that recording requires the CPU RUNNING, that screenshots are rejected while recording, that timelines are absolute game-clock anchored at the recording boot, that execute/load only load the event table and must be followed by the boot-aligned reset/wait/abort sequence, and that executing/saving never self-clear so wait_complete always times out on un-aborted replays.

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?

Front-loaded PURPOSE/USAGE/BEHAVIOR/RETURNS structure makes a dense description scannable, and nearly every clause carries actionable detail (timing anchor, auto-abort, restore_rtc pollution). It is long and occasionally repetitive with the schema, but not padded.

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 stateful 10-parameter replay tool with an output schema present, the description covers the full lifecycle semantics an agent needs: action prerequisites, cross-action state interactions, timing anchoring, and which return fields appear per action. Nothing material is left unstated.

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 already 100%, so the baseline is 3, but the description adds cross-parameter context the schema treats piecewise: which fields pair with which action, that the schema defaults for value/version exist for legacy callers and must not be relied on, and the ordering constraint on restore_rtc relative to the reset.

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?

States a specific verb set and resource: record input sequences, execute them, save/load .ppr recordings in the PPSSPP replay subsystem. This is clearly distinct from siblings like ppsspp_press_button or ppsspp_wait_frames, which provide inputs/frames rather than aggregate replay lifecycle control.

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

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

Explicitly enumerates the ten actions and their per-action prerequisites (execute needs version + base64_input, time_set needs value, save/load take a bare file name under output/replays/, session_id optional when exactly one session is active). It also states when not to rely on defaults and warns when restore_rtc is needed and when it must be set relative to the boot-aligned reset.

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 explicitly declares 'STATE-CHANGE', matching the annotations (readOnlyHint=false, idempotentHint=false). It adds behavioral context beyond annotations by naming error codes (SCRIPT_NOT_FOUND, SESSION_NOT_FOUND) and noting that skeleton scripts are non-functional. While it doesn't detail what state changes occur, the description covers the critical edge cases and the fact that it runs arbitrary registered code.

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 exceptionally well-structured with clear PURPOSE, USAGE, BEHAVIOR, and RETURNS sections. It is concise, with every sentence providing necessary information and no filler. The front-loaded purpose statement immediately tells the agent what the tool does.

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 that runs scripts with three parameters, an output schema, and a rich set of sibling tools, the description is complete. It covers how to obtain valid names, handles the session_id requirement, describes error behavior, and specifies the return shape. The agent has everything needed to call it correctly without additional lookups.

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 100%, so all three parameters (name, input, session_id) are already well-documented in the schema. The description adds marginal value by referencing ppsspp_list_scripts for name discovery and clarifying the session_id priority, but these are largely restatements of schema hints. The baseline of 3 is appropriate because the schema carries the load, and the description does not meaningfully enhance parameter meaning beyond that.

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 ('Invoke') and resource ('manifest-registered diagnostic script') with validated input, clearly distinguishing it from siblings like ppsspp_list_scripts (which lists scripts) and ppsspp_reload_scripts (which reloads). It even notes that skeleton scripts return not_implemented, further disambiguating expected behavior.

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

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

The USAGE section explicitly tells the agent to get the script name from ppsspp_list_scripts, mentions that skeleton scripts return not_implemented, and clarifies the session_id requirement with the error SESSION_NOT_FOUND when missing. It also implies when not to use the tool (for skeleton scripts) without being verbose.

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 declare readOnly/destructive/idempotent; the description adds substantive behavior the annotations cannot carry — consecutive-timeout abort rules, per-chunk skipping of unreadable regions, auto-backgrounding above 2 MiB, a FIFO registry cap of 4 shared process-globally (other sessions can evict your handle), an 8/32 MiB initial-scan cap, and a 600 s job budget. This is exactly the operational context an agent needs before committing to a long scan.

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 and sectioned (PURPOSE/USAGE/BEHAVIOR/ROUTING/RETURNS), so an agent can stop reading early. It is long, and the auto-backgrounding rule is repeated in USAGE, BEHAVIOR, and the background parameter, which is mild redundancy for a 17-parameter tool.

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

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

For a three-mode, 17-parameter tool with concurrency and timeout hazards, the description covers mode selection, session lifecycle, failure modes, and background handoff. An output schema exists, so the RETURNS section is a convenience rather than a necessity, and nothing an agent needs to invoke this 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 description coverage is 100%, so the baseline is 3; the description goes further by specifying cross-parameter contracts (which params matter per mode, that narrow/list/drop must resolve to the same creating session, that the initial cap lifts under background=true). It doesn't restate hex-format syntax or enum values already in the schema, which is the right restraint.

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 PURPOSE line names a specific verb+resource split into three concrete modes (byte-pattern search, value scan with narrowing, charset-aware string harvesting), which is far more than a restatement of the name. Combined with the ROUTING section naming siblings (ppsspp_diff_memory, ppsspp_breakpoint, read_memory), an agent can place this tool precisely in the family.

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 block gives explicit parameter combinations per mode and the phase workflow (initial → narrow → list/drop), and the ROUTING block states when to use a sibling instead ('what-changed-between-two-points -> ppsspp_diff_memory', 'who-accesses-this-address -> ppsspp_breakpoint', 'known addresses -> read_memory directly'). When-not guidance is explicit, including the 'frozen session' trap.

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 readOnly/idempotent/destructive annotations, it discloses the render-to-VRAM auto-fallback, unreliable colors on VRAM, crash risk of 'output', and the empty=true instead of error behavior. These are precisely the behavioral traits that affect invocation and interpretation of results.

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?

Organized into PURPOSE, USAGE, BEHAVIOR, and RETURNS with each sentence carrying distinct information and no filler. The critical caveats are near the top and easy to scan.

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 annotations covering safety and an output schema covering metadata, the description adds exactly what is needed: purpose, source selection rules, empty-capture semantics, and how the image is returned and where it is saved. No critical invocation detail 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 100%, so the schema already documents the parameters, but the description adds operationally important semantics: source default plus fallback behavior, the 'output' risk warning, mode deprecation and exclusivity, and the single-active-session condition for omitting session_id.

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?

States a specific verb, resource, and output: captures the framebuffer as an ImageContent plus metadata. The purpose is clear, but it does not explicitly distinguish itself from close siblings such as ppsspp_frame_snapshot or ppsspp_dump_texture.

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 actionable usage conditions: session_id may be omitted when exactly one session is active, source='render' is the safe default, and source='output' is explicitly marked crash-risk and not to be used. It explains mutual exclusivity with the deprecated mode param, though it does not name alternative tools for when this tool should be avoided.

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, idempotentHint=true, and destructiveHint=false, and the description repeats 'READ-ONLY.' It also discloses loop/wrap behavior and match collection, but these details are already in the schema's parameter descriptions, so the description adds little new behavioral context beyond the annotations.

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

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

The description uses four labeled one-line sections (PURPOSE, USAGE, BEHAVIOR, RETURNS) and front-loads the purpose. Every line earns its place, and there is no fluff or redundant elaboration.

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 the detailed input schema covering all parameters, the read-only/idempotent annotations, and an output schema present, the description gives enough operational context including defaults, wrap behavior, and return envelope. An agent has all needed information 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?

Schema description coverage is 100%, and every parameter already has thorough semantic explanation (e.g., end=0 wrap behavior, '$' stripping, max_results loop mechanism). The description's USAGE line merely summarizes these details without adding further meaning, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'Loop-search disassembly for a substring, collecting matching instructions with context.' This makes the tool's function immediately clear and inherently differentiates it from siblings like ppsspp_disassemble (one-shot disassembly) and ppsspp_memory_info_search (searching memory values rather than disassembly text).

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 concrete invocation guidance: required session_id and match, leading '$' stripping, start address, end=0 wrap-around, and max_results default. It does not explicitly name alternatives or state when not to use this tool, but the context is clear enough to proceed.

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 'READ-ONLY' statement merely restates readOnlyHint/destructiveHint=false already in annotations, and the RETURNS shape is largely covered by the output schema. The one genuinely additive detail is 'Returns a single extent per matching tag', which clarifies result granularity, but permissions, pagination/limits, and failure modes are unaddressed.

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?

Four labeled sections, front-loaded PURPOSE, zero filler sentences. The agent can parse purpose, inputs, safety, and return shape at a glance.

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 annotations carrying the safety profile, a 100%-covered schema, and an output schema describing the {regions[], count, raw, text} return, the description covers what an agent needs to invoke correctly. Only cross-tool routing guidance 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 description coverage is 100%, so all five parameters (including hex-string address/end semantics and the type filter examples) are already documented in the schema. The description only repeats the case-insensitive substring nature of 'match' and the optionality of the filters, adding nothing new.

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?

States a specific verb and resource: searching PPSSPP's memory-tracking metadata for allocation/texture tags. This is distinguishable from siblings like ppsspp_search_disasm (disassembly) and ppsspp_scan (memory scanning), though no sibling is named explicitly.

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 line identifies the required inputs (session_id + match) and the optional filters, which implies when the tool applies. However, it gives no guidance on when to prefer this over ppsspp_search_disasm, ppsspp_scan, or ppsspp_read_memory, and no exclusions.

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 BEHAVIOR section explicitly labels this as a STATE-CHANGE operation, states that the position persists until the next send_analog call, and notes that it is not idempotent in effect. This adds meaningful context beyond the annotations (which only say readOnlyHint=false, idempotentHint=false) by explaining the persistence semantics.

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 well-structured with clear PURPOSE, USAGE, BEHAVIOR, and RETURNS sections. Every sentence earns its place, and the most important information (what the tool does and required parameters) 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 description covers purpose, usage, behavior, and return value. With an output schema present and full parameter schema coverage, nothing critical is missing. It could slightly improve by noting whether the analog position resets on session end, but this is a minor gap.

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

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

Schema description coverage is 100%, so the schema already fully documents all three parameters. The description adds a concise summary of the coordinate system but does not add new information beyond what the schema provides. 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 states a specific verb ('Send') and resource ('analog stick position'), and precisely defines the coordinate semantics (x, y in [0, 255], 128 = center). It clearly distinguishes this from sibling input tools like ppsspp_press_button and ppsspp_hold_buttons by focusing on analog state rather than discrete button presses.

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

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

The USAGE section explicitly lists required parameters (session_id + x + y) and explains the value mapping (0 = full left/up, 255 = full right/down). It does not explicitly name alternative tools or when-not-to-use conditions, but the purpose is specific enough that an agent can infer when to use it versus siblings.

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?

Goes well beyond the annotations: declares START spawns a subprocess + WS debugger, STOP terminates it with an explicit 'never taskkill the process yourself' warning, wait_ready's lock-free polling and [BOOT_TIMEOUT] failure mode, the 30-min idle GC side effect, and resilient self-heal behavior. None of this is recoverable from the readOnlyHint=false/destructiveHint=false hints 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?

Labeled PURPOSE/USAGE/BEHAVIOR/RETURNS sections are front-loaded and scannable. Some content (the RETURNS breakdown) is duplicated by the schema and output schema, so a few sentences do not strictly earn their 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 7-parameter, multi-action tool with no idempotency and open-world behavior, the description covers triggers, ordering, failure modes, and state semantics. An output schema exists, yet the description pre-explains the return shapes, leaving no gap an agent would need to fill.

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 100% schema coverage the schema already documents each parameter, so the baseline is 3, but the description adds cross-parameter semantics the schema does not: which action consumes which argument, and the resilient-start reinterpretation of timeout_s as a per-attempt budget. It restates some field meanings rather than extending all of them, keeping it off a 5.

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 PURPOSE line names a specific resource (PPSSPP debug sessions) and enumerates the exact verb set (list/start/stop/get/wait_ready), so the agent knows the tool's scope instantly. It also explicitly differentiates from the sibling ppsspp_health for per-session health probing.

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?

USAGE spells out per-action parameter requirements and a hard ordering rule ('Call wait_ready AFTER start and BEFORE any memory tool') with the reason (WS answers before CPU boots). It names the alternative (ppsspp_health) and the fallback (pass wait_ready=true on start) rather than leaving routing to inference.

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 discloses that register/clear mutate state, the registry is PER-SESSION keyed by session_id, it is seeded from addresses.yaml, and clear removes only user-registered probes so the configured baseline survives. It even contrasts delete semantics with ppsspp_breakpoint mem_remove. The one nuance is that the description calls clear idempotent while idempotentHint=false applies to the whole multi-action tool — a refinement rather than a hard contradiction, since register is not idempotent.

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?

Labeled sections (PURPOSE/USAGE/ROUTING/BEHAVIOR/RETURNS) make it front-loaded and scannable, and every section carries non-redundant information. It is somewhat long for a single tool, and the RETURNS line partly duplicates the existing output schema, keeping it just below a 5.

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

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

For a high-complexity tool (8 params, 4 actions) the description covers the action model, per-session registry lifetime, mutation semantics, idempotent delete behavior, and the return shape — with an output schema and annotations also present. Nothing an agent needs to invoke 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 description coverage is 100%, so the schema already documents name, size, names, samples, address and the action enum in detail. The description restates the action/parameter pairing ('register needs name + address (+size 1/2/4, description); observe takes comma-separated names') but adds no syntax or format meaning beyond what the schema provides. Baseline 3 is correct.

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 pairing — 'Named memory-probe registry plus running-state observation' — and immediately distinguishes the two modes (register once, sample cheaply). The ROUTING section names the exact siblings it is not (ppsspp_frame_snapshot, ppsspp_breakpoint trace), so an agent can separate this from adjacent memory tools without opening a 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?

ROUTING gives explicit when-to-use-this-vs-alternatives: recurring sampled probes across loops go here, one-shot paused snapshots go to ppsspp_frame_snapshot, single-address access watches go to ppsspp_breakpoint(action='trace'). The USAGE line also spells out which parameters each action requires.

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?

Declares the tool as STATE-CHANGE, discloses that 'reset' reboots the game and loses in-memory state, that 'run_until' sets a temp breakpoint and is fire-and-forget with no hit confirmation, and that resume pc/ticks are LOW-trust. This goes well beyond the readOnly/destructive/idempotent 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?

Front-loaded with PURPOSE/USAGE/ROUTING labels and tightly organized, but it is dense and partially duplicates the enum descriptions in the schema, which costs a little economy.

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

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

Covers purpose, routing, per-action behavior, and even return-field trust levels. With an output schema already present, nothing an agent needs to invoke this 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 already 100%, so baseline is 3, but the description adds genuine nuance: the schema default '0x0' should not be relied on for run_until, run_until returns immediately with no confirmation, and resume pc/ticks are a best-effort snapshot. This meaningfully supplements 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?

States a specific verb and resource ('Aggregate CPU run-state control') and enumerates the exact actions. It also contrasts itself with the sibling ppsspp_batch_step, so an agent can distinguish the two without opening schemas.

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?

Gives explicit routing rules: single run-state operations go here, multi-step press/wait/probe sequences and cpu_step go to ppsspp_batch_step. It also states per-action requirements ('run_until' requires address) and the session_id omission rule.

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 declare idempotentHint=true, but the description states 'STATE-CHANGE. Sleeps the caller; emulator advances N frames.' This implies each call advances the emulator, so repeated calls with the same arguments would have additional effect, directly contradicting idempotentHint=true. Per the rules, this is an annotation contradiction, so score 1.

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

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

The description is organized into PURPOSE, USAGE, BEHAVIOR, and RETURNS sections. It is front-loaded with the purpose and every sentence is concise and informative, with no wasted words.

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 annotations, a full output schema, and 100% schema coverage, the description supplies the core operational context (state-change, session validation, return shape). It is adequate for invocation, though it lacks sibling differentiation, which is more properly a purpose/usage concern.

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 100%, and the schema already documents frames, interval, and session_id in detail. The description only restates that session_id and frames are required and interval is optional, adding no extra semantics beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 and resource: 'Wait N frames ... to let the emulator advance.' It is clear what the tool does, but it does not name or differentiate from siblings like ppsspp_step or ppsspp_batch_step, so it falls short of a 5.

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 lists required parameters (session_id + frames) and optional interval, but gives no explicit guidance on when to prefer this tool over alternatives such as ppsspp_step or ppsspp_batch_step. Usage context is implied by the purpose, but there are no when/when-not conditions or alternatives named.

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, destructiveHint=false, so safety is partly covered, but the description adds genuinely new context: it is a polling loop that never mutates state, it blocks ~duration_frames/60 seconds (cap 18000 frames), and it is 'storm-free' on hot addresses. The concurrency/lock behavior (SESSION_BUSY) is only in the schema, not here, keeping it short of a 5.

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?

Labeled PURPOSE/USAGE/BEHAVIOR/RETURNS sections front-load the key facts with no filler. The RETURNS block duplicates information already carried by the output schema, costing a little economy, but overall it is tight and skimmable.

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 full schema coverage, rich annotations and an output schema, the description supplies the extra behavioral context (blocking duration, cap, lock implications implied via the schema) that an agent needs to call it correctly. It is complete for this tool's complexity, though it could have surfaced the session-lock behavior in prose.

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 100%, so all five parameters including mode, interval_frames and the lock caveat on duration_frames are already documented in the schema. The description adds only a light gloss ('Polls the value every interval_frames and records changes'), which is marginal over what structured fields provide, so the baseline 3 applies.

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

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

The opening sentence names a specific verb+resource ('Value-change watch on an address') and immediately positions it against a sibling concept ('zero-pause alternative to a read watchpoint'). An agent can distinguish it from ppsspp_read_memory and ppsspp_breakpoint without opening any 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 USAGE line specifies the required inputs and the description names one alternative (read watchpoint) with the condition that selects this tool (zero-pause, storm-free on hot addresses). It lacks explicit when-not guidance against other siblings like ppsspp_breakpoint or ppsspp_state_observer, so it is clear context but not full routing.

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 destructiveHint=true and idempotentHint=false, but the description adds real value beyond them: it defines which ranges are protected (kernel below 0x08800000 and top.prx code), states the exempt case (addresses.yaml), and notes that a ToolError (PROTECTED_ADDRESS) is raised without force. This is meaningful operational detail, not repetition of the 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 labeled PURPOSE/USAGE/BEHAVIOR/RETURNS structure is front-loaded and scannable, with no filler sentences. It is appropriately sized for a 6-parameter mutation tool, though the terse phrasings occasionally assume reader familiarity.

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 annotations covering the safety profile, a full output schema documenting the return shape, and 100% schema coverage on all six parameters, the description supplies exactly the remaining context an agent needs: format options, destructive nature, force requirement, and error behavior.

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 100%, so the schema already documents data, value, force, format, address and session_id in depth. The description echoes the format enum and the data/value roles without adding syntax or edge cases beyond the schema, matching the baseline 3 when structured fields do the heavy lifting.

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 ('Write u8/u16/u32 or raw bytes to memory') and names the accepted formats, so the tool's function is unambiguous. It does not explicitly contrast itself with siblings like ppsspp_read_memory or ppsspp_write_register, leaving differentiation to the tool name.

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 block lists the required inputs (session_id + address + data + format) and the BEHAVIOR block explains when force=true is needed, which implies usage context. However, it never states when to choose this tool over ppsspp_write_register or other mutation siblings, so alternatives are left to inference.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine value beyond them by disclosing that the CPU is paused and resumed internally and that no manual pause is required.

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 PURPOSE/USAGE/BEHAVIOR/RETURNS structure is front-loaded and easy to scan. The USAGE line slightly duplicates schema information, but no sentence is wasted.

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, the RETURNS line is a bonus rather than a necessity, and the pause/resume disclosure closes the main behavioral gap. Complete enough for a destructive mutation tool whose annotations already carry the safety signals.

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 100%, and the name/value descriptions already document alias normalization, hex format, and out-of-range rejection. The description largely echoes the schema, so the baseline 3 applies.

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

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

States a precise verb (Set) plus resource (CPU register) and enumerates scope: GPR/FPU/VFPU names plus pc/hi/lo. This is enough to distinguish it from the sibling ppsspp_write_memory without opening either 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 USAGE line only restates the required parameter trio already declared in the schema and adds no when-to-use or when-not guidance. It never says when to prefer this over ppsspp_write_memory or other mutation tools, so usage is only implied.

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