List Services

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

No annotations are supplied, so the description carries the full behavioral burden. The verb "Lista" implies a read, and the mention of health/unhealthy checks hints at the payload, but nothing is said about result size, pagination, failure modes when the cluster is unknown, or which unhealthy checks are surfaced — despite an output schema existing that could be referenced.

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?

A single front-loaded sentence with no filler; the resource comes before the returned facets. It is efficient, though brevity here trades away the differentiation and parameter detail the tool needs.

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 one-parameter list tool with an output schema covering return values, the description need only state what is listed and the scope, which it does. Missing guidance about alternatives and the cluster identifier are real gaps, but the output schema removes the need to describe return shape.

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% for the single required parameter "cluster", and the description only echoes it as "de um cluster" without saying whether that is a cluster name, ID, or display label, nor its format or case sensitivity. The one parameter that determines success is effectively undocumented in both structured and unstructured fields.

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?

"Lista os serviços de um cluster com estado, saúde e checks não saudáveis" states a specific verb (list) and resource (cluster services) and even names the returned facets (status, health, unhealthy checks). It does not distinguish itself from near-siblings such as get_service or cluster_health_summary, and the Portuguese wording diverges from the otherwise English tool surface.

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?

There is no guidance on when to choose this over get_service (single service detail) or cluster_health_summary. It also gives no precondition such as whether the cluster must exist or what authorization is needed, leaving selection entirely to inference from the name.

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