Capture a simulator screenshot

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention prerequisites (e.g., simulator must be booted), whether the operation is read-only, or what happens if the simulator is not available. The includeImage parameter is not explained, and no side effects or failure modes are described. This is a significant gap for a tool with zero annotation coverage.

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 extremely concise: two sentences with no filler. The main action is front-loaded, followed by the usage purpose. Every word earns its place, and it is well-structured for quick scanning by an agent.

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 simple tool with three parameters and no output schema, the description leaves important gaps: it does not explain the includeImage parameter, does not state prerequisites like a booted simulator, and does not indicate whether the command can fail or what the response looks like. The description provides only the core action and a use case, which is insufficient for an agent to invoke it correctly without additional assumptions.

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 description does not add any meaning about the parameters beyond the schema. The schema already describes udid and outputPath, but includeImage has no description in the schema. With 67% schema coverage (moderate), the description should compensate by explaining the undocumented parameter, but it does not. It only mentions 'PNG path' which echoes outputPath without adding value.

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 action (capture a simulator screenshot), the output format (PNG path), and the underlying command (xcrun simctl io screenshot). It also gives the intended purpose (evidence for visual review and before/after comparison), which makes it unambiguous and distinct from other simulator tools like preview or show.

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 provides a clear usage context: 'Use as evidence for visual review and before/after comparison.' This tells when it is appropriate, but it does not explicitly mention when not to use it or contrast it with alternatives like simulator_preview_start. No exclusions are stated, so it earns a 4 rather than a 5.

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