@egain/egain-mcp-server 1.0.26 → 1.1.0

package/src/funcs/{querySearch.ts → aiSearch.ts}

@@ -32,9 +32,56 @@ import { Result } from "../types/fp.js";
  * Hybrid Search
  *
  * @remarks
- * The Search API is a hybrid search service that combines semantic understanding with keyword precision to deliver fast, contextual, and relevant results from your enterprise knowledge base. It enables secure, role-aware access to articles, FAQs, and documentation across customer, agent, and employee interfaces. Each query returns a ranked list of results with snippets, metadata, and relevance scores. <br>**This endpoint is only available for Self Service environments.**
+ * Hybrid Search
+ *
+ * ## How to Use This Tool
+ *
+ * **CRITICAL**: This tool requires a `request` parameter containing the request object. All parameters must be passed inside a `request` object.
+ *
+ * **Parameter Format**:
+ * - Always wrap parameters in a `request` object: `{"request": {"portalID": "PZ-9999", "q": "loan information"}}`
+ * - Required parameters:
+ *   - `portalID` (string) - The portal ID (format: 2-4 letter prefix + dash + 4-15 digits, e.g., "PZ-9999")
+ *   - `q` (string) - The search query string (must be URL-escaped)
+ * - Optional parameters:
+ *   - `Dollar_lang` (string, default: "en-US") - Language code
+ *   - `dollarFilterUserProfileID` (string) - User profile ID filter
+ *   - `dollarFilterTags` (object) - Object where keys are Category Tag IDs and values are arrays of Tag IDs
+ *   - `dollarFilterTopicIds` (array) - Array of topic IDs to filter by
+ *   - `articleCustomAdditionalAttributes` (string) - Comma-separated custom attribute names
+ *   - `Dollar_pagenum` (number, default: 1) - Page number for pagination
+ *   - `Dollar_pagesize` (number, default: 20) - Number of results per page
+ *
+ * **Example**: To search for "loan information" in portal "PZ-9999", call with:
+ * ```json
+ * {"request": {"portalID": "PZ-9999", "q": "loan information"}}
+ * ```
+ *
+ * **Example with optional parameters**:
+ * ```json
+ * {"request": {"portalID": "PZ-9999", "q": "loan information", "Dollar_lang": "en-US", "Dollar_pagesize": 25}}
+ * ```
+ *
+ * **Note**: This endpoint is only available for Self Service environments.
+ *
+ * ## Displaying Results (MCP-Specific)
+ * **CRITICAL**: When this tool returns data successfully, you MUST display the search results to the user in your response. Do not silently process the data - always show the user what was returned.
+ *
+ * **What to display:**
+ * - Display all search results with article names and IDs
+ * - Show article `snippet` or `keywordSnippet` (the relevant text excerpt)
+ * - Display `normalizedScore` or `relevanceScore` to indicate relevance
+ * - Show `docType`, `source`, and `topicBreadcrumb` metadata
+ * - Display `contextualSummary` if available
+ * - Include `paginationInfo` if pagination is used
+ * - Format results in a numbered list with clear relevance indicators
+ *
+ * **Example**: "I found 10 articles matching 'loan information': 1) [Article Name] (ID: PROD-123) - [snippet] (Relevance: 0.89)..."
+ *
+ * ## Overview
+ * The Search API is a hybrid search service that combines semantic understanding with keyword precision to deliver fast, contextual, and relevant results from your enterprise knowledge base. It enables secure, role-aware access to articles, FAQs, and documentation across customer, agent, and employee interfaces. Each query returns a ranked list of results with snippets, metadata, and relevance scores.
  */
-export function querySearch(
+export function aiSearch(
   client$: EgainMcpCore,
   request: AiSearchRequest,
   options?: RequestOptions,

package/src/funcs/{getAnnouncements.ts → getAnnouncementArticles.ts}

@@ -3,7 +3,7 @@
  */
 
 import { EgainMcpCore } from "../core.js";
-import { encodeFormQuery, encodeSimple } from "../lib/encodings.js";
+import { encodeFormQuery, encodeSimple, queryJoin } from "../lib/encodings.js";
 import * as M from "../lib/matchers.js";
 import { compactMap } from "../lib/primitives.js";
 import { safeParse } from "../lib/schemas.js";
@@ -34,16 +34,52 @@ import { Result } from "../types/fp.js";
  * @remarks
  * Get Announcements
  *
+ * ## How to Use This Tool
+ *
+ * **CRITICAL**: This tool requires a `request` parameter containing the request object. All parameters must be passed inside a `request` object.
+ *
+ * **Parameter Format**:
+ * - Always wrap parameters in a `request` object: `{"request": {"portalID": "PZ-9999"}}`
+ * - Required parameter:
+ *   - `portalID` (string) - The portal ID (format: 2-4 letter prefix + dash + 4-15 digits, e.g., "PZ-9999")
+ *   - `acceptLanguage` (string, default: "en-US") - Accept-Language header value
+ * - Optional parameters:
+ *   - `Dollar_lang` (string, default: "en-US") - Language code
+ *   - `Dollar_pagesize` (number, default: 10) - Number of results per page
+ *
+ * **Example**: To get announcements from portal "PZ-9999", call with:
+ * ```json
+ * {"request": {"portalID": "PZ-9999"}}
+ * ```
+ *
+ * **Example with optional parameters**:
+ * ```json
+ * {"request": {"portalID": "PZ-9999", "Dollar_lang": "en-US", "Dollar_pagesize": 20}}
+ * ```
+ *
+ * ## Displaying Results (MCP-Specific)
+ * **CRITICAL**: When this tool returns data successfully, you MUST display the announcement articles to the user in your response. Do not silently process the data - always show the user what was returned.
+ *
+ * **What to display:**
+ * - Display all announcement articles with their names and IDs
+ * - Show the article content (`content` or `contentText`) for each announcement
+ * - Display metadata such as `createdDate`, `modifiedDate`, `articleSummary`
+ * - Show `attachments` if present
+ * - Include `paginationInfo` if pagination is used
+ * - Format announcements in a clear list format
+ *
+ * **Example**: "Here are the announcements for this portal: 1) [Announcement Name] (ID: PROD-123) - [content]..."
+ *
  * ## Prerequisites
  * - Requires a valid portal ID. If you don't have the portal ID, first call 'get-portals' to get available portals.
- * - Portal ID format: 2-4 letter prefix + dash + 4-15 digits (e.g., "EB-123456789")
+ * - Portal ID format: 2-4 letter prefix + dash + 4-15 digits (e.g., "PROD-1004")
  *
  * ## Overview
  * The Get Announcements API allows a user to retrieve all announcement articles for a specific portal. Announcements are special articles that are prominently displayed to users and typically contain important updates, news, or notifications.
  *
  * This API returns announcement articles with their full content, metadata, and any associated attachments or links.
  */
-export function getAnnouncements(
+export function getAnnouncementArticles(
   client$: EgainMcpCore,
   request: GetAnnouncementArticlesRequest,
   options?: RequestOptions,
@@ -105,13 +141,19 @@ async function $do(
   const path$ = pathToFunc("/portals/{portalID}/articles/announcements")(
     pathParams$,
   );
-  const query$ = encodeFormQuery({
-    "$filter[tags]": payload$.dollarFilterTags,
-    "$lang": payload$.Dollar_lang,
-    "$pagenum": payload$.Dollar_pagenum,
-    "$pagesize": payload$.Dollar_pagesize,
-    "workflowMilestone": payload$.workflowMilestone,
-  });
+  const query$ = queryJoin(
+    encodeFormQuery({
+      "articleResultAdditionalAttributes":
+        payload$.articleResultAdditionalAttributes,
+    }, { explode: false }),
+    encodeFormQuery({
+      "$filter[tags]": payload$.dollarFilterTags,
+      "$lang": payload$.Dollar_lang,
+      "$pagenum": payload$.Dollar_pagenum,
+      "$pagesize": payload$.Dollar_pagesize,
+      "workflowMilestone": payload$.workflowMilestone,
+    }),
+  );
 
   const headers$ = new Headers(compactMap({
     Accept: "application/json",
@@ -120,6 +162,21 @@ async function $do(
       payload$.acceptLanguage,
       { explode: false, charEncoding: "none" },
     ),
+    "x-egain-activity-id": encodeSimple(
+      "x-egain-activity-id",
+      payload$.xEgainActivityId,
+      { explode: false, charEncoding: "none" },
+    ),
+    "x-ext-integration-id": encodeSimple(
+      "x-ext-integration-id",
+      payload$.xExtIntegrationId,
+      { explode: false, charEncoding: "none" },
+    ),
+    "x-ext-interaction-id": encodeSimple(
+      "x-ext-interaction-id",
+      payload$.xExtInteractionId,
+      { explode: false, charEncoding: "none" },
+    ),
   }));
   const securityInput = await extractSecurity(client$._options.security);
   const requestSecurity = resolveGlobalSecurity(securityInput);

package/src/funcs/{getArticle.ts → getArticleById.ts}

@@ -34,6 +34,48 @@ import { Result } from "../types/fp.js";
  * @remarks
  * Get Article by ID
  *
+ * ## How to Use This Tool
+ *
+ * **CRITICAL**: This tool requires a `request` parameter containing the request object. All parameters must be passed inside a `request` object.
+ *
+ * **Parameter Format**:
+ * - Always wrap parameters in a `request` object: `{"request": {"portalID": "PZ-9999", "articleID": "PROD-2996"}}`
+ * - Required parameters:
+ *   - `portalID` (string) - The portal ID (format: 2-4 letter prefix + dash + 4-15 digits, e.g., "PZ-9999")
+ *   - `articleID` (string) - The article ID (format: 2-4 letter prefix + dash + 4-15 digits, e.g., "PROD-2996")
+ *   - `acceptLanguage` (string, default: "en-US") - Accept-Language header value
+ * - Optional parameters:
+ *   - `Dollar_lang` (string, default: "en-US") - Language code
+ *   - `articleAdditionalAttributes` (array) - Additional article attributes to return
+ *   - `Dollar_customAdditionalAttributes` (string) - Custom additional attributes
+ *   - `accessSource` (string, default: "article_view") - How the article was accessed
+ *   - `publishViewId` (string) - Publish view ID
+ *   - `workflowMilestone` (string) - Workflow milestone filter
+ *
+ * **Example**: To get article "PROD-2996" from portal "PZ-9999", call with:
+ * ```json
+ * {"request": {"portalID": "PZ-9999", "articleID": "PROD-2996"}}
+ * ```
+ *
+ * **Example with optional parameters**:
+ * ```json
+ * {"request": {"portalID": "PZ-9999", "articleID": "PROD-2996", "Dollar_lang": "en-US", "accessSource": "article_view"}}
+ * ```
+ *
+ * ## Displaying Results (MCP-Specific)
+ * **CRITICAL**: When this tool returns data successfully, you MUST display the article content to the user in your response. Do not silently process the data - always show the user what was returned.
+ *
+ * **What to display:**
+ * - Display the article `name` as the title
+ * - Show the article `content` or `contentText` (the full article body)
+ * - Display article metadata: `id`, `articleType`, `createdDate`, `modifiedDate`
+ * - Show `attachments` if present
+ * - Display `topicBreadcrumb` to show where the article is categorized
+ * - Include any other relevant metadata like `articleSummary`, `description`, `articleKeywords`
+ * - Format the article content in a readable way for the user
+ *
+ * **Example**: "Here's the article '[Article Name]' (ID: PROD-2996): [article content]. This article is categorized under: [topic breadcrumb]..."
+ *
  * ## Prerequisites
  * - Requires a valid portal ID. If you don't have the portal ID, first call 'get-portals' to get available portals.
  * - Portal ID format: 2-4 letter prefix + dash + 4-15 digits (e.g., "EB-123456789")
@@ -46,7 +88,7 @@ import { Result } from "../types/fp.js";
  * - The "Allow Structured Authoring" setting is enabled at the partition/department level
  * - The "Use Structured Authoring" flag is set on the article type
  */
-export function getArticle(
+export function getArticleById(
   client$: EgainMcpCore,
   request: GetArticleByIdRequest,
   options?: RequestOptions,
@@ -132,6 +174,21 @@ async function $do(
       payload$.acceptLanguage,
       { explode: false, charEncoding: "none" },
     ),
+    "x-egain-activity-id": encodeSimple(
+      "x-egain-activity-id",
+      payload$.xEgainActivityId,
+      { explode: false, charEncoding: "none" },
+    ),
+    "x-ext-integration-id": encodeSimple(
+      "x-ext-integration-id",
+      payload$.xExtIntegrationId,
+      { explode: false, charEncoding: "none" },
+    ),
+    "x-ext-interaction-id": encodeSimple(
+      "x-ext-interaction-id",
+      payload$.xExtInteractionId,
+      { explode: false, charEncoding: "none" },
+    ),
   }));
   const securityInput = await extractSecurity(client$._options.security);
   const requestSecurity = resolveGlobalSecurity(securityInput);

package/src/funcs/{queryAnswers.ts → getBestAnswer.ts}

@@ -10,6 +10,10 @@ import { safeParse } from "../lib/schemas.js";
 import { RequestOptions } from "../lib/sdks.js";
 import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
 import { pathToFunc } from "../lib/url.js";
+import {
+  AnswersResponse,
+  AnswersResponse$zodSchema,
+} from "../models/answersresponse.js";
 import { APIError } from "../models/errors/apierror.js";
 import {
   ConnectionError,
@@ -22,8 +26,6 @@ import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
 import {
   GetBestAnswerRequest,
   GetBestAnswerRequest$zodSchema,
-  GetBestAnswerResponse,
-  GetBestAnswerResponse$zodSchema,
 } from "../models/getbestanswerop.js";
 import { APICall, APIPromise } from "../types/async.js";
 import { Result } from "../types/fp.js";
@@ -34,26 +36,62 @@ import { Result } from "../types/fp.js";
  * @remarks
  * Get Answers
  *
+ * ## How to Use This Tool
+ *
+ * **CRITICAL**: This tool requires a `request` parameter containing the request object. All parameters must be passed inside a `request` object.
+ *
+ * **Parameter Format**:
+ * - Always wrap parameters in a `request` object: `{"request": {"portalID": "PZ-9999", "q": "loan information", "Dollar_lang": "en-US"}}`
+ * - Required parameters:
+ *   - `portalID` (string) - The portal ID (format: 2-4 letter prefix + dash + 4-15 digits, e.g., "PZ-9999")
+ *   - `q` (string) - The search query string
+ *   - `Dollar_lang` (string) - Language code (e.g., "en-US")
+ * - Optional parameters:
+ *   - `dollarFilterUserProfileID` (string) - User profile ID filter
+ *   - `dollarFilterTags` (object) - Object where keys are Category Tag IDs and values are arrays of Tag IDs
+ *   - `dollarFilterTopicIds` (array) - Array of topic IDs to filter by
+ *   - `AnswersRequest` (object) - Request body parameters:
+ *     - `eventId` (string, **required**) - Event ID
+ *     - `sessionId` (string, **required**) - Session ID
+ *     - `channel` (object, **optional**, recommended to omit) - Channel information. Omit unless specifically needed. If you receive a 400 error with channel, retry without it.
+ *     - `context` (object) - Additional context (companyContext, pageContext, userContext)
+ *
+ * **Example**: To get answers for query "loan information" from portal "PZ-9999", call with:
+ * ```json
+ * {"request": {"portalID": "PZ-9999", "q": "loan information", "Dollar_lang": "en-US", "AnswersRequest": {"eventId": "event-123", "sessionId": "session-456"}}}
+ * ```
+ *
+ * **Note**: The `channel` field in `AnswersRequest` is optional and recommended to omit unless specifically needed. The API works reliably without it.
+ *
+ * ## Displaying Results (MCP-Specific)
+ * **CRITICAL**: When this tool returns data successfully, you MUST display the results to the user in your response. Do not silently process the data - always show the user what was returned.
+ *
+ * **What to display:**
+ * - Display the `answer.answerValue` text prominently as the main answer to the user's query
+ * - Indicate the answer type (`answerType`: "certified" or "generative")
+ * - If `relevanceScore` is present, you may mention the confidence level
+ * - List all `references` (article IDs and names) that were used to generate the answer
+ * - Display `searchResults` showing related articles with their names, IDs, snippets, and relevance scores
+ * - Format the answer in a clear, readable way - this is the primary response the user is seeking
+ *
+ * **Example**: "Based on the knowledge base, here's the answer: [answerValue]. This answer was generated using information from: [list references]. Related articles: [list search results]..."
+ *
  * ## Prerequisites
  * - Requires a valid portal ID. If you don't have the portal ID, first call 'get-portals' to get available portals.
- * - Portal ID format: 2-4 letter prefix + dash + 4-15 digits (e.g., "EB-123456789")
+ * - Portal ID format: 2-4 letter prefix + dash + 4-15 digits (e.g., "PROD-1004")
  *
  * ## Overview
  * The Answers API enables users to get the best answer for a user query. This API can return certified answers or generative answers along with search results, providing users with comprehensive responses to their questions.
  *
  * The API leverages AI capabilities to provide intelligent answers based on the knowledge base content, making it easier for users to find the information they need quickly and accurately.
- *
- * ## Request Body Notes
- * - **channel field**: Optional. **Recommended to omit** unless specifically needed. The API works reliably without it. If you receive a 400 Bad Request error when including channel, retry the request without the channel field.
- * - **Required fields**: eventId and sessionId are required in the request body.
  */
-export function queryAnswers(
+export function getBestAnswer(
   client$: EgainMcpCore,
   request: GetBestAnswerRequest,
   options?: RequestOptions,
 ): APIPromise<
   Result<
-    GetBestAnswerResponse,
+    AnswersResponse,
     | APIError
     | SDKValidationError
     | UnexpectedClientError
@@ -77,7 +115,7 @@ async function $do(
 ): Promise<
   [
     Result<
-      GetBestAnswerResponse,
+      AnswersResponse,
       | APIError
       | SDKValidationError
       | UnexpectedClientError
@@ -175,7 +213,7 @@ async function $do(
   };
 
   const [result$] = await M.match<
-    GetBestAnswerResponse,
+    AnswersResponse,
     | APIError
     | SDKValidationError
     | UnexpectedClientError
@@ -184,9 +222,9 @@ async function $do(
     | RequestTimeoutError
     | ConnectionError
   >(
-    M.json(200, GetBestAnswerResponse$zodSchema, { key: "AnswersResponse" }),
-    M.nil(400, GetBestAnswerResponse$zodSchema),
-    M.nil(500, GetBestAnswerResponse$zodSchema),
+    M.json(200, AnswersResponse$zodSchema, { key: "AnswersResponse" }),
+    M.nil(400, AnswersResponse$zodSchema),
+    M.nil(500, AnswersResponse$zodSchema),
   )(response, req$, { extraFields: responseFields$ });
 
   return [result$, { status: "complete", request: req$, response }];

package/src/funcs/{getPortals.ts → getMyPortals.ts}

@@ -35,13 +35,43 @@ import { Result } from "../types/fp.js";
  * Get All Portals Accessible to User
  *
  * ## Overview
- * The Get All Portals Accessible to User API allows a user to fetch all portals accessible to the user across all departments.
+ * Retrieves the list of portals available to the authenticated user or application. Each portal contains a readable portal ID that is required by almost all other Portal Manager APIs.
+ *
  * - If no access tags are specified for a portal, any user can access the portal.
  * - If access tags are specified for a portal, users with a user profile that allows access can access the portal. For users with multiple user profiles, the user profile that allows access does not need to be the active user profile.
  * - Global users (partition) cannot be assigned user profiles; their access is limited to portals without access restrictions.
  * - The only articles returned are associated to an Article type when the parameter “Include in browse on portals” is set to "Yes".
  * - When the `shortUrlTemplate` query parameter is provided, the API filters accessible portals according to the specified language and template name. A portal short URL specific to the `shortUrlTemplate` value is returned in the response when available. If there is no short URL for a language, the portal object returns an empty `shortURL` field.
  *
+ * ## Prerequisites
+ * Authentication is required. No portal ID is needed for this call. This is typically the first API you should call before using any other tool.
+ *
+ * ## How to Use This Tool
+ * - Call this endpoint to discover which portals you have access to. Use the returned portal IDs as inputs to Retrieve, Answers, Search, Article, and Suggestion APIs.
+ *
+ * ## Parameter Requirements
+ * This tool requires **both** a query language parameter **and** an HTTP language header. An empty request object is **invalid** and MUST NOT be used.
+ *
+ * ### Required (both MUST be provided)
+ * - `Dollar_lang` (string, default: "en-US") - Language code
+ * - `Accept-Language` (string, default: "en-US") - Accept-Language header value
+ *
+ * Both parameters **MUST** be present on every invocation.
+ * If either parameter is missing, the request is invalid.
+ *
+ * #### Optional
+ *
+ * - `Dollar_pagenum` — Page number to retrieve (defaults to `1` if omitted)
+ * - `Dollar_pagesize` — Number of items per page (server default applied if omitted)
+ *
+ * **Example**: To get all portals accessible to the user, call with:
+ * ```json
+ * {"request": {"Dollar_lang": "en-US", "Accept-Language": "en-US"}}
+ * ```
+ *
+ * ## Overview
+ * The Get All Portals Accessible to User API allows a user to fetch all portals accessible to the user across all departments.
+ *
  * ## Pagination behavior (CRITICAL for AI assistants)
  *
  * **IMPORTANT**: This endpoint is paginated. When searching for a portal by name or listing portals, you MUST automatically fetch ALL pages before concluding that a portal doesn't exist.
@@ -81,8 +111,11 @@ import { Result } from "../types/fp.js";
  * - Search the complete merged list before concluding the portal doesn't exist
  *
  * This ensures reliable portal name-to-ID resolution and prevents false "not found" errors.
+ *
+ * ## Displaying Results (MCP-Specific)
+ * Always display the list of portals returned. Show portal name, portal ID, and any descriptive metadata. If multiple portals exist, prompt the user to select one for subsequent calls.
  */
-export function getPortals(
+export function getMyPortals(
   client$: EgainMcpCore,
   request: GetMyPortalsRequest,
   options?: RequestOptions,

package/src/funcs/getPopularArticles.ts

@@ -3,7 +3,7 @@
  */
 
 import { EgainMcpCore } from "../core.js";
-import { encodeFormQuery, encodeSimple } from "../lib/encodings.js";
+import { encodeFormQuery, encodeSimple, queryJoin } from "../lib/encodings.js";
 import * as M from "../lib/matchers.js";
 import { compactMap } from "../lib/primitives.js";
 import { safeParse } from "../lib/schemas.js";
@@ -34,6 +34,45 @@ import { Result } from "../types/fp.js";
  * @remarks
  * Get Popular Articles
  *
+ * ## How to Use This Tool
+ *
+ * **CRITICAL**: This tool requires a `request` parameter containing the request object. All parameters must be passed inside a `request` object.
+ *
+ * **Parameter Format**:
+ * - Always wrap parameters in a `request` object: `{"request": {"portalID": "PZ-9999"}}`
+ * - Required parameter:
+ *   - `portalID` (string) - The portal ID (format: 2-4 letter prefix + dash + 4-15 digits, e.g., "PZ-9999")
+ *   - `acceptLanguage` (string, default: "en-US") - Accept-Language header value
+ * - Optional parameters:
+ *   - `Dollar_lang` (string, default: "en-US") - Language code
+ *   - `Dollar_pagenum` (number, default: 1) - Page number for pagination
+ *   - `Dollar_pagesize` (number, default: 10) - Number of results per page
+ *   - `dollarFilterTopicId` (string) - Filter by topic ID
+ *   - `dollarFilterTags` (string) - Comma-separated list of Tag/Tag Group IDs
+ *
+ * **Example**: To get popular articles from portal "PZ-9999", call with:
+ * ```json
+ * {"request": {"portalID": "PZ-9999"}}
+ * ```
+ *
+ * **Example with optional parameters**:
+ * ```json
+ * {"request": {"portalID": "PZ-9999", "Dollar_lang": "en-US", "Dollar_pagesize": 20}}
+ * ```
+ *
+ * ## Displaying Results (MCP-Specific)
+ * **CRITICAL**: When this tool returns data successfully, you MUST display the popular articles to the user in your response. Do not silently process the data - always show the user what was returned.
+ *
+ * **What to display:**
+ * - Display all popular articles with their names and IDs
+ * - Show article summaries or descriptions when available
+ * - Display metadata such as `articleType`, `createdDate`, `modifiedDate`
+ * - Show `imageURL` if available (mention thumbnail availability)
+ * - Include `paginationInfo` if pagination is used
+ * - Format articles in a numbered or bulleted list
+ *
+ * **Example**: "Here are the most popular articles: 1) [Article Name] (ID: PROD-123) - [summary]..."
+ *
  * ## Prerequisites
  * - Requires a valid portal ID. If you don't have the portal ID, first call 'get-portals' to get available portals.
  * - Portal ID format: 2-4 letter prefix + dash + 4-15 digits (e.g., "EB-123456789")
@@ -105,13 +144,19 @@ async function $do(
   const path$ = pathToFunc("/portals/{portalID}/populararticles")(
     pathParams$,
   );
-  const query$ = encodeFormQuery({
-    "$filter[tags]": payload$.dollarFilterTags,
-    "$filter[topicId]": payload$.dollarFilterTopicId,
-    "$lang": payload$.Dollar_lang,
-    "$pagenum": payload$.Dollar_pagenum,
-    "$pagesize": payload$.Dollar_pagesize,
-  });
+  const query$ = queryJoin(
+    encodeFormQuery({
+      "articleResultAdditionalAttributes":
+        payload$.articleResultAdditionalAttributes,
+    }, { explode: false }),
+    encodeFormQuery({
+      "$filter[tags]": payload$.dollarFilterTags,
+      "$filter[topicId]": payload$.dollarFilterTopicId,
+      "$lang": payload$.Dollar_lang,
+      "$pagenum": payload$.Dollar_pagenum,
+      "$pagesize": payload$.Dollar_pagesize,
+    }),
+  );
 
   const headers$ = new Headers(compactMap({
     Accept: "application/json",
@@ -120,6 +165,21 @@ async function $do(
       payload$.acceptLanguage,
       { explode: false, charEncoding: "none" },
     ),
+    "x-egain-activity-id": encodeSimple(
+      "x-egain-activity-id",
+      payload$.xEgainActivityId,
+      { explode: false, charEncoding: "none" },
+    ),
+    "x-ext-integration-id": encodeSimple(
+      "x-ext-integration-id",
+      payload$.xExtIntegrationId,
+      { explode: false, charEncoding: "none" },
+    ),
+    "x-ext-interaction-id": encodeSimple(
+      "x-ext-interaction-id",
+      payload$.xExtInteractionId,
+      { explode: false, charEncoding: "none" },
+    ),
   }));
   const securityInput = await extractSecurity(client$._options.security);
   const requestSecurity = resolveGlobalSecurity(securityInput);

package/src/funcs/makeSuggestion.ts

@@ -2,6 +2,7 @@
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
  */
 
+import * as z from "zod";
 import { EgainMcpCore } from "../core.js";
 import { encodeJSON, encodeSimple } from "../lib/encodings.js";
 import * as M from "../lib/matchers.js";
@@ -22,9 +23,8 @@ import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
 import {
   MakeSuggestionRequest,
   MakeSuggestionRequest$zodSchema,
-  MakeSuggestionResponse,
-  MakeSuggestionResponse$zodSchema,
 } from "../models/makesuggestionop.js";
+import { WSErrorCommon, WSErrorCommon$zodSchema } from "../models/wserrorcommon.js";
 import { APICall, APIPromise } from "../types/async.js";
 import { Result } from "../types/fp.js";
 
@@ -34,6 +34,49 @@ import { Result } from "../types/fp.js";
  * @remarks
  * Make a Suggestion
  *
+ * ## How to Use This Tool
+ *
+ * **CRITICAL**: This tool requires a `request` parameter containing the request object. All parameters must be passed inside a `request` object.
+ *
+ * **Parameter Format**:
+ * - Always wrap parameters in a `request` object: `{"request": {"portalID": "PZ-9999", "CreateSuggestion": {...}}}`
+ * - Required parameters:
+ *   - `portalID` (string) - The portal ID (format: 2-4 letter prefix + dash + 4-15 digits, e.g., "PZ-9999")
+ *   - `CreateSuggestion` (object) - The suggestion object with:
+ *     - `name` (string, **required**) - Name/title of the suggestion
+ *     - `content` (string, **required**) - Content/description of the suggestion
+ *     - `language` (object, **required**) - Language object with `code` property (e.g., {"code": "en-US"})
+ *   - `acceptLanguage` (string, default: "en-US") - Accept-Language header value
+ *
+ * - Optional parameters:
+ *   - `CreateSuggestion` additional optional fields:
+ *     - `description` (string) - Additional description
+ *     - `feedbackArticle` (object) - Article ID object if providing feedback on existing article: `{"id": "PROD-2996"}`
+ *     - `attachments` (object) - Attachments object
+ *     - `customAttributes` (array) - Custom attributes array
+ *
+ * **Example**: To create a suggestion in portal "PZ-9999", call with:
+ * ```json
+ * {"request": {"portalID": "PZ-9999", "CreateSuggestion": {"name": "New Article Request", "content": "Please add information about loan rates", "language": {"code": "en-US"}}}}
+ * ```
+ *
+ * **Example with feedback on existing article**:
+ * ```json
+ * {"request": {"portalID": "PZ-9999", "CreateSuggestion": {"name": "Article Feedback", "content": "This article needs updating", "language": {"code": "en-US"}, "feedbackArticle": {"id": "PROD-2996"}}}}
+ * ```
+ *
+ * ## Displaying Results (MCP-Specific)
+ * **CRITICAL**: When this tool returns data successfully, you MUST display the suggestion creation result to the user in your response. Do not silently process the data - always show the user what was returned.
+ *
+ * **What to display:**
+ * - Confirm that the suggestion was successfully created
+ * - Display the suggestion `id` if returned in the response
+ * - Show the suggestion `name` and `content` that was submitted
+ * - If an error occurs, display the error message clearly
+ * - Provide confirmation message to the user
+ *
+ * **Example**: "Your suggestion '[Suggestion Name]' has been successfully submitted. Suggestion ID: [id]..."
+ *
  * ## Prerequisites
  * - Requires a valid portal ID. If you don't have the portal ID, first call 'get-portals' to get available portals.
  * - Portal ID format: 2-4 letter prefix + dash + 4-15 digits (e.g., "EB-123456789")
@@ -49,7 +92,7 @@ export function makeSuggestion(
   options?: RequestOptions,
 ): APIPromise<
   Result<
-    MakeSuggestionResponse,
+    Record<string, never> | WSErrorCommon,
     | APIError
     | SDKValidationError
     | UnexpectedClientError
@@ -73,7 +116,7 @@ async function $do(
 ): Promise<
   [
     Result<
-      MakeSuggestionResponse,
+      Record<string, never> | WSErrorCommon,
       | APIError
       | SDKValidationError
       | UnexpectedClientError
@@ -116,6 +159,21 @@ async function $do(
       payload$.acceptLanguage,
       { explode: false, charEncoding: "none" },
     ),
+    "x-egain-activity-id": encodeSimple(
+      "x-egain-activity-id",
+      payload$.xEgainActivityId,
+      { explode: false, charEncoding: "none" },
+    ),
+    "x-ext-integration-id": encodeSimple(
+      "x-ext-integration-id",
+      payload$.xExtIntegrationId,
+      { explode: false, charEncoding: "none" },
+    ),
+    "x-ext-interaction-id": encodeSimple(
+      "x-ext-interaction-id",
+      payload$.xExtInteractionId,
+      { explode: false, charEncoding: "none" },
+    ),
   }));
   const securityInput = await extractSecurity(client$._options.security);
   const requestSecurity = resolveGlobalSecurity(securityInput);
@@ -170,7 +228,7 @@ async function $do(
   };
 
   const [result$] = await M.match<
-    MakeSuggestionResponse,
+    Record<string, never> | WSErrorCommon,
     | APIError
     | SDKValidationError
     | UnexpectedClientError
@@ -179,12 +237,12 @@ async function $do(
     | RequestTimeoutError
     | ConnectionError
   >(
-    M.nil(201, MakeSuggestionResponse$zodSchema),
-    M.json([400, 401, 403, 404, 406], MakeSuggestionResponse$zodSchema, {
+    M.nil(201, z.object({})),
+    M.json([400, 401, 403, 404, 406], WSErrorCommon$zodSchema, {
       key: "WSErrorCommon",
     }),
-    M.nil(415, MakeSuggestionResponse$zodSchema),
-    M.json(500, MakeSuggestionResponse$zodSchema, { key: "WSErrorCommon" }),
+    M.nil(415, WSErrorCommon$zodSchema),
+    M.json(500, WSErrorCommon$zodSchema, { key: "WSErrorCommon" }),
   )(response, req$, { extraFields: responseFields$ });
 
   return [result$, { status: "complete", request: req$, response }];