From 2026e71697d918d98e99f3146dbb263d03158c59 Mon Sep 17 00:00:00 2001
From: TomasKristof <tomask@kontent.ai>
Date: Tue, 15 Jul 2025 15:04:17 +0200
Subject: [PATCH] Standardize tool descriptions for Kontent.ai API

- Added a new rules file to enforce standardized naming patterns for tool descriptions, emphasizing the inclusion of "Kontent.ai" and specifying API sources.
- Modified tool registration messages across multiple files to align with the new naming guidelines, enhancing clarity for users.
---
 .cursor/rules/kontent-tool-descriptions.mdc  | 41 +++++++++++++++
 README.md                                    | 52 ++++++++++----------
 src/tools/add-content-item-mapi.ts           |  2 +-
 src/tools/add-content-type-mapi.ts           |  2 +-
 src/tools/add-content-type-snippet-mapi.ts   |  2 +-
 src/tools/add-taxonomy-group-mapi.ts         |  2 +-
 src/tools/delete-content-item-mapi.ts        |  2 +-
 src/tools/delete-language-variant-mapi.ts    |  2 +-
 src/tools/filter-variants-mapi.ts            |  2 +-
 src/tools/get-asset-mapi.ts                  |  2 +-
 src/tools/get-taxonomy-group-mapi.ts         |  2 +-
 src/tools/get-type-mapi.ts                   |  2 +-
 src/tools/get-type-snippet-mapi.ts           |  2 +-
 src/tools/get-variant-mapi.ts                |  2 +-
 src/tools/list-assets-mapi.ts                |  2 +-
 src/tools/list-content-type-snippets-mapi.ts |  2 +-
 src/tools/list-content-types-mapi.ts         |  2 +-
 src/tools/list-languages-mapi.ts             |  2 +-
 src/tools/list-taxonomy-groups-mapi.ts       |  2 +-
 src/tools/list-workflows-mapi.ts             |  2 +-
 src/tools/update-content-item-mapi.ts        |  2 +-
 src/tools/upsert-language-variant-mapi.ts    |  2 +-
 22 files changed, 87 insertions(+), 46 deletions(-)
 create mode 100644 .cursor/rules/kontent-tool-descriptions.mdc

diff --git a/.cursor/rules/kontent-tool-descriptions.mdc b/.cursor/rules/kontent-tool-descriptions.mdc
new file mode 100644
index 0000000..c751e54
--- /dev/null
+++ b/.cursor/rules/kontent-tool-descriptions.mdc
@@ -0,0 +1,41 @@
+---
+description: Enforce standardized naming pattern for Kontent.ai MCP tool descriptions
+globs: src/tools/*
+alwaysApply: false
+---
+
+When creating or modifying MCP tool descriptions, follow this standardized pattern:
+
+**Template:** `"[Action] [Kontent.ai entity] [method/context] [API source]"`
+
+## Required Elements:
+1. **Always include "Kontent.ai"** explicitly in the description
+2. **Action verbs:** Use consistent verbs like:
+   - Get / Retrieve
+   - Add / Create 
+   - Update / Modify
+   - Delete / Remove
+   - List / Get all
+   - Filter / Search
+
+3. **Entity specification:** Clearly identify the Kontent.ai entity:
+   - content type, content item, language variant
+   - asset, taxonomy group, workflow
+   - etc.
+
+4. **API source:** Always specify the API being used:
+   - "from Management API"
+   - "via Management API" 
+   - "from Delivery API"
+
+## Examples:
+✅ **Good:**
+- "Get Kontent.ai content type by internal ID from Management API"
+- "Add new Kontent.ai content item via Management API"
+- "Create or update Kontent.ai language variant of a content item via Management API"
+- "Get a specific Kontent.ai asset by internal ID from Management API"
+
+❌ **Bad:**
+- "Get content type by ID" (missing Kontent.ai, missing API source)
+- "Add content type" (missing Kontent.ai, missing API source)
+- "Retrieve item" (too vague, missing Kontent.ai)
diff --git a/README.md b/README.md
index 5bd27e0..85bf0f6 100644
--- a/README.md
+++ b/README.md
@@ -58,53 +58,53 @@ npx @kontent-ai/mcp-server@latest sse
 
 ### Context and Setup
 
-* **get-initial-context** – 🚨 **MANDATORY FIRST STEP**: Provides essential context, configuration, and operational guidelines for Kontent.ai. This tool MUST be called before using any other tools to understand the platform structure, core entities, relationships, and best practices.
+* **get-initial-context** – 🚨 **MANDATORY FIRST STEP**: This tool MUST be called before using ANY other tools. It provides essential context, configuration, and operational guidelines for Kontent.ai
 
 ### Content Type Management
 
-* **get-type-mapi** – Get a specific content type by internal ID
-* **list-content-types-mapi** – List all content types in the environment
-* **add-content-type-mapi** – Create a new content type with elements
+* **get-type-mapi** – Get Kontent.ai content type by internal ID from Management API
+* **list-content-types-mapi** – Get all Kontent.ai content types from Management API
+* **add-content-type-mapi** – Add new Kontent.ai content type via Management API
 
 ### Content Type Snippet Management
 
-* **get-type-snippet-mapi** – Get a specific content type snippet by internal ID
-* **list-content-type-snippets-mapi** – List all content type snippets
-* **add-content-type-snippet-mapi** – Create a new content type snippet
+* **get-type-snippet-mapi** – Get Kontent.ai content type snippet by internal ID from Management API
+* **list-content-type-snippets-mapi** – Get all Kontent.ai content type snippets from Management API
+* **add-content-type-snippet-mapi** – Add new Kontent.ai content type snippet via Management API
 
 ### Taxonomy Management
 
-* **get-taxonomy-group-mapi** – Get a specific taxonomy group by internal ID
-* **list-taxonomy-groups-mapi** – List all taxonomy groups
-* **add-taxonomy-group-mapi** – Create a new taxonomy group with terms
+* **get-taxonomy-group-mapi** – Get Kontent.ai taxonomy group by internal ID from Management API
+* **list-taxonomy-groups-mapi** – Get all Kontent.ai taxonomy groups from Management API
+* **add-taxonomy-group-mapi** – Add new Kontent.ai taxonomy group via Management API
 
 ### Content Item Management
 
-* **get-item-mapi** – Get a specific content item by internal ID
-* **get-item-dapi** – Get a content item by codename from Delivery API
-* **get-variant-mapi** – Get a language variant of a content item by internal IDs
-* **add-content-item-mapi** – Create a new content item (structure only)
-* **update-content-item-mapi** – Update an existing content item by internal ID (name, collection)
-* **delete-content-item-mapi** – Delete a content item by internal ID
-* **upsert-language-variant-mapi** – Create or update a language variant with content using internal IDs
-* **delete-language-variant-mapi** – Delete a language variant of a content item by internal IDs
-* **filter-variants-mapi** – Search and filter language variants using filters and search phrases
+* **get-item-mapi** – Get Kontent.ai item by internal ID from Management API
+* **get-item-dapi** – Get Kontent.ai item by codename from Delivery API
+* **get-variant-mapi** – Get Kontent.ai language variant of content item from Management API
+* **add-content-item-mapi** – Add new Kontent.ai content item via Management API. This creates the content item structure but does not add content to language variants. Use upsert-language-variant-mapi to add content to the item
+* **update-content-item-mapi** – Update existing Kontent.ai content item by internal ID via Management API. The content item must already exist - this tool will not create new items
+* **delete-content-item-mapi** – Delete Kontent.ai content item by internal ID from Management API
+* **upsert-language-variant-mapi** – Create or update Kontent.ai language variant of a content item via Management API. This adds actual content to the content item elements. Elements should be provided as JSON string in the format expected by the SDK
+* **delete-language-variant-mapi** – Delete Kontent.ai language variant from Management API
+* **filter-variants-mapi** – Search and filter Kontent.ai language variants of content items using Management API
 
 ### Asset Management
 
-* **get-asset-mapi** – Get a specific asset by internal ID
-* **list-assets-mapi** – List all assets in the environment
+* **get-asset-mapi** – Get a specific Kontent.ai asset by internal ID from Management API
+* **list-assets-mapi** – Get all Kontent.ai assets from Management API
 
 ### Language Management
 
-* **list-languages-mapi** – List all languages configured in the environment
+* **list-languages-mapi** – Get all Kontent.ai languages from Management API
 
 ### Workflow Management
 
-* **list-workflows-mapi** – List all workflows in the environment with their lifecycle stages and transitions
-* **change-variant-workflow-step-mapi** – Change the workflow step of a language variant (move content through workflow stages)
-* **publish-variant-mapi** – Publish or schedule a language variant for publication. Supports immediate publishing (happens right now) or scheduled publishing at a specific future date and time with optional timezone specification
-* **unpublish-variant-mapi** – Unpublish or schedule unpublishing of a language variant. Supports immediate unpublishing (removes content from Delivery API right now) or scheduled unpublishing at a specific future date and time with optional timezone specification
+* **list-workflows-mapi** – Get all Kontent.ai workflows from Management API. Workflows define the content lifecycle stages and transitions between them
+* **change-variant-workflow-step-mapi** – Change the workflow step of a language variant in Kontent.ai. This operation moves a language variant to a different step in the workflow, enabling content lifecycle management such as moving content from draft to review, review to published, etc.
+* **publish-variant-mapi** – Publish or schedule a language variant of a content item in Kontent.ai. This operation can either immediately publish the variant or schedule it for publication at a specific future date and time with optional timezone specification
+* **unpublish-variant-mapi** – Unpublish or schedule unpublishing of a language variant of a content item in Kontent.ai. This operation can either immediately unpublish the variant (making it unavailable through the Delivery API) or schedule it for unpublishing at a specific future date and time with optional timezone specification
 
 ### Utility
 
diff --git a/src/tools/add-content-item-mapi.ts b/src/tools/add-content-item-mapi.ts
index 5dab7f0..2a463ce 100644
--- a/src/tools/add-content-item-mapi.ts
+++ b/src/tools/add-content-item-mapi.ts
@@ -7,7 +7,7 @@ import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "add-content-item-mapi",
-    "Add a new content item via Management API. This creates the content item structure but does not add content to language variants. Use upsert-language-variant-mapi to add content to the item.",
+    "Add new Kontent.ai content item via Management API. This creates the content item structure but does not add content to language variants. Use upsert-language-variant-mapi to add content to the item.",
     {
       name: z
         .string()
diff --git a/src/tools/add-content-type-mapi.ts b/src/tools/add-content-type-mapi.ts
index 616f283..02f9c1e 100644
--- a/src/tools/add-content-type-mapi.ts
+++ b/src/tools/add-content-type-mapi.ts
@@ -11,7 +11,7 @@ import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "add-content-type-mapi",
-    "Add a new content type via Management API",
+    "Add new Kontent.ai content type via Management API",
     {
       name: z.string().describe("Display name of the content type"),
       codename: z
diff --git a/src/tools/add-content-type-snippet-mapi.ts b/src/tools/add-content-type-snippet-mapi.ts
index 84e7708..0fe228e 100644
--- a/src/tools/add-content-type-snippet-mapi.ts
+++ b/src/tools/add-content-type-snippet-mapi.ts
@@ -8,7 +8,7 @@ import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "add-content-type-snippet-mapi",
-    "Add a new content type snippet via Management API",
+    "Add new Kontent.ai content type snippet via Management API",
     {
       name: z.string().describe("Display name of the content type snippet"),
       codename: z
diff --git a/src/tools/add-taxonomy-group-mapi.ts b/src/tools/add-taxonomy-group-mapi.ts
index 801238d..4c0a4b4 100644
--- a/src/tools/add-taxonomy-group-mapi.ts
+++ b/src/tools/add-taxonomy-group-mapi.ts
@@ -7,7 +7,7 @@ import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "add-taxonomy-group-mapi",
-    "Add a new taxonomy group via Management API",
+    "Add new Kontent.ai taxonomy group via Management API",
     taxonomyGroupSchemas,
     async (taxonomyGroup) => {
       const client = createMapiClient();
diff --git a/src/tools/delete-content-item-mapi.ts b/src/tools/delete-content-item-mapi.ts
index e4b316f..688d27f 100644
--- a/src/tools/delete-content-item-mapi.ts
+++ b/src/tools/delete-content-item-mapi.ts
@@ -7,7 +7,7 @@ import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "delete-content-item-mapi",
-    "Delete a content item by internal ID from Management API",
+    "Delete Kontent.ai content item by internal ID from Management API",
     {
       id: z.string().describe("Internal ID of the content item to delete"),
     },
diff --git a/src/tools/delete-language-variant-mapi.ts b/src/tools/delete-language-variant-mapi.ts
index 6d530db..c5245ce 100644
--- a/src/tools/delete-language-variant-mapi.ts
+++ b/src/tools/delete-language-variant-mapi.ts
@@ -7,7 +7,7 @@ import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "delete-language-variant-mapi",
-    "Delete a language variant of a content item from Management API",
+    "Delete Kontent.ai language variant from Management API",
     {
       itemId: z.string().describe("Internal ID of the content item"),
       languageId: z
diff --git a/src/tools/filter-variants-mapi.ts b/src/tools/filter-variants-mapi.ts
index 6689011..4f87522 100644
--- a/src/tools/filter-variants-mapi.ts
+++ b/src/tools/filter-variants-mapi.ts
@@ -7,7 +7,7 @@ import { throwError } from "../utils/throwError.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "filter-variants-mapi",
-    "Search and filter language variants of content items using the Management API.",
+    "Search and filter Kontent.ai language variants of content items using Management API",
     filterVariantsSchema.shape,
     async ({
       search_phrase,
diff --git a/src/tools/get-asset-mapi.ts b/src/tools/get-asset-mapi.ts
index 897542c..018c3fa 100644
--- a/src/tools/get-asset-mapi.ts
+++ b/src/tools/get-asset-mapi.ts
@@ -7,7 +7,7 @@ import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "get-asset-mapi",
-    "Get a specific asset by internal ID from Management API",
+    "Get a specific Kontent.ai asset by internal ID from Management API",
     {
       assetId: z.string().describe("Internal ID of the asset to retrieve"),
     },
diff --git a/src/tools/get-taxonomy-group-mapi.ts b/src/tools/get-taxonomy-group-mapi.ts
index 7c861cf..b6c05e0 100644
--- a/src/tools/get-taxonomy-group-mapi.ts
+++ b/src/tools/get-taxonomy-group-mapi.ts
@@ -7,7 +7,7 @@ import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "get-taxonomy-group-mapi",
-    "Get taxonomy group by internal ID from Management API",
+    "Get Kontent.ai taxonomy group by internal ID from Management API",
     {
       id: z.string().describe("Internal ID of the taxonomy group to get"),
     },
diff --git a/src/tools/get-type-mapi.ts b/src/tools/get-type-mapi.ts
index 1b2c096..fca6c19 100644
--- a/src/tools/get-type-mapi.ts
+++ b/src/tools/get-type-mapi.ts
@@ -7,7 +7,7 @@ import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "get-type-mapi",
-    "Get content type by internal ID from Management API",
+    "Get Kontent.ai content type by internal ID from Management API",
     {
       id: z.string().describe("Internal ID of the content type to get"),
     },
diff --git a/src/tools/get-type-snippet-mapi.ts b/src/tools/get-type-snippet-mapi.ts
index fedc444..c3614f9 100644
--- a/src/tools/get-type-snippet-mapi.ts
+++ b/src/tools/get-type-snippet-mapi.ts
@@ -7,7 +7,7 @@ import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "get-type-snippet-mapi",
-    "Get content type snippet by internal ID from Management API",
+    "Get Kontent.ai content type snippet by internal ID from Management API",
     {
       id: z.string().describe("Internal ID of the content type snippet to get"),
     },
diff --git a/src/tools/get-variant-mapi.ts b/src/tools/get-variant-mapi.ts
index 6d6120f..0905395 100644
--- a/src/tools/get-variant-mapi.ts
+++ b/src/tools/get-variant-mapi.ts
@@ -7,7 +7,7 @@ import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "get-variant-mapi",
-    "Get language variant of a content item from Management API",
+    "Get Kontent.ai language variant of content item from Management API",
     {
       itemId: z.string().describe("Internal ID of the content item"),
       languageId: z
diff --git a/src/tools/list-assets-mapi.ts b/src/tools/list-assets-mapi.ts
index 619a658..ad6c3cd 100644
--- a/src/tools/list-assets-mapi.ts
+++ b/src/tools/list-assets-mapi.ts
@@ -6,7 +6,7 @@ import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "list-assets-mapi",
-    "Get all assets from Management API",
+    "Get all Kontent.ai assets from Management API",
     {},
     async () => {
       const client = createMapiClient();
diff --git a/src/tools/list-content-type-snippets-mapi.ts b/src/tools/list-content-type-snippets-mapi.ts
index 1f16dee..dae4315 100644
--- a/src/tools/list-content-type-snippets-mapi.ts
+++ b/src/tools/list-content-type-snippets-mapi.ts
@@ -6,7 +6,7 @@ import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "list-content-type-snippets-mapi",
-    "Get all content type snippets from Management API",
+    "Get all Kontent.ai content type snippets from Management API",
     {},
     async () => {
       const client = createMapiClient();
diff --git a/src/tools/list-content-types-mapi.ts b/src/tools/list-content-types-mapi.ts
index 0f42308..5bd83f9 100644
--- a/src/tools/list-content-types-mapi.ts
+++ b/src/tools/list-content-types-mapi.ts
@@ -6,7 +6,7 @@ import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "list-content-types-mapi",
-    "Get all content types from Management API",
+    "Get all Kontent.ai content types from Management API",
     {},
     async () => {
       const client = createMapiClient();
diff --git a/src/tools/list-languages-mapi.ts b/src/tools/list-languages-mapi.ts
index 5fb311a..9258025 100644
--- a/src/tools/list-languages-mapi.ts
+++ b/src/tools/list-languages-mapi.ts
@@ -6,7 +6,7 @@ import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "list-languages-mapi",
-    "Get all languages from Management API",
+    "Get all Kontent.ai languages from Management API",
     {},
     async () => {
       const client = createMapiClient();
diff --git a/src/tools/list-taxonomy-groups-mapi.ts b/src/tools/list-taxonomy-groups-mapi.ts
index e844053..a7e7444 100644
--- a/src/tools/list-taxonomy-groups-mapi.ts
+++ b/src/tools/list-taxonomy-groups-mapi.ts
@@ -6,7 +6,7 @@ import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "list-taxonomy-groups-mapi",
-    "Get all taxonomy groups from Management API",
+    "Get all Kontent.ai taxonomy groups from Management API",
     {},
     async () => {
       const client = createMapiClient();
diff --git a/src/tools/list-workflows-mapi.ts b/src/tools/list-workflows-mapi.ts
index 92e75d8..b4af50d 100644
--- a/src/tools/list-workflows-mapi.ts
+++ b/src/tools/list-workflows-mapi.ts
@@ -6,7 +6,7 @@ import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "list-workflows-mapi",
-    "Get all workflows from Management API. Workflows define the content lifecycle stages and transitions between them.",
+    "Get all Kontent.ai workflows from Management API. Workflows define the content lifecycle stages and transitions between them.",
     {},
     async () => {
       const client = createMapiClient();
diff --git a/src/tools/update-content-item-mapi.ts b/src/tools/update-content-item-mapi.ts
index 84fc49c..0701282 100644
--- a/src/tools/update-content-item-mapi.ts
+++ b/src/tools/update-content-item-mapi.ts
@@ -7,7 +7,7 @@ import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "update-content-item-mapi",
-    "Update an existing content item by internal ID via Management API. The content item must already exist - this tool will not create new items.",
+    "Update existing Kontent.ai content item by internal ID via Management API. The content item must already exist - this tool will not create new items.",
     {
       id: z.string().describe("Internal ID of the content item to update"),
       name: z
diff --git a/src/tools/upsert-language-variant-mapi.ts b/src/tools/upsert-language-variant-mapi.ts
index 648453e..ffa55aa 100644
--- a/src/tools/upsert-language-variant-mapi.ts
+++ b/src/tools/upsert-language-variant-mapi.ts
@@ -8,7 +8,7 @@ import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server: McpServer): void => {
   server.tool(
     "upsert-language-variant-mapi",
-    "Create or update a language variant of a content item via Management API. This adds actual content to the content item elements. Elements should be provided as JSON string in the format expected by the SDK.",
+    "Create or update Kontent.ai language variant of a content item via Management API. This adds actual content to the content item elements. Elements should be provided as JSON string in the format expected by the SDK.",
     {
       itemId: z.string().describe("Internal ID of the content item"),
       languageId: z