@atlaskit/ads-mcp 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @atlaskit/ads-mcp
 
+## 1.3.0
+
+### Minor Changes
+
+- [`f5a335ff3aa42`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/f5a335ff3aa42) -
+  Improve MCP tool routing guidance for ADS and public Atlaskit package fallback research.
+
+### Patch Changes
+
+- Updated dependencies
+
 ## 1.2.1
 
 ### Patch Changes

package/README.md

@@ -21,6 +21,7 @@ to help ensure your interfaces are accessible to all users.
 
 - [Available Tools](#available-tools)
   - [Design System Tools](#design-system-tools)
+  - [Atlaskit Fallback Research Tools](#atlaskit-fallback-research-tools)
   - [Accessibility Tools](#accessibility-tools)
 - [Accessibility Features](#accessibility-features)
   - [Example Usage](#example-usage)
@@ -54,46 +55,74 @@ to help ensure your interfaces are accessible to all users.
 
 - `ads_get_all_tokens` - Get all available design tokens for colors, spacing, typography, etc.
 - `ads_search_tokens` - Search for specific design tokens by name, description, or example values
-- `ads_get_all_components` - Get all available components with basic information (full catalog)
-- `ads_search_components` - Search for components by name, description, category, or package name
+- `ads_get_all_components` - Get all canonical ADS components with basic information (full catalog)
+- `ads_search_components` - Search canonical ADS components by name, description, category, or
+  package name
 - `ads_get_all_icons` - Get all available icons from the design system
 - `ads_search_icons` - Search for specific icons by name, keywords, or categorization
 - `ads_plan` - Search for multiple design system resources (tokens, icons, components) in a single
   efficient operation
 
+Use `ads_*` tools first for standard UI work. They are the canonical source for ADS components,
+tokens, icons, foundations, accessibility, lint rules, i18n, and migrations.
+
+### Atlaskit Fallback Research Tools
+
+- `atlaskit_get_components` - Get a compact inventory of public `@atlaskit/*` component packages
+  outside the ADS catalog
+- `atlaskit_search_components` - Search non-ADS public `@atlaskit/*` components with examples and
+  props
+- `atlaskit_get_hooks` - Get a compact inventory of public `@atlaskit/*` hooks outside the ADS
+  catalog
+- `atlaskit_search_hooks` - Search non-ADS public `@atlaskit/*` hooks with usage details
+- `atlaskit_get_utilities` - Get a compact inventory of public `@atlaskit/*` utilities outside the
+  ADS catalog
+- `atlaskit_search_utilities` - Search non-ADS public `@atlaskit/*` utilities with usage details
+
+Use `atlaskit_*` tools for fallback research when an ADS search has no useful match, or when you are
+looking for a public `@atlaskit/*` package that is not part of ADS. Do not treat Atlaskit results as
+equal-priority replacements for ADS components in standard UI decisions.
+
 #### Design System Tools Usage
 
 ```typescript
-// Search for components (recommended approach)
-const buttonComponents = await search_components({
+// Search for canonical ADS components (recommended approach)
+const buttonComponents = await ads_search_components({
 	terms: ['button', 'click'],
 	limit: 3,
 });
 
 // Search for specific tokens
-const colorTokens = await search_tokens({
+const colorTokens = await ads_search_tokens({
 	terms: ['color.text', 'primary'],
 	limit: 5,
 });
 
 // Search for icons
-const addIcons = await search_icons({
+const addIcons = await ads_search_icons({
 	terms: ['add', 'plus', 'create'],
 	limit: 2,
 });
 
 // Search for multiple resources at once (most efficient for complex UI patterns)
-const designResources = await plan({
-	tokens_search: ['color.text', 'space.100', 'radius.small'],
-	icons_search: ['add', 'edit', 'delete'],
-	components_search: ['Button', 'TextField', 'Modal'],
+const designResources = await ads_plan({
+	tokens: ['color.text', 'space.100', 'radius.small'],
+	icons: ['add', 'edit', 'delete'],
+	components: ['Button', 'TextField', 'Modal'],
+	atlaskitComponents: [],
+	limit: 2,
+});
+
+// Search public @atlaskit/* packages only when ADS has no useful match
+const atlaskitComponents = await atlaskit_search_components({
+	terms: ['editor-core', 'onboarding'],
 	limit: 2,
 });
 
 // Get all available items (fallback when search doesn't find what you need)
-const allComponents = await get_all_components();
-const allTokens = await get_all_tokens();
-const allIcons = await get_all_icons();
+const allComponents = await ads_get_all_components();
+const allTokens = await ads_get_all_tokens();
+const allIcons = await ads_get_all_icons();
 ```
 
 ### Accessibility Tools
@@ -124,19 +153,19 @@ The ADS MCP server includes comprehensive accessibility analysis and guidance:
 
 ```typescript
 // Analyze a component for accessibility issues using axe-core
-const analysis = await analyze_a11y({
+const analysis = await ads_analyze_a11y({
 	code: `<button onClick={handleClose}><CloseIcon /></button>`,
 	componentName: 'CloseButton',
 	includePatternAnalysis: true, // Also include pattern-based analysis
 });
 
 // Get specific accessibility guidelines
-const guidelines = await get_a11y_guidelines({
+const guidelines = await ads_get_a11y_guidelines({
 	topic: 'buttons',
 });
 
 // Get fix suggestions for a violation
-const fixes = await suggest_a11y_fixes({
+const fixes = await ads_suggest_a11y_fixes({
 	violation: 'Button missing accessible label',
 	code: `<button onClick={handleClose}><CloseIcon /></button>`,
 });

package/dist/cjs/instructions.js

@@ -4,4 +4,4 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.instructions = void 0;
-var instructions = exports.instructions = "\nYou are an expert in the Atlassian Design System (ADS).\nYou can search for tokens, icons, and components and return guidance on how to build user interfaces.\nYou have special accessibility knowledge and can ensure interfaces built with ADS components are accessible to all users.\nYou can analyze code for accessibility violations, provide specific fix suggestions, and offer guidance on accessibility best practices.\nFor 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).\nThese 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.\n";
+var instructions = exports.instructions = "\nYou are an expert in the Atlassian Design System (ADS).\nYou can search for tokens, icons, and components and return guidance on how to build user interfaces.\nUse ads_* tools for canonical ADS resources: components, tokens, icons, foundations, accessibility, lint rules, i18n, and migrations.\nUse atlaskit_* tools only for further research into public @atlaskit/* scoped packages that are not covered by the ADS catalog, such as non-ADS components, hooks, and utilities. Prefer ADS resources first for standard UI.\nYou have special accessibility knowledge and can ensure interfaces built with ADS components are accessible to all users.\nYou can analyze code for accessibility violations, provide specific fix suggestions, and offer guidance on accessibility best practices.\nFor 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).\nThese 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.\n";

package/dist/cjs/tools/get-all-components/list-get-all-components-tool.js

@@ -10,7 +10,7 @@ var _zodToJsonSchema = require("../../helpers/zod-to-json-schema");
 
 var listGetAllComponentsTool = exports.listGetAllComponentsTool = {
   name: 'ads_get_all_components',
-  description: "Returns **every** Atlassian Design System component record as separate JSON text chunks (full catalog; large payload).\n\nWHEN TO USE:\nLast resort when `ads_plan` / `ads_search_components` is insufficient and you must enumerate all components. Prefer search for normal component picking.\n\nNo parameters.",
+  description: "Returns **every** canonical Atlassian Design System (ADS) component record as separate JSON text chunks (full catalog; large payload). For non-ADS public `@atlaskit/*` packages, use `atlaskit_get_components` or `atlaskit_search_components`.\n\nWHEN TO USE:\nLast resort when `ads_plan` / `ads_search_components` is insufficient and you must enumerate all components. Prefer search for normal component picking.\n\nNo parameters.",
   annotations: {
     title: 'Get all ADS components',
     readOnlyHint: true,

package/dist/cjs/tools/get-atlaskit-components/list-get-atlaskit-components-tool.js

@@ -10,7 +10,7 @@ var _helpers = require("../../helpers");
 
 var listGetAtlaskitComponentsTool = exports.listGetAtlaskitComponentsTool = {
   name: 'atlaskit_get_components',
-  description: "Returns the names and packages of all atlaskit components excluding components covered by the Atlassian Design System.\n\nWHEN TO USE:\nUse this when you want to see what components are available without the full metadata payload.\n\nNo parameters.",
+  description: "Returns a compact inventory of public `@atlaskit/*` component packages that are not covered by the Atlassian Design System (ADS) component catalog. Output is names and packages only.\n\nWHEN TO USE:\nUse this for fallback discovery after ADS component search is not enough, or when you need to see which non-ADS `@atlaskit/*` components are available without the full metadata payload. For implementation examples and props, use `atlaskit_search_components`.\n\nNo parameters.",
   annotations: {
     title: 'Get all Atlaskit components',
     readOnlyHint: true,

package/dist/cjs/tools/get-atlaskit-hooks/list-get-atlaskit-hooks-tool.js

@@ -10,7 +10,7 @@ var _helpers = require("../../helpers");
 
 var listGetAtlaskitHooksTool = exports.listGetAtlaskitHooksTool = {
   name: 'atlaskit_get_hooks',
-  description: "Returns the names and packages of all atlaskit hooks excluding hooks covered by the Atlassian Design System.\n\nWHEN TO USE:\nUse this when you want to see what hooks are available without the full metadata payload.\n\nNo parameters.",
+  description: "Returns a compact inventory of public `@atlaskit/*` hooks that are not covered by the Atlassian Design System (ADS) catalog. Output is names and packages only.\n\nWHEN TO USE:\nUse this for fallback discovery when you need a non-ADS `@atlaskit/*` hook inventory without the full metadata payload. For usage guidance, parameters, and return values, use `atlaskit_search_hooks`.\n\nNo parameters.",
   annotations: {
     title: 'Get all Atlaskit hooks',
     readOnlyHint: true,

package/dist/cjs/tools/get-atlaskit-utilities/list-get-atlaskit-utilities-tool.js

@@ -10,7 +10,7 @@ var _helpers = require("../../helpers");
 
 var listGetAtlaskitUtilitiesTool = exports.listGetAtlaskitUtilitiesTool = {
   name: 'atlaskit_get_utilities',
-  description: "Returns the names and packages of all atlaskit utilities (functions, constants, types) excluding utilities covered by the Atlassian Design System.\n\nWHEN TO USE:\nUse this when you want to see what utilities are available without the full metadata payload.\n\nNo parameters.",
+  description: "Returns a compact inventory of public `@atlaskit/*` utilities (functions, constants, types) that are not covered by the Atlassian Design System (ADS) catalog. Output is names and packages only.\n\nWHEN TO USE:\nUse this for fallback discovery when you need a non-ADS `@atlaskit/*` utility inventory without the full metadata payload. For usage guidance and signatures, use `atlaskit_search_utilities`.\n\nNo parameters.",
   annotations: {
     title: 'Get all Atlaskit utilities',
     readOnlyHint: true,

package/dist/cjs/tools/plan/list-plan-tool.js

@@ -10,7 +10,7 @@ var _planInputSchema = require("./plan-input-schema");
 
 var listPlanTool = exports.listPlanTool = {
   name: 'ads_plan',
-  description: "Runs **ads_search_tokens**, **ads_search_icons**, **ads_search_components**, and **ads_search_atlaskit_components** in one call and returns a single JSON payload (each section only if that list was non-empty). Use this as the default way to discover ADS **tokens**, **icons**, and **components** (including legacy/broader Atlaskit) for a UI task.\n\nWHEN TO USE:\n**Implementing or iterating on a UI**\u2014new screen, feature, or polish\u2014and you need candidate **token** names, **icon** imports, and **component** packages/props in one pass. Also use when exploring ADS building blocks before you write code.\n\nAt least one of `tokens`, `icons`, `components`, or `atlaskitComponents` must contain search terms (use `[]` for lists you do not need).\n\nPrefer supplying **multiple** terms per non-empty array when you know them\u2014broader queries improve recall. Some queries return no rows where metadata is thin; try alternate wording.\n\nThis is equivalent to calling the individual search tools; there are no extra merge semantics beyond concatenating results.\n\nExample request:\n```json\n{\n\t\"tokens\": [\"spacing\", \"inverted text\", \"background primary\", \"animation\"],\n\t\"icons\": [\"search\", \"folder\", \"user\"],\n\t\"components\": [\"button\", \"input\", \"select\", \"heading\"],\n\t\"atlaskitComponents\": [\"inline-dialog\", \"onboarding\", \"page-layout\"]\n}\n```\n\nExample token usage:\n```tsx\nimport { token } from '@atlaskit/tokens';\nconst styles = css({ color: token('color.text'), padding: token('space.100') });\n```\n\nExample icon usage:\n```tsx\nimport AddIcon from '@atlaskit/icon/core/add';\n<AddIcon label=\"Add work item\" size=\"small\" />\n```",
+  description: "Runs **ads_search_tokens**, **ads_search_icons**, **ads_search_components**, and optionally **atlaskit_search_components** in one call and returns a single JSON payload (each section only if that list was non-empty). Use this as the default way to discover ADS **tokens**, **icons**, and **components** for a UI task.\n\nWHEN TO USE:\n**Implementing or iterating on a UI**\u2014new screen, feature, or polish\u2014and you need candidate **token** names, **icon** imports, and **ADS component** packages/props in one pass. Also use when exploring ADS building blocks before you write code.\n\nADS-FIRST ROUTING:\nUse `components` for canonical ADS components. Use `atlaskitComponents` only as explicit fallback research for public `@atlaskit/*` packages outside the ADS catalog, or after ADS component search has no useful match. This tool does not auto-populate `atlaskitComponents` from `components`.\n\nAt least one of `tokens`, `icons`, `components`, or `atlaskitComponents` must contain search terms (use `[]` for lists you do not need).\n\nPrefer supplying **multiple** terms per non-empty array when you know them\u2014broader queries improve recall. Some queries return no rows where metadata is thin; try alternate wording.\n\nThis is equivalent to calling the individual search tools; there are no extra merge semantics beyond concatenating results.\n\nExample request:\n```json\n{\n\t\"tokens\": [\"spacing\", \"inverted text\", \"background primary\", \"animation\"],\n\t\"icons\": [\"search\", \"folder\", \"user\"],\n\t\"components\": [\"button\", \"input\", \"select\", \"heading\"],\n\t\"atlaskitComponents\": [\"editor-core\", \"onboarding\", \"page-layout\"]\n}\n```\n\nExample token usage:\n```tsx\nimport { token } from '@atlaskit/tokens';\nconst styles = css({ color: token('color.text'), padding: token('space.100') });\n```\n\nExample icon usage:\n```tsx\nimport AddIcon from '@atlaskit/icon/core/add';\n<AddIcon label=\"Add work item\" size=\"small\" />\n```",
   annotations: {
     title: 'Search ADS tokens, icons, and components to plan what to build',
     readOnlyHint: true,

package/dist/cjs/tools/plan/plan-input-schema.js

@@ -10,7 +10,7 @@ var _zod = require("zod");
 var planInputSchema = exports.planInputSchema = _zod.z.object({
   tokens: _zod.z.array(_zod.z.string()).describe('Search terms for ADS design tokens (fuzzy by default). Use `[]` if you only need icons or components. Prefer **at least two** terms per non-empty list when you know what you need.'),
   icons: _zod.z.array(_zod.z.string()).describe('Search terms for ADS icons. Use `[]` if you only need tokens or components. Prefer **at least two** terms per non-empty list when known.'),
-  components: _zod.z.array(_zod.z.string()).describe('Search terms for ADS components. Use `[]` if you only need tokens or icons. Prefer **at least two** terms per non-empty list when known.'),
-  atlaskitComponents: _zod.z.array(_zod.z.string()).describe('Search terms for Atlaskit components. Use `[]` if you only need core ADS components. Prefer **at least two** terms per non-empty list when known.'),
-  limit: _zod.z.number().default(2).describe('Max matches **per term** for each non-empty list (default 2). Same limit applies to tokens, icons, and both ADS and atlaskit component searches.').optional()
+  components: _zod.z.array(_zod.z.string()).describe('Search terms for canonical ADS components. Use `[]` if you only need tokens, icons, or explicit Atlaskit fallback research. Prefer **at least two** terms per non-empty list when known.'),
+  atlaskitComponents: _zod.z.array(_zod.z.string()).describe('Search terms for public `@atlaskit/*` components outside the ADS catalog. Use only as explicit fallback research when ADS component search is not enough; this is not auto-populated from `components`. Use `[]` if you only need canonical ADS components. Prefer **at least two** terms per non-empty list when known.'),
+  limit: _zod.z.number().default(2).describe('Max matches **per term** for each non-empty list (default 2). Same limit applies to tokens, icons, ADS components, and explicit Atlaskit component fallback searches.').optional()
 });

package/dist/cjs/tools/plan/plan-tool.js

@@ -29,7 +29,7 @@ var planTool = exports.planTool = /*#__PURE__*/function () {
             isError: true,
             content: [{
               type: 'text',
-              text: 'Error: At least one search type (tokens_search, icons_search, components_search, or atlaskit_components_search) must be provided with search terms'
+              text: 'Error: At least one search type (tokens, icons, components, or atlaskitComponents) must be provided with search terms'
             }]
           });
         case 1:

package/dist/cjs/tools/search-atlaskit-components/list-search-atlaskit-components-tool.js

@@ -10,7 +10,7 @@ var _searchAtlaskitComponentsInputSchema = require("./search-atlaskit-components
 
 var listSearchAtlaskitComponentsTool = exports.listSearchAtlaskitComponentsTool = {
   name: 'atlaskit_search_components',
-  description: "Searches the bundled Atlaskit component catalog. Returns JSON objects with **name**, **package**, **examples**, and **props** for each match (trimmed payload).\n\nWHEN TO USE:\n**Selecting which Atlaskit component to use**\u2014package name, examples, and props\u2014before implementation. Use when searching for specific Atlaskit components that might not be in the core ADS catalog.",
+  description: "Searches the bundled public `@atlaskit/*` component catalog outside the Atlassian Design System (ADS) component catalog. Returns JSON objects with **name**, **package**, **examples**, and **props** for each match (trimmed payload).\n\nWHEN TO USE:\nUse this for fallback research when `ads_search_components` or `ads_plan.components` does not find a useful ADS component, or when the user asks about a specific public `@atlaskit/*` package that is not part of ADS. Prefer canonical ADS components first for standard UI.",
   annotations: {
     title: 'Search Atlaskit components',
     readOnlyHint: true,

package/dist/cjs/tools/search-atlaskit-hooks/list-search-atlaskit-hooks-tool.js

@@ -10,7 +10,7 @@ var _searchAtlaskitHooksInputSchema = require("./search-atlaskit-hooks-input-sch
 
 var listSearchAtlaskitHooksTool = exports.listSearchAtlaskitHooksTool = {
   name: 'atlaskit_search_hooks',
-  description: "Search for atlaskit hooks by name, package, category, description, or keywords.\n\nWHEN TO USE:\nUse this when you want to find a hook but don't know its exact name or package.",
+  description: "Search public `@atlaskit/*` hooks outside the Atlassian Design System (ADS) catalog by name, package, category, description, or keywords.\n\nWHEN TO USE:\nUse this for fallback research when you want to find a non-ADS `@atlaskit/*` hook but do not know its exact name or package.",
   annotations: {
     title: 'Search Atlaskit hooks',
     readOnlyHint: true,

package/dist/cjs/tools/search-atlaskit-utilities/list-search-atlaskit-utilities-tool.js

@@ -10,7 +10,7 @@ var _searchAtlaskitUtilitiesInputSchema = require("./search-atlaskit-utilities-i
 
 var listSearchAtlaskitUtilitiesTool = exports.listSearchAtlaskitUtilitiesTool = {
   name: 'atlaskit_search_utilities',
-  description: "Search for atlaskit utilities (functions, constants, types) by name, package, category, description, or keywords.\n\nWHEN TO USE:\nUse this when you want to find a utility but don't know its exact name or package.",
+  description: "Search public `@atlaskit/*` utilities (functions, constants, types) outside the Atlassian Design System (ADS) catalog by name, package, category, description, or keywords.\n\nWHEN TO USE:\nUse this for fallback research when you want to find a non-ADS `@atlaskit/*` utility but do not know its exact name or package.",
   annotations: {
     title: 'Search Atlaskit utilities',
     readOnlyHint: true,

package/dist/cjs/tools/search-components/list-search-components-tool.js

@@ -10,7 +10,7 @@ var _searchComponentsInputSchema = require("./search-components-input-schema");
 
 var listSearchComponentsTool = exports.listSearchComponentsTool = {
   name: 'ads_search_components',
-  description: "Searches the bundled Atlassian Design System (ADS) component catalog. Returns JSON objects with **name**, **package**, **examples**, and **props** for each match (trimmed payload).\n\nWHEN TO USE:\n**Selecting which ADS component to use**\u2014package name, examples, and props\u2014before implementation. Use when composing a new view or swapping a primitive. Prefer `ads_plan` when you also need token and icon discovery in one shot.",
+  description: "Searches the bundled Atlassian Design System (ADS) component catalog. Returns JSON objects with **name**, **package**, **examples**, and **props** for each match (trimmed payload).\n\nWHEN TO USE:\n**Selecting which canonical ADS component to use**\u2014package name, examples, and props\u2014before implementation. Use when composing a new view or swapping a primitive. Prefer `ads_plan` when you also need token and icon discovery in one shot.\n\nIf you are looking for a public `@atlaskit/*` scoped package that is not part of the ADS component catalog, use `atlaskit_search_components` for fallback research instead of this ADS-only search.",
   annotations: {
     title: 'Search ADS components',
     readOnlyHint: true,

package/dist/cjs/tools/search-components/search-components-tool.js

@@ -93,7 +93,7 @@ var searchComponentsTool = exports.searchComponentsTool = /*#__PURE__*/function
           return _context.abrupt("return", {
             content: [{
               type: 'text',
-              text: "Error: No components found for '".concat(terms.join(', '), "'. Available components: ").concat(components.map(function (c) {
+              text: "Error: No ADS components found for '".concat(terms.join(', '), "'. If this is a public @atlaskit/* package outside the ADS catalog, call atlaskit_search_components with the same terms. Available ADS components: ").concat(components.map(function (c) {
                 return c.name;
               }).join(', '))
             }]

package/dist/es2019/instructions.js

@@ -1,6 +1,8 @@
 export const instructions = `
 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.
+Use ads_* tools for canonical ADS resources: components, tokens, icons, foundations, accessibility, lint rules, i18n, and migrations.
+Use atlaskit_* tools only for further research into public @atlaskit/* scoped packages that are not covered by the ADS catalog, such as non-ADS components, hooks, and utilities. Prefer ADS resources first for standard UI.
 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.
 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).

package/dist/es2019/tools/get-all-components/list-get-all-components-tool.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
 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).
+  description: `Returns **every** canonical Atlassian Design System (ADS) component record as separate JSON text chunks (full catalog; large payload). For non-ADS public \`@atlaskit/*\` packages, use \`atlaskit_get_components\` or \`atlaskit_search_components\`.
 
 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.

package/dist/es2019/tools/get-atlaskit-components/list-get-atlaskit-components-tool.js

@@ -4,10 +4,10 @@ import { z } from 'zod';
 import { zodToJsonSchema } from '../../helpers';
 export const listGetAtlaskitComponentsTool = {
   name: 'atlaskit_get_components',
-  description: `Returns the names and packages of all atlaskit components excluding components covered by the Atlassian Design System.
+  description: `Returns a compact inventory of public \`@atlaskit/*\` component packages that are not covered by the Atlassian Design System (ADS) component catalog. Output is names and packages only.
 
 WHEN TO USE:
-Use this when you want to see what components are available without the full metadata payload.
+Use this for fallback discovery after ADS component search is not enough, or when you need to see which non-ADS \`@atlaskit/*\` components are available without the full metadata payload. For implementation examples and props, use \`atlaskit_search_components\`.
 
 No parameters.`,
   annotations: {

package/dist/es2019/tools/get-atlaskit-hooks/list-get-atlaskit-hooks-tool.js

@@ -4,10 +4,10 @@ import { z } from 'zod';
 import { zodToJsonSchema } from '../../helpers';
 export const listGetAtlaskitHooksTool = {
   name: 'atlaskit_get_hooks',
-  description: `Returns the names and packages of all atlaskit hooks excluding hooks covered by the Atlassian Design System.
+  description: `Returns a compact inventory of public \`@atlaskit/*\` hooks that are not covered by the Atlassian Design System (ADS) catalog. Output is names and packages only.
 
 WHEN TO USE:
-Use this when you want to see what hooks are available without the full metadata payload.
+Use this for fallback discovery when you need a non-ADS \`@atlaskit/*\` hook inventory without the full metadata payload. For usage guidance, parameters, and return values, use \`atlaskit_search_hooks\`.
 
 No parameters.`,
   annotations: {

package/dist/es2019/tools/get-atlaskit-utilities/list-get-atlaskit-utilities-tool.js

@@ -4,10 +4,10 @@ import { z } from 'zod';
 import { zodToJsonSchema } from '../../helpers';
 export const listGetAtlaskitUtilitiesTool = {
   name: 'atlaskit_get_utilities',
-  description: `Returns the names and packages of all atlaskit utilities (functions, constants, types) excluding utilities covered by the Atlassian Design System.
+  description: `Returns a compact inventory of public \`@atlaskit/*\` utilities (functions, constants, types) that are not covered by the Atlassian Design System (ADS) catalog. Output is names and packages only.
 
 WHEN TO USE:
-Use this when you want to see what utilities are available without the full metadata payload.
+Use this for fallback discovery when you need a non-ADS \`@atlaskit/*\` utility inventory without the full metadata payload. For usage guidance and signatures, use \`atlaskit_search_utilities\`.
 
 No parameters.`,
   annotations: {

package/dist/es2019/tools/plan/list-plan-tool.js

@@ -4,10 +4,13 @@ import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
 import { planInputSchema } from './plan-input-schema';
 export const listPlanTool = {
   name: 'ads_plan',
-  description: `Runs **ads_search_tokens**, **ads_search_icons**, **ads_search_components**, and **ads_search_atlaskit_components** in one call and returns a single JSON payload (each section only if that list was non-empty). Use this as the default way to discover ADS **tokens**, **icons**, and **components** (including legacy/broader Atlaskit) for a UI task.
+  description: `Runs **ads_search_tokens**, **ads_search_icons**, **ads_search_components**, and optionally **atlaskit_search_components** in one call and returns a single JSON payload (each section only if that list was non-empty). Use this as the default way to discover ADS **tokens**, **icons**, and **components** for a UI task.
 
 WHEN TO USE:
-**Implementing or iterating on a UI**—new screen, feature, or polish—and you need candidate **token** names, **icon** imports, and **component** packages/props in one pass. Also use when exploring ADS building blocks before you write code.
+**Implementing or iterating on a UI**—new screen, feature, or polish—and you need candidate **token** names, **icon** imports, and **ADS component** packages/props in one pass. Also use when exploring ADS building blocks before you write code.
+
+ADS-FIRST ROUTING:
+Use \`components\` for canonical ADS components. Use \`atlaskitComponents\` only as explicit fallback research for public \`@atlaskit/*\` packages outside the ADS catalog, or after ADS component search has no useful match. This tool does not auto-populate \`atlaskitComponents\` from \`components\`.
 
 At least one of \`tokens\`, \`icons\`, \`components\`, or \`atlaskitComponents\` must contain search terms (use \`[]\` for lists you do not need).
 
@@ -21,7 +24,7 @@ Example request:
 	"tokens": ["spacing", "inverted text", "background primary", "animation"],
 	"icons": ["search", "folder", "user"],
 	"components": ["button", "input", "select", "heading"],
-	"atlaskitComponents": ["inline-dialog", "onboarding", "page-layout"]
+	"atlaskitComponents": ["editor-core", "onboarding", "page-layout"]
 }
 \`\`\`
 

package/dist/es2019/tools/plan/plan-input-schema.js

@@ -3,7 +3,7 @@ import { z } from 'zod';
 export const planInputSchema = z.object({
   tokens: z.array(z.string()).describe('Search terms for ADS design tokens (fuzzy by default). Use `[]` if you only need icons or components. Prefer **at least two** terms per non-empty list when you know what you need.'),
   icons: z.array(z.string()).describe('Search terms for ADS icons. Use `[]` if you only need tokens or components. Prefer **at least two** terms per non-empty list when known.'),
-  components: z.array(z.string()).describe('Search terms for ADS components. Use `[]` if you only need tokens or icons. Prefer **at least two** terms per non-empty list when known.'),
-  atlaskitComponents: z.array(z.string()).describe('Search terms for Atlaskit components. Use `[]` if you only need core ADS components. Prefer **at least two** terms per non-empty list when known.'),
-  limit: z.number().default(2).describe('Max matches **per term** for each non-empty list (default 2). Same limit applies to tokens, icons, and both ADS and atlaskit component searches.').optional()
+  components: z.array(z.string()).describe('Search terms for canonical ADS components. Use `[]` if you only need tokens, icons, or explicit Atlaskit fallback research. Prefer **at least two** terms per non-empty list when known.'),
+  atlaskitComponents: z.array(z.string()).describe('Search terms for public `@atlaskit/*` components outside the ADS catalog. Use only as explicit fallback research when ADS component search is not enough; this is not auto-populated from `components`. Use `[]` if you only need canonical ADS components. Prefer **at least two** terms per non-empty list when known.'),
+  limit: z.number().default(2).describe('Max matches **per term** for each non-empty list (default 2). Same limit applies to tokens, icons, ADS components, and explicit Atlaskit component fallback searches.').optional()
 });

package/dist/es2019/tools/plan/plan-tool.js

@@ -17,7 +17,7 @@ export const planTool = async ({
       isError: true,
       content: [{
         type: 'text',
-        text: 'Error: At least one search type (tokens_search, icons_search, components_search, or atlaskit_components_search) must be provided with search terms'
+        text: 'Error: At least one search type (tokens, icons, components, or atlaskitComponents) must be provided with search terms'
       }]
     };
   }

package/dist/es2019/tools/search-atlaskit-components/list-search-atlaskit-components-tool.js

@@ -4,10 +4,10 @@ import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
 import { searchAtlaskitComponentsInputSchema } from './search-atlaskit-components-input-schema';
 export const listSearchAtlaskitComponentsTool = {
   name: 'atlaskit_search_components',
-  description: `Searches the bundled Atlaskit component catalog. Returns JSON objects with **name**, **package**, **examples**, and **props** for each match (trimmed payload).
+  description: `Searches the bundled public \`@atlaskit/*\` component catalog outside the Atlassian Design System (ADS) component catalog. Returns JSON objects with **name**, **package**, **examples**, and **props** for each match (trimmed payload).
 
 WHEN TO USE:
-**Selecting which Atlaskit component to use**—package name, examples, and props—before implementation. Use when searching for specific Atlaskit components that might not be in the core ADS catalog.`,
+Use this for fallback research when \`ads_search_components\` or \`ads_plan.components\` does not find a useful ADS component, or when the user asks about a specific public \`@atlaskit/*\` package that is not part of ADS. Prefer canonical ADS components first for standard UI.`,
   annotations: {
     title: 'Search Atlaskit components',
     readOnlyHint: true,

package/dist/es2019/tools/search-atlaskit-hooks/list-search-atlaskit-hooks-tool.js

@@ -4,10 +4,10 @@ import { zodToJsonSchema } from '../../helpers';
 import { searchAtlaskitHooksInputSchema } from './search-atlaskit-hooks-input-schema';
 export const listSearchAtlaskitHooksTool = {
   name: 'atlaskit_search_hooks',
-  description: `Search for atlaskit hooks by name, package, category, description, or keywords.
+  description: `Search public \`@atlaskit/*\` hooks outside the Atlassian Design System (ADS) catalog by name, package, category, description, or keywords.
 
 WHEN TO USE:
-Use this when you want to find a hook but don't know its exact name or package.`,
+Use this for fallback research when you want to find a non-ADS \`@atlaskit/*\` hook but do not know its exact name or package.`,
   annotations: {
     title: 'Search Atlaskit hooks',
     readOnlyHint: true,

package/dist/es2019/tools/search-atlaskit-utilities/list-search-atlaskit-utilities-tool.js

@@ -4,10 +4,10 @@ import { zodToJsonSchema } from '../../helpers';
 import { searchAtlaskitUtilitiesInputSchema } from './search-atlaskit-utilities-input-schema';
 export const listSearchAtlaskitUtilitiesTool = {
   name: 'atlaskit_search_utilities',
-  description: `Search for atlaskit utilities (functions, constants, types) by name, package, category, description, or keywords.
+  description: `Search public \`@atlaskit/*\` utilities (functions, constants, types) outside the Atlassian Design System (ADS) catalog by name, package, category, description, or keywords.
 
 WHEN TO USE:
-Use this when you want to find a utility but don't know its exact name or package.`,
+Use this for fallback research when you want to find a non-ADS \`@atlaskit/*\` utility but do not know its exact name or package.`,
   annotations: {
     title: 'Search Atlaskit utilities',
     readOnlyHint: true,

package/dist/es2019/tools/search-components/list-search-components-tool.js

@@ -7,7 +7,9 @@ export const listSearchComponentsTool = {
   description: `Searches the bundled Atlassian Design System (ADS) component catalog. Returns JSON objects with **name**, **package**, **examples**, and **props** for each match (trimmed payload).
 
 WHEN TO USE:
-**Selecting which ADS component to use**—package name, examples, and props—before implementation. Use when composing a new view or swapping a primitive. Prefer \`ads_plan\` when you also need token and icon discovery in one shot.`,
+**Selecting which canonical ADS component to use**—package name, examples, and props—before implementation. Use when composing a new view or swapping a primitive. Prefer \`ads_plan\` when you also need token and icon discovery in one shot.
+
+If you are looking for a public \`@atlaskit/*\` scoped package that is not part of the ADS component catalog, use \`atlaskit_search_components\` for fallback research instead of this ADS-only search.`,
   annotations: {
     title: 'Search ADS components',
     readOnlyHint: true,

package/dist/es2019/tools/search-components/search-components-tool.js

@@ -72,7 +72,7 @@ export const searchComponentsTool = async ({
     return {
       content: [{
         type: 'text',
-        text: `Error: No components found for '${terms.join(', ')}'. Available components: ${components.map(c => c.name).join(', ')}`
+        text: `Error: No ADS components found for '${terms.join(', ')}'. If this is a public @atlaskit/* package outside the ADS catalog, call atlaskit_search_components with the same terms. Available ADS components: ${components.map(c => c.name).join(', ')}`
       }]
     };
   }

package/dist/esm/instructions.js

@@ -1 +1 @@
-export var instructions = "\nYou are an expert in the Atlassian Design System (ADS).\nYou can search for tokens, icons, and components and return guidance on how to build user interfaces.\nYou have special accessibility knowledge and can ensure interfaces built with ADS components are accessible to all users.\nYou can analyze code for accessibility violations, provide specific fix suggestions, and offer guidance on accessibility best practices.\nFor 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).\nThese 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.\n";
+export var instructions = "\nYou are an expert in the Atlassian Design System (ADS).\nYou can search for tokens, icons, and components and return guidance on how to build user interfaces.\nUse ads_* tools for canonical ADS resources: components, tokens, icons, foundations, accessibility, lint rules, i18n, and migrations.\nUse atlaskit_* tools only for further research into public @atlaskit/* scoped packages that are not covered by the ADS catalog, such as non-ADS components, hooks, and utilities. Prefer ADS resources first for standard UI.\nYou have special accessibility knowledge and can ensure interfaces built with ADS components are accessible to all users.\nYou can analyze code for accessibility violations, provide specific fix suggestions, and offer guidance on accessibility best practices.\nFor 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).\nThese 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.\n";

package/dist/esm/tools/get-all-components/list-get-all-components-tool.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
 export var listGetAllComponentsTool = {
   name: 'ads_get_all_components',
-  description: "Returns **every** Atlassian Design System component record as separate JSON text chunks (full catalog; large payload).\n\nWHEN TO USE:\nLast resort when `ads_plan` / `ads_search_components` is insufficient and you must enumerate all components. Prefer search for normal component picking.\n\nNo parameters.",
+  description: "Returns **every** canonical Atlassian Design System (ADS) component record as separate JSON text chunks (full catalog; large payload). For non-ADS public `@atlaskit/*` packages, use `atlaskit_get_components` or `atlaskit_search_components`.\n\nWHEN TO USE:\nLast resort when `ads_plan` / `ads_search_components` is insufficient and you must enumerate all components. Prefer search for normal component picking.\n\nNo parameters.",
   annotations: {
     title: 'Get all ADS components',
     readOnlyHint: true,

package/dist/esm/tools/get-atlaskit-components/list-get-atlaskit-components-tool.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import { zodToJsonSchema } from '../../helpers';
 export var listGetAtlaskitComponentsTool = {
   name: 'atlaskit_get_components',
-  description: "Returns the names and packages of all atlaskit components excluding components covered by the Atlassian Design System.\n\nWHEN TO USE:\nUse this when you want to see what components are available without the full metadata payload.\n\nNo parameters.",
+  description: "Returns a compact inventory of public `@atlaskit/*` component packages that are not covered by the Atlassian Design System (ADS) component catalog. Output is names and packages only.\n\nWHEN TO USE:\nUse this for fallback discovery after ADS component search is not enough, or when you need to see which non-ADS `@atlaskit/*` components are available without the full metadata payload. For implementation examples and props, use `atlaskit_search_components`.\n\nNo parameters.",
   annotations: {
     title: 'Get all Atlaskit components',
     readOnlyHint: true,

package/dist/esm/tools/get-atlaskit-hooks/list-get-atlaskit-hooks-tool.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import { zodToJsonSchema } from '../../helpers';
 export var listGetAtlaskitHooksTool = {
   name: 'atlaskit_get_hooks',
-  description: "Returns the names and packages of all atlaskit hooks excluding hooks covered by the Atlassian Design System.\n\nWHEN TO USE:\nUse this when you want to see what hooks are available without the full metadata payload.\n\nNo parameters.",
+  description: "Returns a compact inventory of public `@atlaskit/*` hooks that are not covered by the Atlassian Design System (ADS) catalog. Output is names and packages only.\n\nWHEN TO USE:\nUse this for fallback discovery when you need a non-ADS `@atlaskit/*` hook inventory without the full metadata payload. For usage guidance, parameters, and return values, use `atlaskit_search_hooks`.\n\nNo parameters.",
   annotations: {
     title: 'Get all Atlaskit hooks',
     readOnlyHint: true,

package/dist/esm/tools/get-atlaskit-utilities/list-get-atlaskit-utilities-tool.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import { zodToJsonSchema } from '../../helpers';
 export var listGetAtlaskitUtilitiesTool = {
   name: 'atlaskit_get_utilities',
-  description: "Returns the names and packages of all atlaskit utilities (functions, constants, types) excluding utilities covered by the Atlassian Design System.\n\nWHEN TO USE:\nUse this when you want to see what utilities are available without the full metadata payload.\n\nNo parameters.",
+  description: "Returns a compact inventory of public `@atlaskit/*` utilities (functions, constants, types) that are not covered by the Atlassian Design System (ADS) catalog. Output is names and packages only.\n\nWHEN TO USE:\nUse this for fallback discovery when you need a non-ADS `@atlaskit/*` utility inventory without the full metadata payload. For usage guidance and signatures, use `atlaskit_search_utilities`.\n\nNo parameters.",
   annotations: {
     title: 'Get all Atlaskit utilities',
     readOnlyHint: true,

package/dist/esm/tools/plan/list-plan-tool.js

@@ -4,7 +4,7 @@ import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
 import { planInputSchema } from './plan-input-schema';
 export var listPlanTool = {
   name: 'ads_plan',
-  description: "Runs **ads_search_tokens**, **ads_search_icons**, **ads_search_components**, and **ads_search_atlaskit_components** in one call and returns a single JSON payload (each section only if that list was non-empty). Use this as the default way to discover ADS **tokens**, **icons**, and **components** (including legacy/broader Atlaskit) for a UI task.\n\nWHEN TO USE:\n**Implementing or iterating on a UI**\u2014new screen, feature, or polish\u2014and you need candidate **token** names, **icon** imports, and **component** packages/props in one pass. Also use when exploring ADS building blocks before you write code.\n\nAt least one of `tokens`, `icons`, `components`, or `atlaskitComponents` must contain search terms (use `[]` for lists you do not need).\n\nPrefer supplying **multiple** terms per non-empty array when you know them\u2014broader queries improve recall. Some queries return no rows where metadata is thin; try alternate wording.\n\nThis is equivalent to calling the individual search tools; there are no extra merge semantics beyond concatenating results.\n\nExample request:\n```json\n{\n\t\"tokens\": [\"spacing\", \"inverted text\", \"background primary\", \"animation\"],\n\t\"icons\": [\"search\", \"folder\", \"user\"],\n\t\"components\": [\"button\", \"input\", \"select\", \"heading\"],\n\t\"atlaskitComponents\": [\"inline-dialog\", \"onboarding\", \"page-layout\"]\n}\n```\n\nExample token usage:\n```tsx\nimport { token } from '@atlaskit/tokens';\nconst styles = css({ color: token('color.text'), padding: token('space.100') });\n```\n\nExample icon usage:\n```tsx\nimport AddIcon from '@atlaskit/icon/core/add';\n<AddIcon label=\"Add work item\" size=\"small\" />\n```",
+  description: "Runs **ads_search_tokens**, **ads_search_icons**, **ads_search_components**, and optionally **atlaskit_search_components** in one call and returns a single JSON payload (each section only if that list was non-empty). Use this as the default way to discover ADS **tokens**, **icons**, and **components** for a UI task.\n\nWHEN TO USE:\n**Implementing or iterating on a UI**\u2014new screen, feature, or polish\u2014and you need candidate **token** names, **icon** imports, and **ADS component** packages/props in one pass. Also use when exploring ADS building blocks before you write code.\n\nADS-FIRST ROUTING:\nUse `components` for canonical ADS components. Use `atlaskitComponents` only as explicit fallback research for public `@atlaskit/*` packages outside the ADS catalog, or after ADS component search has no useful match. This tool does not auto-populate `atlaskitComponents` from `components`.\n\nAt least one of `tokens`, `icons`, `components`, or `atlaskitComponents` must contain search terms (use `[]` for lists you do not need).\n\nPrefer supplying **multiple** terms per non-empty array when you know them\u2014broader queries improve recall. Some queries return no rows where metadata is thin; try alternate wording.\n\nThis is equivalent to calling the individual search tools; there are no extra merge semantics beyond concatenating results.\n\nExample request:\n```json\n{\n\t\"tokens\": [\"spacing\", \"inverted text\", \"background primary\", \"animation\"],\n\t\"icons\": [\"search\", \"folder\", \"user\"],\n\t\"components\": [\"button\", \"input\", \"select\", \"heading\"],\n\t\"atlaskitComponents\": [\"editor-core\", \"onboarding\", \"page-layout\"]\n}\n```\n\nExample token usage:\n```tsx\nimport { token } from '@atlaskit/tokens';\nconst styles = css({ color: token('color.text'), padding: token('space.100') });\n```\n\nExample icon usage:\n```tsx\nimport AddIcon from '@atlaskit/icon/core/add';\n<AddIcon label=\"Add work item\" size=\"small\" />\n```",
   annotations: {
     title: 'Search ADS tokens, icons, and components to plan what to build',
     readOnlyHint: true,

package/dist/esm/tools/plan/plan-input-schema.js

@@ -3,7 +3,7 @@ import { z } from 'zod';
 export var planInputSchema = z.object({
   tokens: z.array(z.string()).describe('Search terms for ADS design tokens (fuzzy by default). Use `[]` if you only need icons or components. Prefer **at least two** terms per non-empty list when you know what you need.'),
   icons: z.array(z.string()).describe('Search terms for ADS icons. Use `[]` if you only need tokens or components. Prefer **at least two** terms per non-empty list when known.'),
-  components: z.array(z.string()).describe('Search terms for ADS components. Use `[]` if you only need tokens or icons. Prefer **at least two** terms per non-empty list when known.'),
-  atlaskitComponents: z.array(z.string()).describe('Search terms for Atlaskit components. Use `[]` if you only need core ADS components. Prefer **at least two** terms per non-empty list when known.'),
-  limit: z.number().default(2).describe('Max matches **per term** for each non-empty list (default 2). Same limit applies to tokens, icons, and both ADS and atlaskit component searches.').optional()
+  components: z.array(z.string()).describe('Search terms for canonical ADS components. Use `[]` if you only need tokens, icons, or explicit Atlaskit fallback research. Prefer **at least two** terms per non-empty list when known.'),
+  atlaskitComponents: z.array(z.string()).describe('Search terms for public `@atlaskit/*` components outside the ADS catalog. Use only as explicit fallback research when ADS component search is not enough; this is not auto-populated from `components`. Use `[]` if you only need canonical ADS components. Prefer **at least two** terms per non-empty list when known.'),
+  limit: z.number().default(2).describe('Max matches **per term** for each non-empty list (default 2). Same limit applies to tokens, icons, ADS components, and explicit Atlaskit component fallback searches.').optional()
 });

package/dist/esm/tools/plan/plan-tool.js

@@ -24,7 +24,7 @@ export var planTool = /*#__PURE__*/function () {
             isError: true,
             content: [{
               type: 'text',
-              text: 'Error: At least one search type (tokens_search, icons_search, components_search, or atlaskit_components_search) must be provided with search terms'
+              text: 'Error: At least one search type (tokens, icons, components, or atlaskitComponents) must be provided with search terms'
             }]
           });
         case 1:

package/dist/esm/tools/search-atlaskit-components/list-search-atlaskit-components-tool.js

@@ -4,7 +4,7 @@ import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
 import { searchAtlaskitComponentsInputSchema } from './search-atlaskit-components-input-schema';
 export var listSearchAtlaskitComponentsTool = {
   name: 'atlaskit_search_components',
-  description: "Searches the bundled Atlaskit component catalog. Returns JSON objects with **name**, **package**, **examples**, and **props** for each match (trimmed payload).\n\nWHEN TO USE:\n**Selecting which Atlaskit component to use**\u2014package name, examples, and props\u2014before implementation. Use when searching for specific Atlaskit components that might not be in the core ADS catalog.",
+  description: "Searches the bundled public `@atlaskit/*` component catalog outside the Atlassian Design System (ADS) component catalog. Returns JSON objects with **name**, **package**, **examples**, and **props** for each match (trimmed payload).\n\nWHEN TO USE:\nUse this for fallback research when `ads_search_components` or `ads_plan.components` does not find a useful ADS component, or when the user asks about a specific public `@atlaskit/*` package that is not part of ADS. Prefer canonical ADS components first for standard UI.",
   annotations: {
     title: 'Search Atlaskit components',
     readOnlyHint: true,

package/dist/esm/tools/search-atlaskit-hooks/list-search-atlaskit-hooks-tool.js

@@ -4,7 +4,7 @@ import { zodToJsonSchema } from '../../helpers';
 import { searchAtlaskitHooksInputSchema } from './search-atlaskit-hooks-input-schema';
 export var listSearchAtlaskitHooksTool = {
   name: 'atlaskit_search_hooks',
-  description: "Search for atlaskit hooks by name, package, category, description, or keywords.\n\nWHEN TO USE:\nUse this when you want to find a hook but don't know its exact name or package.",
+  description: "Search public `@atlaskit/*` hooks outside the Atlassian Design System (ADS) catalog by name, package, category, description, or keywords.\n\nWHEN TO USE:\nUse this for fallback research when you want to find a non-ADS `@atlaskit/*` hook but do not know its exact name or package.",
   annotations: {
     title: 'Search Atlaskit hooks',
     readOnlyHint: true,

package/dist/esm/tools/search-atlaskit-utilities/list-search-atlaskit-utilities-tool.js

@@ -4,7 +4,7 @@ import { zodToJsonSchema } from '../../helpers';
 import { searchAtlaskitUtilitiesInputSchema } from './search-atlaskit-utilities-input-schema';
 export var listSearchAtlaskitUtilitiesTool = {
   name: 'atlaskit_search_utilities',
-  description: "Search for atlaskit utilities (functions, constants, types) by name, package, category, description, or keywords.\n\nWHEN TO USE:\nUse this when you want to find a utility but don't know its exact name or package.",
+  description: "Search public `@atlaskit/*` utilities (functions, constants, types) outside the Atlassian Design System (ADS) catalog by name, package, category, description, or keywords.\n\nWHEN TO USE:\nUse this for fallback research when you want to find a non-ADS `@atlaskit/*` utility but do not know its exact name or package.",
   annotations: {
     title: 'Search Atlaskit utilities',
     readOnlyHint: true,

package/dist/esm/tools/search-components/list-search-components-tool.js

@@ -4,7 +4,7 @@ import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
 import { searchComponentsInputSchema } from './search-components-input-schema';
 export var listSearchComponentsTool = {
   name: 'ads_search_components',
-  description: "Searches the bundled Atlassian Design System (ADS) component catalog. Returns JSON objects with **name**, **package**, **examples**, and **props** for each match (trimmed payload).\n\nWHEN TO USE:\n**Selecting which ADS component to use**\u2014package name, examples, and props\u2014before implementation. Use when composing a new view or swapping a primitive. Prefer `ads_plan` when you also need token and icon discovery in one shot.",
+  description: "Searches the bundled Atlassian Design System (ADS) component catalog. Returns JSON objects with **name**, **package**, **examples**, and **props** for each match (trimmed payload).\n\nWHEN TO USE:\n**Selecting which canonical ADS component to use**\u2014package name, examples, and props\u2014before implementation. Use when composing a new view or swapping a primitive. Prefer `ads_plan` when you also need token and icon discovery in one shot.\n\nIf you are looking for a public `@atlaskit/*` scoped package that is not part of the ADS component catalog, use `atlaskit_search_components` for fallback research instead of this ADS-only search.",
   annotations: {
     title: 'Search ADS components',
     readOnlyHint: true,

package/dist/esm/tools/search-components/search-components-tool.js

@@ -86,7 +86,7 @@ export var searchComponentsTool = /*#__PURE__*/function () {
           return _context.abrupt("return", {
             content: [{
               type: 'text',
-              text: "Error: No components found for '".concat(terms.join(', '), "'. Available components: ").concat(components.map(function (c) {
+              text: "Error: No ADS components found for '".concat(terms.join(', '), "'. If this is a public @atlaskit/* package outside the ADS catalog, call atlaskit_search_components with the same terms. Available ADS components: ").concat(components.map(function (c) {
                 return c.name;
               }).join(', '))
             }]

package/dist/types/instructions.d.ts

@@ -1 +1 @@
-export declare const instructions = "\nYou are an expert in the Atlassian Design System (ADS).\nYou can search for tokens, icons, and components and return guidance on how to build user interfaces.\nYou have special accessibility knowledge and can ensure interfaces built with ADS components are accessible to all users.\nYou can analyze code for accessibility violations, provide specific fix suggestions, and offer guidance on accessibility best practices.\nFor 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).\nThese 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.\n";
+export declare const instructions = "\nYou are an expert in the Atlassian Design System (ADS).\nYou can search for tokens, icons, and components and return guidance on how to build user interfaces.\nUse ads_* tools for canonical ADS resources: components, tokens, icons, foundations, accessibility, lint rules, i18n, and migrations.\nUse atlaskit_* tools only for further research into public @atlaskit/* scoped packages that are not covered by the ADS catalog, such as non-ADS components, hooks, and utilities. Prefer ADS resources first for standard UI.\nYou have special accessibility knowledge and can ensure interfaces built with ADS components are accessible to all users.\nYou can analyze code for accessibility violations, provide specific fix suggestions, and offer guidance on accessibility best practices.\nFor 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).\nThese 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.\n";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/ads-mcp",
-	"version": "1.2.1",
+	"version": "1.3.0",
 	"description": "The official Atlassian Design System MCP server to develop apps and user interfaces matching the Atlassian style.",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",
@@ -21,10 +21,10 @@
 	"types": "dist/types/index.d.ts",
 	"atlaskit:src": "src/index.tsx",
 	"dependencies": {
-		"@atlaskit/icon": "^36.0.0",
-		"@atlaskit/icon-lab": "^7.1.0",
+		"@atlaskit/icon": "^36.1.0",
+		"@atlaskit/icon-lab": "^7.2.0",
 		"@atlaskit/platform-feature-flags": "^2.0.0",
-		"@atlaskit/tokens": "^15.0.0",
+		"@atlaskit/tokens": "^15.1.0",
 		"@axe-core/playwright": "^4.11.1",
 		"@axe-core/puppeteer": "^4.11.1",
 		"@babel/runtime": "^7.0.0",