ansible-know-mcp

Overview Schema Source Related Servers Discussions Admin

Search Modules

search_modules

Read-only

Find Ansible modules by matching keywords against names and descriptions. Optionally filter by namespace or collection handle and return up to 50 FQCN-to-description matches.

Instructions

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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "keyword": "<keyword>"
    },
    "name": "search_modules"
  }
}

Input Schema

Name	Required	Description
`keyword`	Yes	Search term to match against module names and descriptions
`namespace`	No	Optional collection namespace filter (e.g. 'community.docker')
`collection_handle`	No	Session handle returned by ensure_collection. Omit on local stdio; required on remote.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.11.0Nov 6, 2026

addedInput schema / properties / collection_handle

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Session handle returned by ensure_collection. Omit on local stdio; required on remote."
+}

First observedv0.7.0Jul 7, 2026

TDQS

B3.2/5.0

Behavior3/5

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

readOnlyHint=true already tells the agent this is a safe read. The description adds real signal beyond that: a hard cap of 50 matches and the error return shape ({error: str}). It does not cover whether the search spans all installed collections versus only a session-pinned one, or how truncation is signalled when more than 50 match.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the action and the matching rule. The trailing 'Returns: ...' line is slightly redundant given an output schema exists, but it is compact and not padded with filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a keyword search with a full schema and an output schema, the description covers what it does, the result cap, and failure shape. The main remaining gap is environment-dependent behavior, which is only hinted at inside the collection_handle schema description rather than the tool description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all three parameters are documented in the schema itself, and the description adds only the matching-scope detail (name or description). It says nothing about the namespace filter or the collection_handle session semantics, but those are fully covered in the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with matching scope: 'Find Ansible modules by keyword in name or description.' The resource (modules) implicitly separates it from siblings like search_plugins and search_standalone_roles, but the description never names those alternatives or explains the module-vs-plugin distinction, which is genuinely blurry in Ansible.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance at all: no mention of when to pick this over search_plugins, search_docs, or search_collections, and no note that a hit should be followed up with get_module_doc. With 21 sibling tools, this absence forces the agent to infer routing from the name alone.

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