List group CI/CD variables

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful context by explicitly noting that variable VALUES are not exposed, which is a key behavioral disclosure beyond what the annotations convey. This helps set expectations about what the response will contain.

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?

The description is a single concise sentence that clearly states the tool's purpose and its key limitation (doesn't expose values). Perfectly front-loaded and efficient with no wasted words.

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 the tool's moderate complexity (3 params, pagination, output schema present), the description covers the essential semantic: this lists metadata onlyholistically. It could mention that pagination is supported (though the schema implies it), but the output schema handles return structure documentation. The annotations cover safety profile, so overall this is reasonably 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?

Schema description coverage is only 33% – only the 'group' parameter has a description in the schema. The tool description doesn't compensate for the missing parameter semantics of 'page' and 'per_page' at all. While page/per_page are conventional pagination parameters, the description provides zero additional context about their format or behavior, and the group parameter's semantics rely entirely on the schema.

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 'List group CI/CD variable metadata without exposing variable values' clearly states the action (list) and resource (group CI/CD variables), and the key distinguishing detail that values are not exposed. This differentiates it from other variable tools like get_group_ci_variable and update_group_ci_variable which operate on single variables.

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 description implicitly signals when to use this tool: when you need group CI variable metadata without values. The exclusion of variable values ('without exposing variable values') provides clear context for when this tool is NOT appropriate (when values are needed). However, it doesn't explicitly reference sibling alternatives like get_group_ci_variable for value retrieval.

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