Skip to main content
Glama
Sign In
ansible-know-mcp

ansible-know-mcp

by leogallego
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Search Docs

search_docs
Read-only

Search Ansible documentation manifests for conceptual guides by query, topic, audience, or source, returning matching titles, summaries, and URLs for targeted troubleshooting and learning.

Instructions

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.

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": {
      "query": "<query>"
    },
    "name": "search_docs"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYesSearch term to match against documentation titles, summaries, and topics
topicNoFilter by topic tag
sourceNoFilter to a single source (e.g. 'cop-good-practices', 'ansible-core', 'aap-2.6'). Good-practices / 'best practices' / GPA questions use source='cop-good-practices'.
audienceNoFilter by audience tag
core_onlyNoIf true, only return entries marked as core

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.10.0
    • changedInput schema / properties / source / description
      Previous value: -"Filter to a single source (e.g. 'ansible-core')"New value: +"Filter to a single source (e.g. 'cop-good-practices', 'ansible-core', 'aap-2.6'). Good-practices / 'best practices' / GPA questions use source='cop-good-practices'."
  2. First observedv0.7.0

TDQS

A4.4/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, and an output schema exists, so the description's field listing is partly redundant. It does add genuinely non-structural behavior: a hard 20-hit window, the ranking bias toward official and AAP sources, and the failure shape {"error": str}. The source-mapping bullets largely restate what the schema's source description already says.

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?

Front-loaded purpose, then return shape, then a scannable bulleted corpus map, then the truncation caveat. Nearly every line earns its place, though the source-to-corpus bullets partly duplicate the schema's source description and could be tightened.

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

Completeness5/5

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

For a read-only filtered search with a documented output schema, the description supplies what an agent actually needs to call it correctly: which source to pick, the 20-result ceiling, ranking bias, and the error shape. Nothing material about invocation is missing.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning by naming the full corpus vocabulary for source and warning against inventing a 'cop-best-practices' value. It still leaves topic, audience, and core_only semantics to the schema, where the bare 'Filter by topic tag' text offers little help.

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

Purpose5/5

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

States a specific verb and resource ('Search documentation manifests for conceptual guides') and scopes it to conceptual guide content, which separates it from sibling lookups like search_modules, search_plugins, and get_module_doc. The return shape (up to 20 entries with title, summary, topic, audience, lines, source, raw URL) further pins down what kind of result to expect.

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

Usage Guidelines5/5

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

Explicitly maps each corpus to a source value (ansible-core for playbooks/vault/inventory, ansible-lint for rules and profiles, aap-2.x for product manuals, cop-good-practices for opinionated practices) so the agent knows which filter to apply. It also warns that unfiltered search favors official + AAP content and can crowd out CoP results, with a concrete remedy (retry with source='cop-good-practices').

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

Deploy Server

Other Tools