desktop_safety

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

Annotations only say readOnlyHint=false and openWorldHint=false, so the description carries the burden of explaining the mixed read/write nature, and it does: it discloses that E-Stop clearing and whitelist widening/disablement are impossible for the agent. That is meaningful safety context beyond the annotations, though it doesn't say what lock versus tighten actually do to existing rules or whether either is reversible.

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 inspection surface and then the action branch, with parenthetical enum names inline where they help. It is dense but every clause carries information; only the hotkey-config detail feels like it could be trimmed for an agent that can read the 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 five-parameter, dual-mode tool with no output schema and thin schema descriptions, the definition covers the conceptual surface but not the mechanics: no return shape for status inspection, no explanation of how the flat process/hwnd/title_contains shorthand is combined with rules, and no statement of whether lock/tighten are reversible.

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 20% schema coverage across 5 parameters, the description must compensate, and it partly does by surfacing the two write action names and the concept of whitelist rules. However, it never explains hwnd, title_contains, or how the shorthand process parameter relates to the full rules array, so three of five parameters remain undocumented in both places.

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 the concrete resources inspected (E-Stop overlay, hotkey config, whitelist rules, backend health) and the two write actions (lock_whitelist/tighten_whitelist), so the tool's scope is unambiguous. It stops short of naming a sibling to contrast with, leaving the agent to infer that desktop_stop is the trigger rather than the inspector.

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 'OR' structure clearly separates the read branch (inspect state) from the write branch (lock/tighten the whitelist), which maps directly onto the action enum. The closing sentence supplies a firm exclusion — the AI cannot clear an E-Stop or widen a whitelist — but there is no guidance on when to prefer this over a general status tool.

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