event_list

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

Annotations only supply readOnlyHint=true. The description goes well beyond that by disclosing the return envelope, the meaning of the 'truncated' flag, and the correct remediation (re-run with a higher limit rather than reporting an incomplete set) — exactly the kind of behavior an agent cannot infer from structured fields.

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?

Front-loaded with the verb and purpose, then the diagnostic use case, then the return contract, then Args. The truncation warning is the only multi-line passage and it earns its space by preventing a real failure mode; the '[READ]' tag is mildly redundant with readOnlyHint but harmless.

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?

No output schema exists, yet the description supplies the return shape and the truncation semantics. For a 3-parameter, 0-required read tool with all arguments documented and the failure mode flagged, nothing an agent needs is missing.

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%, so the description carries the full burden and does: namespace is defined including the meaningful default behavior ('omit for all namespaces'), limit is defined as a maximum count, and target is tied to a config source. All three parameters are accounted for.

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 ('List recent events') and enumerates the fields returned (type, reason, object, message, age). No sibling tool in the 55-name list covers cluster events, so the resource itself cleanly disambiguates it from pod_describe or pod_logs.

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?

Gives a clear diagnostic context ('why a pod is not starting', citing FailedScheduling) and the truncation re-run path. It never names an alternative (pod_describe, pod_health_rca, workload_readiness_rca) or states when-not to use it, so it stops short of a 5.

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