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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral value beyond them: it discloses a limitation (cross-option rules like mutually_exclusive/required_if cannot be checked and the answer reports what it could not check) and notes YAML 1.1 quirks (unquoted off/yes/0755) that affect results.

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?

Dense and front-loaded with the core purpose, then limitations. It is a single packed sentence-plus-clause, but nearly every phrase earns its place; slightly heavy for one breath but not wasteful.

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?

No output schema exists, so the description carries some of that burden; it hints at the answer's self-reported gaps, which is helpful. Combined with 100% schema coverage and rich annotations, an agent has enough to invoke it correctly, though return shape is only implied.

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 coverage is 100%, so the schema fully documents dir, file, line and task, giving a baseline of 3. The description references the input forms (inline YAML, tasks file/playbook) but adds no format or syntax detail beyond what the schema already provides.

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 (check) and resource (task arguments) and enumerates the exact scope: inline YAML, tasks file or playbook checked against INSTALLED module docs, covering unknown/missing/typed/deprecated options. It also positions itself against ansible-lint's args rule, so an agent can distinguish it from sibling lint/doc tools.

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?

Names the alternative (ansible-lint's args rule) and the condition under which this tool is preferable (it catches action-plugin modules the linter skips), which is clear usage context. However, it never gives an explicit 'use this when X, not when Y' routing statement or prerequisites, so it stops short of a 5.

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

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.

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds real value beyond them: secrets (galaxy tokens, passwords) are always redacted, and settings the server overrides for safety are flagged — both material to interpreting the result.

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?

Two dense sentences with no filler; the core output contract (effective config plus origins) is front-loaded. Slightly clause-heavy but each 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?

No output schema exists, so the description must convey the return shape — and it does: settings with origins, redaction of secrets, and safety-override flags. It covers what an agent needs to interpret results, though it omits any note on pagination/truncation behavior tied to `limit`.

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 `all`, `dir`, `limit`, and `filter` are already fully documented in the schema. The description adds no syntax or behavioral detail about these parameters (e.g. how `filter` interacts with `all`), so baseline 3 applies.

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+resource: the effective Ansible configuration for a directory, mapped to `ansible-config dump`, with per-setting origin attribution. That is far more precise than a tautology. It does not explicitly differentiate itself from siblings like `ansible_project_info`, so it falls short of a 5.

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?

Usage is implied rather than stated: an agent infers it should call this when it needs to know which config values are in effect and where they come from. There is no explicit when-to-use/when-not or naming of an alternative sibling for related questions (e.g. project info).

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: always-redacted output, hidden vault/secret-shaped values, unrendered templates, the dynamic-inventory env-var gate (with a cloud-API caveat), and per-file vault degradation. This is unusually rich behavioral disclosure.

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?

Front-loaded with the resource and operations, and every clause carries information (redaction, gating, degradation). It is a dense run-on paragraph, but little is wasted; a slight structure split would improve scanability.

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 carries return-value burden and does explain what is included, what is redacted, and how vaults/dynamic sources degrade. It falls short of describing the concrete output shape or how 'limit' truncation surfaces, but is otherwise complete for a 6-param, no-required-param 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 coverage is 100%, so the baseline is 3, but the description maps parameters to CLI modes (--graph roots via group, --host targets a host, --list drives vars), adding meaning beyond the schema. It reinforces defaults ('names for the list, values for host') already in the schema, but the mode mapping is genuine added value.

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 states a specific resource (inventory: groups, hosts, inventory-level vars) and the exact operations it maps to (--graph/--list/--host). This clearly distinguishes it from siblings like ansible_playbook_structure and ansible_project_info, which cover different artifacts.

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?

Usage context is implied rather than explicit: the note that script/plugin sources are skipped unless ANSIBLE_MCP_ALLOW_DYNAMIC_INVENTORY=1 tells the agent when dynamic inventories apply. However, there is no explicit when-to-use-this vs. an alternative sibling (e.g., project_info) guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral detail on top: it never mutates files, play-level Jinja and adjacent vars plugins are evaluated during parsing, and lookups in play-level fields are refused unless ANSIBLE_MCP_ALLOW_PLAY_LOOKUPS=1. This is exactly the kind of evaluation/gating nuance an agent cannot get from structured fields, though cost, runtime, or failure modes are unmentioned.

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?

Compact and front-loaded: the output shape and the non-fixing guarantee come first, execution semantics and the env-var guard second. Parenthetical asides carry real information rather than filler, though the second sentence is dense enough to require rereading.

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 carries the return shape ('grouped by rule with counts, severities and file:line locations') plus the max_locations tie-in, which is sufficient for an agent to plan around the result. The main missing piece is when to select this tool over the other Ansible analysis siblings.

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 dir, paths, profile, and max_locations are all documented in the schema itself; baseline is 3. The description adds only a semantic framing for dir ('treat dir as code you would run --syntax-check on') and no syntax or format detail for the other three parameters. Fair but not enriching.

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+resource ('ansible-lint (offline) grouped by rule with counts, severities and file:line locations') and explicitly contrasts itself with the fixing variant ('never fixes anything (ADT MCP's ansible_lint fixes)'). An agent can tell it produces a report rather than edits. It does not distinguish itself from the listed siblings like ansible_check_task_args or ansible_playbook_structure, so it stops short of a 5.

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?

Implies when the tool is appropriate by describing the execution model ('treat dir as code you would run --syntax-check on'), which tells the agent what class of project to point it at. However, it never states when to prefer this over sibling lint/analysis tools, nor does it give preconditions such as needing a valid project directory. Usage is inferable but not explicit.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds meaningful behavior: redirects are resolved and the providing collection version is included, which matters for version-drift correctness.

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?

Two sentences, zero filler, front-loading what the tool returns before the when-to-use rationale. Every clause earns its place.

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 usefully previews the returned fields and notes truncation/example toggles exist via parameters. It could say a bit more about the response shape (e.g. redirect chains, version placement), but an agent has enough to call it correctly.

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 schema already documents all six parameters including the 'dir' fallback chain and the 'description_chars' truncation semantics. The description adds no parameter-level syntax or format detail beyond what the schema provides; baseline 3 is appropriate.

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 resource ('Exact options of a module or plugin as INSTALLED here') and enumerates the payload ('type, required, default, choices, aliases, suboptions'), plus the collection version and resolved redirects. This is clearly distinguished from sibling tool ansible_module_search, which finds modules rather than describing one.

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?

Gives an explicit trigger ('Use before writing a task') and a rationale ('options drift between collection versions, so training-data guesses are often wrong'). No named alternative or exclusion, but the usage context is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral information: the ranking order (exact name, prefix, token, then description match) and the reference implementation, which tells the agent how result ordering behaves.

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?

Two dense sentences with no filler: the first establishes what is searched and the ranking, the second states the required input combination. Everything is front-loaded and nothing is redundant with the schema.

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?

For a 5-parameter, all-optional read-only search tool with full schema coverage and annotations, the description supplies what structured fields cannot: matching and ranking behavior. It omits pagination/limit interaction and the shape of returned entries, but with no output schema and a default limit documented in the schema, those gaps are minor.

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 earns one more point by clarifying that query and collection are combinable inputs ('or both') and by describing how the query string is matched and ranked, which the schema does not state.

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?

Names a specific verb and resource ('Find installed modules or plugins') and even anchors it to the underlying mechanic (ansible-doc -l), so the agent knows exactly what is searched and how results are ordered. It is clearly separable from the sibling ansible_module_doc, which retrieves details for a single module rather than searching the installed set.

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?

It gives invocation guidance ('Pass query, collection, or both') and notes that dir/type are optional-ish, but never states when to use this versus ansible_module_doc or ansible_collections. Usage is implied by the tool name and the search/rank semantics, with no explicit exclusions.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavioral context beyond them: the exact underlying ansible-playbook invocations, the guarantee that no play executes, the fact that play-level Jinja and adjacent vars plugins ARE evaluated during parsing, and that lookups in play-level fields are refused unless ANSIBLE_MCP_ALLOW_PLAY_LOOKUPS=1. The execution-side-effect disclosure is exactly what an agent needs.

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?

Two sentences, front-loaded with the return shape before the parsing semantics. The second sentence is dense with nested parentheticals and the env-var caveat, which makes it slightly harder to skim, but no clause is filler.

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?

There is no output schema, so the description carries the burden of describing the return value, and it does so explicitly (plays, hosts, tasks with file:line, tags, deprecation warnings) while also disclosing the parsing model and the lookup restriction. An agent has everything needed to call this correctly.

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% and each of the 7 parameters carries its own CLI-flag mapping (--tags, --limit, --syntax-check, etc.), so the schema already does the heavy lifting. The description adds no per-parameter syntax or constraint detail, making the baseline 3 appropriate.

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 resource and enumerates exactly what it returns: plays, matched hosts, tasks with module and file:line, tags, and parsing deprecation warnings. This is clearly distinct from siblings like ansible_lint_summary or ansible_inventory, which cover different artifacts.

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?

Gives strong context: it is a static analysis tool ('never runs a play') and explicitly frames the playbook as code you would run --syntax-check on. It does not, however, name an alternative sibling or state when to prefer e.g. ansible_lint_summary over this, so the routing guidance is contextual rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description still adds a genuine behavioral fact beyond them: it never connects to a managed host, which tells the agent there are no side effects or remote auth requirements. It stops short of describing cost or output size, so not 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?

Two sentences, no filler. The high-value instruction ('Call it first') is placed after the content list but before the routing clause, and each clause in the enumeration maps to something the tool actually returns.

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?

There is no output schema, but the description compensates by listing the returned categories in detail. Combined with the annotations covering safety and idempotency, an agent has everything needed to decide to call it and to interpret the result.

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?

There is a single optional parameter and schema coverage is 100% – the schema already documents the ANSIBLE_MCP_DIR / working-directory fallback that the description would otherwise need to supply. The description adds no additional semantics for 'dir', so the baseline 3 applies.

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 concrete verb-plus-resource framing ('What this Ansible checkout contains and how Ansible sees it') and then enumerates the exact payload: ansible-core version, effective config, collections/roles paths, binaries, playbooks, inventories, roles, requirements files. That enumeration lets an agent separate it from siblings like ansible_config or ansible_collections, which each return a narrower slice.

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?

'Call it first' states the ordering explicitly, and the parenthetical routes work away from this tool: controller state goes to AAP MCP, actions to ADT MCP. Both the when and the when-not are present, so the agent has a decision rule rather than an inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description goes beyond that by disclosing output-handling behavior the agent cannot infer: no_log is honoured, default values are redacted, and undocumented defaults are flagged — genuinely useful context for interpreting results.

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?

Two sentences, no filler, with the output inventory front-loaded. The first sentence is dense with a long comma-separated list, but every item is substantive content rather than padding.

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?

There is no output schema, so the description must carry the return-value burden — and it does, enumerating the sections returned and noting redaction. Combined with read-only annotations and covered input forms, an agent has enough to call and interpret this correctly; only the absence of explicit sibling routing keeps it from a 5.

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 coverage is 100%, so the schema already documents all four parameters, giving a baseline of 3. The description adds resolution semantics not present in the schema, notably the roles_path lookup and the dir/roles convention, which clarifies how the required 'role' argument is resolved.

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 names the specific resource (a role's interface) and enumerates exactly what it surfaces: argument_specs entry points/options, defaults (redacted), undocumented defaults, dependencies, vars names, galaxy_info. That is far more precise than a tautology, and the resource is clearly distinct from siblings like ansible_module_doc or ansible_playbook_structure, though no sibling is named explicitly.

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?

It states the accepted role forms ('local roles (roles_path, dir/roles, or a path) and collection roles (ns.collection.role)'), which tells the agent what inputs are valid but not when to prefer this tool over alternatives such as ansible_module_doc or ansible_project_info. Usage is implied rather than routed.

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

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

Annotations cover read-only/idempotent/non-destructive, and the description adds genuinely non-derivable behavior: it downloads the target collection from Galaxy or configured servers into the server's cache on first use (network + latency implication) and explicitly guarantees it will not modify the project directory, requirements files, or collections paths. That mutation-safety boundary is exactly the kind of context annotations cannot express.

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?

Two dense sentences with no filler; the finding categories and the side-effect guarantee are front-loaded before the download caveat. The enumeration of change classes is long but each item is informative rather than redundant.

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?

For a six-parameter, no-output-schema analysis tool, the description conveys the return shape (per-finding file:line attribution, requirements.yml constraints, a verdict) and the side-effect profile, which is what an agent needs to decide to call it. Minor gaps remain around syntax_check interplay and result ordering, but nothing critical is missing.

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 parameters like dir, version, playbooks, syntax_check, and include_unused are already fully documented in the schema. The description mentions requirements.yml constraints and the file:line attribution, but adds no syntax, format, or default nuance beyond the schema, so the baseline of 3 applies.

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 and resource with unusual precision: it reports what breaks in the current project's tasks when one collection moves to an exact version, enumerating the change classes (redirects, tombstones, removed options/aliases, newly required options, dropped choices, type/default changes). This is clearly differentiable from siblings like ansible_collections (inventory of installed collections) or ansible_module_doc (docs lookup).

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 'if one collection moves to an exact version' framing establishes the triggering scenario clearly, and the download/caching sentence plus 'never touches dir, requirements files or your collections paths' sets expectations for a pre-upgrade probe. However, no alternative tool is named for adjacent questions (e.g. a plain version listing), so an agent must infer the boundary rather than being routed explicitly.

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