Collections vs requirements

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower, yet the description still adds real behavioral content: the exact result vocabulary (ok, VIOLATES with file:line, MISSING), that galaxy constraint rules drive the verdict, and that shadowed collections are resolved by COLLECTIONS_PATHS order. It does not describe output shape or how multiple violations are aggregated, keeping it short of a 5.

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?

A single dense sentence that front-loads the input/output contract (requirements.yml vs installed, statuses) before the auxiliary shadowing rule. The opening fragment lacks an explicit verb, which costs it a point, but there is no filler and every clause carries information.

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?

With no output schema, the description bears the return-value burden and largely meets it by naming the three result states and the file:line detail, plus the shadowing diagnostic. Remaining gaps — output structure, aggregation of multiple failures, handling of a missing requirements file — are minor for a read-only checker.

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 the baseline is 3. The description's mention of requirements.yml and COLLECTIONS_PATHS loosely touches the requirements and dir parameters but adds no syntax, precedence default, or meaning beyond the schema — notably nothing about include_extras.

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 tool is a comparison/diff of a requirements file against installed collections and roles, returning ok/VIOLATES/MISSING — a specific operation on a specific resource, and 'Never installs anything' distinguishes it from any install-oriented sibling. The verb is implicit ('requirements.yml ... against what is installed') and the name 'ansible_collections' alone would suggest listing rather than diffing, but the title and body together make the purpose recoverable.

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?

There is no statement of when to use this versus siblings such as ansible_upgrade_impact or ansible_config, and no prerequisites (e.g. must the project be a real Ansible project dir?). Only the negative 'Never installs anything' hints at scope; an agent gets no routing guidance.

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