@atlaskit/ads-mcp 0.18.1 → 0.19.0

package/dist/cjs/tools/suggest-a11y-fixes/index.js

@@ -19,16 +19,16 @@ function _createForOfIteratorHelper(r, e) { var t = "undefined" != typeof Symbol
 function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
 function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; } /* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
 var suggestA11yFixesInputSchema = exports.suggestA11yFixesInputSchema = _zod.z.object({
-  violation: _zod.z.string().describe('Description of the accessibility violation'),
-  code: _zod.z.string().describe('The problematic code that needs fixing'),
-  component: _zod.z.string().optional().describe('Component name or type'),
-  context: _zod.z.string().optional().describe('Additional context about the usage')
+  violation: _zod.z.string().describe('Human-readable description of the issue (e.g. axe rule help text, "button has no accessible name", "missing alt"). Used to match curated recipes when possible; otherwise the tool falls back to generic guidance.'),
+  code: _zod.z.string().describe('Snippet of the problematic code or markup so the response can be tailored (may be shown in the output for traceability).'),
+  component: _zod.z.string().optional().describe('Optional: React component name involved (e.g. `Button`, `TextField`)—may be ADS or app-specific.'),
+  context: _zod.z.string().optional().describe('Optional: where this appears (e.g. modal, table row, page section) or constraints.')
 });
 var listSuggestA11yFixesTool = exports.listSuggestA11yFixesTool = {
   name: 'ads_suggest_a11y_fixes',
-  description: "Suggests specific accessibility fixes using Atlassian Design System components and patterns.",
+  description: "Suggests remediation steps for an accessibility issue described in natural language (often pasted from **axe-core**, ESLint, or review).\n\nWHAT YOU GET (varies by match):\n- **Curated hit:** ADS-biased examples and patterns from this server\u2019s recipe map (components, tokens, common fixes).\n- **No strong match:** Generic guidance (e.g. \u201Cuse ADS components\u201D, labeling, testing)\u2014still useful, but **not** guaranteed to be ADS-specific. May reference axe/atlassian.design resources.\n\nWHEN TO USE:\nAfter `ads_analyze_a11y` or `ads_analyze_localhost_a11y`, or whenever you have a violation string. For **topic-level** Atlassian Design System accessibility guidance, call `ads_get_a11y_guidelines` (this tool is fix-oriented, not a full guideline browse).\n\nDoes not replace manual testing with assistive technologies or keyboard-only navigation.",
   annotations: {
-    title: 'Suggest Accessibility Fixes',
+    title: 'Suggest accessibility fixes',
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,
@@ -169,7 +169,7 @@ var suggestA11yFixesTool = exports.suggestA11yFixesTool = /*#__PURE__*/function
                 availableFixTypes: Object.keys(_fixes.accessibilityFixes),
                 suggestions: ['Try describing the issue with keywords like: button, label, missing, text, color, contrast, focus, etc.', 'Use axe-core violation IDs or descriptions directly', 'Be more specific about the element type (button, input, image, etc.)'],
                 additionalResources: ['https://atlassian.design/llms-a11y.txt - Complete ADS accessibility documentation', 'https://atlassian.design/foundations/accessibility - ADS accessibility foundation'],
-                recommendation: 'Try the get_a11y_guidelines tool for component-specific guidance'
+                recommendation: 'Try the ads_get_a11y_guidelines tool for component-specific guidance'
               }, null, 2)
             }]
           });

package/dist/es2019/helpers/fuse-multi-term.js

@@ -0,0 +1,98 @@
+/**
+ * Allocation for multi-query Fuse search: each term alone, plus one spaced combined query.
+ *
+ * `poolMax = limit * termCount`. From each term we take up to `perTermTake` hits; the rest of the
+ * pool is filled from the spaced combined query.
+ */
+export function computeMultiTermFuseAllocation(limit, termCount) {
+  if (termCount <= 1) return {
+    perTermTake: 1,
+    combinedTake: 0,
+    totalTake: 1
+  };
+  const perTermTake = Math.max(Math.round(limit / termCount), 1);
+  const combinedTake = Math.max(limit * termCount - termCount * perTermTake, 1);
+  const totalTake = Math.max(perTermTake * termCount + combinedTake, 1);
+  return {
+    perTermTake,
+    combinedTake,
+    totalTake
+  };
+}
+/**
+ * Runs `search` for each term (top `perTermTake`) and for `terms.join(' ')` (top `combinedTake`),
+ * merges pools, sorts globally by Fuse score, then returns the first `limit` **distinct** keys
+ * (later duplicate keys are skipped).
+ *
+ * Default `tokenKey` uses `item.name` when present; pass an explicit `tokenKey` for types without
+ * `name` (e.g. icons keyed by `componentName`).
+ */
+export function mergeMultiTermFuseResults({
+  searchTerms,
+  limit,
+  search,
+  tokenKey = item => {
+    var _name;
+    return String((_name = item.name) !== null && _name !== void 0 ? _name : '');
+  },
+  searchTermsJoin = ' '
+}) {
+  const n = searchTerms.length;
+  if (n === 0) {
+    return [];
+  }
+  if (n === 1) {
+    return takeFirstUniqueKeys(sortByScoreAsc(toScoredHits(search(searchTerms[0]), tokenKey)), limit);
+  }
+  const {
+    perTermTake,
+    combinedTake,
+    totalTake
+  } = computeMultiTermFuseAllocation(limit, n);
+  const termsCombined = searchTerms.join(searchTermsJoin);
+  const pool = [];
+  for (const term of searchTerms) {
+    pool.push(...topRankedFromQuery(search, term, tokenKey, perTermTake));
+  }
+
+  // Combine the terms together and search as well.
+  pool.push(...topRankedFromQuery(search, termsCombined, tokenKey, combinedTake));
+
+  // Grab the top combinations of all queries' results.
+  return takeFirstUniqueKeys(sortByScoreAsc(pool), totalTake);
+}
+
+/**
+ * Best `take` hits for one Fuse query (ranked by score, then slice).
+ */
+function topRankedFromQuery(search, query, tokenKey, take) {
+  return sortByScoreAsc(toScoredHits(search(query), tokenKey)).slice(0, take);
+}
+function toScoredHits(fuseHits, tokenKey) {
+  return fuseHits.map(hit => {
+    var _hit$score;
+    return {
+      item: hit.item,
+      score: (_hit$score = hit.score) !== null && _hit$score !== void 0 ? _hit$score : Number.POSITIVE_INFINITY,
+      key: tokenKey(hit.item)
+    };
+  });
+}
+function sortByScoreAsc(hits) {
+  return [...hits].sort((a, b) => a.score - b.score);
+}
+function takeFirstUniqueKeys(sortedHits, limit) {
+  const seen = new Set();
+  const out = [];
+  for (const h of sortedHits) {
+    if (seen.has(h.key)) {
+      continue;
+    }
+    seen.add(h.key);
+    out.push(h.item);
+    if (out.length >= limit) {
+      break;
+    }
+  }
+  return out;
+}

package/dist/es2019/helpers/index.js

@@ -1,6 +1,7 @@
 /* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
 
 import { zodToJsonSchema as zodToJsonSchemaHelper } from 'zod-to-json-schema';
+export { computeMultiTermFuseAllocation, mergeMultiTermFuseResults } from './fuse-multi-term';
 export const cleanQuery = query => query.trim().toLowerCase().replace(/\s+/g, '');
 export const zodToJsonSchema = (schema, options) => {
   return zodToJsonSchemaHelper(schema, options);

package/dist/es2019/index.js

@@ -7,14 +7,17 @@ import { validateToolArguments } from './helpers/validation';
 import { instructions } from './instructions';
 import { analyzeA11yInputSchema, analyzeA11yLocalhostInputSchema, analyzeA11yTool, analyzeLocalhostA11yTool, listAnalyzeA11yTool, listAnalyzeLocalhostA11yTool } from './tools/analyze-a11y';
 import { getA11yGuidelinesInputSchema, getA11yGuidelinesTool, listGetA11yGuidelinesTool } from './tools/get-a11y-guidelines';
+import { getAllComponentsTool, listGetAllComponentsTool } from './tools/get-all-components';
 import { getAllIconsTool, listGetAllIconsTool } from './tools/get-all-icons';
 import { getAllTokensTool, listGetAllTokensTool } from './tools/get-all-tokens';
-import { getComponentsTool, listGetComponentsTool } from './tools/get-components';
 import { getGuidelinesInputSchema, getGuidelinesTool, listGetGuidelinesTool } from './tools/get-guidelines';
 import { getLintRulesInputSchema, getLintRulesTool, listGetLintRulesTool } from './tools/get-lint-rules';
 import { i18nConversionInputSchema, i18nConversionTool, listI18nConversionTool } from './tools/i18n-conversion';
 import { listMigrationGuidesTool, migrationGuidesInputSchema, migrationGuidesTool } from './tools/migration-guides';
 import { listPlanTool, planInputSchema, planTool } from './tools/plan';
+import { listSearchComponentsTool, searchComponentsInputSchema, searchComponentsTool } from './tools/search-components';
+import { listSearchIconsTool, searchIconsInputSchema, searchIconsTool } from './tools/search-icons';
+import { listSearchTokensTool, searchTokensInputSchema, searchTokensTool } from './tools/search-tokens';
 import { listSuggestA11yFixesTool, suggestA11yFixesInputSchema, suggestA11yFixesTool } from './tools/suggest-a11y-fixes';
 
 // eslint-disable-next-line import/no-extraneous-dependencies -- this uses require because not all node versions this package supports use the same import assertions/attributes
@@ -45,88 +48,83 @@ const generateLogger = level => (...args) => {
     console.error(`[ads-mcp.custom-logging][${level}]`, ...args);
   }
 };
-export const getToolRegistry = () => {
-  const baseTools = {
-    [listAnalyzeA11yTool.name]: {
-      handler: analyzeA11yTool,
-      inputSchema: analyzeA11yInputSchema,
-      tool: listAnalyzeA11yTool
-    },
-    [listAnalyzeLocalhostA11yTool.name]: {
-      handler: analyzeLocalhostA11yTool,
-      inputSchema: analyzeA11yLocalhostInputSchema,
-      tool: listAnalyzeLocalhostA11yTool
-    },
-    [listGetA11yGuidelinesTool.name]: {
-      handler: getA11yGuidelinesTool,
-      inputSchema: getA11yGuidelinesInputSchema,
-      tool: listGetA11yGuidelinesTool
-    },
-    [listGetComponentsTool.name]: {
-      handler: getComponentsTool,
-      inputSchema: null,
-      tool: listGetComponentsTool
-    },
-    [listPlanTool.name]: {
-      handler: planTool,
-      inputSchema: planInputSchema,
-      tool: listPlanTool
-    },
-    // NOTE: These should not actually be called as they're not in the `list_tools` endpoint.
-    // But there might be a reason to keep them around for backwards-compatibility.
-    // [listSearchComponentsTool.name]: {
-    //   handler: searchComponentsTool,
-    //   inputSchema: searchComponentsInputSchema,
-    //   tool: listSearchComponentsTool,
-    // },
-    // [listSearchIconsTool.name]: {
-    //   handler: searchIconsTool,
-    //   inputSchema: searchIconsInputSchema,
-    //   tool: listSearchIconsTool,
-    // },
-    // [listSearchTokensTool.name]: {
-    //   handler: searchTokensTool,
-    //   inputSchema: searchTokensInputSchema,
-    //   tool: listSearchTokensTool,
-    // },
-    [listSuggestA11yFixesTool.name]: {
-      handler: suggestA11yFixesTool,
-      inputSchema: suggestA11yFixesInputSchema,
-      tool: listSuggestA11yFixesTool
-    },
-    [listMigrationGuidesTool.name]: {
-      handler: migrationGuidesTool,
-      inputSchema: migrationGuidesInputSchema,
-      tool: listMigrationGuidesTool
-    },
-    [listI18nConversionTool.name]: {
-      handler: i18nConversionTool,
-      inputSchema: i18nConversionInputSchema,
-      tool: listI18nConversionTool
-    },
-    [listGetGuidelinesTool.name]: {
-      handler: getGuidelinesTool,
-      inputSchema: getGuidelinesInputSchema,
-      tool: listGetGuidelinesTool
-    },
-    [listGetAllTokensTool.name]: {
-      handler: getAllTokensTool,
-      inputSchema: null,
-      tool: listGetAllTokensTool
-    },
-    [listGetAllIconsTool.name]: {
-      handler: getAllIconsTool,
-      inputSchema: null,
-      tool: listGetAllIconsTool
-    },
-    [listGetLintRulesTool.name]: {
-      handler: getLintRulesTool,
-      inputSchema: getLintRulesInputSchema,
-      tool: listGetLintRulesTool
-    }
-  };
-  return baseTools;
-};
+export const getToolRegistry = () => ({
+  [listAnalyzeA11yTool.name]: {
+    handler: analyzeA11yTool,
+    inputSchema: analyzeA11yInputSchema,
+    tool: listAnalyzeA11yTool
+  },
+  [listAnalyzeLocalhostA11yTool.name]: {
+    handler: analyzeLocalhostA11yTool,
+    inputSchema: analyzeA11yLocalhostInputSchema,
+    tool: listAnalyzeLocalhostA11yTool
+  },
+  [listGetA11yGuidelinesTool.name]: {
+    handler: getA11yGuidelinesTool,
+    inputSchema: getA11yGuidelinesInputSchema,
+    tool: listGetA11yGuidelinesTool
+  },
+  [listGetAllComponentsTool.name]: {
+    handler: getAllComponentsTool,
+    inputSchema: null,
+    tool: listGetAllComponentsTool
+  },
+  [listPlanTool.name]: {
+    handler: planTool,
+    inputSchema: planInputSchema,
+    tool: listPlanTool
+  },
+  [listSearchComponentsTool.name]: {
+    handler: searchComponentsTool,
+    inputSchema: searchComponentsInputSchema,
+    tool: listSearchComponentsTool
+  },
+  [listSearchIconsTool.name]: {
+    handler: searchIconsTool,
+    inputSchema: searchIconsInputSchema,
+    tool: listSearchIconsTool
+  },
+  [listSearchTokensTool.name]: {
+    handler: searchTokensTool,
+    inputSchema: searchTokensInputSchema,
+    tool: listSearchTokensTool
+  },
+  [listSuggestA11yFixesTool.name]: {
+    handler: suggestA11yFixesTool,
+    inputSchema: suggestA11yFixesInputSchema,
+    tool: listSuggestA11yFixesTool
+  },
+  [listMigrationGuidesTool.name]: {
+    handler: migrationGuidesTool,
+    inputSchema: migrationGuidesInputSchema,
+    tool: listMigrationGuidesTool
+  },
+  [listI18nConversionTool.name]: {
+    handler: i18nConversionTool,
+    inputSchema: i18nConversionInputSchema,
+    tool: listI18nConversionTool
+  },
+  [listGetGuidelinesTool.name]: {
+    handler: getGuidelinesTool,
+    inputSchema: getGuidelinesInputSchema,
+    tool: listGetGuidelinesTool
+  },
+  [listGetAllTokensTool.name]: {
+    handler: getAllTokensTool,
+    inputSchema: null,
+    tool: listGetAllTokensTool
+  },
+  [listGetAllIconsTool.name]: {
+    handler: getAllIconsTool,
+    inputSchema: null,
+    tool: listGetAllIconsTool
+  },
+  [listGetLintRulesTool.name]: {
+    handler: getLintRulesTool,
+    inputSchema: getLintRulesInputSchema,
+    tool: listGetLintRulesTool
+  }
+});
 server.setRequestHandler(ListToolsRequestSchema, async (request, extra) => {
   const toolRegistry = getToolRegistry();
   const tools = Object.values(toolRegistry).map(toolConfig => toolConfig.tool);

package/dist/es2019/instructions.js

@@ -3,5 +3,6 @@ You are an expert in the Atlassian Design System (ADS).
 You can search for tokens, icons, and components and return guidance on how to build user interfaces.
 You have special accessibility knowledge and can ensure interfaces built with ADS components are accessible to all users.
 You can analyze code for accessibility violations, provide specific fix suggestions, and offer guidance on accessibility best practices.
-These tools will support you, but for deep research, you may also want to to fetch https://atlassian.design/llms.txt, https://atlassian.design/llms-a11y.txt, or https://atlassian.design/ directly.
+For org-wide standards alongside ADS tools: pair Context Engine \`get_accessibility_docs\` with \`ads_get_a11y_guidelines\`, \`get_content_standards_docs\` with \`ads_get_guidelines\`, and \`get_i18n_docs\` with \`ads_i18n_conversion_guide\` (Traduki/i18n policy plus the bundled formatMessage refactor guide).
+These tools will support you, but for deep research you may also fetch https://atlassian.design/llms.txt, https://atlassian.design/llms-a11y.txt, or https://atlassian.design/ directly.
 `;

package/dist/es2019/tools/analyze-a11y/index.js

@@ -6,16 +6,23 @@ import puppeteer from 'puppeteer';
 import { z } from 'zod';
 import { zodToJsonSchema } from '../../helpers';
 export const analyzeA11yInputSchema = z.object({
-  code: z.string().describe('React component code to analyze for accessibility'),
-  componentName: z.string().describe('Name of the component being analyzed').optional(),
-  context: z.string().describe('Additional context about the component usage').optional(),
-  includePatternAnalysis: z.boolean().default(true).describe('Include pattern-based analysis in addition to axe-core').optional()
+  code: z.string().describe('Source code of a React component or JSX snippet to analyze (string content only—no file path).'),
+  componentName: z.string().optional().describe('Optional label for the component under review (for summaries and reports).'),
+  context: z.string().optional().describe('Optional: how the component is used (e.g. in a form, modal) to improve suggestions.'),
+  includePatternAnalysis: z.boolean().default(true).describe('When true (default), runs regex-based heuristics on the code string (e.g. unlabeled buttons, missing alt) in addition to other analysis.').optional()
 });
 export const listAnalyzeA11yTool = {
   name: 'ads_analyze_a11y',
-  description: 'Analyze React component code for accessibility violations using axe-core and generate ADS-specific suggestions.',
+  description: `Analyzes a **string of React/JSX** code for likely accessibility issues (heuristics and/or axe-related paths) and returns hints that often **point to** \`ads_suggest_a11y_fixes\` or generic axe/WCAG-style context—not every finding maps to a specific ADS component fix.
+
+WHEN TO USE:
+You have component source as text and want automated checks or heuristics before or during a code review.
+
+LIMITATIONS:
+- Does not replace testing in a real browser with assistive technologies or full keyboard traversal.
+- For rendered UI, \`ads_analyze_localhost_a11y\` (live URL + axe) is preferable when available—it is **only exposed when this MCP runs locally**, not in the remote MCP deployment.`,
   annotations: {
-    title: 'Analyze Accessibility',
+    title: 'Analyze accessibility (code string)',
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,
@@ -24,16 +31,25 @@ export const listAnalyzeA11yTool = {
   inputSchema: zodToJsonSchema(analyzeA11yInputSchema)
 };
 export const analyzeA11yLocalhostInputSchema = z.object({
-  url: z.string().describe('The URL to analyze for accessibility (e.g. `http://localhost:9000`)'),
-  componentName: z.string().optional().describe('Name of the component being analyzed'),
-  context: z.string().optional().describe('Additional context about the component usage'),
-  selector: z.string().optional().describe('CSS selector to target a specific element for analysis (e.g. `#my-form` or `[data-role="button"]`)')
+  url: z.string().describe('Fully qualified page URL to load (e.g. `http://localhost:9000` or a dev URL). Must be reachable from this MCP process.'),
+  componentName: z.string().optional().describe('Optional label for reporting (e.g. feature or component under test).'),
+  context: z.string().optional().describe('Optional: route, user flow, or feature context for the analyzed page.'),
+  selector: z.string().optional().describe('Optional CSS selector to scope axe analysis to a subtree (e.g. `#my-form`, `[data-testid="panel"]`). Omit to analyze the whole document.')
 });
 export const listAnalyzeLocalhostA11yTool = {
   name: 'ads_analyze_localhost_a11y',
-  description: `Analyze a live web page for accessibility violations using axe-core and generate ADS-specific suggestions.`,
+  description: `Loads a **live URL** in a headless browser, runs **axe-core**, and returns violations with follow-up hints (often suggesting \`ads_suggest_a11y_fixes\`). Output is anchored in **axe** rule text; remediation may be generic or ADS-biased depending on the violation.
+
+**Availability:** This tool is only registered when the ADS MCP runs **on your machine** (local MCP). It is **not** available in the **remote** MCP offering—use \`ads_analyze_a11y\` on source text there instead.
+
+WHEN TO USE:
+You have a running app or storybook page and need automated accessibility results on **rendered** UI—especially local or staging URLs.
+
+LIMITATIONS:
+- Does not replace manual testing with assistive technologies or keyboard-only navigation.
+- Requires network access to the URL from the environment running the MCP.`,
   annotations: {
-    title: 'Analyze Localhost Accessibility',
+    title: 'Analyze accessibility (live URL)',
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,

package/dist/es2019/tools/get-a11y-guidelines/index.js

@@ -5,13 +5,20 @@ import { zodToJsonSchema } from '../../helpers';
 import { accessibilityGuidelines } from './guidelines';
 const topics = Object.keys(accessibilityGuidelines);
 export const getA11yGuidelinesInputSchema = z.object({
-  topic: z.string().optional().describe('Select the topic to get the accessibility guidelines for: ' + topics.join(', '))
+  topic: z.string().optional().describe('ADS accessibility topic key. Omit to receive all topics and the full guideline bundle. Pass a valid key (see response \`availableTopics\`) or \`general\` for a focused overview when supported. Known topics: ' + topics.join(', ') + '.')
 });
 export const listGetA11yGuidelinesTool = {
   name: 'ads_get_a11y_guidelines',
-  description: 'Get accessibility guidelines and best practices from the Atlassian Design System.',
+  description: `Returns Atlassian Design System (ADS) accessibility guidance: best practices and patterns for buttons, interactions, color contrast, forms, and other design-system topics shipped in this tool.
+
+Use this alongside the Context Engine MCP tool \`get_accessibility_docs\` for Atlassian-wide accessibility standards (e.g. A11YKB); this tool supplies ADS-specific component and pattern guidance.
+
+WHEN TO USE:
+You MUST call this when generating or substantially changing a new interactive or visual user interface built with ADS, or when you need topic-specific ADS guidance (e.g. focus, forms, motion).
+
+DO NOT rely on generic web accessibility advice alone—ADS conventions may differ. Use \`get_accessibility_docs\` for org-wide standards and this tool for ADS-topic guidance.`,
   annotations: {
-    title: 'Get Accessibility Guidelines',
+    title: 'Get ADS accessibility guidelines',
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,

package/dist/es2019/tools/{get-components → get-all-components}/index.js

@@ -3,9 +3,14 @@
 import { z } from 'zod';
 import { zodToJsonSchema } from '../../helpers';
 import { loadAllComponents } from './load-all-components';
-export const listGetComponentsTool = {
-  name: 'ads_get_components',
-  description: `Fetch all Atlassian Design System components. Only use when \`ads_search_components\` does not return what you're looking for.`,
+export const listGetAllComponentsTool = {
+  name: 'ads_get_all_components',
+  description: `Returns **every** Atlassian Design System component record as separate JSON text chunks (full catalog; large payload).
+
+WHEN TO USE:
+Last resort when \`ads_plan\` / \`ads_search_components\` is insufficient and you must enumerate all components. Prefer search for normal component picking.
+
+No parameters.`,
   annotations: {
     title: 'Get all ADS components',
     readOnlyHint: true,
@@ -15,7 +20,7 @@ export const listGetComponentsTool = {
   },
   inputSchema: zodToJsonSchema(z.object({}))
 };
-export const getComponentsTool = async () => {
+export const getAllComponentsTool = async () => {
   return {
     content: loadAllComponents().map(component => ({
       // NOTE: Ideally one day the MCP would support structured content…

package/dist/es2019/tools/get-all-icons/index.js

@@ -5,7 +5,12 @@ import { zodToJsonSchema } from '../../helpers';
 import { icons } from './icons';
 export const listGetAllIconsTool = {
   name: 'ads_get_all_icons',
-  description: "Fetch all Atlassian Design System icons. Only use when `ads_search_icons` does not return what you're looking for.",
+  description: `Returns **every** ADS icon record as separate JSON text chunks (full catalog; large payload).
+
+WHEN TO USE:
+Last resort when \`ads_plan\` / \`ads_search_icons\` is insufficient and you must enumerate all icons. Prefer search for normal icon picking.
+
+No parameters.`,
   annotations: {
     title: 'Get all ADS icons',
     readOnlyHint: true,

package/dist/es2019/tools/get-all-tokens/index.js

@@ -6,7 +6,12 @@ import { zodToJsonSchema } from '../../helpers';
 const inputSchema = z.object({});
 export const listGetAllTokensTool = {
   name: 'ads_get_all_tokens',
-  description: "Fetch all Atlassian Design System tokens. Only use when `ads_search_tokens` does not return what you're looking for.",
+  description: `Returns **every** ADS design token from bundled metadata (name, example value, usage guidelines)—one JSON object per token, **very large** output.
+
+WHEN TO USE:
+Last resort when \`ads_plan\` / \`ads_search_tokens\` cannot answer the question and you need the full list (e.g. exhaustive audit). Prefer targeted search for normal development.
+
+No parameters.`,
   annotations: {
     title: 'Get all ADS tokens',
     readOnlyHint: true,

package/dist/es2019/tools/get-guidelines/index.js

@@ -5,19 +5,32 @@ import { z } from 'zod';
 import { cleanQuery, zodToJsonSchema } from '../../helpers';
 import { guidelinesStructuredContent } from './guidelines-structured-content.codegen';
 export const getGuidelinesInputSchema = z.object({
-  terms: z.array(z.string()).default([]).describe('An array of search terms to find content guidelines by keywords or content, eg. `["messages", "empty state", "voice tone"]`. If empty or not provided, returns all guidelines.').optional(),
-  limit: z.number().default(1).describe('Maximum number of results per search term in the array (default: 1)').optional()
+  terms: z.array(z.string()).default([]).describe('Search terms matched against guideline keywords and body (fuzzy). Examples: `["empty state", "voice tone"]`, `["color tokens", "spacing"]`, `["elevation", "grid"]`. Omit or use an empty array to return **all** guidelines as Markdown.').optional(),
+  limit: z.number().default(1).describe('Max matches **per term** when `terms` is non-empty (default 1). Ignored when returning all guidelines.').optional()
 });
 export const listGetGuidelinesTool = {
   name: 'ads_get_guidelines',
-  description: `Get Atlassian Design System content guidelines (foundations content) with optional search functionality.
+  description: `Returns Atlassian Design System (ADS) **foundations** guidelines as Markdown: the bundled design-system-docs foundations set (not component API docs).
 
-- If search parameters are provided, searches for guidelines matching the criteria by keywords or content.
-- If no search parameters are provided, returns all guidelines.
+TOPIC COVERAGE:
+- **Content & UX writing**: messaging types (empty state, error, success, warning, info, feature discovery), voice and tone, inclusive language, grammar and style, date/time copy handoff, vocabulary pointers.
+- **Visual foundations**: color (roles, accents, palette, charts, pickers), borders and radius, elevation and z-index, spacing and layout primitives (box/inline/stack), grid, iconography, logos.
+- **Design tokens**: concepts, themes, migration, using tokens in code and in Figma.
+- **Typography**: typefaces, scale, applying text styles and tokens.
+- **Accessibility overview**: building accessible apps and related foundations pages bundled here.
 
-Example: use this tool to look up content guidance for designing messages, voice and tone, date and time, inclusive writing, or language and grammar.`,
+When working with content, use this tool alongside the Context Engine MCP tool \`get_content_standards_docs\` for Atlassian-wide content standards (CDSTD/BAIT-style org guidance); this tool supplies ADS-specific foundations.
+
+WHAT YOU GET:
+- With \`terms\`: fuzzy search over keywords and content; concatenated Markdown for matches.
+- Without \`terms\` (or empty): the full guideline set as Markdown.
+
+WHEN TO USE:
+Use this when you are **building or updating a visual interface**, **writing or reviewing user-facing copy**, or need to **answer foundations questions** about ADS: content patterns, visual appearance, design tokens, typography, spacing, color, grid, motion, and related topics shipped in this bundle.
+
+It is **not** for picking a component’s props or package (use \`ads_plan\` / \`ads_search_components\`) or for interactive accessibility rules and patterns (use \`ads_get_a11y_guidelines\`, with Context Engine \`get_accessibility_docs\` for org-wide a11y standards).`,
   annotations: {
-    title: 'Get ADS guidelines',
+    title: 'Get ADS guidelines (content, a11y, visual design, design tokens, typography)',
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,

package/dist/es2019/tools/get-lint-rules/index.js

@@ -5,20 +5,24 @@ import { z } from 'zod';
 import { cleanQuery, zodToJsonSchema } from '../../helpers';
 import { lintRulesMcpStructuredContent } from './lint-rules-structured-content.codegen';
 export const getLintRulesInputSchema = z.object({
-  terms: z.array(z.string()).default([]).describe('An array of search terms to find lint rules by name or description, eg. `["icon-label", "xcss", "design token"]`. If empty or not provided, returns all lint rules.').optional(),
-  limit: z.number().default(1).describe('Maximum number of results per search term in the array (default: 1)').optional(),
-  exactName: z.boolean().default(false).describe('Enable to explicitly search lint rules by the exact rule name match (when you know the rule name, but need more details)').optional()
+  terms: z.array(z.string()).default([]).describe('Search terms matched against rule name, description, and docs body (fuzzy unless \`exactName\` is true). Example: `["icon-label", "xcss", "design token"]`. Omit or empty: return **all** rules as JSON.').optional(),
+  limit: z.number().default(1).describe('Max matches **per term** when searching (default 1). Not used when returning all rules.').optional(),
+  exactName: z.boolean().default(false).describe('If true, resolve each term by **exact** ESLint rule name (case-insensitive). If false, fuzzy search across name, description, and content.').optional()
 });
 export const listGetLintRulesTool = {
   name: 'ads_get_lint_rules',
-  description: `Get Atlassian Design System ESLint rule documentation (constellation) with optional search functionality.
+  description: `Returns documentation for **Constellation** (Atlassian Design System) ESLint rules shipped with this MCP—rule purpose, examples, and fixes where available.
 
-- If search parameters are provided, searches for lint rules matching the criteria.
-- If no search parameters are provided, returns all lint rules.
+WHAT YOU GET:
+- No \`terms\`: JSON array of all rule payloads.
+- With \`terms\`: fuzzy search (or exact rule name when \`exactName\` is true); JSON for one or more matching rules.
 
-Example: use this tool to look up documentation for rules like icon-label, ensure-proper-xcss-usage, or no-deprecated-apis.`,
+WHEN TO USE:
+Explaining or fixing an ESLint message from ADS rules (e.g. \`icon-label\`, \`ensure-proper-xcss-usage\`, \`no-deprecated-apis\`), or browsing rule docs without opening the repo. Prefer this over guessing from rule id alone.
+
+This tool does not run ESLint; it only returns bundled documentation.`,
   annotations: {
-    title: 'Get ADS lint rules',
+    title: 'Get ADS ESLint rule docs',
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,

package/dist/es2019/tools/i18n-conversion/index.js

@@ -4,25 +4,22 @@ import { z } from 'zod';
 import { zodToJsonSchema } from '../../helpers';
 import { i18nConversionGuide } from './guide';
 export const i18nConversionInputSchema = z.object({
-  guide: z.enum(['hardcoded-string-to-formatmessage']).describe('The i18n conversion guide to retrieve.')
+  guide: z.enum(['hardcoded-string-to-formatmessage']).describe('Which bundled guide to return. Currently only `hardcoded-string-to-formatmessage` (JSX literals → `formatMessage` / intl patterns).')
 });
 export const listI18nConversionTool = {
   name: 'ads_i18n_conversion_guide',
-  description: `Provides comprehensive guide for converting hardcoded strings to use formatMessage from @atlassian/jira-intl or react-intl-next.
+  description: `Returns a **bundled** step-by-step guide for replacing hardcoded UI strings with \`formatMessage\` (and related patterns) using @atlassian/jira-intl or react-intl-next: message constants, placeholders, descriptions, and scope/limitations for systematic refactors.
 
-**TRIGGER**: Use this tool when you encounter:
-- "fix hardcoded string" / "fix hardcoded strings" / "fix hardcoded string in [file]"
-- "convert hardcoded string" / "convert to i18n" / "convert to formatMessage"
-- "translate string" / "internationalize string" / "i18n this string"
-- "use formatMessage" / "use FormattedMessage" / "wrap in formatMessage"
-- "literal string" / "fix literal string" / "convert literal string"
-- ESLint errors: "Literal string in JSX content should be internationalized. Use FormattedMessage or intl.formatMessage()"
-- ESLint errors: "@atlassian/i18n/no-literal-string-in-jsx"
-- Requests to convert hardcoded strings to i18n messages
+When working with i18n or hardcoded UI strings, use this tool alongside the Context Engine MCP tool \`get_i18n_docs\` for Atlassian-wide Traduki / i18n standards (message definition, extraction, pluralisation, formatting, workflow); this tool supplies the concrete hardcoded-string → \`formatMessage\` playbook bundled in ADS MCP.
 
-This tool helps LLM agents systematically convert hardcoded strings while respecting scope limitations and following best practices for message constants, placeholders, and descriptions.`,
+WHEN TO USE / TYPICAL TRIGGERS:
+- Refactoring JSX or TS literals to i18n; "fix hardcoded string(s)", "convert hardcoded string in [file]", "literal string in JSX".
+- "Convert to i18n", "convert to formatMessage", "translate this string", "internationalize this string", "i18n this string".
+- "Use formatMessage", "use FormattedMessage", "wrap in formatMessage", "fix literal string".
+- ESLint: \`Literal string in JSX content should be internationalized. Use FormattedMessage or intl.formatMessage()\`.
+- ESLint: \`@atlassian/i18n/no-literal-string-in-jsx\`.`,
   annotations: {
-    title: 'i18n Conversion Guide',
+    title: 'i18n conversion guide',
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,