Improve search tool descriptions and usage guidance

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontent-ai/mcp-server",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "type": "module",
   "scripts": {
     "build": "rimraf build && tsc",

src/tools/context/initial-context.ts

@@ -149,8 +149,8 @@ All MCP tools have been optimized to work with internal IDs for maximum efficien
 
 ### Content Search Tools
 
-The MCP server provides two search tools with distinct purposes:
-- **filter-variants-mapi**: Exact keyword matching with advanced filtering capabilities
-- **search-variants-mapi**: AI-powered semantic/conceptual search (when available)
+**CRITICAL DISTINCTION**:
+- **search-variants-mapi**: Finds content WHERE THE MAIN TOPIC matches a concept (e.g., "articles about wildlife")
+- **filter-variants-mapi**: Finds SPECIFIC WORDS anywhere in content, regardless of topic (e.g., brand compliance, detecting prohibited terms in any content)
 
-See each tool's description for detailed usage guidelines and selection criteria.`;
+See each tool's description for detailed usage guidelines.`;

src/tools/filter-variants-mapi.ts

@@ -11,11 +11,16 @@ export const registerTool = (server: McpServer): void => {
     `Filter Kontent.ai language variants of content items using Management API.
 
     USE FOR:
-    - EXACT keyword matching: finding specific words, phrases, names, codes, or IDs in content. Example: 'find items containing rabbit' → search 'rabbit'
-    - Advanced filtering by content type, contributors, workflow steps, taxonomies etc
+    - EXACT keyword matching: finding specific words, phrases, names, codes, or IDs anywhere in content, regardless of overall topic
+      ✓ Example: 'find items containing rabbit' → search 'rabbit'
+    - Brand guideline compliance: detecting prohibited terms across all content
+      ✓ Example: Search "hunt beast prey" to find content containing ANY of these terms (natural OR operator)
     - CAN expand concepts to keywords when using filter (e.g., "neurology-related" → "neurology neurological brain nervous system")
+    - Advanced filtering by content type, contributors, workflow steps, taxonomies etc
     - Also use as fallback when AI search is unavailable
-    - Optionally includes full content of variants with include_content parameter`,
+    - Optionally includes full content of variants with include_content parameter
+
+    BEST FOR: Finding needles in haystacks - specific words in otherwise unrelated content. Multiple search terms use OR logic.`,
     filterVariantsSchema.shape,
     async (
       {

src/tools/search-variants-mapi.ts

@@ -14,20 +14,32 @@ export const registerTool = (server: McpServer): void => {
   server.tool(
     "search-variants-mapi",
     `AI-powered semantic search for finding Kontent.ai content by meaning, concepts, themes, and content similarity in a specific language variant. This tool uses vector database and AI to enable searching by meaning and similarity rather than exact keyword matching.
-    
+
     CRITICAL REQUIREMENTS:
     - The AI search feature may not be available for all Kontent.ai environments
     - If you receive an "unavailable" status response, DO NOT attempt to use this tool again in the same session
     - Use filter-variants-mapi for exact text matching when semantic search is unavailable
     - Requires language variant filter parameter (e.g., default language '00000000-0000-0000-0000-000000000000')
     - The tool always RETURNS ONLY TOP 50 most relevant items at max
     - Limited filtering options (only by variant ID) - use filter-variants-mapi for advanced filtering by content types, workflow steps, taxonomies, etc.
-    
+
     USE FOR:
-    - Conceptual search: NEVER extract keywords, pass the single concept/theme as-is (e.g., "find content about keeping beverages cold" → searchPhrase: "beverage coolers")
-    - Finding content about topics: Use topic as-is (e.g., "find fairy tales" → searchPhrase: "fairy tales")
-    - Content similarity: Find articles similar to a given topic or story theme (e.g. "<<larger piece of content to search similar items>>" -> searchPhrase: "<<larger piece of content to search similar items>>")
-    - Thematic content discovery based on meaning and context`,
+    - Finding content WHERE THE OVERALL TOPIC/THEME matches a concept
+      ✓ Example: "fairy tales" → finds articles primarily about fairy tales
+      ✓ Example: "beverage temperature control" → finds content focused on keeping drinks cold/hot
+    - Content similarity: Finding articles with similar overall themes
+    - Thematic content discovery when the main subject matter is what you're looking for
+
+    DO NOT USE FOR:
+    - Finding specific words scattered in otherwise unrelated content
+      ✗ Example: Finding "challenge" term in articles about various topics (use filter-variants-mapi)
+    - Brand guideline violations or prohibited term detection (use filter-variants-mapi)
+    - Compliance audits looking for specific keywords (use filter-variants-mapi)
+    - Finding exhaustive and exact number of results (use filter-variants-mapi)
+
+    CRITICAL: This is SEMANTIC search for topic matching. Pass natural language concepts AS-IS. DO NOT generate keyword lists or concatenate multiple keywords.
+    ✓ CORRECT: "animal predators" or "articles about temperature control"
+    ✗ WRONG: "animal beast creature wild hunt predator prey attack"`,
     searchOperationSchema.shape,
     async (
       { searchPhrase, filter },