Add get_tools_by_ids functionality, and enhance README with new tool descriptions and examples.

README.md

@@ -7,21 +7,12 @@ Official Qveris MCP Server SDK — Dynamically search and execute tools via natu
 
 ## Overview
 
-This SDK provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables LLMs to discover and execute third-party tools through the Qveris API. With just two simple tools, your AI assistant can:
+This SDK provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables LLMs to discover and execute third-party tools through the Qveris API. With three simple tools, your AI assistant can:
 
 - **Search** for tools using natural language queries
+- **Get** detailed information about specific tools by their IDs
 - **Execute** any discovered tool with the appropriate parameters
 
-## Installation
-
-```bash
-# Using npx (recommended for MCP)
-npx @qverisai/sdk
-
-# Or install globally
-npm add -g @qverisai/sdk
-```
-
 ## Quick Start
 
 ### 1. Get Your API Key
@@ -96,7 +87,7 @@ Search for available tools based on natural language queries.
 ```json
 {
   "query": "send email notification",
-  "limit": 5
+  "limit": 10
 }
 ```
 
@@ -110,18 +101,37 @@ Execute a discovered tool with specific parameters.
 | `search_id` | string | ✓ | Search ID from the search that found this tool |
 | `params_to_tool` | string | ✓ | JSON string of parameters to pass to the tool |
 | `session_id` | string | | Session identifier (auto-generated if omitted) |
-| `max_data_size` | number | | Max response size in bytes (default: 20480) |
+| `max_response_size` | number | | Max response size in bytes (default: 20480) |
 
 **Example:**
 
 ```json
 {
-  "tool_id": "openweathermap_current_weather",
-  "search_id": "abc123",
+  "tool_id": "openweathermap.weather.execute.v1",
+  "search_id": "abcd1234-ab12-ab12-ab12-abcdef123456",
   "params_to_tool": "{\"city\": \"London\", \"units\": \"metric\"}"
 }
 ```
 
+### `get_tools_by_ids`
+
+Get detailed descriptions of tools based on their tool IDs. Useful for retrieving information about specific tools when you already know their IDs from previous searches.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `tool_ids` | array | ✓ | Array of tool IDs to retrieve (at least one required) |
+| `search_id` | string | | Search ID from the search that returned the tool(s) |
+| `session_id` | string | | Session identifier (auto-generated if omitted) |
+
+**Example:**
+
+```json
+{
+  "tool_ids": ["openweathermap.weather.execute.v1", "worldbank_refined.search_indicators.v1"],
+  "search_id": "abcd1234-ab12-ab12-ab12-abcdef123456"
+}
+```
+
 ## Session Management
 
 Providing a consistent `session_id` in a same user session in any tool call enables:
@@ -137,8 +147,8 @@ If not provided, the SDK automatically generates and maintains a session ID for
 
 ```json
 {
-  "execution_id": "exec-123",
-  "tool_id": "openweathermap_current_weather",
+  "execution_id": "abcd1234-ab12-ab12-ab12-abcdef123456",
+  "tool_id": "openweathermap.weather.execute.v1",
   "success": true,
   "result": {
     "data": {
@@ -153,7 +163,7 @@ If not provided, the SDK automatically generates and maintains a session ID for
 
 ### Large Responses
 
-When tool output exceeds `max_data_size`, you'll receive:
+When tool output exceeds `max_response_size`, you'll receive:
 
 ```json
 {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qverisai/sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Official Qveris AI MCP Server SDK - Search and execute tools via natural language",
   "keywords": [
     "qveris",

src/api/client.test.ts

@@ -131,6 +131,146 @@ describe('QverisClient', () => {
     });
   });
 
+  describe('getToolsByIds', () => {
+    let client: QverisClient;
+    let fetchMock: ReturnType<typeof vi.fn>;
+
+    beforeEach(() => {
+      client = new QverisClient({ apiKey: 'test-api-key' });
+      fetchMock = vi.fn();
+      global.fetch = fetchMock;
+    });
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it('should make POST request to /tools/by-ids endpoint', async () => {
+      const mockResponse = {
+        search_id: 'search-123',
+        results: [
+          {
+            tool_id: 'weather-tool-1',
+            name: 'Weather API',
+            description: 'Get weather data',
+          },
+        ],
+        total: 1,
+      };
+
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockResponse,
+      });
+
+      const result = await client.getToolsByIds({
+        tool_ids: ['weather-tool-1'],
+      });
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        'https://qveris.ai/api/v1/tools/by-ids',
+        expect.objectContaining({
+          method: 'POST',
+          headers: {
+            Authorization: 'Bearer test-api-key',
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({
+            tool_ids: ['weather-tool-1'],
+          }),
+        })
+      );
+
+      expect(result).toEqual(mockResponse);
+    });
+
+    it('should include search_id and session_id when provided', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          search_id: 'search-456',
+          results: [],
+        }),
+      });
+
+      await client.getToolsByIds({
+        tool_ids: ['tool-1', 'tool-2'],
+        search_id: 'search-456',
+        session_id: 'session-abc',
+      });
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.objectContaining({
+          body: JSON.stringify({
+            tool_ids: ['tool-1', 'tool-2'],
+            search_id: 'search-456',
+            session_id: 'session-abc',
+          }),
+        })
+      );
+    });
+
+    it('should handle multiple tool IDs', async () => {
+      const toolIds = ['tool-1', 'tool-2', 'tool-3'];
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          search_id: 'search-123',
+          results: toolIds.map((id) => ({
+            tool_id: id,
+            name: `Tool ${id}`,
+            description: `Description for ${id}`,
+          })),
+          total: toolIds.length,
+        }),
+      });
+
+      const result = await client.getToolsByIds({
+        tool_ids: toolIds,
+      });
+
+      expect(result.results).toHaveLength(3);
+      expect(result.total).toBe(3);
+    });
+
+    it('should throw ApiError on non-OK response', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: false,
+        status: 400,
+        statusText: 'Bad Request',
+        json: async () => ({ message: 'Invalid tool_ids' }),
+      });
+
+      await expect(
+        client.getToolsByIds({ tool_ids: [] })
+      ).rejects.toEqual({
+        status: 400,
+        message: 'Invalid tool_ids',
+        details: { message: 'Invalid tool_ids' },
+      });
+    });
+
+    it('should handle non-JSON error response', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: false,
+        status: 500,
+        statusText: 'Internal Server Error',
+        json: async () => {
+          throw new Error('Not JSON');
+        },
+      });
+
+      await expect(
+        client.getToolsByIds({ tool_ids: ['tool-1'] })
+      ).rejects.toEqual({
+        status: 500,
+        message: 'Internal Server Error',
+        details: undefined,
+      });
+    });
+  });
+
   describe('executeTool', () => {
     let client: QverisClient;
     let fetchMock: ReturnType<typeof vi.fn>;
@@ -202,7 +342,7 @@ describe('QverisClient', () => {
       );
     });
 
-    it('should include max_data_size when provided', async () => {
+    it('should include max_response_size when provided', async () => {
       fetchMock.mockResolvedValueOnce({
         ok: true,
         json: async () => ({
@@ -217,7 +357,7 @@ describe('QverisClient', () => {
       await client.executeTool('tool-1', {
         search_id: 'search-123',
         parameters: {},
-        max_data_size: 102400,
+        max_response_size: 102400,
       });
 
       expect(fetchMock).toHaveBeenCalledWith(
@@ -226,7 +366,7 @@ describe('QverisClient', () => {
           body: JSON.stringify({
             search_id: 'search-123',
             parameters: {},
-            max_data_size: 102400,
+            max_response_size: 102400,
           }),
         })
       );

src/api/client.ts

@@ -10,6 +10,7 @@
 import type {
   SearchRequest,
   SearchResponse,
+  GetToolsByIdsRequest,
   ExecuteRequest,
   ExecuteResponse,
   QverisClientConfig,
@@ -126,7 +127,7 @@ export class QverisClient {
    * const result = await client.searchTools({
    *   query: 'send SMS message',
    *   limit: 10,
-   *   session_id: 'user-123'
+   *   session_id: 'abcd1234-ab12-ab12-ab12-abcdef123456'
    * });
    *
    * console.log(`Found ${result.total} tools`);
@@ -139,6 +140,34 @@ export class QverisClient {
     return this.request<SearchResponse>('POST', '/search', request);
   }
 
+  /**
+   * Get tool descriptions by their IDs.
+   *
+   * Retrieves detailed information about specific tools when you already
+   * know their tool_ids. Useful for refreshing tool metadata or getting
+   * details for tools from previous searches.
+   *
+   * @param request - Request parameters with tool IDs
+   * @returns Tool information matching the provided IDs
+   *
+   * @example
+   * ```typescript
+   * const result = await client.getToolsByIds({
+   *   tool_ids: ['weather-tool-1', 'email-tool-2'],
+   *   search_id: 'abcd1234-ab12-ab12-ab12-abcdef123456',
+   *   session_id: 'abcd1234-ab12-ab12-ab12-abcdef123456'
+   * });
+   *
+   * console.log(`Retrieved ${result.results.length} tools`);
+   * for (const tool of result.results) {
+   *   console.log(`- ${tool.name}: ${tool.description}`);
+   * }
+   * ```
+   */
+  async getToolsByIds(request: GetToolsByIdsRequest): Promise<SearchResponse> {
+    return this.request<SearchResponse>('POST', '/tools/by-ids', request);
+  }
+
   /**
    * Execute a tool with the specified parameters.
    *
@@ -152,8 +181,8 @@ export class QverisClient {
    * @example
    * ```typescript
    * const result = await client.executeTool('openweathermap_current', {
-   *   search_id: 'search-abc123',
-   *   session_id: 'user-123',
+   *   search_id: 'abcd1234-ab12-ab12-ab12-abcdef123456',
+   *   session_id: 'abcd1234-ab12-ab12-ab12-abcdef123456',
    *   parameters: {
    *     city: 'Tokyo',
    *     units: 'metric'