skypilot_realtime_gpu_availability

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

Annotations declare readOnlyHint=true, so the safety profile is covered. The description reveals it queries a live cluster and shows current quantities, but says nothing about refresh cadence, cost/latency of the Kubernetes query, or whether results are cached. For a 'real-time' tool, that's a notable gap.

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?

Three sentences, all substantive, front-loaded with the core purpose. Efficient, though the is_ssh sentence is a bit dense with parenthetical booleans.

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-value explanation isn't required. The description covers the query scope and three of four parameters. Missing only the context parameter's meaning, which is minor given the tool's otherwise clear scope.

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 burden and compensates partially by explaining is_ssh's boolean semantics fully. However, context, name_filter, and quantity_filter receive no description beyond their names – name_filter's matching rules (substring? exact?) and quantity_filter's semantics (minimum available count) are not clarified.

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 (Get) and resource (real-time GPU availability) with context (in a Kubernetes cluster). Explicitly distinguishes from the Slurm sibling via the Kubernetes qualifier, so an agent can pick it correctly.

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?

Describes filtering capabilities ('Filter by GPU name or minimum quantity') and explains the is_ssh parameter's semantics, implying usage. But there's no explicit when-to-use guidance relative to alternatives like skypilot_list_accelerators or skypilot_list_accelerator_counts.

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