docs: enhance API parameter descriptions

Updated descriptions in the Zendesk tools to provide clearer guidance on parameter usage, limits, and expected values, ensuring developers have precise documentation for API interactions.

Author: winromulus

src/ES.FX.Zendesk.MCP.Host/Hosting/McpServerHostingExtensions.cs

@@ -67,7 +67,7 @@ public static McpOptions GetMcpOptions(this IHostApplicationBuilder builder)
     /// <returns>The builder, for chaining.</returns>
     public static IMcpServerBuilder WithToolsInArea<[DynamicallyAccessedMembers(
             DynamicallyAccessedMemberTypes.PublicMethods | DynamicallyAccessedMemberTypes.NonPublicMethods)]
-        TTool>(this IMcpServerBuilder builder, ZendeskToolAreaGate gate)
+    TTool>(this IMcpServerBuilder builder, ZendeskToolAreaGate gate)
         => gate.Allows<TTool>() ? builder.WithTools<TTool>() : builder;
 
     /// <summary>

src/ES.FX.Zendesk.MCP.Host/Tools/ZendeskArticleTools.cs

@@ -18,14 +18,18 @@ public sealed class ZendeskArticleTools(IZendeskClient zendeskApiClient)
         "primary way to find an existing answer to resolve or deflect a ticket. Returns relevance-ranked results " +
         "with snippets; call articles_get for the full article body. Read-only.")]
     public Task<ZendeskArticleSearchResults> Search(
-        [Description("The customer's question or keywords to search for.")]
+        [Description(
+            "The customer's question or keywords to search for; matches article title, body, and labels. " +
+            "Wrap a phrase in double quotes for an exact-phrase match (e.g. \"carrot potato\"). Required — " +
+            "this search cannot run on locale alone.")]
         string query,
-        [Description("Optional locale to scope results, e.g. \"en-us\".")]
+        [Description("Optional locale to scope results; a valid enabled locale (e.g. \"en-us\"), or \"*\" to search all locales.")]
         string? locale = null,
         [Description("The 1-based page number (optional).")]
         int? page = null,
         [Description(
-            "Results per page (default 25, max 100). The total is in 'count'; a non-null 'next_page' means more pages.")]
+            "Results per page, an integer (min 1, max 100); default 25. Results are relevance-ranked by default. " +
+            "The total is in 'count'; a non-null 'next_page' means more pages.")]
         int? perPage = 25,
         CancellationToken cancellationToken = default)
         => ZendeskToolInvoker.InvokeAsync(() =>
@@ -53,11 +57,13 @@ public Task<ZendeskArticlesResult> List(
         string? locale = null,
         [Description("When set, lists only the articles in this section (see articles_sections_list).")]
         long? sectionId = null,
-        [Description("The cursor page size (max 100).")]
+        [Description("The cursor page size; the Help Center API caps at 100 records per page (default 30).")]
         int? pageSize = null,
         [Description("The cursor from the previous page's meta.after_cursor (optional).")]
         string? afterCursor = null,
-        [Description("Sideloads resolved inline as sibling arrays: \"users\", \"sections\", \"categories\".")]
+        [Description(
+            "Sideloads resolved inline as sibling arrays. Allowed values: \"users\" (the author), \"sections\", " +
+            "\"categories\", and \"translations\" (embedded within the article). Only these four are valid.")]
         string[]? include = null,
         CancellationToken cancellationToken = default)
         => ZendeskToolInvoker.InvokeAsync(() =>
@@ -78,7 +84,8 @@ public Task<ZendeskHelpCenterSectionsResult> Sections(
         [Description("The 1-based page number (optional).")]
         int? page = null,
         [Description(
-            "Results per page (default 100, max 100). The total is in 'count'; a non-null 'next_page' means more pages.")]
+            "Results per page; offset pagination caps at 100 records per page (default 100). The total is in " +
+            "'count'; a non-null 'next_page' means more pages.")]
         int? perPage = 100,
         CancellationToken cancellationToken = default)
         => ZendeskToolInvoker.InvokeAsync(() =>
@@ -109,7 +116,8 @@ public Task<ZendeskHelpCenterCategoriesResult> Categories(
         [Description("The 1-based page number (optional).")]
         int? page = null,
         [Description(
-            "Results per page (default 100, max 100). The total is in 'count'; a non-null 'next_page' means more pages.")]
+            "Results per page; offset pagination caps at 100 records per page (default 100). The total is in " +
+            "'count'; a non-null 'next_page' means more pages.")]
         int? perPage = 100,
         CancellationToken cancellationToken = default)
         => ZendeskToolInvoker.InvokeAsync(() =>

src/ES.FX.Zendesk.MCP.Host/Tools/ZendeskAttachmentTools.cs

@@ -25,7 +25,9 @@ public sealed class ZendeskAttachmentTools(IZendeskClient zendeskApiClient)
         "('encoding':'base64'). 'truncated':true means the file exceeded the size cap and was cut short. Use to read " +
         "a customer's error log, CSV export, or config a screenshot won't convey. Read-only.")]
     public Task<ZendeskAttachmentContent> Read(
-        [Description("The numeric attachment id (from a comment's attachments[].id).")]
+        [Description(
+            "The numeric attachment id. It is not directly listable — obtain it from a ticket comment's " +
+            "attachments[].id (list the ticket's comments first).")]
         long id,
         CancellationToken cancellationToken)
         => ZendeskToolInvoker.InvokeAsync(() =>

src/ES.FX.Zendesk.MCP.Host/Tools/ZendeskBrandTools.cs

@@ -14,11 +14,12 @@ public sealed class ZendeskBrandTools(IZendeskClient zendeskApiClient)
     /// <summary>Lists Zendesk brands.</summary>
     [McpServerTool(Name = "brands_list", ReadOnly = true, OpenWorld = true)]
     [Description(
-        "Lists Zendesk brands — decodes the brand_id carried on tickets in multibrand accounts. Cursor " +
-        "pagination: pass pageSize/afterCursor; the result's meta.has_more/meta.after_cursor drive continuation. " +
-        "Read-only.")]
+        "Lists Zendesk brands — decodes the brand_id carried on tickets in multibrand accounts. Requires admin, or " +
+        "an agent with the assign_tickets_to_any_brand permission, to list all brands; agents without it see only " +
+        "brands they are members of. Cursor pagination: pass pageSize/afterCursor; the result's " +
+        "meta.has_more/meta.after_cursor drive continuation. Read-only.")]
     public Task<ZendeskBrandsResult> List(
-        [Description("The cursor page size (optional, max 100).")]
+        [Description("The cursor page size (optional; Zendesk limits most endpoints to a max of 100, defaulting to 100).")]
         int? pageSize = null,
         [Description("The cursor from the previous page's meta.after_cursor (omit for the first page).")]
         string? afterCursor = null,

src/ES.FX.Zendesk.MCP.Host/Tools/ZendeskGroupTools.cs

@@ -23,8 +23,10 @@ public Task<ZendeskGroupsResult> List(
             "Results per page (default 100, max 100). The total is in 'count'; a non-null 'next_page' means more pages.")]
         int? perPage = 100,
         [Description(
-            "Sideloads to resolve inline as sibling arrays: \"users\" returns each group's members in the same " +
-            "roundtrip, avoiding per-group groups_memberships_list calls.")]
+            "Comma-separated sideloads to resolve inline as sibling arrays: \"users\" returns each group's members " +
+            "in the same roundtrip, avoiding per-group groups_memberships_list calls. Documented values are " +
+            "\"users\" and \"group_settings\"; there is no closed enum for group sideloads, so unknown values are " +
+            "silently ignored.")]
         string[]? include = null,
         CancellationToken cancellationToken = default)
         => ZendeskToolInvoker.InvokeAsync(() =>
@@ -56,7 +58,8 @@ public Task<ZendeskGroupMembershipsResult> Memberships(
             "Results per page (default 100, max 100). The total is in 'count'; a non-null 'next_page' means more pages.")]
         int? perPage = 100,
         [Description(
-            "Sideloads to resolve ids inline in one call: any of \"users\", \"groups\". Returned as sibling arrays.")]
+            "Comma-separated sideloads to resolve ids inline in one call; valid values are \"users\" and " +
+            "\"groups\". Returned as sibling arrays.")]
         string[]? include = null,
         CancellationToken cancellationToken = default)
         => ZendeskToolInvoker.InvokeAsync(() =>
@@ -82,8 +85,9 @@ public Task<ZendeskGroupsResult> Assignable(
     /// <summary>Returns the approximate group count.</summary>
     [McpServerTool(Name = "groups_count", ReadOnly = true, OpenWorld = true)]
     [Description(
-        "Returns the number of Zendesk groups. The value is cached and approximate above 100,000 (refreshed roughly " +
-        "every 24 hours; 'refreshed_at' reports the cache time and may be null while Zendesk recomputes). Read-only.")]
+        "Returns the number of Zendesk groups. The value is cached and approximate above 100,000: it is refreshed " +
+        "only every ~24 hours and 'value' is capped at 100,000 until that refresh completes ('refreshed_at' reports " +
+        "the cache time and may be null while Zendesk recomputes). Read-only.")]
     public Task<ZendeskCount> Count(CancellationToken cancellationToken)
         => ZendeskToolInvoker.InvokeAsync(() => zendeskApiClient.Groups.CountAsync(cancellationToken));
 

src/ES.FX.Zendesk.MCP.Host/Tools/ZendeskGroupWriteTools.cs

@@ -74,7 +74,7 @@ public Task<object> Delete(
         "directly to the agent assume this group. Returns the created membership. Write operation — honors the " +
         "server execution mode: rejected in read-only mode, simulated (no changes made) in dry-run mode.")]
     public Task<object> MembershipsCreate(
-        [Description("The numeric Zendesk user id of the agent.")]
+        [Description("The numeric Zendesk user id of the agent (must be an agent, not an end user).")]
         long userId,
         [Description("The numeric Zendesk group id.")]
         long groupId,
@@ -97,7 +97,8 @@ public Task<object> MembershipsCreate(
         "Returns a job_status — poll job_statuses_get until completed. Write operation — honors the " +
         "server execution mode: rejected in read-only mode, simulated (no changes made) in dry-run mode.")]
     public Task<object> MembershipsCreateMany(
-        [Description("The memberships to create (1-100). Each item needs 'user_id' and 'group_id'.")]
+        [Description(
+            "The memberships to create (1-100). Each item needs an agent 'user_id' and a 'group_id'.")]
         ZendeskGroupMembership[] memberships,
         CancellationToken cancellationToken)
         => ZendeskToolInvoker.InvokeWriteAsync(executionMode,
@@ -115,7 +116,8 @@ public Task<object> MembershipsCreateMany(
         "tickets in that group. Returns a completion acknowledgement. Write operation — honors the server " +
         "execution mode: rejected in read-only mode, simulated (no changes made) in dry-run mode.")]
     public Task<object> MembershipsDelete(
-        [Description("The numeric group membership id.")]
+        [Description(
+            "The numeric group membership id (not a user or group id — get it from groups_memberships_list).")]
         long membershipId,
         CancellationToken cancellationToken)
         => ZendeskToolInvoker.InvokeWriteAsync(executionMode,
@@ -128,11 +130,14 @@ public Task<object> MembershipsDelete(
     [McpServerTool(Name = "groups_memberships_delete_many", ReadOnly = false, Destructive = true,
         Idempotent = false, OpenWorld = true)]
     [Description(
-        "Removes up to 100 Zendesk group memberships by their MEMBERSHIP ids. Returns a job_status — poll " +
-        "job_statuses_get until completed. Write operation — honors the server execution mode: rejected " +
-        "in read-only mode, simulated (no changes made) in dry-run mode.")]
+        "Removes up to 100 Zendesk group memberships by their MEMBERSHIP ids. Side effect: Zendesk schedules a job " +
+        "un-assigning the agents' working tickets in those groups. Returns a job_status — poll job_statuses_get " +
+        "until completed. Write operation — honors the server execution mode: rejected in read-only mode, " +
+        "simulated (no changes made) in dry-run mode.")]
     public Task<object> MembershipsDeleteMany(
-        [Description("The numeric group membership ids to remove (1-100).")]
+        [Description(
+            "The numeric group membership ids to remove (1-100; not user or group ids — get them from " +
+            "groups_memberships_list).")]
         long[] membershipIds,
         CancellationToken cancellationToken)
         => ZendeskToolInvoker.InvokeWriteAsync(executionMode,
@@ -151,7 +156,9 @@ public Task<object> MembershipsDeleteMany(
     public Task<object> MembershipsMakeDefault(
         [Description("The numeric Zendesk user id owning the membership.")]
         long userId,
-        [Description("The numeric group membership id to make default.")]
+        [Description(
+            "The numeric group membership id to make default (not a user or group id; must belong to the given " +
+            "userId).")]
         long membershipId,
         CancellationToken cancellationToken)
         => ZendeskToolInvoker.InvokeWriteAsync(executionMode,

src/ES.FX.Zendesk.MCP.Host/Tools/ZendeskJobStatusTools.cs

@@ -15,9 +15,10 @@ public sealed class ZendeskJobStatusTools(IZendeskClient zendeskApiClient)
     /// <summary>Lists recent Zendesk job statuses.</summary>
     [McpServerTool(Name = "job_statuses_list", ReadOnly = true, OpenWorld = true)]
     [Description(
-        "Lists recent Zendesk job statuses (the async jobs returned by bulk write tools). Zendesk retains job " +
-        "status data for roughly one day. Cursor pagination: pass pageSize/afterCursor; the result's " +
-        "meta.has_more/meta.after_cursor drive continuation. Read-only.")]
+        "Lists recent Zendesk job statuses (the async jobs returned by bulk write tools), sorted first by " +
+        "completion date, then by creation date, in descending order. Zendesk retains job status data for roughly " +
+        "one day. Cursor pagination only: pass pageSize/afterCursor; the result's meta.has_more/meta.after_cursor " +
+        "drive continuation. Read-only.")]
     public Task<ZendeskJobStatusesResult> List(
         [Description("The cursor page size (optional, max 100).")]
         int? pageSize = null,
@@ -35,7 +36,9 @@ public Task<ZendeskJobStatusesResult> List(
         "job_status) until 'status' is 'completed' or 'failed'; 'results' then carries the per-item outcomes. " +
         "Job status data is retained for roughly one day. Read-only.")]
     public Task<ZendeskJobStatus> Read(
-        [Description("The job status id (a string, returned by the bulk operation that started the job).")]
+        [Description(
+            "The job status id — an opaque string (not numeric), returned by the bulk operation that started the " +
+            "job.")]
         string id,
         CancellationToken cancellationToken)
         => ZendeskToolInvoker.InvokeAsync(() => zendeskApiClient.JobStatuses.GetByIdAsync(id, cancellationToken));
@@ -46,7 +49,7 @@ public Task<ZendeskJobStatus> Read(
         "Returns up to 100 Zendesk job statuses in one request (more than 100 ids is rejected by design). Use to " +
         "poll several bulk jobs at once instead of calling job_statuses_get repeatedly. Read-only.")]
     public Task<ZendeskJobStatusesResult> ReadMany(
-        [Description("The job status ids (strings, at most 100).")]
+        [Description("The job status ids — opaque strings (not numeric); at most 100.")]
         string[] ids,
         CancellationToken cancellationToken)
         => ZendeskToolInvoker.InvokeAsync(() => zendeskApiClient.JobStatuses.GetManyAsync(ids, cancellationToken));

src/ES.FX.Zendesk.MCP.Host/Tools/ZendeskMacroTools.cs

@@ -21,7 +21,8 @@ public Task<ZendeskMacrosResult> List(
         [Description("The 1-based page number (optional).")]
         int? page = null,
         [Description(
-            "Results per page (default 25, max 100). The total is in 'count'; a non-null 'next_page' means more pages.")]
+            "Results per page (default 25, max 100 — Zendesk clamps higher values to 100). The total is in 'count'; " +
+            "a non-null 'next_page' means more pages.")]
         int? perPage = 25,
         CancellationToken cancellationToken = default)
         => ZendeskToolInvoker.InvokeAsync(() => zendeskApiClient.Macros.ListAsync(page, perPage, cancellationToken));
@@ -35,7 +36,8 @@ public Task<ZendeskMacrosResult> ListActive(
         [Description("The 1-based page number (optional).")]
         int? page = null,
         [Description(
-            "Results per page (default 25, max 100). The total is in 'count'; a non-null 'next_page' means more pages.")]
+            "Results per page (default 25, max 100 — Zendesk clamps higher values to 100). The total is in 'count'; " +
+            "a non-null 'next_page' means more pages.")]
         int? perPage = 25,
         CancellationToken cancellationToken = default)
         => ZendeskToolInvoker.InvokeAsync(() =>