Configure Key Auth

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

The annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, but the description adds nothing to them: it never states that SSH keys are written to files or hosts, that a target group is contacted over the network, whether existing keys are overwritten, or what authorization is needed. Its second sentence even broadens the claimed scope to 'bulk inventory operations', which is a different behavior from key auth.

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 only two short sentences, so it has no verbosity problem. However, the second sentence is generic family boilerplate that conflicts with the operation name, so it does not earn its place and actively misdirects rather than front-loading useful scope.

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 16-parameter, multi-mode tool that writes SSH keys into an inventory, two sentences are far too thin. The output schema exists, so return values need not be explained, but the description still omits which parameter selects which operation and what the tool actually changes on disk or across hosts.

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 100%, and the schema's parameter text (notably for 'host' and 'preview') is far richer than the description, so the baseline of 3 applies. The description adds nothing about parameter semantics and does not explain the multi-operation dispatch that its 16 flat parameters imply.

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 first sentence, "Configure key auth (tm_inventory)," simply restates the tool name and title. The second sentence, "Bulk inventory operations against YAML host groups," describes the whole inventory tool family rather than this key-auth operation, and it conflicts with the name; it does not distinguish this tool from siblings such as tm_inventory_rotate_key, tm_inventory_copy_ssh_config, tm_remote_setup_passwordless, or tm_remote_test_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 contains no when-to-use guidance, no prerequisites, and no named alternative. Nothing tells the agent why it would pick this over tm_remote_test_key_auth or tm_remote_setup_passwordless, and it never explains that the 16 parameters are mode-selecting (key vs cmd vs cfg vs lpath), so an agent cannot infer what to call from the text.

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