feat: feedback tool

README.md

@@ -3,6 +3,7 @@
 > A unified interface for performing actions on SaaS tools through AI-friendly APIs.
 
 [![DeepWiki](https://img.shields.io/badge/DeepWiki-StackOneHQ%2Fstackone--ai--node-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/StackOneHQ/stackone-ai-node)
+
 <!-- DeepWiki badge generated by https://deepwiki.ryoppippi.com/ -->
 
 ## Toolsets
@@ -146,11 +147,11 @@ Call `fetchTools()` when you want the SDK to pull the current tool definitions d
 
 ```typescript
 const toolset = new StackOneToolSet({
-  baseUrl: 'https://api.stackone.com',
+  baseUrl: "https://api.stackone.com",
 });
 
 const tools = await toolset.fetchTools();
-const employeeTool = tools.getTool('hris_list_employees');
+const employeeTool = tools.getTool("hris_list_employees");
 
 const result = await employeeTool?.execute({
   query: { limit: 5 },
@@ -165,31 +166,34 @@ You can filter tools by account IDs, providers, and action patterns:
 
 ```typescript
 // Filter by account IDs
-toolset.setAccounts(['account-123', 'account-456']);
+toolset.setAccounts(["account-123", "account-456"]);
 const tools = await toolset.fetchTools();
 // OR
-const tools = await toolset.fetchTools({ accountIds: ['account-123', 'account-456'] });
+const tools = await toolset.fetchTools({
+  accountIds: ["account-123", "account-456"],
+});
 
 // Filter by providers
-const tools = await toolset.fetchTools({ providers: ['hibob', 'bamboohr'] });
+const tools = await toolset.fetchTools({ providers: ["hibob", "bamboohr"] });
 
 // Filter by actions with exact match
 const tools = await toolset.fetchTools({
-  actions: ['hibob_list_employees', 'hibob_create_employees']
+  actions: ["hibob_list_employees", "hibob_create_employees"],
 });
 
 // Filter by actions with glob patterns
-const tools = await toolset.fetchTools({ actions: ['*_list_employees'] });
+const tools = await toolset.fetchTools({ actions: ["*_list_employees"] });
 
 // Combine multiple filters
 const tools = await toolset.fetchTools({
-  accountIds: ['account-123'],
-  providers: ['hibob'],
-  actions: ['*_list_*']
+  accountIds: ["account-123"],
+  providers: ["hibob"],
+  actions: ["*_list_*"],
 });
 ```
 
 This is especially useful when you want to:
+
 - Limit tools to specific linked accounts
 - Focus on specific HR/CRM/ATS providers
 - Get only certain types of operations (e.g., all "list" operations)
@@ -295,6 +299,110 @@ const toolsetWithHeaders = new OpenAPIToolSet({
 
 These are some of the features which you can use with the OpenAPIToolSet and StackOneToolSet.
 
+### Feedback Collection Tool
+
+The StackOne AI SDK includes a built-in feedback collection tool (`meta_collect_tool_feedback`) that allows users to provide feedback on their experience with StackOne tools. This tool is automatically included in the `StackOneToolSet` and helps improve the SDK based on user input.
+
+#### How It Works
+
+The feedback tool:
+
+- **Requires explicit user consent** before submitting feedback
+- **Collects user feedback** about their experience with StackOne tools
+- **Tracks tool usage** by recording which tools were used
+- **Submits to StackOne** via the `/ai/tool-feedback` endpoint
+- **Uses the same API key** as other SDK operations for authentication
+
+#### Usage
+
+The feedback tool is automatically available when using `StackOneToolSet`:
+
+```typescript
+import { StackOneToolSet } from "@stackone/ai";
+
+const toolset = new StackOneToolSet();
+const tools = toolset.getTools("*", "account-id");
+
+// The feedback tool is automatically included
+const feedbackTool = tools.getTool("meta_collect_tool_feedback");
+
+// Use with AI agents - they will ask for user consent first
+const openAITools = tools.toOpenAI();
+// or
+const aiSdkTools = await tools.toAISDK();
+```
+
+#### Manual Usage
+
+You can also use the feedback tool directly:
+
+```typescript
+// Get the feedback tool
+const feedbackTool = tools.getTool("meta_collect_tool_feedback");
+
+// Submit feedback (after getting user consent)
+const result = await feedbackTool.execute({
+  feedback: "The tools worked great! Very easy to use.",
+  account_id: "acc_123456",
+  tool_names: ["hris_list_employees", "hris_create_time_off"],
+});
+```
+
+#### Multiple Account Support
+
+The feedback tool supports both single and multiple account IDs. When you provide an array of account IDs, the feedback will be sent to each account individually:
+
+```typescript
+// Single account ID (string)
+await feedbackTool.execute({
+  feedback: "The tools worked great! Very easy to use.",
+  account_id: "acc_123456",
+  tool_names: ["hris_list_employees", "hris_create_time_off"],
+});
+
+// Multiple account IDs (array)
+await feedbackTool.execute({
+  feedback: "The tools worked great! Very easy to use.",
+  account_id: ["acc_123456", "acc_789012"],
+  tool_names: ["hris_list_employees", "hris_create_time_off"],
+});
+```
+
+**Response Format**: When using multiple account IDs, the tool returns a summary of all submissions:
+
+```typescript
+{
+  message: "Feedback sent to 2 account(s)",
+  total_accounts: 2,
+  successful: 2,
+  failed: 0,
+  results: [
+    {
+      account_id: "acc_123456",
+      status: "success",
+      result: { message: "Feedback successfully stored", ... }
+    },
+    {
+      account_id: "acc_789012",
+      status: "success",
+      result: { message: "Feedback successfully stored", ... }
+    }
+  ]
+}
+```
+
+#### AI Agent Integration
+
+When AI agents use this tool, they will:
+
+1. **Ask for user consent**: "Are you ok with sending feedback to StackOne?"
+2. **Collect feedback**: Get the user's verbatim feedback
+3. **Track tool usage**: Record which tools were used in the session
+4. **Submit to all accounts**: Send the same feedback to each account ID provided
+5. **Report results**: Show which accounts received the feedback successfully
+
+The tool description includes clear instructions for AI agents to always ask for explicit user consent before submitting feedback.
+
 ### Meta Tools (Beta)
 
 Meta tools enable dynamic tool discovery and execution, allowing AI agents to search for relevant tools based on natural language queries without hardcoding tool names.
@@ -304,6 +412,7 @@ Meta tools enable dynamic tool discovery and execution, allowing AI agents to se
 #### How Meta Tools Work
 
 Meta tools provide two core capabilities:
+
 1. **Tool Discovery** (`meta_search_tools`): Search for tools using natural language queries
 2. **Tool Execution** (`meta_execute_tool`): Execute discovered tools dynamically
 

src/index.ts

@@ -5,6 +5,7 @@
 export * as OpenAPILoader from './openapi/loader';
 export { OpenAPIParser } from './openapi/parser';
 export { BaseTool, StackOneTool, Tools } from './tool';
+export { createFeedbackTool } from './tools/feedback';
 export { StackOneAPIError, StackOneError } from './utils/errors';
 
 export {