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

The description adds useful behavioral details beyond the annotations: it states that the framebuffer dimensions are 400 by 240, that a new PNG file is created, and that 'Existing files are never overwritten.' This meaningfully clarifies the safety profile and output behavior, even though the annotations already hint the operation is not read-only.

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

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

Two sentences, front-loaded with the core action and resource, followed by a precise safety guarantee. There is no filler, and every sentence adds necessary information for correct invocation.

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

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

For a simple two-parameter tool with a full schema and output schema present, the description is complete: it states the operation, the output type, the file-creation semantics, and the no-overwrite guarantee. Nothing essential is missing for an agent to call 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 description coverage is 100%, so the schema already documents both parameters well. The description reinforces that output_path must be a new PNG path and that overwriting is avoided, but it does not add substantial meaning beyond the structured parameter descriptions.

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

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

The description names a specific verb ('Capture'), a specific resource ('the 400 by 240 framebuffer'), and an explicit outcome ('to a new PNG path and return it as MCP image content'). It is clearly distinguishable from sibling tools like playdate_record, which would capture continuous footage rather than a single frame.

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

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

The intended usage is clear: use this tool when you need a static screenshot of the Playdate framebuffer saved as a PNG. It does not explicitly name alternatives or provide exclusion criteria, but the describe action is unambiguous enough that an agent can infer when this tool is appropriate.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false; the description adds useful context by calling it a diagnostic primitive and noting normal control tools inject automatically. It does not fully explain what happens when the agent is missing (e.g., whether it injects, errors, or waits), and readOnlyHint=false hints at side effects without spelling them out.

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

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

Two terse sentences with no filler. The description front-loads the tool's identity and purpose, and the auto-injection note earns its place by telling the agent why this tool is not the normal path.

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

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

For a tool with one optional parameter and an output schema, the definition covers the core purpose and relationship to normal control tools. It could add an explicit trigger condition, such as 'use when a control tool reports the agent is unavailable,' but the tool's simple shape makes this a minor omission.

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

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

The single optional parameter 'pid' is fully described in the schema with 100% coverage, so the schema carries the semantic weight. The description adds no parameter-specific guidance, but the baseline 3 applies because the schema is complete.

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 function: a diagnostic primitive that finds the selected Simulator and ensures its control agent is available. The line 'Normal control tools inject automatically' distinguishes it from the sibling control tools. The title reinforces the target resource and action.

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 is implied rather than explicit: 'Diagnostic primitive' and 'Normal control tools inject automatically' suggest this tool is a fallback for checking or forcing injection, not a routine control call. However, it does not explicitly state when to call it, what condition warrants it, or name an alternative tool to prefer.

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 disclose idempotentHint=true and destructiveHint=true, and the description adds the useful behavioral distinction that this loads an existing bundle without building. It does not explain what destructive consequences loading may have on current simulator state, but the annotation covers that safety profile.

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?

A single sentence that front-loads the core action and resource, then adds the critical scoping detail 'without running a build task'. There is no redundant or wasted wording.

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

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

The tool is simple with one required parameter, a full schema description, and an output schema present. The description plus schema is enough for an agent to invoke it correctly; only a slightly richer statement about load-time side effects would push it to full completeness.

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 explains both product_path and pid in sufficient detail. The description adds no parameter-level meaning beyond restating that the bundle must already exist, 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 uses a specific verb and resource: 'Load an existing PDX directory bundle'. The qualifier 'without running a build task' distinguishes this from build-and-run workflows and from sibling tools like playdate_run or playdate_restart.

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

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

The description gives clear context: use this when the .pdx already exists and no build step is needed. It does not explicitly name sibling alternatives or state when not to use it, but the 'without running a build task' contrast implies the broader run/build workflow boundary.

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

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

The description adds meaningful behavioral detail not present in the annotations: the press is momentary ('press and release'), has a bounded duration, and lock toggles immediately without accepting duration_ms. Since the annotations are mostly false flags providing little safety or mutability guidance, this extra context is valuable.

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

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

The description is two short sentences with no filler. The core behavior is front-loaded, and the special lock behavior is stated separately and clearly. Every sentence earns its place.

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

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

Given the complex anyOf schema, the description covers the important distinction between normal presses and the lock toggle. It also communicates boundedness, which is relevant for callers. The output schema exists and the parameter schema is fully described, so nothing critical is missing for correct invocation.

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

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

The schema already documents all parameters with descriptions, so the baseline is 3. The description adds one useful semantic detail beyond the schema: lock does not accept duration_ms. It does not explain pid or button semantics further, but that is not necessary given full schema coverage.

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

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

The description states the specific action ('Press and release a button') and resource (Playdate button), and clearly distinguishes the lock case from normal button presses. It is not a tautology and adds behavioral nuance beyond the title.

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 implies when to use this tool—for temporary presses with a bounded duration—and notes that lock behaves differently by toggling immediately. However, it does not explicitly compare with siblings like playdate_toggle_lock or say when one should be preferred over another.

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

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

The description goes beyond annotations by disclosing that recording state is owned by the Simulator agent, not the MCP server, which is crucial behavioral context. It also clarifies that starting uses a new GIF path while stopping finalizes the active recording. Edge cases like repeated start calls or stopping with no active recording are not covered, but the annotations already signal mutation and non-idempotency.

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

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

The description is two sentences with no filler. The first sentence states the core behavior, and the second adds essential state-ownership context, both earning 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?

The description covers the two modes of operation and the key external-state caveat, while an output schema exists to document return values. It is sufficiently complete for an agent to select and invoke the tool correctly, though behavior during edge cases such as overlapping recordings is not 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%, so the schema already documents pid and output_path. The description adds little semantic value beyond restating 'new GIF path' and the start/stop actions, so the baseline score 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 states the exact behavior: 'Start recording to a new GIF path or stop and finalize the active recording,' with a specific resource (Playdate GIF recording). It is clear on its own, though it does not explicitly differentiate itself from siblings like playdate_capture_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?

The description implies usage by defining the start and stop actions, and the note that recording state belongs to the Simulator agent provides relevant context for when this tool is appropriate. However, it does not explicitly state when to prefer this over sibling tools or mention any exclusions or prerequisites.

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=false and destructiveHint=true, so the agent knows this mutates state destructively. The description adds that the runtime state is reset, which is useful context, but it does not explain consequences such as loss of unsaved progress. No contradiction with annotations.

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

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

The description is a single front-loaded sentence with no filler. It conveys the action, scope, and side effect efficiently.

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

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

The tool is simple, has one optional parameter fully documented in the schema, and has an output schema. The description covers the core behavior and precondition of a currently loaded game, which is sufficient for an agent to invoke the 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%, with the pid parameter already described as a positive process identifier used when more than one simulator is running. The tool description adds no additional parameter guidance, 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 states a specific verb and resource: restart the currently loaded game, resetting its runtime state. It is clear enough to distinguish from playdate_load and playdate_run, though it does not explicitly name a sibling.

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

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

The description gives no guidance on when to use this tool versus siblings like playdate_run, playdate_load, or playdate_set_paused. The intended use is implied by the name and description, but no exclusions or 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 signal destructiveHint=true, readOnlyHint=false, and openWorldHint=true. The description adds orchestration detail—builds, launches, injects, loads—so the agent understands the tool has side effects beyond a simple read or load. No contradiction with annotations.

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

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

Two sentences, no filler. The action sequence is front-loaded, and the usage context is stated plainly in the second sentence. Every word 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?

The description effectively captures the tool's orchestration purpose and its role as the standard entry point. Given the output schema exists and parameter details are covered, the main missing piece is explicit guidance on when to use a lighter sibling instead, but the overall workflow context is sufficient.

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 parameters like product_path, pid, build_task, and project_directory are already documented structurally. The description does not add parameter-level meaning beyond mentioning that the project's build task is run and the PDX is loaded, which is acceptable given full schema coverage.

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

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

The description names a specific multi-step verb sequence: run the mise build task, launch or find the Simulator, inject the control agent, and load the PDX. This clearly identifies the tool's role and distinguishes it from narrower siblings like playdate_load or playdate_inject by presenting it as the full first-call workflow.

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

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

The phrase 'This is the normal first call and reload workflow' gives clear contextual guidance on when to invoke this tool. It does not explicitly list when to prefer alternatives such as playdate_load or playdate_inject, but the normal-workflow framing provides enough direction.

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=false and destructiveHint=false, and the description adds the useful context that this sets simulator accelerometer axes rather than real-device state. However, it does not disclose side effects such as event generation, clamping, units, or coordinate system, so behavioral transparency beyond annotations is limited.

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?

A single sentence that is front-loaded with the action and target. There is no filler, redundancy, or unnecessary detail; every word earns its place.

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

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

For a simple setter with an output schema and safety annotations, the description covers the core resource and fields, and the schema documents the pid parameter. It is not fully complete because units and value ranges for x, y, and z are missing, and there is no guidance on when this tool is appropriate, leaving an agent to infer or guess valid accelerometer semantics.

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

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

Schema description coverage is only 25%, and the description does not fill the gap. It merely restates that x, y, and z are accelerometer values without specifying units, valid ranges, or axis orientation; the optional pid is already documented in the schema, so the description adds little semantic value beyond the property names.

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

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

The description names a specific action ('Set'), a specific resource ('Simulator accelerometer'), and the exact fields (x, y, z). It is clear and implicitly separates this from sibling tools such as playdate_set_crank and playdate_set_button by focusing on accelerometer axes, though it does not explicitly name an alternative.

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?

No guidance is given on when to use this tool vs. alternatives, no prerequisites, and no exclusions. The only contextual hint is the word 'Simulator', which weakly implies this is for simulation rather than physical hardware, but there is no explicit when-to-use guidance.

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

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

Annotations already signal a non-read-only, idempotent, non-destructive action. The description adds behavioral value by clarifying that the operation holds or releases a single button and is designed for building deterministic/simultaneous input sequences. It stops short of explicitly saying the state persists until changed, but no contradiction exists.

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

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

A single front-loaded sentence that communicates the action and purpose without filler. Every phrase ('hold or release,' 'one button,' 'deterministic and simultaneous input sequences') earns its place.

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

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

For a simple three-parameter setter with an output schema and idempotent/destructive annotations, the description covers the operational behavior and use case. The only notable omission is an explicit pointer to playdate_press for momentary taps, but the tool is otherwise callable from the information provided.

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

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

With only 33% schema description coverage, the description compensates by explaining the core relationship: 'hold or release' maps the state enum to persistent down/up semantics, and 'one button' identifies the target. The optional pid is already described in the schema, and the allowed button values are fully enumerated, so the description adds meaning without needing to repeat them.

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 the precise verbs 'hold or release' and names the resource 'one button,' going beyond the generic title. It clearly implies a state-setter distinct from momentary-press siblings like playdate_press, though it does not explicitly name any alternative.

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

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

The phrase 'for deterministic and simultaneous input sequences' gives a clear intended context, and 'hold or release' implies a stateful use case rather than a tap. However, it does not state when not to use it or explicitly point to playdate_press or other siblings for momentary actions.

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

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

Annotations already indicate this is a mutating, idempotent, non-destructive operation. The description adds the meaningful detail that the crank supports both angle and docked states, but it does not disclose additional side effects or runtime requirements. This is adequate but not rich.

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?

A single, front-loaded sentence captures both modes with no redundancy. It is efficient and avoids unnecessary detail.

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, combined with the schema's anyOf branches and the presence of an output schema, gives an agent enough to invoke the tool correctly. A slightly more explicit statement about mutual exclusivity of degrees and docked would make it fully complete, though the schema already enforces this.

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

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

The description gives plain-language meaning to the schema's otherwise bare parameters: 'degrees' is the crank angle in degrees and 'docked' represents the docked state. This helps an agent interpret the anyOf branches correctly beyond what the schema types alone 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?

The description states a specific verb ('Set'), the resource ('crank'), and the two supported modes ('position in degrees' or 'docked'). It is immediately clear what the tool does and how it differs from the sibling tools, which target other Playdate controls.

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 makes the tool's purpose obvious, but it does not explicitly explain when to choose this tool over alternatives or when not to use it. Since no sibling tool targets the crank, this is a minor gap rather than a critical one.

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

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

Annotations already cover key behavioral traits: readOnlyHint=false indicates mutation, idempotentHint=true indicates repeated calls are safe, and destructiveHint=false indicates no destruction. The description adds the context that it targets the running game, but does not describe error cases or output behavior; the existing output schema and annotations carry much of that burden.

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

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

The description is a single short sentence, 'Pause or resume the running game,' that immediately conveys the action and target with no wasted words. It is appropriately sized for a simple state-setting 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 two-parameter tool with full schema coverage, clear annotations, and an output schema present, this description is sufficient. The schema explains pid and paused semantics, and the annotations cover idempotency and safety, so 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 pid and paused thoroughly, including that paused is 'True to pause; false to resume.' The description adds no additional parameter 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 uses a clear verb and object: 'Pause or resume the running game.' It accurately identifies the operation and is distinguishable from siblings like playdate_run and playdate_set_button, though it does not explicitly contrast itself with them.

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 is implied by the phrase 'the running game,' suggesting the tool is appropriate when a game is already active and needs pausing or resuming. However, there is no explicit guidance about alternatives or when not to use this tool.

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

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

Annotations provide no safety profile, so the description carries the burden. It discloses the key behavior: set to a percent, adjust relative, and default to 10. However, it does not mention side effects, persistence, whether the change affects the simulator only, or how it interacts with the current volume 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?

Two short sentences convey both modes and the default behavior without wasted words. The information is front-loaded and easy to parse.

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 simple volume-adjustment tool, an output schema exists, and the anyOf branches are both covered by the description, the definition is nearly complete. A brief note on clamping or muting would be a minor enhancement, but 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 coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by documenting the default adjustment amount ('Defaults to 10 percent') and clarifying the meaning of percent in each mode. The pid parameter remains schema-documented, which is sufficient.

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 ('Set', 'adjust') and a clear resource ('volume'), and explicitly distinguishes the two operational modes ('set' vs 'up/down'). This makes it immediately clear what the tool does and separates it from the other Playdate tools by resource and action.

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

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

The description gives clear operational context: use 'set' for an absolute value and 'up'/'down' for relative adjustment, with a stated default when percent is omitted. There is no alternative tool for volume among the siblings, so no exclusionary guidance is needed; the intended use is clear enough.

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 discloses that the tool may inject the control agent, which meaningfully complements the annotations by explaining the non-read-only behavior. It identifies both the side effect and the condition under which it occurs, with no contradiction.

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

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

Two short sentences deliver purpose, behavior, and a side-effect warning with no filler. The key action is front-loaded and every clause 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?

The description is sufficient for a low-complexity tool: it states the purpose, the conditional mutation, and relies on the output schema for return details. The exact meaning of 'selected Simulator' and 'control agent' is left implicit, but this is unlikely to block correct invocation.

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

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

The schema already provides full documentation for the single optional pid parameter, so the description carries no added parameter burden. The phrase 'selected Simulator' relates to the selection context but does not add semantic detail beyond the schema.

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

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

The description names a specific action and resource: find the selected Simulator, ensure its control agent is available, and return agent status. It is clear and not a tautology, but it does not contrast with sibling tools such as playdate_inject or playdate_run.

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

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

There is no explicit when-to-use guidance or mention of alternatives. The sentence 'This may inject the agent when it is absent' hints at a relevant side effect, but it does not tell the agent when to prefer this tool over playdate_inject or other 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?

Annotations already convey readOnlyHint=false and idempotentHint=false, so the mutation and non-idempotent nature are structured. The description adds the specific 'toggle' semantics—flipping the lock state rather than setting it—but does not disclose side effects, effects of omitting pid, or interaction with the simulator.

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

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

The description is a single focused sentence with no filler. The action is front-loaded, and the length is appropriate for a one-parameter toggle operation.

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

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

For a simple tool with one optional parameter, annotations, and an output schema, the description covers the essential action. The main gap is the lack of usage guidance, but this is not critical given the tool's simplicity.

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 optional pid parameter is fully documented in the schema. The description adds no extra meaning about the parameter, so the baseline score 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 states a specific verb ('toggle') and resource ('Simulator's Playdate lock state'), which is enough to tell it apart from siblings like playdate_set_paused or playdate_press. It closely echoes the title but adds 'Simulator's' and is not a tautology.

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?

No guidance is provided on when to use this tool versus alternatives such as playdate_set_paused or playdate_press. There are no prerequisites, conditions, or exclusions, leaving usage entirely 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?

The description discloses a real behavioral quirk: the gif action may open a Save Recording dialog. Annotations do not provide meaningful safety context beyond all-false hints, so the description carries the burden, but it only covers one action and says nothing about side effects of pause, restart, console, or others.

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

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

The description is short and the behavioral caveat is front-loaded in the second sentence. The first sentence largely repeats the title, but the word 'exact' adds a small amount of precision, so the text is still efficient overall.

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

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

The tool is simple, the action enum is in the schema, and an output schema exists, so return-value information is not required. The description covers the main gotcha (gif dialog) and directs to the right alternative. It could be more complete by flagging which actions are non-interactive or require a running simulator, but it is sufficient for most calls.

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

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

The schema describes pid and provides self-explanatory enum values for action, so the schema already covers much of the parameter meaning. The description adds a useful caveat about the gif action, but it does not explain pid selection or the meaning of less obvious actions like sampler or lua-memory.

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 clear verb and resource: 'Invoke an exact Simulator toolbar action.' It also distinguishes itself from playdate_record for GIF capture. However, it does not enumerate or otherwise clarify the specific toolbar actions beyond the schema, and it overlaps with the tool title.

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

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

The description gives an explicit when-not/alternative rule: for the gif action, use playdate_record instead to avoid the Save Recording dialog. This is useful but only addresses one of several possible actions, leaving sibling distinctions like playdate_set_paused vs. the pause action unaddressed.

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