Yarn Cluster Metrics

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

With no annotations, the description must carry the behavioral burden: it implies a read-only snapshot and discloses the RM access requirement, which is genuinely useful operational context. It does not say whether values are live or cached, how RM unavailability surfaces, or the granularity of the percentage figures.

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?

Two sentences, front-loaded with the resource and scope, with the metric list packed efficiently. The README pointer is short and useful rather than filler; there is no redundant restating of the title.

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?

Because an output schema exists, the description is not obliged to explain return values, and its metric summary is a reasonable preview. But for a tool with two undocumented parameters and several closely related YARN siblings, it omits the parameter guidance and sibling routing an agent needs to call it correctly.

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 two parameters (required 'cluster', optional 'service') carry no documented meaning anywhere. The description never mentions either parameter or how 'cluster' relates to the sibling list_clusters tool, which is exactly the gap the description should have filled.

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 concrete verb+resource: a point-in-time snapshot of the YARN cluster as seen by the ResourceManager, and enumerates the covered metrics (memory/vcores total/allocated/free %, running/pending apps, pending containers, active/problem NodeManagers). It is clear enough to separate from siblings like yarn_application_attributes or get_role_log, though it does not explicitly distinguish itself from yarn_utilization_report or cluster_health_summary.

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?

The word 'Fotografia' (snapshot) implies the current-state use case, and the description adds a real prerequisite: access to the RM via the YARN_RM_* settings in the README. However, it names no alternatives and gives no when-not-to-use conditions versus yarn_utilization_report, yarn_queue_usage or cluster_health_summary, leaving the agent to infer the choice.

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