get_kubectl_events

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

With no annotations supplied, the description carries the behavioral burden and does reasonably well: it discloses the SSH execution model, the prerequisite that kubectl must already be configured for the SSH user, the ordering (oldest first, below the column header), and the namespace/warning filtering behavior. Gaps remain around error behavior when SSH fails or kubectl is absent, and around how authentication is supplied, which the schema only hints at via `key_path`/`password`.

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?

Content is front-loaded with capability first and usage guidance after, and each sentence adds information rather than restating the name. The only blemish is awkward line-wrapping that splits "by running kubectl on a remote Linux host via SSH" across lines, slightly hurting scannability.

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?

An output schema exists, so return values need no explanation, and the tool is a read operation whose purpose is clear from the verb. However, for a 10-parameter, no-annotation, SSH-based tool, the definition leaves authentication and connection semantics (key vs. password, host key acceptance, timeout) unaddressed, which is the main thing an agent could get wrong when calling it.

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% across 10 parameters, so the description must compensate — and it only explains three of them (`lines`, `namespace`, `warnings_only`). The connection-critical parameters (`host`, `user`, `port`, `timeout`, `key_path`, `password`, `accept_new_hostkey`) get no meaning beyond an oblique mention of "a remote Linux host via SSH," leaving the auth mechanism and host-key policy entirely undefined.

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 states a specific verb and resource ("Gets the most recent `lines` kubernetes events"), names the underlying command (kubectl get events), and specifies the execution channel (SSH to a remote Linux host). It also distinguishes itself from the sibling describe/logs tools by declaring "USE THIS TOOL FIRST when you don't know what is wrong in a cluster," so an agent can pick it without opening another schema.

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?

It gives an explicit entry-point prescription ("USE THIS TOOL FIRST" for unknown cluster problems) plus concrete scoping rules: all namespaces unless `namespace` is given, and `warnings_only=True` for Warning-type events only. What's missing is the inverse guidance — when to move on to `get_kubectl_describe` or `get_kubectl_logs` — so it stops short of full when/when-not routing.

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