feat(ai): export defaultTools from @commandkit/ai for selective tool configuration (#598)

* Initial plan

* Export defaultTools from @commandkit/ai and update docs

Co-authored-by: twlite <46562212+twlite@users.noreply.github.com>

* Rename instance property to avoid shadowing defaultTools constant

Co-authored-by: twlite <46562212+twlite@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: twlite <46562212+twlite@users.noreply.github.com>

Author: Copilot

apps/website/docs/api-reference/ai/classes/ai-plugin.mdx

@@ -13,7 +13,7 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## AiPlugin
 
-<GenerationInfo sourceFile="packages/ai/src/plugin.ts" sourceLine="43" packageName="@commandkit/ai" />
+<GenerationInfo sourceFile="packages/ai/src/plugin.ts" sourceLine="66" packageName="@commandkit/ai" />
 
 
 

apps/website/docs/api-reference/ai/variables/default-tools.mdx

@@ -0,0 +1,42 @@
+---
+title: "DefaultTools"
+isDefaultIndex: false
+generated: true
+---
+
+import MemberInfo from '@site/src/components/MemberInfo';
+import GenerationInfo from '@site/src/components/GenerationInfo';
+import MemberDescription from '@site/src/components/MemberDescription';
+
+<!-- This file was generated from the CommandKit source. Do not modify. Instead, re-run the "docgen" script -->
+
+
+## defaultTools
+
+<GenerationInfo sourceFile="packages/ai/src/plugin.ts" sourceLine="56" packageName="@commandkit/ai" />
+
+A record of all built-in tools provided by the AI plugin.
+These tools are automatically available to the AI unless `disableBuiltInTools` is set to `true`.
+
+You can use this to selectively include specific built-in tools when `disableBuiltInTools` is enabled:
+
+
+
+*Example*
+
+```ts
+import { configureAI, defaultTools } from '@commandkit/ai';
+
+configureAI({
+  disableBuiltInTools: true,
+  selectAiModel: async (ctx, message) => ({
+    model: google.languageModel('gemini-2.0-flash'),
+    // Only include specific built-in tools
+    tools: {
+      getAvailableCommands: defaultTools.getAvailableCommands,
+      getUserById: defaultTools.getUserById,
+    },
+  }),
+});
+```
+

apps/website/docs/guide/05-official-plugins/01-commandkit-ai.mdx

@@ -258,8 +258,12 @@ CommandKit provides built-in tools that the AI can use automatically:
 - **`getCurrentClientInfo`** - Gets information about the bot
 - **`getGuildById`** - Fetches server information by ID
 - **`getUserById`** - Fetches user information by ID
+- **`getMemberById`** - Fetches guild member information by ID
+- **`createEmbed`** - Creates and sends an embed message
 
-You can disable these tools if needed:
+### Disabling built-in tools
+
+You can disable all built-in tools if needed:
 
 ```ts
 configureAI({
@@ -268,6 +272,46 @@ configureAI({
 });
 ```
 
+### Selectively enabling built-in tools
+
+In many cases, you may not need all built-in tools. You can selectively enable
+specific tools by disabling built-in tools and then manually adding only the
+ones you need using the exported `defaultTools` record:
+
+```ts title="src/ai.ts"
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { configureAI, defaultTools } from '@commandkit/ai';
+
+const google = createGoogleGenerativeAI({
+  apiKey: process.env.GOOGLE_API_KEY,
+});
+
+configureAI({
+  // Disable all built-in tools
+  disableBuiltInTools: true,
+
+  selectAiModel: async (ctx, message) => ({
+    model: google.languageModel('gemini-2.0-flash'),
+    maxSteps: 5,
+    temperature: 0.7,
+    // Manually add only the tools you need
+    tools: {
+      getAvailableCommands: defaultTools.getAvailableCommands,
+      getUserById: defaultTools.getUserById,
+      getGuildById: defaultTools.getGuildById,
+      // Omit tools you don't want, like createEmbed
+    },
+  }),
+
+  messageFilter: async (commandkit, message) => {
+    return message.mentions.users.has(message.client.user.id);
+  },
+});
+```
+
+This approach gives you full control over which built-in tools are available to
+the AI, making your implementation cleaner and more intentional.
+
 ## Creating custom tools
 
 Extend the AI's capabilities by creating custom tools:

apps/website/vercel.json

@@ -1,15 +1,15 @@
 {
-    "$schema": "https://openapi.vercel.sh/vercel.json",
-    "redirects": [
-        {
-            "source": "/discord",
-            "destination": "https://discord.gg/T4faJeH84A",
-            "permanent": true
-        },
-        {
-            "source": "/github",
-            "destination": "https://github.com/neplextech/commandkit",
-            "permanent": true
-        }
-    ]
-}
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "redirects": [
+    {
+      "source": "/discord",
+      "destination": "https://discord.gg/T4faJeH84A",
+      "permanent": true
+    },
+    {
+      "source": "/github",
+      "destination": "https://github.com/neplextech/commandkit",
+      "permanent": true
+    }
+  ]
+}

packages/ai/src/plugin.ts

@@ -30,7 +30,30 @@ export interface AiConfig<T extends ToolParameterType = ToolParameterType> {
   inputSchema: T;
 }
 
-const defaultTools: Record<string, Tool> = {
+/**
+ * A record of all built-in tools provided by the AI plugin.
+ * These tools are automatically available to the AI unless `disableBuiltInTools` is set to `true`.
+ *
+ * You can use this to selectively include specific built-in tools when `disableBuiltInTools` is enabled:
+ *
+ * @example
+ * ```ts
+ * import { configureAI, defaultTools } from '@commandkit/ai';
+ *
+ * configureAI({
+ *   disableBuiltInTools: true,
+ *   selectAiModel: async (ctx, message) => ({
+ *     model: google.languageModel('gemini-2.0-flash'),
+ *     // Only include specific built-in tools
+ *     tools: {
+ *       getAvailableCommands: defaultTools.getAvailableCommands,
+ *       getUserById: defaultTools.getUserById,
+ *     },
+ *   }),
+ * });
+ * ```
+ */
+export const defaultTools: Record<string, Tool> = {
   getAvailableCommands,
   getChannelById,
   getCurrentClientInfo,
@@ -43,7 +66,7 @@ const defaultTools: Record<string, Tool> = {
 export class AiPlugin extends RuntimePlugin<AiPluginOptions> {
   public readonly name = 'AiPlugin';
   private toolsRecord: Record<string, Tool> = {};
-  private defaultTools = defaultTools;
+  private builtInTools = defaultTools;
   private onMessageFunc: ((message: Message) => Promise<void>) | null = null;
 
   public constructor(options: AiPluginOptions) {
@@ -125,7 +148,7 @@ export class AiPlugin extends RuntimePlugin<AiPluginOptions> {
           ...modelOptions,
           tools: {
             // Include built-in least significant tools if not disabled
-            ...(!disableBuiltInTools && this.defaultTools),
+            ...(!disableBuiltInTools && this.builtInTools),
             // include tools added by configureAI()
             // this should be able to override built-in tools
             ...modelOptions.tools,