List resource groups

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

Annotations already declare readOnlyHint=true; description reinforces read-only and adds specifics: reads from gp_toolkit.gp_resgroup_status, lists returned fields, and notes that on vanilla PG it returns available=false. This adds value beyond 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?

Three sentences: first states purpose and source, second adds context, third gives example. Front-loaded with core info, no redundant words. Every sentence serves a purpose.

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?

Given output schema exists, description doesn't need to detail return format. Covers source, fields, vanilla PG behavior, and pairing. Could mention permission requirements or error scenarios, but for a simple list tool it is sufficiently complete.

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?

Only one optional parameter 'database' with schema description. Description adds cross-reference hint to list_databases for configured ids, but does not elaborate on format or constraints. Schema coverage is 100%, so baseline is 3; this is adequate.

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?

Clearly states it lists resource groups, specifies the source view (gp_toolkit.gp_resgroup_status), enumerates returned fields (concurrency, cpu_max_percent, etc.), and distinguishes behavior on vanilla PG. Differentiates from sibling tools by naming a complementary tool (analyze_workload).

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?

Provides context for usage: pairs with analyze_workload for workload diagnosis. Mentions read-only nature and fallback on vanilla PG, implying when the tool is applicable. Could explicitly state when not to use, but the pairing and caveat provide good guidance.

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