@plotday/twister 0.52.0 → 0.54.0

package/src/plot.ts

@@ -1,7 +1,6 @@
 import type { NewSchedule, NewScheduleOccurrence, Schedule } from "./schedule";
 import { type Tag } from "./tag";
 import { type Callback } from "./tools/callbacks";
-import { type AuthProvider } from "./tools/integrations";
 import { type JSONValue } from "./utils/types";
 import { Uuid } from "./utils/uuid";
 
@@ -12,13 +11,13 @@ export { type AuthProvider } from "./tools/integrations";
 
 /**
  * @fileoverview
- * Core Plot entity types for working with threads, notes, priorities, and contacts.
+ * Core Plot entity types for working with threads, notes, focuses, and contacts.
  *
  * ## Type Pattern: Null vs Undefined Semantics
  *
  * Plot entity types use a consistent pattern to distinguish between missing, unset, and explicitly cleared values:
  *
- * ### Entity Types (Thread, Priority, Note, Actor)
+ * ### Entity Types (Thread, Focus, Note, Actor)
  * - **Required fields**: No `?`, cannot be `undefined`
  *   - Example: `id: Uuid`, `title: string`
  * - **Nullable fields**: Use `| null` to allow explicit clearing
@@ -31,10 +30,10 @@ export { type AuthProvider } from "./tools/integrations";
  *   - `null` = field included but not set
  *   - Value = field has a value
  *
- * ### New* Types (NewThread, NewNote, NewPriority)
+ * ### New* Types (NewThread, NewNote, NewFocus)
  * Used for creating or updating entities. Support partial updates by distinguishing omitted vs cleared fields:
  * - **Required fields**: Must be provided (no `?`)
- *   - Example: `title: string` in NewPriority
+ *   - Example: `title: string` in NewFocus
  * - **Optional fields**: Use `?` to make them optional
  *   - Example: `title?: string`, `author?: NewActor`
  *   - `undefined` (omitted) = don't set/update this field
@@ -77,7 +76,7 @@ export { type AuthProvider } from "./tools/integrations";
 export type ActorId = string & { readonly __brand: "ActorId" };
 
 /**
- * Theme colors for priorities.
+ * Theme colors for focuses.
  */
 export enum ThemeColor {
   /** Catalyst - Green */
@@ -99,73 +98,67 @@ export enum ThemeColor {
 }
 
 /**
- * Represents a priority context within Plot.
+ * Represents a focus within Plot.
  *
- * Priorities are similar to projects in other apps. All Activity is in a Priority.
- * Priorities can be nested.
+ * A focus is similar to a project or area-of-life. All Activity is in a Focus.
+ * Focuses are flat — they have no parent and no children. Threads not matched
+ * to any focus live in the Inbox.
  */
-export type Priority = {
-  /** Unique identifier for the priority */
+export type Focus = {
+  /** Unique identifier for the focus */
   id: Uuid;
-  /** Human-readable title for the priority */
+  /** Human-readable title for the focus */
   title: string;
-  /** Whether this priority has been archived */
+  /** Whether this focus has been archived */
   archived: boolean;
   /**
-   * Optional key for referencing this priority.
-   * Keys are unique per priority tree (a user's personal priorities or the root of a shared priority).
+   * Optional key for referencing this focus.
+   * Keys are unique per user.
    */
   key: string | null;
-  /** Optional theme color for the priority (0-7). If not set, inherits from parent or defaults to 7 (Resolution). */
+  /** Optional theme color for the focus (0-7). Defaults to 7 (Resolution) when not set. */
   color: ThemeColor | null;
+  /** Optional icon for the focus (a curated icon key). Defaults to the focus icon when not set. */
+  icon: string | null;
 };
 
 /**
- * Type for creating new priorities.
+ * Type for creating new focuses.
  *
  * Supports multiple creation patterns:
- * - Provide a specific UUID for the priority
- * - Provide a key for upsert within the user's priorities
+ * - Provide a specific UUID for the focus
+ * - Provide a key for upsert within the user's focuses
  * - Omit both to auto-generate a new UUID
- *
- * Optionally specify a parent priority by ID or key for hierarchical structures.
  */
-export type NewPriority = Pick<Priority, "title"> &
-  Partial<Omit<Priority, "id" | "title">> &
+export type NewFocus = Pick<Focus, "title"> &
+  Partial<Omit<Focus, "id" | "title">> &
   (
     | {
         /**
-         * Unique identifier for the priority, generated by Uuid.Generate().
-         * Specifying an ID allows tools to track and upsert priorities.
+         * Unique identifier for the focus, generated by Uuid.Generate().
+         * Specifying an ID allows tools to track and upsert focuses.
          */
         id: Uuid;
       }
     | {
         /**
-         * Unique key for the priority within the user's priorities.
+         * Unique key for the focus within the user's focuses.
          * Can be used to upsert without knowing the UUID.
-         * For example, "@plot" identifies the Plot priority.
+         * For example, "@plot" identifies the Plot focus.
          */
         key: string;
       }
     | {
         /* Neither id nor key is required. An id will be generated and returned. */
       }
-  ) & {
-    /** Add the new priority as the child of another priority */
-    parent?: { id: Uuid } | { key: string };
-  };
+  );
 
 /**
- * Type for updating existing priorities.
- * Must provide either id or key to identify the priority to update.
- * Set `parent` to move the priority under a new parent (requires PriorityAccess.Full).
+ * Type for updating existing focuses.
+ * Must provide either id or key to identify the focus to update.
  */
-export type PriorityUpdate = ({ id: Uuid } | { key: string }) &
-  Partial<Pick<Priority, "title" | "archived">> & {
-    /** Move the priority under a new parent. Requires PriorityAccess.Full. */
-    parent?: { id: Uuid } | { key: string };
-  };
+export type FocusUpdate = ({ id: Uuid } | { key: string }) &
+  Partial<Pick<Focus, "title" | "archived">>;
 
 /**
  * Enumeration of supported action types.
@@ -184,6 +177,8 @@ export enum ActionType {
   conferencing = "conferencing",
   /** File attachment links stored in R2 */
   file = "file",
+  /** Reference to an attachment hosted by a connector's source system */
+  fileRef = "fileRef",
   /** Thread reference links for navigating to related threads */
   thread = "thread",
   /** Structured plan of operations for user approval */
@@ -301,6 +296,22 @@ export type Action =
       /** Intrinsic height of the image in pixels (only for image files) */
       imageHeight?: number | null;
     }
+  | {
+      /** Reference to an attachment hosted by a connector's source system */
+      type: ActionType.fileRef;
+      /** Opaque identifier interpreted only by the owning connector */
+      ref: string;
+      /** Display filename */
+      fileName: string;
+      /** File size in bytes if known */
+      fileSize: number | null;
+      /** MIME type */
+      mimeType: string;
+      /** Intrinsic width of the image in pixels (only for image files) */
+      imageWidth?: number | null;
+      /** Intrinsic height of the image in pixels (only for image files) */
+      imageHeight?: number | null;
+    }
   | {
       /** Thread reference action for navigating to a related thread */
       type: ActionType.thread;
@@ -358,9 +369,9 @@ export type ThreadMeta = {
 
 /**
  * Thread sub-type that determines the thread's icon and category.
- * Available types depend on whether the priority is shared:
- * - Private priorities: "action" (default for tasks), "notes" (default), "idea", "goal", "decision"
- * - Shared priorities: all above plus "discussion" (default), "announcement", "ask"
+ * Available types depend on whether the focus is shared:
+ * - Private focuses: "action" (default for tasks), "notes" (default), "idea", "goal", "decision"
+ * - Shared focuses: all above plus "discussion" (default), "announcement", "ask"
  */
 export type ThreadType =
   | "action"
@@ -382,10 +393,39 @@ export type Tags = { [K in Tag]?: ActorId[] };
  */
 export type NewTags = { [K in Tag]?: NewActor[] };
 
+/**
+ * A single emoji reaction key. Either:
+ * - A Unicode emoji grapheme cluster (e.g. `"👍"`, `"👨‍👩‍👧"`), or
+ * - A provider-scoped custom-emoji ref of the form
+ *   `"<provider>:<workspaceId>/<name>"` (e.g. `"slack:T0123/party_parrot"`).
+ *
+ * Anything matching a known provider prefix is treated as a custom-emoji
+ * reference; everything else is rendered as the Unicode it contains.
+ *
+ * Reactions are the open-set counterpart to {@link Tag}'s count range
+ * (`1000+`). Use reactions for emoji that round-trip with chat platforms;
+ * use tags for Plot-managed compute/toggle state (todo, pinned, urgent,
+ * ...).
+ */
+export type Reaction = string;
+
+/**
+ * Emoji reactions on an item, keyed by emoji string, with the list of
+ * actors who added each reaction.
+ */
+export type Reactions = Record<Reaction, ActorId[]>;
+
+/**
+ * A set of reactions to add to an item, along with the actors adding each
+ * reaction. To remove a reaction for a given actor, omit them from the
+ * `NewActor[]` list — passing an empty list removes the reaction entirely.
+ */
+export type NewReactions = Record<Reaction, NewActor[]>;
+
 /**
  * Thread access level determining visibility.
- * - "public": Visible to all users with priority access
- * - "members": Visible to priority members (default for shared priorities)
+ * - "public": Visible to all users with focus access
+ * - "members": Visible to focus members (default for shared focuses)
  * - "private": Visible only to creator and contacts listed in accessContacts
  */
 export type ThreadAccessLevel = "public" | "members" | "private";
@@ -408,6 +448,12 @@ export type ThreadCommon = {
   archived: boolean;
   /** Tags attached to this thread. Maps tag ID to array of actor IDs who added that tag. */
   tags: Tags;
+  /**
+   * Emoji reactions on this item. Maps each emoji (Unicode grapheme or
+   * `provider:workspace/name` custom-emoji ref) to the list of actor IDs
+   * who reacted with it.
+   */
+  reactions: Reactions;
 };
 
 /**
@@ -417,8 +463,8 @@ export type ThreadCommon = {
 type ThreadFields = ThreadCommon & {
   /** The display title/summary of the thread */
   title: string;
-  /** The priority context this thread belongs to */
-  priority: Priority;
+  /** The focus context this thread belongs to */
+  focus: Focus;
   /** The thread's sub-type/category. Determines the displayed icon. */
   type: ThreadType | null;
   /** Thread access level: "public", "members", or "private" */
@@ -454,7 +500,7 @@ export type NewThreadWithNotes = NewThread & {
  * ```
  */
 export type NewThread = Partial<
-  Omit<ThreadFields, "priority" | "tags" | "id" | "accessContacts">
+  Omit<ThreadFields, "focus" | "tags" | "reactions" | "id" | "accessContacts">
 > &
   (
     | {
@@ -466,14 +512,20 @@ export type NewThread = Partial<
       }
   ) &
   {
-    /** Explicit priority - disables automatic priority matching. When omitted, the server classifies the thread using the user's priority rules. */
-    priority?: Pick<Priority, "id">;
+    /** Explicit focus - disables automatic focus matching. When omitted, the server classifies the thread using the user's focus rules. */
+    focus?: Pick<Focus, "id">;
   } & {
     /**
      * All tags to set on the new thread.
      */
     tags?: NewTags;
 
+    /**
+     * Emoji reactions to set on the new thread.
+     * Each emoji maps to the list of actors who reacted with it.
+     */
+    reactions?: NewReactions;
+
     /**
      * The thread's sub-type/category. Sets the thread's icon.
      * If omitted, defaults to "notes" (private) or "discussion" (shared).
@@ -492,7 +544,7 @@ export type NewThread = Partial<
      * - undefined/omitted (default): Thread is unread for users, except auto-marked
      *   as read for the author if they are the twist owner (user)
      * - true: Thread is explicitly unread for ALL users (use sparingly)
-     * - false: Thread is marked as read for all users in the priority at creation time
+     * - false: Thread is marked as read for all users in the focus at creation time
      */
     unread?: boolean;
 
@@ -549,6 +601,12 @@ type ThreadSingleUpdateFields = ThreadBulkUpdateFields & {
    */
   tags?: NewTags;
 
+  /**
+   * Emoji reactions to change on the thread. Pass an empty `NewActor[]` to
+   * remove a reaction entirely; omit an emoji to leave it untouched.
+   */
+  reactions?: NewReactions;
+
   /**
    * Add or remove the twist's tags.
    * Maps tag ID to boolean: true = add tag, false = remove tag.
@@ -574,10 +632,10 @@ type ThreadSingleUpdateFields = ThreadBulkUpdateFields & {
   preview?: string | null;
 
   /**
-   * Move the thread to a different priority. Requires ThreadAccess.Full.
-   * The target priority must be owned by the twist's user.
+   * Move the thread to a different focus. Requires ThreadAccess.Full.
+   * The target focus must be owned by the twist's user.
    */
-  priority?: Pick<Priority, "id">;
+  focus?: Pick<Focus, "id">;
 };
 
 export type ThreadUpdate =
@@ -635,7 +693,7 @@ export type Note = ThreadCommon & {
    * When set (even to []), the note is private to the listed contacts plus the creator.
    */
   accessContacts: ActorId[] | null;
-  /** Priority twist IDs (twists/connectors) mentioned for dispatch routing. Does not include user contacts. */
+  /** Focus twist IDs (twists/connectors) mentioned for dispatch routing. Does not include user contacts. */
   mentions: ActorId[];
 };
 
@@ -651,7 +709,7 @@ export type Note = ThreadCommon & {
 export type NewNote = Partial<
   Omit<
     Note,
-    "author" | "thread" | "tags" | "mentions" | "accessContacts" | "id" | "key" | "reNote"
+    "author" | "thread" | "tags" | "reactions" | "mentions" | "accessContacts" | "id" | "key" | "reNote"
   >
 > &
   ({ id: Uuid } | { key: string } | {}) & {
@@ -681,6 +739,12 @@ export type NewNote = Partial<
      */
     tags?: NewTags;
 
+    /**
+     * Emoji reactions to set on the note. Pass an empty `NewActor[]` to
+     * remove a reaction entirely; omit an emoji to leave it untouched.
+     */
+    reactions?: NewReactions;
+
     /**
      * Contacts who can see this note, or null/undefined to inherit thread visibility.
      * Accepts resolved ActorId UUIDs or email-based NewContact objects (resolved server-side).
@@ -701,7 +765,7 @@ export type NewNote = Partial<
      * - undefined/omitted (default): Thread is unread for users, except auto-marked
      *   as read for the author if they are the twist owner (user)
      * - true: Thread is explicitly unread for ALL users (use sparingly)
-     * - false: Thread is marked as read for all users in the priority at note creation time
+     * - false: Thread is marked as read for all users in the focus at note creation time
      *
      * For the default behavior, omit this field entirely.
      * Use false for initial sync to avoid marking historical items as unread.
@@ -748,6 +812,12 @@ export type NoteUpdate = ({ id: Uuid; key?: string } | { key: string }) &
      */
     tags?: NewTags;
 
+    /**
+     * Emoji reactions to change on the note. Pass an empty `NewActor[]` to
+     * remove a reaction entirely; omit an emoji to leave it untouched.
+     */
+    reactions?: NewReactions;
+
     /**
      * Add or remove the twist's tags.
      * Maps tag ID to boolean: true = add tag, false = remove tag.
@@ -861,8 +931,22 @@ type NewContactBase = {
   /**
    * External provider account source. Used for identity resolution
    * when email is unavailable and for privacy compliance reporting.
+   *
+   * The runtime scopes the resulting `contact_external_account` row to
+   * the dispatching twist instance (i.e. one row per connection per
+   * contact), so the same Plot contact can have multiple rows when
+   * reachable through multiple connections (e.g. two Slack workspaces,
+   * Gmail + Google Chat sharing one Google account).
    */
-  source?: { provider: AuthProvider; accountId: string };
+  source?: { accountId: string };
+  /**
+   * Optional connector-defined role for this contact on the thread, matching
+   * a `LinkTypeConfig.contactRoles[].id` (e.g. "to" / "cc" / "bcc" for
+   * email, "required" / "optional" for calendar). Omitted ⇒ default role.
+   * Connectors set this on inbound sync; the runtime persists it under
+   * `thread.contact_meta[contact_id].role`.
+   */
+  role?: string;
 };
 
 /**
@@ -954,7 +1038,7 @@ export type NewLink = Partial<
 > & {
   /**
    * Canonical ID for the item in an external system.
-   * When set, uniquely identifies the link within a priority tree. This performs
+   * When set, uniquely identifies the link for the user. This performs
    * an upsert.
    *
    * @deprecated Pass `sources: [...]` instead. Both fields can be set during
@@ -988,7 +1072,7 @@ export type NewLink = Partial<
      * Whether the thread should be marked as unread for users.
      * - undefined/omitted (default): Thread is unread for users, except auto-marked
      *   as read for the author if they are the twist owner (user)
-     * - false: Thread is marked as read for all users in the priority at creation time
+     * - false: Thread is marked as read for all users in the focus at creation time
      */
     unread?: boolean;
     /**
@@ -999,11 +1083,11 @@ export type NewLink = Partial<
      */
     archived?: boolean;
     /**
-     * Explicit priority (disables automatic priority matching).
+     * Explicit focus (disables automatic focus matching).
      * Only used when the link creates a new thread. When omitted, the
-     * server classifies the thread using the user's priority rules.
+     * server classifies the thread using the user's focus rules.
      */
-    priority?: Pick<Priority, "id">;
+    focus?: Pick<Focus, "id">;
   };
 
 /**
@@ -1051,8 +1135,8 @@ export type PlanOperation =
       /** Current thread title for display */
       threadTitle: string;
       changes: Partial<Pick<ThreadFields, "archived" | "title" | "type">> & {
-        /** Move to this priority */
-        priority?: { id: Uuid; title: string };
+        /** Move to this focus */
+        focus?: { id: Uuid; title: string };
       };
     }
   | {
@@ -1069,9 +1153,9 @@ export type PlanOperation =
   | {
       type: "createThread";
       title: string;
-      priorityId: Uuid;
-      /** Priority title for display */
-      priorityTitle: string;
+      focusId: Uuid;
+      /** Focus title for display */
+      focusTitle: string;
     }
   | {
       type: "createNote";
@@ -1081,12 +1165,9 @@ export type PlanOperation =
       content: string;
     }
   | {
-      type: "updatePriority";
-      priorityId: Uuid;
-      /** Current priority title for display */
-      priorityTitle: string;
-      changes: Partial<Pick<Priority, "title" | "archived">> & {
-        /** Move under this parent */
-        parent?: { id: Uuid; title: string };
-      };
+      type: "updateFocus";
+      focusId: Uuid;
+      /** Current focus title for display */
+      focusTitle: string;
+      changes: Partial<Pick<Focus, "title" | "archived">>;
     };

package/src/schedule.ts

@@ -14,7 +14,7 @@ export { Uuid } from "./utils/uuid";
  * Represents a schedule entry for a thread.
  *
  * Schedules define when a thread occurs in time. A thread may have zero or more schedules:
- * - Shared schedules (userId is null): visible to all members of the thread's priority
+ * - Shared schedules (userId is null): visible to all members of the thread's focus
  * - Per-user schedules (userId set): private ordering/scheduling for a specific user
  *
  * For recurring events in the SDK, start/end represent the first occurrence's

package/src/tag.ts

@@ -1,54 +1,23 @@
 /**
- * Thread tags. Three types:
- * 1. Special tags, which trigger other behaviors
- * 2. Toggle tags, which anyone can toggle a shared value on or off
- * 3. Count tags, where everyone can add or remove their own
+ * Compute tags — system state the runtime auto-manages on threads and
+ * notes (`todo`, `done`, `twist` activity marker, …).
+ *
+ * The toggle range (100–999) and count range (1000–1027) have been
+ * retired in favour of the open Unicode emoji `Reaction` type — see
+ * `@plotday/twister/plot`'s `Reactions` / `NewReactions` and the
+ * per-row `note.reactions` / `thread.reactions` fields. Connectors
+ * route emoji reactions through `reactions`, not `tags`.
+ *
+ * `Tag.Twist` is the surviving non-trivial tag: a system marker the
+ * runtime adds to a note while a twist is processing it, and clears
+ * once the twist returns. It's not user-facing and not a reaction.
  */
 export enum Tag {
-  // Special tags
   Todo = 1,
   Done = 3,
-
-  // Toggle tags
-  Pinned = 100,
-  Urgent = 101,
-  Goal = 103,
-  Decision = 104,
-  Waiting = 105,
-  Blocked = 106,
-  Warning = 107,
-  Question = 108,
-  Twist = 109,
-  Star = 110,
-  Idea = 111,
-
-  // Count tags
-  Yes = 1000,
-  No = 1001,
-  Volunteer = 1002,
-  Tada = 1003,
-  Fire = 1004,
-  Totally = 1005,
-  Looking = 1006,
-  Love = 1007,
-  Rocket = 1008,
-  Sparkles = 1009,
-  Thanks = 1010,
-  Smile = 1011,
-  Wave = 1012,
-  Praise = 1015,
-  Applause = 1016,
-  Cool = 1017,
-  Sad = 1018,
-  Reply = 1019,
-  Thinking = 1013,
-  Remember = 1014,
-  Agreed = 1020,
-  Relieved = 1021,
-  Send = 1022,
-  Noted = 1023,
-  Laugh = 1024,
-  Surprised = 1025,
-  Confused = 1026,
-  Dismayed = 1027,
+  /** System marker for "a twist is processing this note." Set by the
+   * runtime when a twist callback fires, cleared on return. Twists
+   * may still write `{ [Tag.Twist]: true | false }` to twistTags to
+   * mark/unmark a note explicitly. */
+  Twist = 12,
 }

package/src/tools/ai.ts

@@ -69,8 +69,11 @@ export abstract class AI extends ITool {
    * Returns which AI capabilities are currently available.
    * Check this before calling prompt() or embed() to gracefully
    * handle cases where AI is disabled by the user.
+   *
+   * Built-in tools are accessed as RPC stubs, so from a twist this call
+   * resolves asynchronously — always `await` it.
    */
-  abstract available(): AICapabilities;
+  abstract available(): AICapabilities | Promise<AICapabilities>;
 
   /**
    * Sends a request to an AI model and returns the response using the Vercel AI SDK.
@@ -134,7 +137,7 @@ export abstract class AI extends ITool {
    *   tools: {
    *     getWeather: {
    *       description: "Get weather for a city",
-   *       parameters: Type.Object({
+   *       inputSchema: Type.Object({
    *         city: Type.String()
    *       }),
    *       execute: async ({ city }) => {
@@ -165,6 +168,12 @@ export type AICapabilities = {
   prompt: boolean;
   /** Whether AI embedding generation is available. */
   embed: boolean;
+  /**
+   * Whether provider-native web search is available. True for Plot AI and
+   * Anthropic/Google BYOK providers; false for OpenAI/custom BYOK providers
+   * that don't expose a server-side web search tool through this runtime.
+   */
+  webSearch: boolean;
 };
 
 /**
@@ -345,6 +354,31 @@ export interface AIRequest<
    * Controls diversity by limiting to top probability tokens.
    */
   topP?: number;
+
+  /**
+   * Enable provider-native web search so the model can retrieve
+   * up-to-date information from the web. The search is executed
+   * server-side by the provider and any pages used are returned in
+   * {@link AIResponse.sources}.
+   *
+   * Only available on web-search-capable providers (Anthropic and
+   * Google). Check {@link AICapabilities.webSearch} via `available()`
+   * before relying on it; on unsupported providers the flag is ignored.
+   *
+   * Pass `true` for defaults, or an object to cap the number of searches.
+   */
+  webSearch?: boolean | { maxUses?: number };
+
+  /**
+   * Maximum number of sequential generation steps for agentic tool use.
+   * When the model calls a tool, its result is fed back and the model is
+   * called again, up to `maxSteps` times, until it produces a final answer.
+   *
+   * Defaults to 1 (single step — tool calls are returned but not looped),
+   * preserving prior behavior. Set higher (e.g. 6) to let the model chain
+   * tool calls into a final answer.
+   */
+  maxSteps?: number;
 }
 
 /**
@@ -742,17 +776,19 @@ export interface ToolExecutionOptions {
  */
 export type AITool<PARAMETERS extends ToolParameters = any, RESULT = any> = {
   /**
-   * The schema of the input that the tool expects. The language model will use this to generate the input.
-   * It is also used to validate the output of the language model.
-   * Use descriptions to make the input understandable for the language model.
+   * The schema of the input that the tool expects, expressed as a Typebox
+   * schema. The language model uses this to generate (and the runtime to
+   * validate) the tool input. Use field descriptions to make the input
+   * understandable for the model.
+   *
+   * This is the canonical field read by the runtime. `parameters` is an
+   * accepted alias for backwards compatibility.
    */
-  parameters: PARAMETERS;
+  inputSchema: TSchema;
   /**
-   * The schema of the input that the tool expects. The language model will use this to generate the input.
-   * It is also used to validate the output of the language model.
-   * Use descriptions to make the input understandable for the language model.
+   * @deprecated Alias for {@link inputSchema}. Prefer `inputSchema`.
    */
-  inputSchema: TSchema;
+  parameters?: PARAMETERS;
   /**
    * An optional description of what the tool does.
    * Will be used by the language model to decide whether to use the tool.