@fruggr/zendesk-mcp-server 2.0.0 → 2.1.0

package/README.md

@@ -151,6 +151,27 @@ zendesk-mcp-server acme --namespace tickets
 
 </details>
 
+## Help Center context (instructions + resources)
+
+Beyond tools, the server hands an LLM the structural context it needs to work
+against *your* Help Center — so it stops guessing locales or fuzzy-matching
+section names and uses real IDs instead. This is delivered through two
+MCP-native channels (both active only when the `help_center` namespace is, and
+disabled together with `--no-topology`):
+
+- **`instructions`** (sent on `initialize`): a short, static blob auto-loaded by
+  compliant clients. It names the subdomain and points at the topology resource.
+- **`zendesk-hc://topology`** (a pull-only [MCP resource](https://modelcontextprotocol.io/docs/concepts/resources)):
+  read on demand, it returns Markdown describing the active locales (and the
+  default), the category → section tree with IDs, the visibility user segments,
+  the permission groups, and the calling user's role. It is fetched **with the
+  caller's own token**, so it respects that user's read permissions. On a very
+  large Help Center the section tree is summarized (per-category, with a pointer
+  to `list_sections`) to stay concise.
+
+Clients that don't consume `instructions` or `resources` simply ignore them —
+the feature degrades silently. Use `--no-topology` to turn both off server-wide.
+
 ## Prerequisites
 
 - **Node.js** >= 20 (runtime — declared in `package.json#engines.node`)
@@ -418,6 +439,8 @@ Options:
   --namespace <ns>        Filter by namespace (repeatable): tickets, help_center, users
   --tool <name>           Filter by tool name (repeatable, forces --mode all)
   --read-only             Only expose read operations
+  --no-topology           Disable the Help Center structural context
+                          (instructions + zendesk-hc://topology resource)
   --log-level <level>     debug | info (default) | warn | error
   --transport <t>         stdio (default) | http
   --host <host>           HTTP bind host (default: 0.0.0.0)

package/dist/index.js

@@ -566,6 +566,14 @@ const ConfigSchema = z.object({
 	readOnly: z.boolean(),
 	namespaces: z.array(Namespace).optional(),
 	tools: z.array(z.string()).optional(),
+	/**
+	* Whether to expose the Help Center structural context (the `instructions`
+	* blob + the `zendesk-hc://topology` resource). On by default; an operator
+	* disables it server-wide with `--no-topology` (e.g. on a very large Help
+	* Center, or when the context is unwanted). Only ever active when the
+	* `help_center` namespace itself is active.
+	*/
+	topology: z.boolean().default(true),
 	transport: Transport,
 	host: z.string().min(1),
 	port: z.number().int().min(0).max(65535),
@@ -596,6 +604,7 @@ const parseCliArgs = (args) => {
 			result.mode = next;
 			i++;
 		} else if (arg === "--read-only") result.readOnly = true;
+		else if (arg === "--no-topology") result.topology = false;
 		else if (arg === "--namespace" && next) {
 			result.namespaces = result.namespaces ?? [];
 			result.namespaces.push(next);
@@ -653,6 +662,7 @@ const loadConfig = (argv = process.argv.slice(2)) => {
 		readOnly: cli.readOnly ?? false,
 		namespaces: cli.namespaces,
 		tools: cli.tools,
+		topology: cli.topology ?? true,
 		transport,
 		host,
 		port,
@@ -771,6 +781,246 @@ const helpCenterUpload = async (subdomain, token, path, formData) => {
 	return response.json();
 };
 //#endregion
+//#region src/guidance/instructions.ts
+/** Stable URI of the dynamic Help Center topology resource. */
+const TOPOLOGY_RESOURCE_URI = "zendesk-hc://topology";
+/**
+* Whether the Help Center structural context (init instructions + the
+* `zendesk-hc://topology` resource) should be exposed. True only when the
+* feature is enabled (`--no-topology` not set) AND the `help_center` namespace
+* is active (no `--namespace` filter, or one that includes it). Shared by the
+* instructions builder and the resource registration in `server.ts` so both
+* gates stay in sync.
+*/
+const helpCenterContextEnabled = (config) => config.topology && (!config.namespaces?.length || config.namespaces.includes("help_center"));
+/**
+* The static `instructions` blob sent on `initialize`. Deliberately short and
+* I/O-free: it must not trigger the lazy OAuth/PKCE flow just to connect, and
+* it stays within a tight token budget. The rich, dynamic topology lives in the
+* pull-only `zendesk-hc://topology` resource referenced here.
+*/
+const buildInstructions = (config) => {
+	if (!helpCenterContextEnabled(config)) return void 0;
+	return [
+		`This MCP server is connected to the Zendesk Help Center of "${config.subdomain}".`,
+		"",
+		`Before creating or editing Help Center content, read the resource ${TOPOLOGY_RESOURCE_URI}.`,
+		"It describes the active locales (and the default one), the category → section tree with IDs,",
+		"the visibility user segments, the permission groups, and your current role.",
+		"Prefer the IDs from that resource (section_id, permission_group_id, user_segment_id, locale)",
+		"over guessing from names."
+	].join("\n");
+};
+//#endregion
+//#region src/utils/formatting.ts
+const truncateIfNeeded = (text) => {
+	if (text.length <= 25e3) return text;
+	return `${text.slice(0, CHARACTER_LIMIT)}\n\n--- Response truncated (${text.length} chars, limit ${CHARACTER_LIMIT}). Use pagination or filters to reduce results. ---`;
+};
+const formatPagination = (meta) => {
+	const parts = [`Results: ${meta.count}`];
+	if (meta.has_more) parts.push(`More available (cursor: ${meta.after_cursor})`);
+	return parts.join(" | ");
+};
+const formatTicket = (ticket) => [
+	`## Ticket #${ticket.id}: ${ticket.subject}`,
+	`- **Status**: ${ticket.status} | **Priority**: ${ticket.priority ?? "none"} | **Type**: ${ticket.type ?? "none"}`,
+	`- **Requester**: ${ticket.requester_id} | **Assignee**: ${ticket.assignee_id ?? "unassigned"}`,
+	`- **Tags**: ${ticket.tags.length > 0 ? ticket.tags.join(", ") : "none"}`,
+	`- **Created**: ${ticket.created_at} | **Updated**: ${ticket.updated_at}`,
+	ticket.description ? `\n${ticket.description}` : ""
+].filter(Boolean).join("\n");
+const formatComment = (comment) => {
+	const lines = [`### ${comment.public ? "Public comment" : "Internal note"} by ${comment.author_id}`, `*${comment.created_at}*`];
+	if (comment.attachments?.length) {
+		const summary = comment.attachments.map((a) => `#${a.id} (${a.content_type})`).join(", ");
+		lines.push(`Attachments: ${summary}`);
+	}
+	lines.push("", comment.body);
+	return lines.join("\n");
+};
+const formatUser = (user) => [
+	`## ${user.name} (${user.id})`,
+	`- **Email**: ${user.email}`,
+	`- **Role**: ${user.role}`,
+	user.role_type != null ? `- **Role type**: ${user.role_type}` : "",
+	`- **Active**: ${user.active}`,
+	user.organization_id ? `- **Organization**: ${user.organization_id}` : ""
+].filter(Boolean).join("\n");
+const formatOrganization = (org) => [
+	`## ${org.name} (${org.id})`,
+	org.details ? `- **Details**: ${org.details}` : "",
+	org.domain_names.length > 0 ? `- **Domains**: ${org.domain_names.join(", ")}` : "",
+	org.tags.length > 0 ? `- **Tags**: ${org.tags.join(", ")}` : ""
+].filter(Boolean).join("\n");
+const formatArticleSummary = (article) => [
+	`## ${article.title} (${article.id})`,
+	`- **Locale**: ${article.locale} | **Source locale**: ${article.source_locale}`,
+	`- **Section**: ${article.section_id} | **Draft**: ${article.draft}`,
+	typeof article.position === "number" ? `- **Position**: ${article.position}` : "",
+	article.label_names.length > 0 ? `- **Labels**: ${article.label_names.join(", ")}` : "",
+	`- **Created**: ${article.created_at} | **Updated**: ${article.updated_at}`
+].filter(Boolean).join("\n");
+const formatArticle = (article) => [
+	formatArticleSummary(article),
+	"",
+	article.body
+].join("\n");
+const formatTranslationSummary = (translation) => [
+	`## Translation: ${translation.locale} (${translation.id})`,
+	`- **Title**: ${translation.title}`,
+	`- **Draft**: ${translation.draft}`,
+	`- **Updated**: ${translation.updated_at}`
+].join("\n");
+const formatTranslation = (translation) => [
+	formatTranslationSummary(translation),
+	"",
+	translation.body
+].join("\n");
+const formatCategory = (category) => `- **${category.name}** (${category.id}) — ${category.description || "No description"}`;
+const formatSection = (section) => `- **${section.name}** (${section.id}) — Category: ${section.category_id} — ${section.description || "No description"}`;
+const formatPermissionGroup = (group) => `- **${group.name}** (${group.id})${group.built_in ? " — Built-in" : ""}`;
+const formatContentTag = (tag) => `- **${tag.name}** (${tag.id})`;
+const formatLabel = (label) => `- **${label.name}** (${label.id})`;
+const formatUserSegment = (segment) => `- **${segment.name}** (${segment.id}) — ${segment.user_type}${segment.built_in ? " — Built-in" : ""}`;
+const formatAttachment = (attachment) => `- **${attachment.file_name}** (${attachment.id}) — ${attachment.content_type} — ${attachment.size} bytes`;
+const formatList = (items, formatter, meta) => {
+	return truncateIfNeeded([meta ? formatPagination(meta) : "", items.map(formatter).join("\n\n")].filter(Boolean).join("\n\n"));
+};
+//#endregion
+//#region src/utils/pagination.ts
+const buildCursorParams = (pageSize, cursor) => {
+	const params = { "page[size]": String(pageSize) };
+	if (cursor) params["page[after]"] = cursor;
+	return params;
+};
+const buildOffsetParams = (perPage, page) => {
+	const params = { per_page: String(perPage) };
+	if (page && page > 1) params["page"] = String(page);
+	return params;
+};
+const extractPaginationMeta = (response) => ({
+	has_more: response.meta?.has_more ?? response.next_page != null,
+	after_cursor: response.meta?.after_cursor ?? null,
+	count: response.count ?? 0
+});
+const extractSearchPaginationMeta = (response, perPage, page) => {
+	const count = response.count ?? 0;
+	const has_more = count > page * perPage;
+	return {
+		has_more,
+		after_cursor: has_more ? String(page + 1) : null,
+		count
+	};
+};
+//#endregion
+//#region src/guidance/topology.ts
+/**
+* Fetch the structural topology with the CALLER'S token, so the result respects
+* that user's read permissions (no privileged shared credential). Categories
+* and sections are each capped at one max-size page; `sectionsHasMore` /
+* `categoriesHasMore` signal a Help Center too large to enumerate inline.
+*/
+const fetchTopology = async (subdomain, token) => {
+	const pageParams = { "page[size]": String(100) };
+	const [locales, categoriesRes, sectionsRes, segmentsRes, permsRes, meRes] = await Promise.all([
+		helpCenterGet(subdomain, token, "/locales"),
+		helpCenterGet(subdomain, token, "/categories", pageParams),
+		helpCenterGet(subdomain, token, "/sections", pageParams),
+		helpCenterGet(subdomain, token, "/user_segments"),
+		zendeskGet(subdomain, token, "/guide/permission_groups"),
+		zendeskGet(subdomain, token, "/users/me")
+	]);
+	return {
+		subdomain,
+		locales,
+		categories: categoriesRes.categories ?? [],
+		sections: sectionsRes.sections ?? [],
+		sectionsHasMore: extractPaginationMeta(sectionsRes).has_more,
+		categoriesHasMore: extractPaginationMeta(categoriesRes).has_more,
+		userSegments: segmentsRes.user_segments ?? [],
+		permissionGroups: permsRes.permission_groups ?? [],
+		currentUser: meRes.user
+	};
+};
+const renderTree = (data) => {
+	if (data.categoriesHasMore || data.sectionsHasMore) {
+		const reasons = [];
+		if (data.categoriesHasMore) reasons.push(`more than 100 categories`);
+		if (data.sectionsHasMore) reasons.push(`more than 100 sections`);
+		return [
+			`Large Help Center (${reasons.join(" and ")}) — the full tree is omitted to stay concise.`,
+			data.categoriesHasMore ? "Categories (partial list):" : "Categories:",
+			...data.categories.map(formatCategory),
+			"",
+			...data.categoriesHasMore ? ["Use the `list_categories` tool to enumerate all categories."] : [],
+			"Use the `list_sections` tool (filtered by `category_id`) to enumerate sections under a category."
+		];
+	}
+	const byCategory = /* @__PURE__ */ new Map();
+	for (const section of data.sections) {
+		const list = byCategory.get(section.category_id) ?? [];
+		list.push(section);
+		byCategory.set(section.category_id, list);
+	}
+	const lines = [];
+	for (const category of data.categories) {
+		lines.push(formatCategory(category));
+		for (const section of byCategory.get(category.id) ?? []) lines.push(`  ${formatSection(section)}`);
+	}
+	return lines.length ? lines : ["_(no categories)_"];
+};
+/** Render the topology as a compact Markdown document for the LLM context. */
+const formatTopology = (data) => {
+	return truncateIfNeeded([
+		`# Zendesk Help Center topology — ${data.subdomain}`,
+		"",
+		`**Your access**: ${data.currentUser.name} (id ${data.currentUser.id}), role "${data.currentUser.role}".`,
+		"",
+		"## Locales",
+		`- Default: ${data.locales.default_locale}`,
+		`- Active: ${data.locales.locales.join(", ")}`,
+		"",
+		"## Categories → sections",
+		...renderTree(data),
+		"",
+		"## Visibility (user segments)",
+		...data.userSegments.length ? data.userSegments.map(formatUserSegment) : ["_(none)_"],
+		"",
+		"## Permission groups",
+		...data.permissionGroups.length ? data.permissionGroups.map(formatPermissionGroup) : ["_(none)_"]
+	].join("\n"));
+};
+/**
+* Build a topology provider holding a memoized-promise cache (TTL
+* `TOPOLOGY_TTL_MS`). In HTTP mode `createMcpServer` — and therefore this
+* provider — is instantiated PER SESSION, so this cache is per-session /
+* per-caller: it must NOT be hoisted to module scope, or one tenant's structure
+* would leak to another. The promise (not the value) is cached to coalesce
+* concurrent reads; failures are evicted so the next read retries with a fresh
+* token. A 401 notifies `onUnauthorized` (stdio OAuth only) to invalidate the
+* stale token, mirroring the tool dispatch path in `server.ts`.
+*/
+const createTopologyProvider = (getToken, subdomain, onUnauthorized) => {
+	let cached;
+	return { read() {
+		const now = Date.now();
+		if (cached && now - cached.at < 3e5) return cached.promise;
+		const promise = (async () => {
+			return formatTopology(await fetchTopology(subdomain, await getToken()));
+		})().catch((err) => {
+			cached = void 0;
+			if (onUnauthorized && err instanceof ZendeskApiError && err.status === 401) onUnauthorized();
+			throw err;
+		});
+		cached = {
+			at: now,
+			promise
+		};
+		return promise;
+	} };
+};
+//#endregion
 //#region src/routing/registry.ts
 const filterTools = (allTools, options) => allTools.filter((tool) => {
 	if (options.readOnly && !tool.readOnly) return false;
@@ -883,108 +1133,6 @@ const markdownToHtml = (markdown) => {
 	return String(mdToHtmlProcessor.processSync(markdown));
 };
 //#endregion
-//#region src/utils/formatting.ts
-const truncateIfNeeded = (text) => {
-	if (text.length <= 25e3) return text;
-	return `${text.slice(0, CHARACTER_LIMIT)}\n\n--- Response truncated (${text.length} chars, limit ${CHARACTER_LIMIT}). Use pagination or filters to reduce results. ---`;
-};
-const formatPagination = (meta) => {
-	const parts = [`Results: ${meta.count}`];
-	if (meta.has_more) parts.push(`More available (cursor: ${meta.after_cursor})`);
-	return parts.join(" | ");
-};
-const formatTicket = (ticket) => [
-	`## Ticket #${ticket.id}: ${ticket.subject}`,
-	`- **Status**: ${ticket.status} | **Priority**: ${ticket.priority ?? "none"} | **Type**: ${ticket.type ?? "none"}`,
-	`- **Requester**: ${ticket.requester_id} | **Assignee**: ${ticket.assignee_id ?? "unassigned"}`,
-	`- **Tags**: ${ticket.tags.length > 0 ? ticket.tags.join(", ") : "none"}`,
-	`- **Created**: ${ticket.created_at} | **Updated**: ${ticket.updated_at}`,
-	ticket.description ? `\n${ticket.description}` : ""
-].filter(Boolean).join("\n");
-const formatComment = (comment) => {
-	const lines = [`### ${comment.public ? "Public comment" : "Internal note"} by ${comment.author_id}`, `*${comment.created_at}*`];
-	if (comment.attachments?.length) {
-		const summary = comment.attachments.map((a) => `#${a.id} (${a.content_type})`).join(", ");
-		lines.push(`Attachments: ${summary}`);
-	}
-	lines.push("", comment.body);
-	return lines.join("\n");
-};
-const formatUser = (user) => [
-	`## ${user.name} (${user.id})`,
-	`- **Email**: ${user.email}`,
-	`- **Role**: ${user.role}`,
-	user.role_type != null ? `- **Role type**: ${user.role_type}` : "",
-	`- **Active**: ${user.active}`,
-	user.organization_id ? `- **Organization**: ${user.organization_id}` : ""
-].filter(Boolean).join("\n");
-const formatOrganization = (org) => [
-	`## ${org.name} (${org.id})`,
-	org.details ? `- **Details**: ${org.details}` : "",
-	org.domain_names.length > 0 ? `- **Domains**: ${org.domain_names.join(", ")}` : "",
-	org.tags.length > 0 ? `- **Tags**: ${org.tags.join(", ")}` : ""
-].filter(Boolean).join("\n");
-const formatArticleSummary = (article) => [
-	`## ${article.title} (${article.id})`,
-	`- **Locale**: ${article.locale} | **Source locale**: ${article.source_locale}`,
-	`- **Section**: ${article.section_id} | **Draft**: ${article.draft}`,
-	typeof article.position === "number" ? `- **Position**: ${article.position}` : "",
-	article.label_names.length > 0 ? `- **Labels**: ${article.label_names.join(", ")}` : "",
-	`- **Created**: ${article.created_at} | **Updated**: ${article.updated_at}`
-].filter(Boolean).join("\n");
-const formatArticle = (article) => [
-	formatArticleSummary(article),
-	"",
-	article.body
-].join("\n");
-const formatTranslationSummary = (translation) => [
-	`## Translation: ${translation.locale} (${translation.id})`,
-	`- **Title**: ${translation.title}`,
-	`- **Draft**: ${translation.draft}`,
-	`- **Updated**: ${translation.updated_at}`
-].join("\n");
-const formatTranslation = (translation) => [
-	formatTranslationSummary(translation),
-	"",
-	translation.body
-].join("\n");
-const formatCategory = (category) => `- **${category.name}** (${category.id}) — ${category.description || "No description"}`;
-const formatSection = (section) => `- **${section.name}** (${section.id}) — Category: ${section.category_id} — ${section.description || "No description"}`;
-const formatPermissionGroup = (group) => `- **${group.name}** (${group.id})${group.built_in ? " — Built-in" : ""}`;
-const formatContentTag = (tag) => `- **${tag.name}** (${tag.id})`;
-const formatLabel = (label) => `- **${label.name}** (${label.id})`;
-const formatUserSegment = (segment) => `- **${segment.name}** (${segment.id}) — ${segment.user_type}${segment.built_in ? " — Built-in" : ""}`;
-const formatAttachment = (attachment) => `- **${attachment.file_name}** (${attachment.id}) — ${attachment.content_type} — ${attachment.size} bytes`;
-const formatList = (items, formatter, meta) => {
-	return truncateIfNeeded([meta ? formatPagination(meta) : "", items.map(formatter).join("\n\n")].filter(Boolean).join("\n\n"));
-};
-//#endregion
-//#region src/utils/pagination.ts
-const buildCursorParams = (pageSize, cursor) => {
-	const params = { "page[size]": String(pageSize) };
-	if (cursor) params["page[after]"] = cursor;
-	return params;
-};
-const buildOffsetParams = (perPage, page) => {
-	const params = { per_page: String(perPage) };
-	if (page && page > 1) params["page"] = String(page);
-	return params;
-};
-const extractPaginationMeta = (response) => ({
-	has_more: response.meta?.has_more ?? response.next_page != null,
-	after_cursor: response.meta?.after_cursor ?? null,
-	count: response.count ?? 0
-});
-const extractSearchPaginationMeta = (response, perPage, page) => {
-	const count = response.count ?? 0;
-	const has_more = count > page * perPage;
-	return {
-		has_more,
-		after_cursor: has_more ? String(page + 1) : null,
-		count
-	};
-};
-//#endregion
 //#region src/tools/help-center.ts
 const largeArticleHint = (body, sectionCount) => {
 	if (body.length < 3e3 && sectionCount < 4) return null;
@@ -1063,11 +1211,11 @@ const createHelpCenterTools = (ctx) => {
 			namespace: "help_center",
 			readOnly: true,
 			title: "List Help Center Categories",
-			description: "List all Help Center categories. Optionally filter by locale.",
+			description: "List all Help Center categories. Categories are the top level of the Guide hierarchy (category → section → article); each entry includes its id, name and locale. Results are cursor-paginated. Pair a returned category id with list_sections to drill down, then list_articles to reach articles. Pass a locale to read category names in that translation.",
 			inputSchema: z.object({
-				locale: z.string().optional(),
-				page_size: z.number().int().min(1).max(100).default(100),
-				cursor: z.string().optional()
+				locale: z.string().optional().describe("Locale for category names (e.g., \"en-us\", \"fr\"). Defaults to the Help Center default locale."),
+				page_size: z.number().int().min(1).max(100).default(100).describe("Categories per page (1-100, default 100)."),
+				cursor: z.string().optional().describe("Pagination cursor from a previous response; omit for the first page.")
 			}),
 			annotations: {
 				readOnlyHint: true,
@@ -1089,12 +1237,12 @@ const createHelpCenterTools = (ctx) => {
 			namespace: "help_center",
 			readOnly: true,
 			title: "List Help Center Sections",
-			description: "List sections, optionally filtered by category ID and locale.",
+			description: "List Help Center sections. Sections are the middle level of the Guide hierarchy (category → section → article) and group related articles; each entry includes its id, name, category_id and locale. Results are cursor-paginated. Pass category_id to list only one category's sections (ids come from list_categories), then use a section id with list_articles. Pass a locale to read section names in that translation.",
 			inputSchema: z.object({
-				category_id: z.number().int().optional(),
-				locale: z.string().optional(),
-				page_size: z.number().int().min(1).max(100).default(100),
-				cursor: z.string().optional()
+				category_id: z.number().int().optional().describe("Restrict to sections of this category (id from list_categories). Omit to list every section."),
+				locale: z.string().optional().describe("Locale for section names (e.g., \"en-us\", \"fr\"). Defaults to the Help Center default locale."),
+				page_size: z.number().int().min(1).max(100).default(100).describe("Sections per page (1-100, default 100)."),
+				cursor: z.string().optional().describe("Pagination cursor from a previous response; omit for the first page.")
 			}),
 			annotations: {
 				readOnlyHint: true,
@@ -1189,13 +1337,13 @@ const createHelpCenterTools = (ctx) => {
 			namespace: "help_center",
 			readOnly: false,
 			title: "Create Article Translation",
-			description: "Create a translation for an existing article in a specific locale.",
+			description: "Create a translation for an existing article in a specific locale. The article must already exist (create it with create_article); this adds a new localized version and returns the created translation (locale, title, draft state). The target locale must not already have a translation — use update_article_translation to modify an existing one, and list_article_translations to see which locales exist. Provide the full HTML body.",
 			inputSchema: z.object({
-				article_id: z.number().int(),
+				article_id: z.number().int().describe("ID of the existing article to translate."),
 				locale: z.string().describe("Target locale (e.g., \"fr\", \"de\")"),
-				title: z.string().min(1),
+				title: z.string().min(1).describe("Translated article title."),
 				body: z.string().min(1).describe("Translated body (HTML)"),
-				draft: z.boolean().default(false)
+				draft: z.boolean().default(false).describe("Create the translation as a draft (not visible to end users). Defaults to false (published).")
 			}),
 			annotations: {
 				readOnlyHint: false,
@@ -1357,8 +1505,8 @@ const createHelpCenterTools = (ctx) => {
 			namespace: "help_center",
 			readOnly: false,
 			title: "Create Content Tag",
-			description: "Create a new content tag for Guide articles.",
-			inputSchema: z.object({ name: z.string().min(1).describe("Content tag name") }),
+			description: "Create a new content tag for Guide articles. Content tags are end-user visible labels that help readers discover related articles; this returns the created tag with its id. Check list_content_tags first to avoid duplicates, then attach the new id via the content_tag_ids parameter of create_article or update_article. For internal search-ranking labels that are not shown to end users, use article labels (list_labels) instead.",
+			inputSchema: z.object({ name: z.string().min(1).describe("Content tag name as shown to end users (e.g., \"billing\", \"getting-started\").") }),
 			annotations: {
 				readOnlyHint: false,
 				destructiveHint: false,
@@ -1419,8 +1567,8 @@ const createHelpCenterTools = (ctx) => {
 			namespace: "help_center",
 			readOnly: true,
 			title: "List Article Attachments",
-			description: "List all attachments for an article.",
-			inputSchema: z.object({ article_id: z.number().int().describe("Article ID") }),
+			description: "List all attachments for an article. Returns attachment metadata only (id, file name, content type, size, URL), not the file bytes; both inline and block attachments are included. This is for Help Center articles — for attachments on support tickets use get_ticket_attachments instead. Upload new files with create_article_attachment.",
+			inputSchema: z.object({ article_id: z.number().int().describe("ID of the Help Center article whose attachments to list.") }),
 			annotations: {
 				readOnlyHint: true,
 				destructiveHint: false,
@@ -1851,7 +1999,7 @@ const createTicketTools = (ctx) => {
 			namespace: "tickets",
 			readOnly: false,
 			title: "Create Zendesk Ticket",
-			description: "Create a new Zendesk support ticket with subject, description, and optional priority/type/assignee/tags.",
+			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"),
@@ -1860,20 +2008,20 @@ const createTicketTools = (ctx) => {
 					"high",
 					"normal",
 					"low"
-				]).optional(),
+				]).optional().describe("Ticket priority. One of urgent, high, normal, low."),
 				type: z.enum([
 					"problem",
 					"incident",
 					"question",
 					"task"
-				]).optional(),
-				assignee_id: z.number().int().optional(),
-				group_id: z.number().int().optional(),
-				tags: z.array(z.string()).optional(),
+				]).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."),
 				custom_fields: z.array(z.object({
 					id: z.number().int(),
 					value: z.unknown()
-				})).optional()
+				})).optional().describe("Custom field values as { id, value } pairs (field ids come from your Zendesk admin settings).")
 			}),
 			annotations: {
 				readOnlyHint: false,
@@ -1899,7 +2047,7 @@ const createTicketTools = (ctx) => {
 			namespace: "tickets",
 			readOnly: false,
 			title: "Update Zendesk Ticket",
-			description: "Update an existing ticket (status, priority, type, assignee, group, subject, tags, custom fields).",
+			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"),
 				status: z.enum([
@@ -1909,27 +2057,27 @@ const createTicketTools = (ctx) => {
 					"hold",
 					"solved",
 					"closed"
-				]).optional(),
+				]).optional().describe("New ticket status. One of new, open, pending, hold, solved, closed."),
 				priority: z.enum([
 					"urgent",
 					"high",
 					"normal",
 					"low"
-				]).optional(),
+				]).optional().describe("Ticket priority. One of urgent, high, normal, low."),
 				type: z.enum([
 					"problem",
 					"incident",
 					"question",
 					"task"
-				]).optional(),
-				assignee_id: z.number().int().optional(),
-				group_id: z.number().int().optional(),
-				subject: z.string().optional(),
-				tags: z.array(z.string()).optional(),
+				]).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."),
+				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(),
 					value: z.unknown()
-				})).optional()
+				})).optional().describe("Custom field values as { id, value } pairs (field ids come from your Zendesk admin settings).")
 			}),
 			annotations: {
 				readOnlyHint: false,
@@ -2190,10 +2338,10 @@ const createUserTools = (ctx) => {
 			namespace: "users",
 			readOnly: true,
 			title: "List Zendesk Organizations",
-			description: "List all organizations with pagination.",
+			description: "List all organizations with pagination. Returns the name and id of each organization plus basic fields; results are cursor-paginated. Use get_organization with an id for full details (tags, domains, notes), or search for query-based lookups by name. Organizations group end users and can be referenced when creating or filtering tickets.",
 			inputSchema: z.object({
-				page_size: z.number().int().min(1).max(100).default(100),
-				cursor: z.string().optional()
+				page_size: z.number().int().min(1).max(100).default(100).describe("Organizations per page (1-100, default 100)."),
+				cursor: z.string().optional().describe("Pagination cursor from a previous response; omit for the first page.")
 			}),
 			annotations: {
 				readOnlyHint: true,
@@ -2294,10 +2442,14 @@ const registerProxyTool = (server, toolName, title, tools, readOnlyMode, onUnaut
 };
 const createMcpServer = (config, getToken, logger = silentLogger, onUnauthorized) => {
 	const pkg = readPackageInfo();
+	const instructions = buildInstructions(config);
 	const server = new McpServer({
 		name: pkg.name,
 		version: pkg.version
-	}, { capabilities: { logging: {} } });
+	}, {
+		capabilities: { logging: {} },
+		...instructions ? { instructions } : {}
+	});
 	logger.attachServer(server);
 	const filteredTools = filterTools(createAllTools({
 		subdomain: config.subdomain,
@@ -2328,6 +2480,18 @@ const createMcpServer = (config, getToken, logger = silentLogger, onUnauthorized
 			registerProxyTool(server, "zendesk", "Zendesk", filteredTools, config.readOnly, onUnauthorized);
 			break;
 	}
+	if (helpCenterContextEnabled(config)) {
+		const topology = createTopologyProvider(getToken, config.subdomain, onUnauthorized);
+		server.registerResource("help-center-topology", TOPOLOGY_RESOURCE_URI, {
+			title: "Zendesk Help Center topology",
+			description: "Active locales, category → section tree, visibility segments, permission groups, and your role. Read before creating or editing content.",
+			mimeType: "text/markdown"
+		}, async (uri) => ({ contents: [{
+			uri: uri.toString(),
+			mimeType: "text/markdown",
+			text: await topology.read()
+		}] }));
+	}
 	logger.info("tools_registered", {
 		count: filteredTools.length,
 		mode: config.mode