@fruggr/zendesk-mcp-server 2.5.0 → 2.6.0

package/dist/index.js

@@ -960,6 +960,8 @@ const formatList = (items, formatter, meta) => {
 };
 //#endregion
 //#region src/utils/pagination.ts
+const PER_PAGE_DESC = "Number of results per page for offset pagination (1-100). Pair with `page` to walk large result sets; the response header reports the total count and whether more pages remain.";
+const PAGE_DESC = "1-based page number for offset pagination. Increment it while keeping `per_page` fixed to fetch subsequent pages; page 1 is the first page.";
 const buildCursorParams = (pageSize, cursor) => {
 	const params = { "page[size]": String(pageSize) };
 	if (cursor) params["page[after]"] = cursor;
@@ -1207,6 +1209,7 @@ const markdownToHtml = (markdown) => {
 };
 //#endregion
 //#region src/tools/help-center.ts
+const ARTICLE_ID_DESC = "Article ID — the numeric id of the Help Center article. Obtain it from list_articles or search_articles.";
 const largeArticleHint = (body, sectionCount) => {
 	if (body.length < 3e3 && sectionCount < 4) return null;
 	return [
@@ -1226,10 +1229,10 @@ const createHelpCenterTools = (ctx) => {
 			title: "Search Help Center Articles",
 			description: "Full-text search across Help Center articles (metadata only, no body). Use get_article for full content. Supports locale filtering. Returns total count.",
 			inputSchema: z.object({
-				query: z.string().min(1).describe("Search query"),
+				query: z.string().min(1).describe("Full-text query matched against article titles and body. Plain keywords; combine with the locale filter to scope to one language."),
 				locale: z.string().optional().describe("Filter by locale (e.g., \"en-us\", \"fr\")"),
-				per_page: z.number().int().min(1).max(100).default(100).describe("Results per page"),
-				page: z.number().int().min(1).default(1).describe("Page number")
+				per_page: z.number().int().min(1).max(100).default(100).describe(PER_PAGE_DESC),
+				page: z.number().int().min(1).default(1).describe(PAGE_DESC)
 			}),
 			annotations: {
 				readOnlyHint: true,
@@ -1259,7 +1262,7 @@ const createHelpCenterTools = (ctx) => {
 			title: "Get Help Center Article",
 			description: "Retrieve an article by ID with full body content. For large articles, prefer get_article_outline + get_article_section to save tokens. Optionally specify locale for a translated version. Returns body (HTML), metadata, source_locale, and list of available translations.",
 			inputSchema: z.object({
-				article_id: z.number().int().describe("Article ID"),
+				article_id: z.number().int().describe(ARTICLE_ID_DESC),
 				locale: z.string().optional().describe("Locale for translated version")
 			}),
 			annotations: {
@@ -1341,8 +1344,8 @@ const createHelpCenterTools = (ctx) => {
 			title: "List Help Center Articles",
 			description: "List articles (metadata only, no body). Use get_article for full content. Optionally filter by section ID and locale. Supports sort_by (\"title\", \"created_at\", \"updated_at\") and include_translations: true to show available translation locales per article. Note: include_translations must be re-sent on each paginated request.",
 			inputSchema: z.object({
-				section_id: z.number().int().optional(),
-				locale: z.string().optional(),
+				section_id: z.number().int().optional().describe("Restrict the listing to one section (numeric id from list_sections). Omit to list articles across all sections."),
+				locale: z.string().optional().describe("Restrict to a single locale, e.g. \"en-us\" or \"fr\". Omit for the default locale."),
 				page_size: z.number().int().min(1).max(100).default(100).describe("Articles per page (1-100, default 100)."),
 				cursor: z.string().optional().describe("Pagination cursor from a previous response; omit for the first page."),
 				sort_by: z.enum([
@@ -1350,8 +1353,8 @@ const createHelpCenterTools = (ctx) => {
 					"updated_at",
 					"position",
 					"title"
-				]).default("position").describe("Sort field"),
-				sort_order: z.enum(["asc", "desc"]).default("asc").describe("Sort direction"),
+				]).default("position").describe("Field to sort by; \"position\" (the default) is the manual order set in Guide."),
+				sort_order: z.enum(["asc", "desc"]).default("asc").describe("Sort direction: ascending or descending."),
 				include_translations: z.boolean().default(false).describe("Include available translation locales per article (causes 1 extra API call per article)")
 			}),
 			annotations: {
@@ -1391,7 +1394,7 @@ const createHelpCenterTools = (ctx) => {
 			readOnly: true,
 			title: "List Article Translations",
 			description: "List all available translations for an article (metadata only, no body: locale, title, draft, updated_at). Use get_article with locale for full translated content.",
-			inputSchema: z.object({ article_id: z.number().int().describe("Article ID") }),
+			inputSchema: z.object({ article_id: z.number().int().describe(ARTICLE_ID_DESC) }),
 			annotations: {
 				readOnlyHint: true,
 				destructiveHint: false,
@@ -1447,11 +1450,11 @@ const createHelpCenterTools = (ctx) => {
 			title: "Update Article Translation",
 			description: "Update article content (title, body) in a specific locale. For targeted edits on one or a few sections, prefer update_article_section — this tool replaces the FULL body and re-sends the entire article on each write. Use the article's source_locale (from get_article) for the default language, or another locale for translations.",
 			inputSchema: z.object({
-				article_id: z.number().int(),
-				locale: z.string(),
-				title: z.string().optional(),
-				body: z.string().optional(),
-				draft: z.boolean().optional()
+				article_id: z.number().int().describe("Article ID — the numeric id of the article whose translation to update. Obtain it from list_articles or search_articles."),
+				locale: z.string().describe("Locale of the translation to update, e.g. \"en-us\" or \"fr\". Use the source_locale (from get_article) to edit the default language."),
+				title: z.string().optional().describe("New title for this locale. Omit to leave the current title unchanged."),
+				body: z.string().optional().describe("New full body (HTML) for this locale. Replaces the entire body — for a single-section edit prefer update_article_section. Omit to leave the body unchanged."),
+				draft: z.boolean().optional().describe("When true, keeps this translation as a draft; when false, publishes it.")
 			}),
 			annotations: {
 				readOnlyHint: false,
@@ -1495,16 +1498,16 @@ const createHelpCenterTools = (ctx) => {
 			title: "Create Help Center Article",
 			description: "Create a new article in a section. The locale becomes the article's source_locale. Requires a permission_group_id (use list_permission_groups to find available IDs). To add content in other locales afterwards, use create_article_translation.",
 			inputSchema: z.object({
-				section_id: z.number().int(),
-				title: z.string().min(1),
-				body: z.string().min(1).describe("Article body (HTML)"),
+				section_id: z.number().int().describe("Section that will contain the article (numeric id from list_sections)."),
+				title: z.string().min(1).describe("Title of the new article, in its source locale."),
+				body: z.string().min(1).describe("Article body as HTML (this becomes the source-locale content)."),
 				permission_group_id: z.number().int().describe("Permission group ID (use list_permission_groups to find it)"),
 				user_segment_id: z.number().int().optional().describe("User segment ID for visibility (use list_user_segments to find it). Defaults to everyone."),
 				author_id: z.number().int().optional().describe("Author user ID. Defaults to the authenticated user."),
 				content_tag_ids: z.array(z.string()).optional().describe("Content tag IDs (use list_content_tags to find them)"),
-				locale: z.string().optional(),
-				draft: z.boolean().default(true),
-				promoted: z.boolean().default(false),
+				locale: z.string().optional().describe("Source locale for the article, e.g. \"en-us\" or \"fr\". Defaults to the Help Center's default locale; becomes the article's source_locale."),
+				draft: z.boolean().default(true).describe("When true (default), the article is created unpublished; set false to publish immediately."),
+				promoted: z.boolean().default(false).describe("When true, marks the article as promoted (featured) in its section. Defaults to false."),
 				label_names: z.array(z.string()).optional().describe("Label names for search ranking (use list_labels to see existing labels)")
 			}),
 			annotations: {
@@ -1529,15 +1532,15 @@ const createHelpCenterTools = (ctx) => {
 			title: "Update Help Center Article",
 			description: "Update article metadata only (draft, promoted, labels, tags, visibility, section, sort position, etc.). Does NOT update content (title, body) — use update_article_translation for that.",
 			inputSchema: z.object({
-				article_id: z.number().int(),
-				draft: z.boolean().optional(),
-				promoted: z.boolean().optional(),
-				label_names: z.array(z.string()).optional().describe("Label names for search ranking"),
-				content_tag_ids: z.array(z.string()).optional().describe("Content tag IDs"),
-				user_segment_id: z.number().int().optional().describe("User segment ID for visibility"),
-				author_id: z.number().int().optional().describe("Author user ID"),
-				permission_group_id: z.number().int().optional().describe("Permission group ID"),
-				section_id: z.number().int().optional(),
+				article_id: z.number().int().describe("Article ID — the numeric id of the article to update. Obtain it from list_articles or search_articles."),
+				draft: z.boolean().optional().describe("Set true to unpublish the article (revert to draft) or false to publish it."),
+				promoted: z.boolean().optional().describe("Set true to promote (feature) the article in its section, or false to unpromote it."),
+				label_names: z.array(z.string()).optional().describe("Label names for search ranking (use list_labels to see existing labels)."),
+				content_tag_ids: z.array(z.string()).optional().describe("Content tag ids to attach (use list_content_tags to find them)."),
+				user_segment_id: z.number().int().optional().describe("User segment that controls who can see the article (id from list_user_segments)."),
+				author_id: z.number().int().optional().describe("User id of the article author (from search_users)."),
+				permission_group_id: z.number().int().optional().describe("Guide permission group controlling who can edit (id from list_permission_groups)."),
+				section_id: z.number().int().optional().describe("Move the article to this section (numeric id from list_sections)."),
 				position: z.number().int().min(0).optional().describe("Sort position within the section (manual ordering only; 0 = first/top). New articles default to position 0. To move an article to the END of its section, set this to one more than the highest current position: read the highest position P from list_articles with sort_by=\"position\", sort_order=\"desc\", then set position = P + 1.")
 			}),
 			annotations: {
@@ -1652,9 +1655,14 @@ const createHelpCenterTools = (ctx) => {
 			},
 			handler: async (params) => {
 				const { article_id } = params;
+				const attachments = (await helpCenterGet(subdomain, await getToken(), `/articles/${article_id}/attachments`)).article_attachments ?? [];
+				if (attachments.length === 0) return { content: [{
+					type: "text",
+					text: `No attachments found on article #${article_id}.`
+				}] };
 				return { content: [{
 					type: "text",
-					text: formatList((await helpCenterGet(subdomain, await getToken(), `/articles/${article_id}/attachments`)).article_attachments ?? [], formatAttachment)
+					text: formatList(attachments, formatAttachment)
 				}] };
 			}
 		},
@@ -1665,7 +1673,7 @@ const createHelpCenterTools = (ctx) => {
 			title: "Get Article Outline",
 			description: "Return a compact outline of an article (list of sections delimited by h1/h2/h3, with word counts) for the given locale (defaults to source_locale). Includes available translations with their outdated status. Use get_article_section to fetch a specific section.",
 			inputSchema: z.object({
-				article_id: z.number().int().describe("Article ID"),
+				article_id: z.number().int().describe(ARTICLE_ID_DESC),
 				locale: z.string().optional().describe("Locale of the body to outline (defaults to article source_locale)")
 			}),
 			annotations: {
@@ -1706,7 +1714,7 @@ const createHelpCenterTools = (ctx) => {
 			title: "Get Article Section",
 			description: "Retrieve the content of a single section of an article in a given locale. Use get_article_outline first to discover section indexes. Default format=\"html\" for round-trip safety. Pass format=\"markdown\" only for human review — the Markdown representation is lossy on some structures (<pre> with <br>, tables with multi-<p> cells are kept as raw HTML to limit the damage, but do not round-trip markdown content back through update_article_section).",
 			inputSchema: z.object({
-				article_id: z.number().int().describe("Article ID"),
+				article_id: z.number().int().describe(ARTICLE_ID_DESC),
 				locale: z.string().describe("Locale of the body (e.g., \"en-us\", \"fr\")"),
 				section_index: z.number().int().min(0).describe("0-based index of the section (see get_article_outline)"),
 				format: z.enum(["html", "markdown"]).default("html").describe("Output format. \"html\" (default) is round-trip safe. \"markdown\" is lossy on some HTML structures — use only for human review, not before update_article_section.")
@@ -1742,7 +1750,7 @@ const createHelpCenterTools = (ctx) => {
 			title: "Update Article Section",
 			description: "Replace the content of a single section of an article in a given locale, keeping the rest of the body intact. The server fetches the current body, replaces the targeted section, and PUTs the full reconstructed body via the Translations API. Default format=\"html\" for fidelity. Use format=\"markdown\" only when you control the input and know it does not rely on structures that round-trip poorly (code blocks with line breaks, tables with multi-paragraph cells). The section heading is preserved and is NOT part of the replaced content.",
 			inputSchema: z.object({
-				article_id: z.number().int().describe("Article ID"),
+				article_id: z.number().int().describe(ARTICLE_ID_DESC),
 				locale: z.string().describe("Locale of the translation to update"),
 				section_index: z.number().int().min(0).describe("0-based index of the section to replace (see get_article_outline)"),
 				content: z.string().describe("New content for the section (heading excluded). HTML by default, Markdown if format=\"markdown\"."),
@@ -1776,8 +1784,8 @@ const createHelpCenterTools = (ctx) => {
 			title: "Compare Article Translations",
 			description: "Compare section structure between two locales of the same article, matched by index. Returns a compact table (one row per section) with status: \"ok\" (both present, source/target word count ratio within 25%), \"different\" (word count ratio diverges by more than 25% — size signal only, NOT a semantic divergence: two locales may legitimately differ in verbosity) or \"missing\" (section absent in target). Useful to spot structurally stale or missing sections; do not interpret \"different\" as an edit regression on its own.",
 			inputSchema: z.object({
-				article_id: z.number().int().describe("Article ID"),
-				source_locale: z.string().describe("Source (reference) locale"),
+				article_id: z.number().int().describe(ARTICLE_ID_DESC),
+				source_locale: z.string().describe("Reference locale to diff against, e.g. \"en-us\". Usually the article source_locale (from get_article)."),
 				target_locale: z.string().describe("Target locale to compare against source")
 			}),
 			annotations: {
@@ -1828,7 +1836,7 @@ const createHelpCenterTools = (ctx) => {
 			title: "Create Article Attachment",
 			description: "Upload an attachment to an article. Provide file content as base64-encoded string.",
 			inputSchema: z.object({
-				article_id: z.number().int().describe("Article ID"),
+				article_id: z.number().int().describe(ARTICLE_ID_DESC),
 				file_name: z.string().min(1).describe("File name (e.g., \"screenshot.png\")"),
 				file_base64: z.string().min(1).describe("File content encoded as base64"),
 				content_type: z.string().default("application/octet-stream").describe("MIME type (e.g., \"image/png\", \"application/pdf\")")
@@ -1879,9 +1887,9 @@ const createSearchTools = (ctx) => {
 		title: "Zendesk Unified Search",
 		description: "Search across tickets, users, and organizations. Supports filters like \"type:ticket status:open\", \"type:user role:agent\". Returns total count and paginated results (100 per page). Organization results include name and ID only — use get_organization for full details (tags, domains, details).",
 		inputSchema: z.object({
-			query: z.string().min(1).describe("Zendesk search query"),
-			per_page: z.number().int().min(1).max(100).default(100).describe("Results per page (max 100)"),
-			page: z.number().int().min(1).default(1).describe("Page number (1-based)")
+			query: z.string().min(1).describe("Zendesk search query. Supports type/status/role filters (e.g. \"type:ticket status:open\", \"type:user role:agent\") and free text; omit a type filter to search tickets, users and organizations at once."),
+			per_page: z.number().int().min(1).max(100).default(100).describe(PER_PAGE_DESC),
+			page: z.number().int().min(1).default(1).describe(PAGE_DESC)
 		}),
 		annotations: {
 			readOnlyHint: true,
@@ -2012,8 +2020,8 @@ const createTicketTools = (ctx) => {
 			title: "Get Zendesk Ticket",
 			description: "Retrieve a Zendesk ticket by ID, including its live SLA state (per-metric stage and breach countdown) when an SLA policy applies, plus its comments if requested. Returns ticket details (subject, status, priority, assignee, tags, description) and optionally all comments/internal notes. The per-ticket Show endpoint exposes no SLA, so the SLA block is resolved via a scoped search and may be absent for a very high-volume requester or a just-updated ticket; SLA targets and policy conditions live in list_sla_policies.",
 			inputSchema: z.object({
-				ticket_id: z.number().int().describe("Ticket ID"),
-				include_comments: z.boolean().default(false).describe("Include ticket comments")
+				ticket_id: z.number().int().describe("Ticket ID — the numeric id of the ticket to fetch. Obtain it from search_tickets or list_tickets."),
+				include_comments: z.boolean().default(false).describe("When true, appends the full public comment and internal note thread to the response. Defaults to false to keep the payload small; enable it when you need the conversation, not just the ticket fields.")
 			}),
 			annotations: {
 				readOnlyHint: true,
@@ -2043,7 +2051,7 @@ const createTicketTools = (ctx) => {
 			title: "Get Zendesk Ticket Attachments",
 			description: "Retrieve ticket attachments. Images are embedded inline; other files are listed as text references.",
 			inputSchema: z.object({
-				ticket_id: z.number().int().describe("Ticket ID"),
+				ticket_id: z.number().int().describe("Ticket ID — the numeric id of the ticket whose attachments to fetch. Obtain it from search_tickets or list_tickets."),
 				attachment_ids: z.array(z.number().int()).optional().describe("Attachment IDs to fetch directly (e.g. extracted from a previous get_ticket(include_comments=true) call). When provided, skips the comments fetch entirely. When omitted, all attachments of the ticket are returned.")
 			}),
 			annotations: {
@@ -2081,11 +2089,11 @@ const createTicketTools = (ctx) => {
 			namespace: "tickets",
 			readOnly: true,
 			title: "Search Zendesk Tickets",
-			description: "Search tickets using Zendesk query syntax, returning each result with its live SLA state (per-metric stage and breach countdown) when an SLA policy applies. Examples: \"status:open assignee:me\", \"priority:urgent type:incident\". Returns total count, so queue triage like \"breaching today\" works without a per-ticket fetch.",
+			description: "Search tickets using Zendesk query syntax, returning each result with its live SLA state (per-metric stage and breach countdown) when an SLA policy applies. Examples: \"status:open assignee:me\", \"priority:urgent ticket_type:incident\". Returns total count, so queue triage like \"breaching today\" works without a per-ticket fetch.",
 			inputSchema: z.object({
-				query: z.string().min(1).describe("Zendesk search query string"),
-				per_page: z.number().int().min(1).max(100).default(100).describe("Results per page"),
-				page: z.number().int().min(1).default(1).describe("Page number")
+				query: z.string().min(1).describe("Zendesk ticket search query — field filters like \"status:open\", \"assignee:me\", \"priority:urgent ticket_type:incident\", combined with free text. A \"type:ticket\" scope is added automatically, so filter the ticket kind with ticket_type: (e.g. ticket_type:incident), never type: (which the API rejects here)."),
+				per_page: z.number().int().min(1).max(100).default(100).describe(PER_PAGE_DESC),
+				page: z.number().int().min(1).default(1).describe(PAGE_DESC)
 			}),
 			annotations: {
 				readOnlyHint: true,
@@ -2114,8 +2122,8 @@ const createTicketTools = (ctx) => {
 			title: "Create Zendesk Ticket",
 			description: "Create a new Zendesk support ticket with subject, description, and optional priority/type/assignee/tags. The description becomes the first public comment of the ticket, and the new ticket id is returned. After creation, use update_ticket to change status or assignee, add_public_comment or add_private_note to reply, and manage_tags to adjust tags. Look up valid assignee_id / group_id and custom field ids via search_users or your Zendesk admin settings.",
 			inputSchema: z.object({
-				subject: z.string().min(1).describe("Ticket subject"),
-				description: z.string().min(1).describe("Ticket description"),
+				subject: z.string().min(1).describe("Ticket subject — the short summary line shown in ticket lists and search results."),
+				description: z.string().min(1).describe("Ticket description — the body of the request. It becomes the ticket's first public comment (visible to the requester)."),
 				priority: z.enum([
 					"urgent",
 					"high",
@@ -2130,7 +2138,7 @@ const createTicketTools = (ctx) => {
 				]).optional().describe("Ticket type. One of problem, incident, question, task."),
 				assignee_id: z.number().int().optional().describe("User id of the agent to assign the ticket to."),
 				group_id: z.number().int().optional().describe("Id of the group to assign the ticket to."),
-				tags: z.array(z.string()).optional().describe("Tags to set on the ticket."),
+				tags: z.array(z.string()).optional().describe("Tags to set on the new ticket. Each tag is a single lowercase token (join multi-word tags with an underscore). Use manage_tags later to add or remove individual tags."),
 				custom_fields: z.array(z.object({
 					id: z.number().int(),
 					value: z.unknown()
@@ -2162,7 +2170,7 @@ const createTicketTools = (ctx) => {
 			title: "Update Zendesk Ticket",
 			description: "Update an existing ticket (status, priority, type, assignee, group, subject, tags, custom fields). Only the fields you pass are changed, and the updated ticket is returned. Setting tags here replaces the whole tag set — use manage_tags to add or remove individual tags without overwriting the rest. This tool does not post replies: use add_public_comment or add_private_note for that. Find the ticket id via search_tickets or list_tickets.",
 			inputSchema: z.object({
-				ticket_id: z.number().int().describe("Ticket ID"),
+				ticket_id: z.number().int().describe("Ticket ID — the numeric id of the ticket to update. Obtain it from search_tickets or list_tickets."),
 				status: z.enum([
 					"new",
 					"open",
@@ -2185,7 +2193,7 @@ const createTicketTools = (ctx) => {
 				]).optional().describe("Ticket type. One of problem, incident, question, task."),
 				assignee_id: z.number().int().optional().describe("User id of the agent to assign the ticket to."),
 				group_id: z.number().int().optional().describe("Id of the group to assign the ticket to."),
-				subject: z.string().optional().describe("New ticket subject line."),
+				subject: z.string().optional().describe("New subject line for the ticket; replaces the current subject when provided."),
 				tags: z.array(z.string()).optional().describe("Replaces the full tag set on the ticket. Use manage_tags for incremental add/remove."),
 				custom_fields: z.array(z.object({
 					id: z.number().int(),
@@ -2212,10 +2220,10 @@ const createTicketTools = (ctx) => {
 			namespace: "tickets",
 			readOnly: false,
 			title: "Add Private Note",
-			description: "Add an internal note (not visible to requester) to a ticket, optionally with file attachments (uploaded via the Zendesk Uploads API and carried on the note).",
+			description: "Add an internal note (not visible to requester) to a ticket, optionally with file attachments (uploaded via the Zendesk Uploads API and carried on the note). The note is appended to the ticket thread; use add_public_comment instead when the reply should be visible to the requester.",
 			inputSchema: z.object({
-				ticket_id: z.number().int().describe("Ticket ID"),
-				body: z.string().min(1).describe("Note content"),
+				ticket_id: z.number().int().describe("Ticket ID — the numeric id of the ticket to annotate. Obtain it from search_tickets or list_tickets."),
+				body: z.string().min(1).describe("Note text (internal, agent-only). Plain text or HTML; not shown to the requester."),
 				attachments: z.array(attachmentSchema).optional().describe("Files to attach to this note (base64-encoded content).")
 			}),
 			annotations: {
@@ -2244,10 +2252,10 @@ const createTicketTools = (ctx) => {
 			namespace: "tickets",
 			readOnly: false,
 			title: "Add Public Comment",
-			description: "Add a public comment (visible to requester) to a ticket, optionally with file attachments (uploaded via the Zendesk Uploads API and carried on the comment).",
+			description: "Add a public comment (visible to requester) to a ticket, optionally with file attachments (uploaded via the Zendesk Uploads API and carried on the comment). The comment is appended to the ticket thread and emails the requester; use add_private_note instead for an internal, agent-only note.",
 			inputSchema: z.object({
-				ticket_id: z.number().int().describe("Ticket ID"),
-				body: z.string().min(1).describe("Comment content"),
+				ticket_id: z.number().int().describe("Ticket ID — the numeric id of the ticket to reply on. Obtain it from search_tickets or list_tickets."),
+				body: z.string().min(1).describe("Comment text sent to the requester. Plain text or HTML; visible in the ticket."),
 				attachments: z.array(attachmentSchema).optional().describe("Files to attach to this comment (base64-encoded content).")
 			}),
 			annotations: {
@@ -2276,7 +2284,7 @@ const createTicketTools = (ctx) => {
 			namespace: "tickets",
 			readOnly: true,
 			title: "List Zendesk Tickets",
-			description: "List tickets with cursor-based pagination, sorted by most recently updated. Page size is controlled by page_size (not per_page, which is the offset-based parameter used by search_tickets); paginate by passing the returned cursor.",
+			description: "List tickets with cursor-based pagination, in Zendesk's default order (ascending ticket id), not by recency. Page size is controlled by page_size (not per_page, which is the offset-based parameter used by search_tickets); paginate by passing the returned cursor. To find tickets by recency or any other criterion, use search_tickets with a query.",
 			inputSchema: z.object({
 				page_size: z.number().int().min(1).max(100).default(100).describe("Tickets per page (1-100, default 100)."),
 				cursor: z.string().optional().describe("Pagination cursor from a previous response; omit for the first page.")
@@ -2302,8 +2310,8 @@ const createTicketTools = (ctx) => {
 			namespace: "tickets",
 			readOnly: true,
 			title: "Get Linked Incidents",
-			description: "Get all incident tickets linked to a problem ticket.",
-			inputSchema: z.object({ problem_id: z.number().int().describe("Problem ticket ID") }),
+			description: "Get all incident tickets linked to a problem ticket. Returns the list of incidents that reference the given problem (Zendesk problem/incident relationship); useful to gauge a problem's blast radius before resolving it.",
+			inputSchema: z.object({ problem_id: z.number().int().describe("Problem ticket ID — the numeric id of the ticket of type \"problem\" whose linked incidents to list. Obtain it from search_tickets or list_tickets.") }),
 			annotations: {
 				readOnlyHint: true,
 				destructiveHint: false,
@@ -2324,11 +2332,11 @@ const createTicketTools = (ctx) => {
 			namespace: "tickets",
 			readOnly: false,
 			title: "Manage Ticket Tags",
-			description: "Add or remove tags on a ticket.",
+			description: "Add or remove tags on a ticket. Performs an incremental read-modify-write: it fetches the ticket's current tags, adds those in `add` and deletes those in `remove`, then saves the merged set — tags you don't list are left untouched and duplicates are collapsed. Adding a tag already present, or removing one that is absent, is a no-op (idempotent). Returns the ticket's full tag set after the update. Use this for incremental tag edits; to overwrite the entire tag set at once, or to change tags alongside other fields, use update_ticket instead. Find the ticket id via search_tickets or list_tickets.",
 			inputSchema: z.object({
-				ticket_id: z.number().int().describe("Ticket ID"),
-				add: z.array(z.string()).optional().describe("Tags to add"),
-				remove: z.array(z.string()).optional().describe("Tags to remove")
+				ticket_id: z.number().int().describe("Ticket ID — the numeric id of the ticket whose tags to modify. Obtain it from search_tickets or list_tickets."),
+				add: z.array(z.string()).optional().describe("Tags to add. Zendesk tags are single tokens: a value containing spaces is stored as separate tags rather than one tag, so join multi-word tags yourself with an underscore or dash (e.g. \"urgent_request\"). Adding a tag already on the ticket is a no-op. Omit to only remove."),
+				remove: z.array(z.string()).optional().describe("Tags to remove. Removing a tag that is not present is a no-op; tags not listed here stay in place. Omit to only add.")
 			}),
 			annotations: {
 				readOnlyHint: false,
@@ -2361,8 +2369,8 @@ const createTicketTools = (ctx) => {
 			title: "List SLA Policies",
 			description: "List the configured SLA policies with their filter conditions and per-priority reply/resolution targets. Use this to explain why a given target applies to a ticket and to reconstruct deadlines deterministically instead of hard-coding the policy matrix. Requires an admin token (or a custom role granted the SLA-management permission); a standard agent token gets 403 here, though it can still read live per-ticket SLA via get_ticket / search_tickets.",
 			inputSchema: z.object({
-				per_page: z.number().int().min(1).max(100).default(100).describe("Results per page"),
-				page: z.number().int().min(1).default(1).describe("Page number")
+				per_page: z.number().int().min(1).max(100).default(100).describe(PER_PAGE_DESC),
+				page: z.number().int().min(1).default(1).describe(PAGE_DESC)
 			}),
 			annotations: {
 				readOnlyHint: true,
@@ -2426,9 +2434,9 @@ const createUserTools = (ctx) => {
 			title: "Search Zendesk Users",
 			description: "Search for users by name, email, or other criteria using Zendesk search query syntax. Returns total count.",
 			inputSchema: z.object({
-				query: z.string().min(1).describe("Search query"),
-				per_page: z.number().int().min(1).max(100).default(100).describe("Results per page"),
-				page: z.number().int().min(1).default(1).describe("Page number")
+				query: z.string().min(1).describe("Zendesk user search query — free text matched against name and email, and/or field filters like \"email:jane@acme.com\", \"role:agent\", \"organization_id:123\". A \"type:user\" scope is added automatically."),
+				per_page: z.number().int().min(1).max(100).default(100).describe(PER_PAGE_DESC),
+				page: z.number().int().min(1).default(1).describe(PAGE_DESC)
 			}),
 			annotations: {
 				readOnlyHint: true,
@@ -2453,8 +2461,8 @@ const createUserTools = (ctx) => {
 			namespace: "users",
 			readOnly: true,
 			title: "Get Zendesk User",
-			description: "Retrieve a user by ID.",
-			inputSchema: z.object({ user_id: z.number().int().describe("User ID") }),
+			description: "Retrieve a single user by their numeric id. Returns the full user record (name, email, role, organization, tags). Use search_users when you only have a name or email, or get_current_user for the authenticated identity.",
+			inputSchema: z.object({ user_id: z.number().int().describe("User ID — the numeric id of the Zendesk user to fetch. Obtain it from search_users, or from the requester/assignee fields of a ticket.") }),
 			annotations: {
 				readOnlyHint: true,
 				destructiveHint: false,
@@ -2475,8 +2483,8 @@ const createUserTools = (ctx) => {
 			namespace: "users",
 			readOnly: true,
 			title: "Get Zendesk Organization",
-			description: "Retrieve an organization by ID.",
-			inputSchema: z.object({ organization_id: z.number().int().describe("Organization ID") }),
+			description: "Retrieve a single organization by its numeric id. Returns full details (name, tags, domains, notes) — more than the name/id that search or list_organizations surface. Use list_organizations to browse or search for a name-based lookup.",
+			inputSchema: z.object({ organization_id: z.number().int().describe("Organization ID — the numeric id of the Zendesk organization to fetch. Obtain it from list_organizations, search, or a user record.") }),
 			annotations: {
 				readOnlyHint: true,
 				destructiveHint: false,