ban_ip

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description must carry most of the behavioral load. 'Acts on the instances immediately' usefully discloses timing/effect, but it does not say whether the ban persists across restarts or config reloads, what happens to already-established connections, or what the result looks like. Useful context, but significant gaps remain for a mutating tool.

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 short sentences, front-loaded with the action and scope, followed by the alternative and the effect. No wasted words or hedging.

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 single required parameter whose nested fields are fully documented in the schema and with no output schema, the description covers action, scope, duration, and the inverse tool. The main omission is persistence/lifecycle behavior, which matters for a security-sensitive mutation.

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%, so every parameter including exp, reason, and service is already documented in the schema; the description's 'for exp seconds (0 = permanent)' and 'globally or per service' largely restate that. It does confirm that 'one or more IPs' maps to the bans array, but adds no syntax or format detail beyond the schema.

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 and resource ('Ban one or more IPs'), plus the scope dimension ('globally or per service') and duration semantics. It is clearly distinguishable from the sibling unban_ip, which it names, and from list_bans.

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?

Names the inverse operation ('Use unban_ip to lift a ban') so the agent knows which sibling selects the opposite action, and 'Acts on the instances immediately' implies this is a live runtime action rather than a config edit. No explicit when-not guidance (e.g., checking list_bans first, or persistence vs. restart) is given.

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