cocos_click_preview

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

With no annotations provided, the description carries full burden and does well: explains post-click waiting behavior ('wait_ms gives post-click animations/scene-changes time to settle'), dependency requirement ('Requires optional playwright dependency'), success/failure outcomes ('Returns {ok: True} on success, raises on navigation/launch failure'), and provides actionable error guidance. Could mention rate limits or concurrency constraints.

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?

Perfectly front-loaded with core functionality, then elaborates on parameters and behavior. Every sentence adds value: first states purpose, second gives usage context, third explains coordinate space, fourth details button parameter, fifth explains wait_ms, sixth covers dependency, seventh describes outcomes. Zero 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?

For a complex 8-parameter tool with no annotations or output schema, the description provides excellent coverage of purpose, usage, parameters, and behavior. Missing details about exact error types or viewport_width/height usage keep it from perfect, but it's highly complete given the constraints.

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 description must compensate fully. It explains all 8 parameters: x/y (coordinates in PAGE space with top-left origin), button (values 'left'/'right'/'middle'), wait_ms (purpose for animations), url (implied as preview target), and mentions viewport dimensions/timeout through sibling reference. Adds crucial context beyond schema titles.

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 clearly states the specific action ('Click at page coordinates'), target resource ('in a running preview'), and distinguishes it from siblings by focusing on UI interaction rather than scene construction or asset management. It goes beyond the tool name to explain the exact functionality.

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 states when to use ('Use this to drive UI you just built') with concrete examples ('Start button, menu tab, card'), mentions sibling tool dependency ('same as cocos_screenshot_preview'), and provides context about coordinate space ('PAGE space, NOT viewport-relative').

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