ansible-know-mcp

Overview Schema Source Related Servers Discussions Admin

Search Plugins

search_plugins

Read-only

Search Ansible plugins by keyword and optionally filter by collection namespace or plugin type to find relevant plugin documentation.

Instructions

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}.

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_plugins"
  }
}

Input Schema

Name	Required	Description
`keyword`	Yes	Search term to match against plugin names and descriptions
`namespace`	No	Optional collection namespace filter (e.g. 'netbox.netbox')
`plugin_type`	No	Plugin type filter (e.g. 'lookup', 'filter'). If omitted, searches all types.
`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?

Annotations already cover the read-only safety profile, so the description's added value is the result cap ("up to 50 matches") and the failure shape ({"error": str}), both genuinely useful behavioral facts. However, it says nothing about what happens when the 50-match cap is hit or how to narrow the search, which is the main behavioral question for a capped search tool.

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?

The core action and result shape are front-loaded in the first sentence, with the type list and error shape following as compact supporting blocks. The plugin-type roster is long but earns its space as the domain of the type filter; only minor waste in restating the return shape that the output schema already covers.

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?

With an output schema present and annotations covering safety, the description is largely complete: action, scope, result cap, and error contract are all stated. The remaining gap is operational guidance for truncated or empty results, and no explicit disambiguation from the module/collection/doc search siblings.

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 keyword, namespace, plugin_type, and collection_handle are already documented, including the remote-vs-stdio rule for collection_handle. The description's plugin-type enumeration does add domain meaning beyond the schema's two examples ('lookup', 'filter'), but it never ties that list explicitly to the plugin_type parameter or explains namespace syntax beyond the schema.

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?

"Find Ansible plugins by keyword" pairs a specific verb with a specific resource, and the enumerated plugin-type list scopes exactly what counts as a plugin (notably excluding modules, which have their own sibling tool). It stops short of naming a sibling such as search_modules or search_docs to route the agent away when modules or free-text docs are the real target.

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 explicit when-to-use, when-not-to-use, or alternative-tool guidance despite 22 siblings including search_modules, search_docs, and search_collections. The plugin-type list hints at applicability, but the agent must infer that this tool is for plugin names/descriptions rather than module or documentation search.

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