Press a Playdate button

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.