screen_info

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

With no annotations, the description carries the full behavioral burden, and it does disclose one important trait: 'pick' and 'switch' are interactive and prompt the user ('reopens the user's screen picker', 'asks the user to change the controlled screen'), which tells an agent these calls surface UI and may block on user input. It does not say whether the controlled-screen change is immediate, what happens on user cancel, or how results are returned for the default 'info' op.

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 compact sentences with no filler, and the per-op semantics are front-loaded after a short summary fragment. The opening noun list is slightly clipped in a way that costs clarity rather than saving space, which keeps it from a top score.

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?

There is no output schema and no annotations, so the description must cover both purpose and returns; it enumerates the returned information (screens, which is controlled, mode, top window) and explains the two mutating ops. For a two-parameter tool this is close to complete, missing only failure/cancel behavior and the shape of the info payload.

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 0%, so the description must compensate, and it largely does: it names all three enum values for 'op' with their distinct semantics and supplies the accepted 'screen' values ('1','2','all'). The remaining gap is the pairing rule for 'switch' without a 'screen' argument and what 'all' means concretely for control.

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?

"Screens, which one you control, mode, top window" identifies the resource and enumerates the data it exposes, but the leading fragment is telegraphic and never states a verb for the default 'info' operation. It is distinguishable from siblings (window, screenshot) by subject matter, but the purpose reads as a list of nouns rather than a described 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 explains what each op value does and when to reach for 'pick' vs 'switch', which is genuine usage guidance for the non-default modes. It gives no guidance on when to use this tool versus related siblings, and no prerequisites for the interactive operations. Usage is implied by the enumerated ops rather than by an explicit decision rule.

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