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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds context that it clears caches and is useful for stale data, reinforcing that it's a non-destructive mutation. It doesn't introduce new side effects beyond what annotations imply, but the added usage scenario improves transparency.

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 concise, consisting of two sentences that directly state the action, scope, and use case. No redundant or irrelevant information is present, and it is well-structured for quick comprehension.

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 schema and annotations, the description provides sufficient context: it explains what the tool does, when to use it, and the parameter is fully documented. The presence of an output schema means return values are not required in the description, and the existing details cover all necessary information.

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?

The input schema includes a single parameter 'scope' with a detailed description explaining each allowed value ('galaxy', 'docs', or null to clear all). The description also mentions the scope types, though less precisely. Together, they provide complete semantic understanding of the parameter.

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 clearly states the tool's function: it clears server caches, specifically listing the types of caches (Galaxy version/docs-blob, standalone-role v1, doc manifest/page, or both). This distinguishes it from sibling tools which are primarily search/get operations, making the purpose unambiguous.

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 provides a specific use case: 'Useful when cached data becomes stale during long-running sessions.' This gives clear guidance on when to invoke the tool. It doesn't explicitly contrast with alternatives, but no direct alternative exists, so the guidance is adequate.

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 indicate idempotentHint=true and destructiveHint=false. The description adds context: version pinning, skip vs reinstall behavior, and detailed return dict with status and error case. This extends beyond the annotations without contradiction.

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 front-loaded with the main purpose, followed by behavioral details in order, then return value format. Every sentence adds value with no redundancy. It is appropriately concise for the complexity.

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 complete input schema, output schema described in detail, and annotations, the description covers all essential aspects: purpose, behavior, parameter effects, return values, and error handling. No gaps remain.

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?

Input schema already covers both parameters with descriptions (100% coverage). The description adds meaning by explaining that omitting version installs and pins latest, and that requesting a different version triggers reinstall. This provides useful behavioral context.

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 clearly states the tool installs a collection to a temporary directory for the session. It uses specific verb (install) and resource (collection), and distinguishes from sibling tools like search_collections or get_collection_docs.

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 explains the behavior (installs once, pins version, skips if same version unless different version requested) but does not explicitly state when to use this tool versus alternatives. There is no mention of exclusions or when not to use it.

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 declare readOnlyHint=true, and the description does not contradict this. Beyond that, it adds useful behavioral context: output is converted to clean Markdown, intended for LLM consumption, and only specific URL sources are accepted. It does not disclose network failure modes or rate limits, but with read-only annotation coverage this is a reasonable level of 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?

The description is short, front-loaded with the core action, and every sentence earns its place. The URL allowlist and the pointer to search_docs are essential operational details, not 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?

For a two-parameter read-only fetch tool with a full output schema and 100% parameter documentation, the description is complete. It tells the agent what the tool does, what input is valid, how to discover inputs, and what output to expect. Nothing essential for correct invocation 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?

The schema has 100% description coverage, so the heavy lifting is already done by the input schema. The description mostly repeats the URL constraints already present in the url parameter description. max_tokens is fully documented in the schema. The description adds no significant semantic detail beyond the structured parameter documentation.

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 and resource: 'Fetch a docs page as clean Markdown.' It clearly states the output form and distinguishes this from discovery tools like search_docs, which are described separately and referenced as the way to find URLs. The tool's identity is unambiguous.

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 instructs agents to 'Use search_docs to discover relevant page URLs' and constrains acceptable inputs to docs.ansible.com, docs.redhat.com, or CoP raw GitHub README.adoc URLs. It clearly excludes arbitrary raw.githubusercontent.com hosts. It does not explicitly contrast fetch_doc with siblings like get_module_doc or get_plugin_doc, so exclusions are not fully exhaustive.

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?

Beyond the idempotentHint annotation, the description reveals significant side effects: it updates MANIFEST.json and AGENTS.md. It also discloses the return shape, including an error variant, and explains partial-batch success behavior (missing names counted as failed, but resolved names still written). This is rich, honest behavioral 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 moderately long but well-structured into a lead sentence, a side-effect paragraph, a return-value paragraph, and a behavior note. Every sentence adds value, with key information front-loaded. Slightly verbose 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?

Given the tool's moderate complexity, the description covers purpose, side effects, return values, and failure semantics. The output schema exists, yet the description still summarizes the return type and error case, making it self-sufficient. No significant gaps identified.

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%: both parameters (install_to and collection_namespace) have detailed descriptions in the schema. The tool description itself adds no additional parameter semantics, so it stays at the baseline of 3.

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 opens with a specific verb and resource: 'Batch generate skills for an entire collection.' This clearly distinguishes it from sibling tools like generate_skill and generate_plugin_skill by emphasizing the collection-wide scope. It also states the byproducts (MANIFEST.json and AGENTS.md updates) further clarifying its unique role.

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 clearly implies when to use this tool: for batch skill generation across a collection, with mention of batched ansible-doc calls. However, it does not explicitly say 'use this instead of generate_skill' or list alternatives/exclusions. Context is strong but explicit guidance against alternatives is missing.

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?

The description discloses that the tool writes SKILL.md to disk and explicitly notes it does not create scripts/ or assets/. It also states the return format as either a string or an error object, going beyond the idempotentHint annotation to clarify side effects and failure behavior.

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 contain the full purpose, side effect, and return behavior, with no filler. The main action is front-loaded in the first sentence.

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 schema and output schema, the description provides sufficient context: what it generates, where it writes, what it returns, and what it excludes. No critical information is missing for a user to use this tool 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?

The input schema covers all three parameters with descriptive text (100% coverage), and the description adds no additional parameter-level details. It references the plugin's fully-qualified name and type indirectly, but the schema already documents these sufficiently.

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 verb+resource: 'Generate a skill package for one plugin.' It clarifies scope (single plugin) and differentiates from sibling tools like generate_role_skill and generate_collection_skills.

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 phrase 'for one plugin' provides clear context for when to use this tool, implying the alternative generate_role_skill for roles. However, it does not explicitly name alternatives or exclusion criteria, 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?

The description discloses side effects ('Writes SKILL.md + assets/playbook.yml to disk'), scope ('no scripts/'), and return behavior ('Returns the SKILL.md content as str, or {"error": str} on failure'). This adds meaningful context beyond the idempotentHint annotation, though it does not explicitly mention overwriting behavior or permissions.

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 with no filler. The first sentence states the core action; the second provides essential behavioral details (file writes and return type). 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 full parameter schema coverage, an output schema, and an idempotency annotation, the description suffices for a focused tool. It explains what is generated, where it is written, and what is returned. The only notable gap is explicit usage guidance versus siblings, but overall the context is adequate.

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 details both role_name and install_to. The description adds little parameter-specific meaning beyond 'for one role,' but the schema carries the full burden, making a 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?

The description clearly states a specific verb and resource: 'Generate a skill package for one role.' It further specifies outputs (SKILL.md + assets/playbook.yml) and distinguishes itself from sibling tools by focusing on a single role rather than plugins, collections, or generic skills.

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?

No explicit guidance on when to use this tool versus alternatives like generate_plugin_skill or generate_collection_skills. The phrase 'for one role' implies a role-specific use case, but there are no stated exclusions, prerequisites, or comparisons to siblings.

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 provide idempotentHint=true. The description adds valuable behavioral context by stating it writes files to disk and returns either SKILL.md content or an error dict, going beyond the annotation's safety hint.

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 two concise sentences, front-loaded with the core purpose, followed by concrete side effects and return behavior. No redundant or filler text.

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 schema covers parameters and annotations cover idempotency, the description sufficiently covers purpose, file-writing side effects, and return value. It slightly lacks explicit usage guidance compared to alternatives, but is otherwise 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?

The input schema provides full descriptions for both parameters (module_name, install_to) with 100% coverage. The description adds no additional parameter-specific meaning, 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?

The description uses a specific verb ('generate') and resource ('skill package for one module'), and clarifies the output contents (SKILL.md, scripts, playbook). This clearly distinguishes it from sibling tools like generate_role_skill and generate_plugin_skill.

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 phrase 'for one module' implies when to use it, but there is no explicit guidance on alternatives or exclusions. Since sibling tools exist for roles, plugins, and collections, the description could have mentioned when not to use this tool.

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?

Beyond the readOnlyHint annotation, the description adds a large-output warning (100 KB+), states the result shape with keys, notes failure returns {'error': str}, and clarifies it does not install the collection. This gives the agent concrete expectations for behavior and consequences.

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 purpose, then warning, usage guidance, result shape, and failure behavior. Each sentence serves a distinct informative purpose with no filler; compact despite covering multiple aspects.

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 output schema is present, the description appropriately focuses on behavior not covered by schema: output size, API-call characteristics, failure shape, and recommendation context. It is complete for a moderate-complexity read-only 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 3 applies. The description does not add new parameter meaning beyond the schema; it references collection-level docs but leaves parameter details to the well-documented input 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?

Description opens with a specific verb+resource+scope: 'Get full parameter-level documentation for every module in a collection from Galaxy.' It also distinguishes itself from siblings by contrasting with get_collection_manifest and get_module_doc, so the purpose is explicit and unique.

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 explicit when-to-use guidance: use get_collection_manifest first for compact overview, get_module_doc for specific modules, and reserve this tool for batch operations needing all parameter details. This is clear guidance with alternatives and 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?

The annotations only declare readOnlyHint: true, but the description adds substantial behavioral context: cached vs. on-demand generation, metadata extraction with no skill generation, error return shape, and the partial-failure behavior where a hard batch failure yields zero module entries but retains roles/plugins. This goes well beyond the annotation.

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?

Every sentence earns its place: purpose, usage guidance, caching behavior, error shape, and failure semantics. The description is front-loaded with the core purpose and then methodically covers edge cases without fluff.

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 single-parameter tool with an output schema, the description covers purpose, selection criteria, caching, generation side effects, error returns, and degraded batch behavior. It is fully self-sufficient for an agent to decide when and how to invoke it.

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%: the only parameter, collection_namespace, already includes an example ('netbox.netbox'). The tool description does not add additional parameter-level detail, so the schema carries the load; this meets the baseline but does not exceed it.

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 opens with a specific verb and resource: 'Get a lightweight collection overview: module/role/plugin names with one-line descriptions.' It clearly distinguishes this from the sibling get_collection_docs by framing it as the preferred exploratory overview tool, and points to get_module_doc for drilling down.

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 says 'Prefer this over get_collection_docs when exploring a collection' and notes it is 'suitable for deciding which modules to drill into with get_module_doc.' This gives clear context and names alternatives, though it does not enumerate explicit when-not-to-use cases beyond the preference statement.

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 only declare readOnlyHint=true, but the description adds significant behavioral details: return structure, fallback logic ('Falls back to Galaxy if collection is not installed locally'), and error response format ('On failure returns {"error": str}'). No contradictions with 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?

The description is concise (three main bullet points) and front-loaded with the core purpose. Every sentence adds value: purpose, return fields, fallback, error handling. 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 has only one parameter and an output schema exists, the description is complete. It covers return fields, fallback behavior, and error response. No gaps for an agent to invoke 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 coverage is 100% for the single parameter (module_name). The description does not add information beyond what the schema already provides (fully-qualified collection name example). 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?

The description clearly states the verb ('Get') and resource ('full structured documentation for one module'). It specifies it returns structured docs, which differentiates it from sibling tools like get_plugin_doc (plugin) and get_collection_docs (collection).

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 gives usage context by listing the return fields and mentioning fallback behavior to Galaxy if the module is not installed locally. However, it does not explicitly state when not to use this tool or suggest alternatives among siblings.

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?

Beyond readOnlyHint annotation, description adds fallback behavior ('Falls back to Galaxy if collection is not installed locally') and error format ('On failure returns {"error": str}'), plus lists return fields.

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?

Description is brief yet covers purpose, return fields, fallback behavior, and error handling. No redundant sentences; front-loaded with main intent.

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 presence, description provides sufficient detail for a simple read-only doc tool. Annotations and description together cover all behavioral aspects.

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?

Input schema has 100% description coverage with clear explanations (e.g., fully-qualified name, plugin type list). Description adds no extra meaning to parameters beyond 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?

Description clearly states 'Get full structured documentation for one plugin' with specific resource and action. It distinguishes from sibling tools like get_module_doc and get_role_doc by specifying 'plugin'.

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?

Tool name and description imply it's for plugin documentation, contrasting with siblings for modules/roles/collections. However, no explicit when-to-use or when-not-to-use guidance is provided.

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 declare readOnlyHint, but description adds return structure details, fallback mechanism, and error response. No contradiction; 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?

Concise, front-loaded with goal, then structured returns, fallback, and error info. No unnecessary words. Ideal length.

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?

Completes the picture with output schema implicitly described, error handling, fallback, and parameter explanation. For a 1-param read-only tool, this is fully sufficient.

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% for the single parameter. Description does not add new meaning beyond schema; 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?

Starts with 'Get full structured documentation for one role' – a specific verb and resource. Clearly distinguishes from siblings like get_module_doc or get_plugin_doc by focusing on roles.

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?

No explicit when-to-use vs alternatives, but the name and description make the purpose obvious. Provides fallback behavior hint but lacks exclusions or alternative recommendations.

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?

Beyond the readOnlyHint annotation, the description adds valuable behavioral details: it searches ANSIBLE_KNOW_SKILLS_PATH when set, otherwise SKILLS_DIR, first match wins, and returns SKILL.md content as str or an error. This is useful context not covered by 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?

The description is concise and well-structured: three short sentences covering purpose, search behavior, and return format. Every sentence earns its place without 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?

For a simple tool with one parameter and an output schema, the description is complete. It covers return values, error behavior, and search path resolution, leaving no significant gaps for an agent to misuse the 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%, and the parameter description already explains the expected format (FQCN or collection namespace). The tool description adds minimal extra meaning just referring to 'by name', which is redundant. 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?

The description clearly states the tool reads a specific skill's SKILL.md content by name, using a specific verb and resource. It distinguishes itself from siblings like list_skills and get_*_doc by focusing on skill content retrieval.

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 implies when to use it (when you need a skill's content by name) and provides context about search paths. It doesn't explicitly exclude alternatives, but the sibling names make the distinction clear.

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?

The readOnlyHint annotation already signals non-mutating behavior; the description adds no additional behavioral details such as permissions, return format, or failure modes. It contributes contextual clarity about identifier origin and scope, but no deep behavioral transparency beyond the annotation.

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 three short sentences, front-loads the core action, and every sentence adds distinct value: what it does, when to use it, and what it does not cover. No filler or redundant implementation details.

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 a single well-defined parameter, readOnlyHint annotation, and an output schema present, the description covers the essential operational context. It tells the agent exactly where identifiers come from and clarifies the boundary against a sibling tool, making it sufficient for effective invocation.

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 parameter is already fully documented. The description reiterates the namespace.role format and references search_standalone_roles, which slightly reinforces meaning, but it does not add materially beyond 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 states specifically that the tool gets documentation for a standalone role using a 2-part namespace.role identifier. It clearly distinguishes from get_role_doc by stating it does not cover collection roles, so the purpose is unambiguous and differentiates among sibling 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?

Explicit usage context is provided: use for standalone roles discovered with search_standalone_roles. It also gives a clear exclusion by saying it does not replace get_role_doc for collection roles, effectively naming the alternative.

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?

Beyond the readOnlyHint annotation, the description discloses the environment variable fallback logic (ANSIBLE_KNOW_SKILLS_PATH vs SKILLS_DIR), duplicate-name resolution behavior, and the exact return/error format. This adds meaningful behavioral context for a read-only operation.

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 concise and well-structured, with a clear opening statement followed by important behavioral details and return format. It has no unnecessary filler, though slightly longer than strictly minimal.

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 an output schema provided and a single optional parameter, the description is fully complete: it covers the purpose, search-path behavior, duplicate resolution, and error handling. It provides all necessary context for an agent to invoke the tool 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?

The input schema already fully describes the 'collection' parameter with 100% coverage. The description adds minimal extra value by clarifying the default behavior when collection is omitted, but doesn't need to compensate for schema gaps.

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 clearly states 'List all available generated skills' with a specific verb and resource, and distinguishes itself from siblings by specifying 'generated' and mentioning the output fields. It's explicitly a listing tool, differentiating it from get_skill and generation 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?

Usage is implied by the 'List all' phrasing and optional collection filter, but the description doesn't explicitly state when to choose this over siblings like get_skill or search_docs. It provides context for the search-path behavior but no direct alternatives or 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 declare the tool destructive and idempotent. The description adds specific detail about replacing an existing skills/ tree, which enriches the behavioral picture without contradicting the 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?

The description is well-structured with a concise summary, a detailed behavior paragraph, and a clear return specification. It is neither verbose nor sparse, with all sentences contributing value.

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 existence of an output schema and the rich annotations, the description is sufficiently complete. It covers purpose, behavior, and return value without elaborating every edge case, which is acceptable.

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 covers all parameters (100% coverage). The description adds structural context, such as the copy destination pattern and default plugin_name, which goes beyond the schema's individual parameter definitions.

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 clearly states it wraps already-generated skills into an Agent Plugins directory, specifying the action, input, and output. It distinguishes itself from sibling generation tools by noting it does not change generate_* output layout.

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 provides clear context on when to use (after skills have been generated) and describes the packaging behavior. It does not explicitly state when not to use it or list alternatives, but the distinction from generate_* tools is implicit.

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 indicate destructiveHint and idempotentHint. The description adds concrete details: it 'Replaces any existing ``skills/`` tree under the target module directory' and clarifies that the generate_* output layout is unchanged. This goes beyond the annotations by specifying exactly what is destroyed and the idempotent behavior.

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 concise, front-loaded with the primary purpose, and includes a deprecation note, behavior details, and return format in a compact manner. No wasted 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 the tool's complexity (5 parameters, 2 required, output schema present), the description covers the main behavioral aspects: purpose, destructive action, idempotency, and expected return. It doesn't explicitly state prerequisites (e.g., that skills must already be generated), but this is implied by 'already-generated skills' and is not a critical gap. The output schema handles return documentation.

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 parameters are already well-documented. The description ties parameters together (e.g., output_dir and module_name in the copying path) but does not add significant new meaning beyond what the schema provides. Baseline of 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?

The description clearly states the tool's purpose: 'Wrap already-generated skills into a Lola-compatible module directory.' It specifies the copying behavior and output format, and distinguishes from the sibling package_as_plugin by mentioning deprecation and preference.

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?

Explicit guidance is given: 'Prefer :func:`package_as_plugin` (Agent Plugins). Kept for one release cycle for backward compatibility.' This tells the agent when to use this tool versus the alternative, and also states the intended use case (marketplace / lola mod add).

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. Description adds return format, non-deprecated filtering, and ranking by download count. No contradiction. 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 plus return structure. Front-loaded with action. No redundant 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?

Complete for a search tool with output schema: covers purpose, usage, return format (including error), and workflow with 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 coverage is 100% with descriptions. Description does not add significant parameter details beyond schema. 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?

Clearly states verb 'Search' and resource 'Ansible Galaxy collections'. Distinguishes from siblings like ensure_collection and get_module_doc. Specifies it returns non-deprecated collections ranked by download count.

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?

Explicitly says to use for discovering which collection provides modules for a platform/use case. Provides follow-up actions (ensure_collection, get_module_doc). Lacks explicit when-not-to-use but strong positive 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?

Beyond the readOnlyHint annotation, the description discloses the result cap (up to 20 entries), the exact fields returned, the error shape, and a nuanced behavioral detail: unfiltered searches may exclude CoP content, so retrying with source='cop-good-practices' is advised. This is rich, non-obvious behavioral 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 front-loaded with the core purpose, followed by return/error behavior and then the source mapping. Every sentence is informative, and the source list is compact and scannable. No filler or redundant restatement of 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?

Given the readOnly annotation, the presence of an output schema, and full schema coverage, the description covers all critical operational context: result limits, returned fields, failure shape, source selection, and edge-case behavior for CoP searches. Nothing essential 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 coverage is 100%, giving a baseline of 3, but the description goes well beyond the schema by enumerating and explaining each source corpus, the default behavior when source is omitted, and the 'do not invent cop-best-practices' caution. This materially improves an agent's ability to select the correct source 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 opens with a specific verb and resource: 'Search documentation manifests for conceptual guides.' This clearly distinguishes the tool from sibling search tools like search_modules, search_plugins, and search_collections, which target different artifact types.

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 gives explicit, actionable source-selection guidance with a detailed corpus-to-source mapping, plus a retry instruction for CoP questions and a warning against inventing 'cop-best-practices.' It does not explicitly contrast this tool with sibling search tools, but the object type ('documentation manifests') and source guidance make the intended usage clear.

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 declare readOnlyHint=true, and the description adds that it returns up to 50 matches, with a specific return format including error cases. No contradictions.

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 two sentences, front-loaded with the core purpose, and includes return format concisely. No unnecessary text.

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 search tool with good schema and annotations, the description covers return format, error case, and limit. It lacks pagination or sorting details, but given the output schema is implied, it is adequate.

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 parameters are well-documented. The description adds context about the search scope and limit but does not detail parameter syntax beyond what's in the schema. 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?

The description clearly states the verb 'Find' and the resource 'Ansible modules', specifying search by keyword in name or description. This distinguishes it from sibling tools like search_collections or search_plugins.

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 tells when to use this tool (when searching for modules) but does not explicitly exclude other tools or state alternatives. The limit of 50 matches is mentioned, but no direct comparison to siblings.

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 indicate readOnlyHint=true, so the bar is lower. The description adds value by describing the return format ({fqcn: short_description}) and failure behavior ({'error': str}), which are beyond the annotation's scope.

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 concise with no wasted words. It front-loads the purpose, then provides return format and failure details, and lists plugin types efficiently in a structured manner.

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 presence of an output schema (not shown but indicated), the description adequately covers the tool’s behavior, return structure, and error handling. The list of plugin types provides sufficient context for effective use.

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 baseline is 3. The description adds value by listing valid plugin types and explaining the return format, which helps understand the effect of the 'keyword' and 'plugin_type' parameters.

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 clearly states 'Find Ansible plugins by keyword,' which is a specific verb+resource. It lists plugin types and distinguishes from sibling tools like search_collections, search_modules, and search_docs.

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 implies usage for searching plugins by keyword but does not explicitly state when to use this tool versus alternatives like search_modules or search_collections. The listed plugin types provide some context but no clear guidance on 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?

The annotations already mark this as read-only, and the description adds meaningful behavioral details: the tag parameter uses only the first comma-separated segment, and a v1-unsupported error may occur if public Galaxy is unavailable. This goes beyond annotations without contradicting them.

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 compact, front-loaded with the core purpose, and every sentence adds information about scope, alternatives, tag behavior, or failure conditions. There is no 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?

For a read-only search tool with two parameters, an output schema, and a clear sibling context, the description provides sufficient guidance: scope, alternative tool use, tag handling, and an edge-case error. The agent can reliably invoke this tool without additional clarification.

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 both parameters. The description adds a small amount of context for tags, but most of that behavior is also captured in the schema itself.

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 opens with a specific verb and resource: 'Search Galaxy standalone/legacy roles by keyword.' It also distinguishes itself by explicitly separating standalone (2-part) roles from collection roles.

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 clearly states that collection roles should use search_collections/get_role_doc instead, giving a direct alternative. It also warns about the v1-unsupported error condition, helping the agent decide if this tool will work in the current environment.

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