Clear server caches.

Clears Galaxy version/docs-blob caches, standalone-role v1 caches, doc manifest/page caches, or both. Useful when cached data becomes stale during long-running sessions.

Install a collection to a temporary directory for this session.

Installs once and pins the resolved version. Subsequent calls with the same namespace skip unless a different version is explicitly requested. If a different version is requested than currently installed, the collection will be reinstalled.

Returns dict with keys:

• namespace: str — the collection namespace

• version: str — the installed/active version (always set)

• status: 'installed' (freshly installed or upgraded) or 'already_installed' (same version already present, no action taken)

• message: str — human-readable summary including the active version

• handle: str — opaque session handle; pass it as collection_handle to subsequent tool calls on remote connections On failure returns {"error": str}.

Pass collection_handle when re-invoking ensure_collection on a remote connection with a handle obtained from a prior call (e.g. to install an additional collection into the same session). Omit it on local stdio, or on remote when you want a brand-new session handle minted.

Fetch a docs page as clean Markdown.

Returns documentation content ready for LLM consumption. Use search_docs to discover relevant page URLs. Accepts docs.ansible.com, docs.redhat.com, or CoP good-practices raw GitHub README.adoc URLs from search_docs hits (not arbitrary raw.githubusercontent.com hosts).

Batch generate skills for an entire collection.

Generates/updates the collection MANIFEST.json as a byproduct. Updates AGENTS.md in the project root with a managed section listing available collections for cross-agent discovery. Returns {"succeeded": int, "failed": int, "total": int, "manifest": dict, "collection_skill": str}, or {"error": str} on failure.

Module/plugin docs use batched ansible-doc calls. Names missing from a batch (or a hard batch failure) are counted in failed; partial batch success still writes skills for resolved names.

Generate a skill package for one plugin.

Writes SKILL.md to disk (no scripts/ or assets/). Returns the SKILL.md content as str, or {"error": str} on failure.

Generate a skill package for one role.

Writes SKILL.md + assets/playbook.yml to disk (no scripts/). Returns the SKILL.md content as str, or {"error": str} on failure.

Generate a skill package for one module.

Writes SKILL.md + scripts + playbook to disk. Returns the SKILL.md content as str, or {"error": str} on failure.

Get full parameter-level documentation for every module in a collection from Galaxy.

WARNING: output can be very large (100 KB+) for collections with many modules. Use get_collection_manifest first for a compact overview, then get_module_doc for the specific modules you need. Reserve this tool for batch operations that genuinely need all parameter details at once (e.g. skill generation).

Returns all module docs in a single API call without installing the collection. Result shape: {"modules": {fqcn: {module_name, short_description, params, examples, is_api_module}, ...}, "doc_source": "galaxy", "doc_version": str}. On failure returns {"error": str}.

Get a lightweight collection overview: module/role/plugin names with one-line descriptions.

Prefer this over get_collection_docs when exploring a collection — it returns a compact summary suitable for deciding which modules to drill into with get_module_doc.

Returns cached MANIFEST.json if available, otherwise generates on-demand (metadata extraction only, no skill generation). On failure returns {"error": str}.

Module docs are fetched in batched ansible-doc calls. If the entire batch fails hard, the manifest is written with zero module entries (roles/plugins from list discovery are still included when present).

Get full structured documentation for one module.

Returns: module_name, short_description, params (list with name/type/required/default/choices/description/aliases), examples (raw YAML), is_api_module, doc_source ('local' or 'galaxy'). When doc_source is 'galaxy', also includes doc_version and optionally doc_warning. Falls back to Galaxy if collection is not installed locally. On failure returns {"error": str}.

Get full structured documentation for one plugin.

Returns: plugin_name, plugin_type, short_description, params, examples, doc_source ('local' or 'galaxy'). Falls back to Galaxy if collection is not installed locally. On failure returns {"error": str}.

Get full structured documentation for one role.

Returns: role_name, content_type ('role'), short_description, doc_source ('local', 'galaxy_readme', or 'unavailable'), entry_points (dict of entry point names to {description, options}), dependencies (list), examples (str). When doc_source is 'galaxy_readme', also includes doc_version and doc_warning. Falls back to Galaxy README parsing if local ansible-doc returns empty. On validation failure returns {"error": str}.

Read a specific skill's SKILL.md content by name.

Searches ANSIBLE_KNOW_SKILLS_PATH (colon-separated) when set, otherwise the single SKILLS_DIR. First match wins.

Returns: SKILL.md content as str, or {"error": str} on failure/not found.

Get standalone role documentation for a 2-part namespace.role identifier.

Use this for standalone roles discovered with search_standalone_roles. This tool does not replace get_role_doc for collection roles.

List all available generated skills. Returns name, description, path for each.

Searches ANSIBLE_KNOW_SKILLS_PATH (colon-separated) when set, otherwise the single SKILLS_DIR. Duplicate names keep the first path's entry.

Returns: [{"name": str, "description": str, "path": str}, ...] or {"error": str} on failure.

Wrap already-generated skills into an Agent Plugins directory.

Does not change generate_* output layout. Copies skills/{collection-kebab}/{skill}/ into {output_dir}/{plugin}/skills/{skill}/ and writes plugin.json (and optionally mcp.json + .tar.gz) per the Agent Plugins specification. Replaces any existing skills/ tree under the target plugin directory (destructive but idempotent).

Returns: {"collection", "plugin_name", "plugin_dir", "skill_count", "skills", "plugin_json", "mcp_json", "archive"} or {"error": str} on failure.

Wrap already-generated skills into a Lola-compatible module directory.

.. deprecated:: Prefer :func:package_as_plugin (Agent Plugins). Kept for one release cycle for backward compatibility.

Does not change generate_* output layout. Copies skills/{collection-kebab}/{skill}/ into {output_dir}/{module}/skills/{skill}/ for marketplace / lola mod add use. Replaces any existing skills/ tree under the target module directory (destructive but idempotent).

Returns: {"collection", "module_name", "module_dir", "skill_count", "skills", "market_yml"} or {"error": str} on failure.

Search Ansible Galaxy for collections by keyword.

Returns non-deprecated collections ranked by download count. Use this to discover which collection provides modules for a specific platform or use case.

After finding a collection, use ensure_collection() to install it, then get_module_doc() or get_collection_manifest() to explore its modules.

Returns: {"query": str, "count": int, "collections": [{"namespace": str, "description": str, "tags": [str], "latest_version": str, "module_count": int, "download_count": int, "deprecated": bool, "signed": bool}, ...]} On failure returns {"error": str}.

Search documentation manifests for conceptual guides.

Returns up to 20 matching entries with title, summary, topic, audience, lines, source, and raw URL. On failure returns {"error": str}.

Choose source by corpus:

• ansible-core (or omit): official HOWTO — playbooks, vault, inventory syntax

• ansible-lint: rules and profiles

• ansible-navigator / ansible-builder / ansible-creator / molecule: matching source

• aap-2.5 / aap-2.6 / aap-2.7: AAP product manuals

• cop-good-practices: CoP opinionated practices (role design, naming, CaC, Git, testing process). Users often say "best practices"; do not invent cop-best-practices. Unfiltered search fills the 20-hit window with official + AAP first; CoP may be absent — retry with source='cop-good-practices' for CoP-shaped questions.

Find Ansible modules by keyword in name or description. Returns up to 50 matches as {fqcn: short_description}.

Returns: {"module.fqcn": "short description", ...} or {"error": str} on failure.

Find Ansible plugins by keyword. Returns up to 50 matches as {fqcn: short_description}.

Plugin types: lookup, filter, test, connection, become, strategy, callback, inventory, cache, cliconf, httpapi, netconf, shell, vars. On failure returns {"error": str}.

Search Galaxy standalone/legacy roles by keyword.

This targets standalone (2-part) roles. Collection roles use search_collections/get_role_doc. tags accepts a single Galaxy tag; if comma-separated values are provided, only the first segment is sent.

If public Galaxy is disabled and no configured server supports v1 role endpoints, expect a v1-unsupported error.