@vellumai/assistant 0.4.29 → 0.4.30

package/src/config/bundled-skills/contacts/SKILL.md

@@ -10,7 +10,7 @@ Manage the user's contacts, relationship graph, access control (trusted contacts
 ## Prerequisites
 
 - Use the injected `INTERNAL_GATEWAY_BASE_URL` for gateway API calls.
-- Use gateway control-plane routes only: this skill calls `/v1/contacts`, `/v1/ingress/*`, and `/v1/integrations/telegram/config` on the gateway, never the assistant runtime port directly.
+- Use gateway control-plane routes only: this skill calls `/v1/contacts`, `/v1/contacts/channels`, `/v1/contacts/invites`, and `/v1/integrations/telegram/config` on the gateway, never the assistant runtime port directly.
 - The bearer token is available as the `$GATEWAY_AUTH_TOKEN` environment variable for control-plane `curl` requests.
 
 ## Contact Management
@@ -96,10 +96,10 @@ Trusted contacts control who is allowed to send messages to the assistant throug
 
 ### Concepts
 
-- **Member**: A user identity (external user ID or chat ID) from a specific channel that has been registered with a policy.
-- **Policy**: Controls what the member can do -- `allow` (can message freely) or `deny` (blocked from messaging).
-- **Status**: The member's lifecycle state -- `active` (currently effective), `revoked` (access removed), or `blocked` (explicitly denied).
-- **Source channel**: The messaging platform the contact uses (e.g., `telegram`, `sms`, `voice`).
+- **Contact channel**: A user identity (external user ID or chat ID) on a specific messaging platform, stored as an entry in a contact's `channels` array. Each channel entry has its own `status` and `policy`.
+- **Policy**: Controls what the contact channel can do -- `allow` (can message freely) or `deny` (blocked from messaging).
+- **Status**: The channel's lifecycle state -- `active` (currently effective), `revoked` (access removed), or `blocked` (explicitly denied).
+- **Channel type**: The messaging platform (e.g., `telegram`, `sms`, `voice`).
 
 ### List trusted contacts
 
@@ -146,27 +146,30 @@ Use this when the user wants to grant someone access to message the assistant. *
 Ask the user: _"I'll add [name/identifier] on [channel] as an allowed contact. Should I proceed?"_
 
 ```bash
-curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/ingress/members" \
+curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/contacts" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
   -d '{
-    "sourceChannel": "<channel>",
-    "externalUserId": "<user_id>",
     "displayName": "<display_name>",
-    "policy": "allow",
-    "status": "active"
+    "channels": [{
+      "type": "<channel>",
+      "address": "<user_id>",
+      "externalUserId": "<user_id>",
+      "status": "active",
+      "policy": "allow"
+    }]
   }'
 ```
 
 Required fields:
 
-- `sourceChannel` -- the channel (e.g., `telegram`, `sms`)
-- At least one of `externalUserId` or `externalChatId`
-
-Optional fields:
-
 - `displayName` -- human-readable name for the contact
-- `username` -- channel-specific handle (e.g., Telegram @username)
+- `channels` -- at least one channel entry with:
+  - `type` -- the channel type (e.g., `telegram`, `sms`)
+  - `address` -- the channel-specific identifier
+  - `externalUserId` -- the user's ID on that channel (or `externalChatId` for chat-based channels)
+  - `status` -- set to `"active"` for immediate access
+  - `policy` -- set to `"allow"` to grant messaging access
 
 If the user provides a name but not an external ID, explain that you need the channel-specific user ID or chat ID to create the contact entry. For Telegram, this is a numeric user ID; for SMS, this is the phone number in E.164 format.
 
@@ -176,16 +179,18 @@ Use this when the user wants to remove someone's access. **Always confirm with t
 
 Ask the user: _"I'll revoke access for [name/identifier]. They will no longer be able to message the assistant. Should I proceed?"_
 
-First, list members to find the member's `id`, then revoke:
+First, list contacts to find the channel's `id` (each entry in a contact's `channels` array has an `id` field -- visible in `GET /v1/contacts` or `vellum contacts list --json` output), then revoke:
+
+**Important**: Before revoking, check the channel's current `status`. If the channel is **blocked**, do not attempt to revoke it -- blocking is stronger than revoking. Inform the user that the contact is already blocked and revoking is not applicable. Only channels with `active` or `pending` status can be revoked.
 
 ```bash
-curl -s -X DELETE "$INTERNAL_GATEWAY_BASE_URL/v1/ingress/members/<member_id>" \
-  -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
+curl -s -X PATCH "$INTERNAL_GATEWAY_BASE_URL/v1/contacts/channels/<channel_id>" \
   -H "Content-Type: application/json" \
-  -d '{"reason": "<optional reason>"}'
+  -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
+  -d '{"status": "revoked", "reason": "<optional reason>"}'
 ```
 
-Replace `<member_id>` with the member's `id` from the list response.
+Replace `<channel_id>` with the channel's `id` from the contact's `channels` array. The API will return a `409 Conflict` error if the channel is currently blocked.
 
 ### Block a user
 
@@ -194,12 +199,14 @@ Use this when the user wants to explicitly block someone. Blocking is stronger t
 Ask the user: _"I'll block [name/identifier]. They will be permanently denied from messaging the assistant. Should I proceed?"_
 
 ```bash
-curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/ingress/members/<member_id>/block" \
+curl -s -X PATCH "$INTERNAL_GATEWAY_BASE_URL/v1/contacts/channels/<channel_id>" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
-  -d '{"reason": "<optional reason>"}'
+  -d '{"status": "blocked", "reason": "<optional reason>"}'
 ```
 
+Replace `<channel_id>` with the channel's `id` from the contact's `channels` array (visible in `GET /v1/contacts` or `vellum contacts list --json` output).
+
 ## Invite Links
 
 Invite links let the guardian share a link or code that automatically grants access when used. Telegram invites use a deep link; voice invites use a phone number + numeric code.
@@ -211,7 +218,7 @@ Use this when the guardian wants to invite someone to message the assistant on T
 **Important**: The shell snippet below emits a `<vellum-sensitive-output>` directive containing the raw invite token. The tool executor automatically strips this directive and replaces the raw token with a placeholder so the LLM never sees it. The placeholder is resolved back to the real token in the final assistant reply.
 
 ```bash
-INVITE_JSON=$(curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/ingress/invites" \
+INVITE_JSON=$(curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/contacts/invites" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
   -d '{
@@ -286,7 +293,7 @@ Use this when the guardian wants to authorize a specific phone number to call th
 **Important**: The response includes a `voiceCode` field that is only returned at creation time and cannot be retrieved later. Extract and present it clearly.
 
 ```bash
-INVITE_JSON=$(curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/ingress/invites" \
+INVITE_JSON=$(curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/contacts/invites" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN" \
   -d '{
@@ -388,7 +395,7 @@ Ask the user: _"I'll revoke the invite [note or ID]. It will no longer be usable
 First, list invites to find the invite's `id`, then revoke:
 
 ```bash
-curl -s -X DELETE "$INTERNAL_GATEWAY_BASE_URL/v1/ingress/invites/<invite_id>" \
+curl -s -X DELETE "$INTERNAL_GATEWAY_BASE_URL/v1/contacts/invites/<invite_id>" \
   -H "Authorization: Bearer $GATEWAY_AUTH_TOKEN"
 ```
 
@@ -425,10 +432,10 @@ Each channel has:
 
 - If a request returns `{ ok: false, error: "..." }`, report the error message to the user.
 - Common errors:
-  - `sourceChannel is required` -- ask the user which channel the contact is on.
-  - `At least one of externalUserId or externalChatId is required` -- ask the user for the contact's channel-specific identifier.
-  - `Member not found or cannot be revoked` -- the member ID may be invalid or the member is already revoked.
-  - `Member not found or already blocked` -- the member ID may be invalid or the member is already blocked.
+  - `Channel not found` -- the channel ID may be invalid; list contacts to find the correct channel ID.
+  - `Channel already revoked` -- the channel has already been revoked.
+  - `Channel already blocked` -- the channel has already been blocked.
+  - `Cannot revoke a blocked channel` -- the channel is blocked; blocking is stronger than revoking. Tell the user the contact is already blocked.
   - `sourceChannel is required for create` -- when creating an invite, always pass `"sourceChannel": "telegram"` for Telegram or `"sourceChannel": "voice"` for voice invites.
   - `expectedExternalUserId is required for voice invites` -- voice invites must include the invitee's phone number.
   - `expectedExternalUserId must be in E.164 format` -- the phone number must start with `+` followed by country code and number (e.g., `+15551234567`).
@@ -445,15 +452,15 @@ Each channel has:
 
 ## Typical Workflows
 
-**"Who can message me?"** -- List all active members, present as a formatted list.
+**"Who can message me?"** -- List all contacts, present active channels as a formatted list.
 
-**"Add my friend to Telegram"** -- Ask for their Telegram user ID (numeric) and optional display name, confirm, then add with `policy: "allow"` and `status: "active"`.
+**"Add my friend to Telegram"** -- Ask for their Telegram user ID (numeric) and display name, confirm, then create a contact with a channel entry with `policy: "allow"` and `status: "active"`.
 
-**"Remove [name]'s access"** -- List members to find them, confirm the revocation, then delete.
+**"Remove [name]'s access"** -- List contacts to find them, identify the channel to revoke, confirm the revocation, then patch the channel status to `"revoked"`.
 
-**"Block [name]"** -- List members to find them, confirm the block, then execute.
+**"Block [name]"** -- List contacts to find them, identify the channel to block, confirm the block, then patch the channel status to `"blocked"`.
 
-**"Show me blocked contacts"** -- List with `status=blocked` filter.
+**"Show me blocked contacts"** -- List contacts and filter for channels with `status: "blocked"`.
 
 **"Create a Telegram invite link"** / **"Invite someone on Telegram"** -- Create an invite with `sourceChannel: "telegram"`, look up the bot username, build the deep link, and present it with sharing instructions.
 

package/src/config/bundled-skills/contacts/TOOLS.json

@@ -41,7 +41,15 @@
               "properties": {
                 "type": {
                   "type": "string",
-                  "enum": ["email", "slack", "whatsapp", "phone", "telegram", "discord", "other"],
+                  "enum": [
+                    "email",
+                    "slack",
+                    "whatsapp",
+                    "phone",
+                    "telegram",
+                    "discord",
+                    "other"
+                  ],
                   "description": "Channel type"
                 },
                 "address": {
@@ -55,6 +63,10 @@
               },
               "required": ["type", "address"]
             }
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["display_name"]
@@ -76,7 +88,7 @@
           },
           "channel_address": {
             "type": "string",
-            "description": "Search by channel address (email, phone, handle — partial match)"
+            "description": "Search by channel address (email, phone, handle \u2014 partial match)"
           },
           "channel_type": {
             "type": "string",
@@ -89,6 +101,10 @@
           "limit": {
             "type": "number",
             "description": "Maximum results to return (default 20, max 100)"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": []
@@ -111,6 +127,10 @@
           "merge_id": {
             "type": "string",
             "description": "ID of the contact to merge into the kept contact (will be deleted)"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["keep_id", "merge_id"]

package/src/config/bundled-skills/contacts/tools/contact-merge.ts

@@ -1,5 +1,8 @@
-import { getGatewayInternalBaseUrl } from "../../../../config/env.js";
-import { mintEdgeRelayToken } from "../../../../runtime/auth/token-service.js";
+import {
+  gatewayGet,
+  gatewayPost,
+  GatewayRequestError,
+} from "../../../../runtime/gateway-internal-client.js";
 import type {
   ToolContext,
   ToolExecutionResult,
@@ -35,72 +38,49 @@ export async function executeContactMerge(
   }
 
   try {
-    const gatewayBase = getGatewayInternalBaseUrl();
-    const token = mintEdgeRelayToken();
-    const headers = {
-      Accept: "application/json",
-      Authorization: `Bearer ${token}`,
-    };
-
     // Validate both contacts exist before merging
-    const [keepResp, mergeResp] = await Promise.all([
-      fetch(`${gatewayBase}/v1/contacts/${keepId}`, {
-        method: "GET",
-        headers,
-      }),
-      fetch(`${gatewayBase}/v1/contacts/${mergeId}`, {
-        method: "GET",
-        headers,
-      }),
+    const [keepResult, mergeResult] = await Promise.allSettled([
+      gatewayGet<{ ok: boolean; contact: ContactResponse }>(
+        `/v1/contacts/${keepId}`,
+      ),
+      gatewayGet<{ ok: boolean; contact: ContactResponse }>(
+        `/v1/contacts/${mergeId}`,
+      ),
     ]);
 
-    if (!keepResp.ok) {
-      return { content: `Error: Contact "${keepId}" not found`, isError: true };
+    if (keepResult.status === "rejected") {
+      if (
+        keepResult.reason instanceof GatewayRequestError &&
+        keepResult.reason.statusCode === 404
+      ) {
+        return {
+          content: `Error: Contact "${keepId}" not found`,
+          isError: true,
+        };
+      }
+      throw keepResult.reason;
     }
-    if (!mergeResp.ok) {
-      return {
-        content: `Error: Contact "${mergeId}" not found`,
-        isError: true,
-      };
+    if (mergeResult.status === "rejected") {
+      if (
+        mergeResult.reason instanceof GatewayRequestError &&
+        mergeResult.reason.statusCode === 404
+      ) {
+        return {
+          content: `Error: Contact "${mergeId}" not found`,
+          isError: true,
+        };
+      }
+      throw mergeResult.reason;
     }
 
-    const keepData = (await keepResp.json()) as {
-      ok: boolean;
-      contact: ContactResponse;
-    };
-    const mergeData = (await mergeResp.json()) as {
-      ok: boolean;
-      contact: ContactResponse;
-    };
-    const keepContact = keepData.contact;
-    const mergeContact = mergeData.contact;
+    const keepContact = keepResult.value.contact;
+    const mergeContact = mergeResult.value.contact;
 
     // Execute the merge
-    const mergeResult = await fetch(`${gatewayBase}/v1/contacts/merge`, {
-      method: "POST",
-      headers: {
-        ...headers,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({ keepId, mergeId }),
-    });
-
-    if (!mergeResult.ok) {
-      const body = await mergeResult.text();
-      let message = `Gateway request failed (${mergeResult.status})`;
-      try {
-        const parsed = JSON.parse(body) as { error?: string };
-        if (parsed.error) message = parsed.error;
-      } catch {
-        if (body) message = body;
-      }
-      return { content: `Error: ${message}`, isError: true };
-    }
-
-    const resultData = (await mergeResult.json()) as {
+    const { data: resultData } = await gatewayPost<{
       ok: boolean;
       contact: ContactResponse;
-    };
+    }>("/v1/contacts/merge", { keepId, mergeId });
     const merged = resultData.contact;
 
     const channelList = merged.channels

package/src/config/bundled-skills/contacts/tools/contact-search.ts

@@ -1,5 +1,7 @@
-import { getGatewayInternalBaseUrl } from "../../../../config/env.js";
-import { mintEdgeRelayToken } from "../../../../runtime/auth/token-service.js";
+import {
+  gatewayGet,
+  GatewayRequestError,
+} from "../../../../runtime/gateway-internal-client.js";
 import type {
   ToolContext,
   ToolExecutionResult,
@@ -56,9 +58,6 @@ export async function executeContactSearch(
   }
 
   try {
-    const gatewayBase = getGatewayInternalBaseUrl();
-    const token = mintEdgeRelayToken();
-
     const params = new URLSearchParams();
     if (query) params.set("query", query);
     if (channelAddress) params.set("channelAddress", channelAddress);
@@ -67,32 +66,9 @@ export async function executeContactSearch(
     if (limit !== undefined) params.set("limit", String(limit));
 
     const qs = params.toString();
-    const url = `${gatewayBase}/v1/contacts${qs ? `?${qs}` : ""}`;
-
-    const resp = await fetch(url, {
-      method: "GET",
-      headers: {
-        Accept: "application/json",
-        Authorization: `Bearer ${token}`,
-      },
-    });
-
-    if (!resp.ok) {
-      const body = await resp.text();
-      let message = `Gateway request failed (${resp.status})`;
-      try {
-        const parsed = JSON.parse(body) as { error?: string };
-        if (parsed.error) message = parsed.error;
-      } catch {
-        if (body) message = body;
-      }
-      return { content: `Error: ${message}`, isError: true };
-    }
-
-    const data = (await resp.json()) as {
-      ok: boolean;
-      contacts: ContactResponse[];
-    };
+    const data = await gatewayGet<{ ok: boolean; contacts: ContactResponse[] }>(
+      `/v1/contacts${qs ? `?${qs}` : ""}`,
+    );
     const results = data.contacts;
 
     if (results.length === 0) {
@@ -109,6 +85,10 @@ export async function executeContactSearch(
 
     return { content: lines.join("\n"), isError: false };
   } catch (err) {
+    if (err instanceof GatewayRequestError) {
+      const message = err.gatewayError ?? err.message;
+      return { content: `Error: ${message}`, isError: true };
+    }
     const msg = err instanceof Error ? err.message : String(err);
     return { content: `Error: ${msg}`, isError: true };
   }

package/src/config/bundled-skills/contacts/tools/contact-upsert.ts

@@ -1,5 +1,7 @@
-import { getGatewayInternalBaseUrl } from "../../../../config/env.js";
-import { mintEdgeRelayToken } from "../../../../runtime/auth/token-service.js";
+import {
+  gatewayPost,
+  GatewayRequestError,
+} from "../../../../runtime/gateway-internal-client.js";
 import type {
   ToolContext,
   ToolExecutionResult,
@@ -78,49 +80,29 @@ export async function executeContactUpsert(
   }));
 
   try {
-    const gatewayBase = getGatewayInternalBaseUrl();
-    const token = mintEdgeRelayToken();
-
-    const resp = await fetch(`${gatewayBase}/v1/contacts`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${token}`,
-      },
-      body: JSON.stringify({
-        id: input.id as string | undefined,
-        displayName: displayName.trim(),
-        relationship: input.relationship as string | undefined,
-        importance,
-        responseExpectation: input.response_expectation as string | undefined,
-        preferredTone: input.preferred_tone as string | undefined,
-        channels,
-      }),
-    });
-
-    if (!resp.ok) {
-      const body = await resp.text();
-      let message = `Gateway request failed (${resp.status})`;
-      try {
-        const parsed = JSON.parse(body) as { error?: string };
-        if (parsed.error) message = parsed.error;
-      } catch {
-        if (body) message = body;
-      }
-      return { content: `Error: ${message}`, isError: true };
-    }
-
-    const data = (await resp.json()) as {
+    const { status, data } = await gatewayPost<{
       ok: boolean;
       contact: ContactResponse;
-    };
-    const created = resp.status === 201;
+    }>("/v1/contacts", {
+      id: input.id as string | undefined,
+      displayName: displayName.trim(),
+      relationship: input.relationship as string | undefined,
+      importance,
+      responseExpectation: input.response_expectation as string | undefined,
+      preferredTone: input.preferred_tone as string | undefined,
+      channels,
+    });
+
+    const created = status === 201;
 
     return {
       content: `${created ? "Created" : "Updated"} contact:\n${formatContact(data.contact)}`,
       isError: false,
     };
   } catch (err) {
+    if (err instanceof GatewayRequestError) {
+      return { content: `Error: ${err.message}`, isError: true };
+    }
     const msg = err instanceof Error ? err.message : String(err);
     return { content: `Error: ${msg}`, isError: true };
   }

package/src/config/bundled-skills/document/TOOLS.json

@@ -16,6 +16,10 @@
           "initial_content": {
             "type": "string",
             "description": "Initial Markdown content to populate the editor (optional)"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         }
       },
@@ -42,6 +46,10 @@
             "type": "string",
             "enum": ["replace", "append"],
             "description": "Whether to replace all content or append to the end. Defaults to append."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["surface_id", "content"]

package/src/config/bundled-skills/email-setup/SKILL.md

@@ -2,7 +2,7 @@
 name: "Email Setup"
 description: "Create the assistant's own email address via the Vellum hosted API (one-time setup)"
 user-invocable: true
-metadata: {"vellum": {"emoji": "📧"}}
+metadata: { "vellum": { "emoji": "📧" } }
 ---
 
 You are setting up your own personal email address. This is a one-time operation — once you have an email, you do not need to run this again.
@@ -16,17 +16,17 @@ Only proceed if the user explicitly asks you to create or set up **your own** (t
 Before doing anything, check whether you already have an email address configured:
 
 ```bash
-vellum email status --json
+vellum email status
 ```
 
-Inspect `health.inboxes` in the response. If at least one inbox exists, tell the user the existing address and stop — do NOT create another one.
+Inspect `addresses` in the response. If at least one address exists, tell the user the existing address and stop — do NOT create another one.
 
 ## Step 2: Create Your Email
 
-Create a new inbox through the domain CLI:
+Create a new inbox through the CLI:
 
 ```bash
-vellum email inbox create --username <your-username> --json
+vellum email inbox create --username <your-username>
 ```
 
 For `<your-username>`, use your assistant name (lowercased, alphanumeric only). Check your identity from `IDENTITY.md` or `USER.md` to determine your name. If you don't have a name yet, ask the user what username they'd like for your email.
@@ -36,10 +36,10 @@ Use the returned `inbox.address` (or `inbox.id` if `address` is empty) as the cr
 ## Step 3: Verify Status
 
 ```bash
-vellum email status --json
+vellum email status
 ```
 
-Confirm the created inbox appears in `health.inboxes`.
+Confirm the created inbox appears in `addresses`.
 
 ## Step 4: Confirm Setup
 
@@ -58,8 +58,11 @@ After the inbox is created and visible in status:
 ## Troubleshooting
 
 ### API key not configured
+
 If you get an error about a missing API key, the email provider has not been set up. Tell the user:
+
 > "Email isn't configured yet. Please set up the email integration first."
 
 ### Inbox creation failed
+
 If inbox creation returns an error (e.g. username taken), try a variation of the name (append a number or use a nickname) and retry once. If it still fails, report the error to the user.

package/src/config/bundled-skills/followups/TOOLS.json

@@ -32,6 +32,10 @@
           "reminder_cron_id": {
             "type": "string",
             "description": "Deprecated alias for reminder_schedule_id. Use reminder_schedule_id instead."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["channel", "thread_id"]
@@ -63,6 +67,10 @@
           "overdue_only": {
             "type": "boolean",
             "description": "When true, return only pending follow-ups past their expected response deadline"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": []
@@ -89,6 +97,10 @@
           "thread_id": {
             "type": "string",
             "description": "Thread ID to match (used with channel for auto-resolution)"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": []