panelica_ssh_users_post_v1_ssh_users_id_suspend

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

The description explicitly notes 'Mutating: changes server state' and 'Required scopes: accounts:write'. The mutating note aligns with readOnlyHint=false, but the scope requirement is useful information not present in annotations. However, it doesn't disclose potential side effects like whether active sessions are terminated or if the action is reversible, which would add more transparency. Given annotations already convey the non-read-only nature, the description adds only marginal behavioral context.

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, with each line adding distinct value: action, HTTP endpoint, category, required scopes, and mutation status. No filler or redundancy. It front-loads the action and efficiently conveys essential metadata.

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?

This is a simple tool with only two parameters (one optional body with no static schema) and no output schema. The description covers the core action and security requirements but lacks guidance on when to use it versus the unsuspend sibling, and does not explain what the body parameter is used for or what the response contains. For its simplicity, it is adequate but not fully complete.

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%, meeting the baseline of 3. However, the schema descriptions are minimal ('Path parameter: id' and 'Request body...'). The description itself adds no parameter-specific guidance, such as what the id represents or what the body should contain. Since the baseline is met and the description doesn't improve it, a 3 is appropriate.

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 'Suspend SSH user', a specific verb and resource that clearly distinguishes it from sibling tools like unsuspend, delete, and create. It also provides the HTTP method and endpoint, reinforcing the action. This is unambiguous and easily understood.

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?

No guidance is given on when to use this tool versus alternatives such as unsuspend or delete. There is no mention of prerequisites, typical use cases, or scenarios where a different action would be more appropriate. The description only states the action and metadata, without helping the agent decide between similar operations.

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