sim_install

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

No annotations are provided, so the description carries the full burden. It adds genuinely useful behavioral context — that app_path is a Mac-side path and where the .app actually lives after a build — which goes beyond the schema. However, it omits what happens on failure, whether installation is reversible, and what the response contains. For an un-annotated mutation tool, this is partial but not complete disclosure.

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 short, front-loaded sentences: the core purpose leads, and the path-composition guidance follows as a practical note. Every sentence earns its place; there is minimal waste, though the second sentence could arguably be folded more tightly.

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?

Has an output schema, so return values need not be described. For a 5-parameter tool with 0% schema coverage and no annotations, the description covers purpose and the critical app_path, but leaves host, user, udid, and key_path semantically unexplained. An agent would need to infer their roles from titles alone, which is a meaningful gap.

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 does only for app_path (explaining its Mac-side origin and how to compose it). The remaining parameters — host, user, udid, key_path — receive no explanation beyond their titles, so the description only partially offsets the coverage gap.

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?

States a specific verb-resource pair ('Install a .app bundle on a simulator') and names the underlying command (xcrun simctl install), which distinguishes it cleanly from the sibling sim_uninstall, sim_launch, and sim_terminate tools. The purpose is unambiguous even without opening the schema.

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?

Provides concrete contextual guidance: the tool is meant to be used after a build_dproj for iOSSimARM64 with deploy chained, and tells the agent exactly how to compose app_path (paserver_scratch_dir + project name). It does not state exclusions or when to prefer an alternative, but the usage context is clear and actionable.

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