fix(tools): type blueprint/scheduling schemas and document state traps in tool contracts (WM-4172)

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@makehq/sdk",
-    "version": "1.6.4",
+    "version": "1.6.5",
     "description": "Make TypeScript SDK",
     "license": "MIT",
     "author": "Make",

src/endpoints/credential-requests.tools.ts

@@ -96,7 +96,11 @@ export const tools: MakeTool[] = [
         inputSchema: {
             type: 'object',
             properties: {
-                requestId: { type: 'string', description: 'The credential request ID to delete' },
+                requestId: {
+                    type: 'string',
+                    description:
+                        'The credential request ID to delete — the string ID returned by credential-requests_create or credential-requests_list. NOT a numeric connectionId; to delete a connection use connections_delete.',
+                },
             },
             required: ['requestId'],
         },
@@ -427,7 +431,7 @@ export const tools: MakeTool[] = [
         description:
             'Add new OAuth scopes to an existing connection. Use this when a connection exists but lacks the permissions (scopes) needed for a specific operation. ' +
             'Creates a credential request that the end-user must authorize via the returned publicUri to grant the additional scopes. ' +
-            'Fails if all requested scopes are already present on the connection.',
+            'Fails if all requested scopes are already present on the connection — that error means the connection already satisfies the requirement: treat it as success and use the connection as-is; do not retry.',
         category: 'credential-requests',
         scope: 'credential-requests:write',
         scopeId: 'connectionId',
@@ -450,7 +454,7 @@ export const tools: MakeTool[] = [
                 scopes: {
                     type: 'array',
                     description:
-                        'One or more new OAuth scope strings to add to the connection. At least one scope must be new (not already granted).',
+                        'One or more new OAuth scope strings to add to the connection. At least one scope must be new (not already granted). Get the exact scope strings a module needs from credential-requests_list-app-modules-with-creds — do not guess them.',
                     minItems: 1,
                     items: {
                         type: 'string',

src/endpoints/executions.tools.ts

@@ -34,7 +34,8 @@ export const tools: MakeTool[] = [
     {
         name: 'executions_get-detail',
         title: 'Get execution detail',
-        description: 'Get detailed result of a specific execution.',
+        description:
+            'Get the full per-module detail of an execution: the inputs and outputs of each module, the failing module and its error. ALWAYS call this after a failed or suspicious run BEFORE retrying or editing the scenario. For lightweight status/duration metadata only, use executions_get instead.',
         category: 'executions',
         scope: 'scenarios:read',
         scopeId: 'scenarioId',
@@ -49,7 +50,12 @@ export const tools: MakeTool[] = [
             type: 'object',
             properties: {
                 scenarioId: { type: 'number', description: 'The scenario ID the execution belongs to' },
-                executionId: { type: 'string', description: 'The execution ID to retrieve' },
+                executionId: {
+                    type: 'string',
+                    pattern: '^[0-9a-f]{32}$',
+                    description:
+                        "The execution ID to retrieve — a 32-character lowercase hex string as returned by scenarios_run or executions_list (e.g. 'a07e16f2ad134bf49cf83a00aa95c0a5')",
+                },
             },
             required: ['scenarioId', 'executionId'],
         },
@@ -61,7 +67,8 @@ export const tools: MakeTool[] = [
     {
         name: 'executions_get',
         title: 'Get execution',
-        description: 'Get details of a specific execution.',
+        description:
+            'Get execution metadata only: status, duration, operations consumed and error class — NOT per-module inputs/outputs. To see what each module did or why a run failed, use executions_get-detail instead.',
         category: 'executions',
         scope: 'scenarios:read',
         scopeId: 'scenarioId',
@@ -76,7 +83,12 @@ export const tools: MakeTool[] = [
             type: 'object',
             properties: {
                 scenarioId: { type: 'number', description: 'The scenario ID the execution belongs to' },
-                executionId: { type: 'string', description: 'The execution ID to retrieve' },
+                executionId: {
+                    type: 'string',
+                    pattern: '^[0-9a-f]{32}$',
+                    description:
+                        "The execution ID to retrieve — a 32-character lowercase hex string as returned by scenarios_run or executions_list (e.g. 'a07e16f2ad134bf49cf83a00aa95c0a5')",
+                },
             },
             required: ['scenarioId', 'executionId'],
         },
@@ -133,7 +145,11 @@ export const tools: MakeTool[] = [
             type: 'object',
             properties: {
                 incompleteExecutionId: { type: 'string', description: 'The incomplete execution ID' },
-                executionId: { type: 'string', description: 'The execution ID to retrieve' },
+                executionId: {
+                    type: 'string',
+                    description:
+                        "The execution ID from the incomplete execution record (see executions_list-for-incomp-exec) — may be UUID-formatted with dashes (e.g. '55602700-e840-45bf-b18c-0aef214dd967'), unlike scenario execution IDs",
+                },
             },
             required: ['incompleteExecutionId', 'executionId'],
         },

src/endpoints/folders.tools.ts

@@ -5,7 +5,7 @@ export const tools: MakeTool[] = [
     {
         name: 'folders_list',
         title: 'List folders',
-        description: 'List folders for a team.',
+        description: 'List scenario folders for a team. If you do not know the teamId, call users_me to learn it.',
         category: 'folders',
         scope: 'scenarios:read',
         scopeId: 'teamId',