ssh_command_alias

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

With no annotations, the description carries the full transparency burden and does well by disclosing no remote execution, no side effects, local config storage, and overwrite-on-add behavior. It does not mention result format, error handling, or config file location, so it stops short of 5.

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?

Three sentences, all substantive and well organized: main purpose first, action semantics second, and the overwrite caveat last. There is no filler, and nothing merely repeats the schema.

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 tool with no output schema or annotations and four distinct actions, the description explains each action's behavior and even gives high-level return expectations for list and suggest. It does not specify exact result formatting or failure behavior, but an agent has sufficient information to select and invoke the tool correctly.

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 coverage is already 100%, and the description adds meaningful operational detail beyond the schema by binding each action to its required parameters (e.g., command doubles as the search term for suggest, add needs both alias and command). This mapping is not fully inferable from the enum alone.

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 identifies the resource ('local shorthand aliases' mapping a short name to a full command string) and scopes behavior to local config with no remote execution, which distinguishes it from the many remote-execution siblings. It falls short of 5 because it does not explicitly differentiate from the similarly named 'ssh_alias' sibling.

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 offers clear action-specific usage guidance: add requires both alias and command, remove requires alias, suggest uses the command field as a search term, and list shows profile/custom-tagged aliases. The 'local config with no remote execution or side effects' phrase gives selection context versus remote tools, although no alternative tool is named explicitly.

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