capture_screenshot

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

With no annotations, the description carries the full load and does well: it declares read-only, no token requirement, ~300ms Unity-side cost dominated by CaptureScreenshot, that mode does not change cost, that file_ref persists to UNITY_MCP_SCREENSHOT_DIR, and that the ~2MB base64 payload is the real cost driver. It stops short of saying whether the capture alters game state or camera framing.

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 mode breakdown is front-loaded and earns its place, but the 'PERF 2026-05-25' dated changelog paragraph and the cost/token narrative repeat themselves and are noise for an agent deciding how to call the 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?

An output schema exists so return shapes need not be spelled out, and the verification-role and mode guidance cover the decision-critical parts. However, for a 5-parameter tool with zero schema coverage and no annotations, leaving four parameters undocumented makes the definition incomplete 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?

Schema description coverage is 0%, so the description must define every parameter. It explains mode thoroughly (three values including the default), which is genuinely additive since the schema has no enum, but width, height, supersize, and skip_if_unchanged are never mentioned anywhere, leaving four of five parameters semantically undefined.

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 tool name plus the mode table make clear this captures a PNG screenshot and controls how the image is returned. It does not, however, distinguish itself from the sibling observe_camera or from read-state probes beyond asserting the screenshot is required for final verification, so the boundary with observe_camera is left implicit.

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?

Explicit when-to-use: final verification of any user-facing change MUST include a screenshot from this tool, one capture per meaningful screen. It also gives mode-selection guidance (re-request with full if metadata was enough, file_ref for local agents) and an explicit escalation path ('ask the user before capturing' when unsure of the screen).

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