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

With readOnlyHint=true already covering the safety profile, the description still adds real context: the full shape of what is returned (severity split by scope, ecosystems, CVE queue ranked by blast radius, remediation campaigns, phased burn-down) and, importantly, the failure mode when Trivy Operator is absent (status='not_installed' plus install guidance). That error-state disclosure goes meaningfully beyond the annotations.

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?

Purpose is front-loaded in the first sentence, followed by the Returns inventory, usage guidance, and the not-installed case. The Returns enumeration is long but each item is a distinct output the caller may need; nothing reads as filler or marketing.

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?

There is no output schema, so the description carries the burden of describing return values and does so comprehensively, plus it covers the degraded not-installed state. For a read-only, filterable report tool this is complete enough to call correctly without further exploration.

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%, with limit and severity fully documented in the schema (including range and default) and cluster_id pointing at list_clusters. The description adds no parameter-level semantics beyond that, so the baseline 3 for schema-driven parameters applies.

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 a concrete verb+resource: 'Get the Trivy Operator image-vulnerability summary for the current cluster,' and then enumerates exactly what the summary contains (severity breakdown, priority CVE queue, burn-down plan, riskiest workloads). This is specific enough that an agent can distinguish it from the many other security siblings like get_security_overview or get_application_container_security.

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 explicit scope of use: 'Use this for any question about vulnerabilities, CVEs, image scanning or cluster security posture instead of reading VulnerabilityReport CRDs directly.' That is a clear when-to-use signal and even names the discouraged alternative (raw CRDs). It stops short of naming which sibling security tools to prefer for adjacent questions.

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