mac_ssh_check

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does this well: it discloses that the tool runs `whoami` over SSH with BatchMode, that it verifies landing on the expected account, and that it returns a fix-up command when key auth isn't set up. This meaningfully adds beyond the tool name. It doesn't cover edge behaviors like timeouts or unreachable hosts, but for a read-only check tool the core behavior is transparent.

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 well structured: a one-line headline, a concise behavioral explanation, then an Args list. The most important information is front-loaded, every sentence contributes necessary context, and the Args section compensates for the schema lacking descriptions. No filler or repetition.

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?

Given the tool's low complexity, the presence of an output schema, and the absence of annotations, the description is nearly complete. It tells the agent what the tool does, how it behaves, and how to fill each parameter. Minor gaps remain, such as not stating whether a specific SSH port is assumed or what the exact 'expected account' check entails, but these are unlikely to prevent 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 compensate and it does. The Args section explains all three parameters: host with a cross-reference to the PAServer profile's Host field, user as the Mac user account, and key_path as an optional explicit private key path. This adds real meaning beyond the bare schema titles, though it stops short of providing examples or format constraints.

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 opens with a specific verb+resource: 'Test SSH connectivity + key auth to the remote Mac.' It then details the exact mechanics (runs `whoami` with BatchMode, verifies the expected account, returns an ssh-copy-id command on failure). This clearly distinguishes it from sibling tools like mac_ssh_run, which would run arbitrary commands, and paserver_check_connection, which checks PAServer connectivity rather than SSH key auth.

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 establishes clear context for when to use the tool: to verify SSH connectivity and key-based authentication to a target Mac, and to get a concrete remediation command if key auth is missing. It also cross-references paserver_info for obtaining the correct host address. However, it does not explicitly name alternatives or state when not to use it (e.g., 'use mac_ssh_run to execute arbitrary commands'), so it stops short of the explicit-when/when-not level.

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