list_gradle_variants

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

With no annotations provided, the description carries full burden for behavioral transparency. It clearly states expected behavior (parsing from assemble* tasks, excluding test APKs), the edge case of multi-module root projects, and the relationship to task arg propagation. However, it does not discuss potential latency, error conditions (e.g., project_dir not set), or what happens if no assemble tasks exist, which would push it to a perfect 5 in this unannotated context.

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, dense paragraph of 4 sentences that front-loads the core purpose in the first sentence, then adds progressively more nuanced context. Every sentence is essential—no fluff, no repetition of schema, and no extraneous explanations. It achieves maximal information density in minimal space.

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 complexity (2 params, no output schema, moderate sibling list), the description is remarkably complete. It covers what the tool does, what it excludes, how variants map to downstream tools, the root project caveat, and cross-referencing to sibling tools like list_gradle_projects and gradle_build. No significant gaps remain for an agent to effectively select and invoke this tool.

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 100%, so baseline is 3. The description does not add parameter-level detail beyond the schema—it mentions task= and project_dir in the prose but provides no additional syntax, allowed values, or format constraints. This is adequate since the schema already describes both parameters clearly, but the description does not enhance understanding of their role beyond restating schema information.

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 uses a specific verb-resource pair ('list the buildable build variants') and distinguishes the tool from its siblings by calling it the 'Android analogue of list schemes' and explaining that each variant maps to an assembleV/installV task. It clearly states what is excluded (test-only APK tasks) and how it relates to other tools like gradle_build.

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 explicitly guides when to use this tool and when to use alternatives: it explains that variants are passed to gradle_build's task= arg, and for multi-module builds, you should use list_gradle_projects first then task='<module>:tasks'. It covers the root project caveat and scoping advice, leaving no ambiguity about appropriate usage.

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