import { z } from "zod"; import { GET_DATA_SUPPORTED_TYPES } from "../services/clients/get-data/get-data-constants"; export const PingSchema = z.object({}); export const GetRelevantQuestionsSchema = z.object({ query: z .string() .describe( "The query to get relevant data questions for, this could be a high level task or question the user is asking or hoping to get answered. Do minimal processing of the original question. You can even pass the complete raw query as it is, the system is smart to make sense of it as it has access to the entire schema. Do not add analytical hints or directions.", ), additionalContext: z .string() .describe( "Additional context to add to the query, this might be older data returned for previous questions or any other relevant context that might help the system generate better questions.", ) .optional(), datasourceIds: z .array(z.string()) .describe( "The datasources to get questions for, this is the ids of the datasources to get data from. This field is required. Each id is a GUID string of the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. An example datasource id is 123e4567-e89b-12d3-a456-426614174000. If a datasource name is provided instead of id, use the getDataSourceSuggestions tool to get the corresponding datasource id and use that to get relevant questions.", ), }); export const GetRelevantQuestionsOutputSchema = z.object({ questions: z.array( z.object({ question: z.string(), datasourceId: z.string(), }), ), }); export const GetAnswerSchema = z.object({ question: z .string() .describe( "The question to get the answer for, these are generally the questions generated by the getRelevantQuestions tool.", ), datasourceId: z .string() .describe( "The datasources to get questions for, this is the ids of the datasources to get data from. This field is required. Each id is a GUID string of the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. An example datasource id is 123e4567-e89b-12d3-a456-426614174000. If a datasource name is provided instead of id, use the getDataSourceSuggestions tool to get the corresponding datasource id and use that to get relevant questions.", ), }); export const GetAnswerOutputSchema = z.object({ data: z.string().describe("The csv data as an answer to the question"), session_identifier: z .string() .describe( "The session identifier for the answer, use for liveboard creation", ), generation_number: z .number() .describe( "The generation number for the answer, use for liveboard creation", ), frame_url: z .string() .describe( "A url which can be used to view the answer in an iframe in the browser", ), fields_info: z .string() .describe("Information about the fields in the answer"), }); export const SearchObjectsInputSchema = z.object({ query: z .string() .min(1) .describe( "The search term to find objects for, matched against object names or descriptions.", ), types: z .array(z.enum(["LIVEBOARD", "LIVEBOARD_VIZ", "ANSWER", "WORKSHEET"])) .optional() .describe( "Restrict results to these object types. Allowed values: 'LIVEBOARD', 'LIVEBOARD_VIZ' (a viz pinned on a Liveboard), 'ANSWER', 'WORKSHEET'. Omit to search all types.", ), author_name: z .string() .optional() .describe( "Restrict results to objects authored by the provided user, matched against the author's display name (case-insensitive).", ), tag: z .string() .optional() .describe( "Restrict results to objects carrying this tag/sticker, matched by tag name (case-insensitive).", ), modified_since: z .number() .int() .optional() .describe( "Only return objects last modified on or after this epoch-millisecond timestamp.", ), verified_only: z .boolean() .optional() .describe("If true, only return objects marked as verified."), limit: z .number() .int() .positive() .optional() .describe("The maximum number of results to return. Defaults to 10."), cursor: z .string() .optional() .describe( "Opaque pagination cursor returned as `next_cursor` by a previous call. Omit for the first page.", ), }); const SearchObjectResultSchema = z.object({ object_id: z .string() .describe( "The GUID to pass to get_data as `object_id`. For a visualization pinned on a Liveboard this is the parent Liveboard's GUID (see `visualization_id`).", ), visualization_id: z .string() .optional() .describe( "Set only when this result is a specific visualization on a Liveboard: `object_id` is the Liveboard and this is the visualization. Pass it to get_data as `visualization_ids` to fetch just this viz.", ), title: z.string().describe("The display name/title of the object."), type: z .string() .describe( "UPPER-case object type: 'LIVEBOARD', 'ANSWER', 'LIVEBOARD_VIZ' (a viz pinned on a Liveboard, i.e. a 'Liveboard viz'; `object_id` is the parent Liveboard and `visualization_id` the viz) or 'WORKSHEET'. Any of these can be passed straight back as a `types` filter.", ), author_name: z .string() .describe("The display name of the user who authored the object."), description: z .string() .optional() .describe("The description of the object; omitted when it has none."), tags: z .array(z.string()) .describe("The names of the tags/stickers applied to the object."), last_modified: z .string() .optional() .describe( "ISO-8601 timestamp of the last modification (e.g. 2026-05-15T14:30:00Z); omitted when unavailable. Render as a plain date.", ), verified: z.boolean().describe("Whether the object is marked as verified."), external_link: z .string() .describe( "Deep link to open the object in the ThoughtSpot UI (opens in a new browser tab; not an embeddable iframe URL).", ), query: z .string() .nullable() .describe( "For an Answer/viz: the sage/TML query tokens that define it (e.g. 'sales by region monthly'). Null for a Liveboard.", ), confidence: z .number() .describe( "Relevance score of the result for the search term. Ranking only β€” never surface as a number to the user.", ), }); // A search_objects call returns one of three scenarios: success (no `status`), // no_results, or error. Modeled as a single object (not a union) so the JSON // Schema root stays `type: "object"` β€” MCP clients reject an `anyOf` root // outputSchema. Scenario-specific fields are therefore optional. export const SearchObjectsResponseSchema = z.object({ status: z .enum(["no_results", "error"]) .optional() .describe( "Absent on a successful hit list. 'no_results' = the query ran but matched nothing; 'error' = the search failed (see `error`).", ), results: z .array(SearchObjectResultSchema) .describe( "Ranked results matching the search; empty for no_results/error.", ), next_cursor: z .string() .nullable() .optional() .describe( "Cursor to pass back as `cursor` for the next page; null when there are no more results, and omitted on error.", ), error: z .object({ code: z .enum([ "INVALID_ARGUMENT", "UNAUTHORIZED", "RATE_LIMITED", "UPSTREAM_TIMEOUT", "INTERNAL", ]) .describe("Machine-readable failure category. Never show to the user."), message: z .string() .describe("Human-readable failure reason; safe to relay to the user."), retryable: z .boolean() .describe("True when retrying the same call may succeed."), }) .optional() .describe("Present only on error."), }); export const GetDataInputSchema = z.object({ object_id: z .string() .describe( "The GUID of the object to fetch data for, typically an `object_id` returned by a prior `search_objects` call. Supports saved Answers and Liveboards. For an answer from the Analytics Agent, pass the answer's `answer_id` from `get_session_updates` verbatim.", ), object_type: z .enum(GET_DATA_SUPPORTED_TYPES) .describe( "The object's type. Required. For a `search_objects` result, pass its `type` verbatim β€” one of `ANSWER`, `LIVEBOARD`, or `LIVEBOARD_VIZ`. For `LIVEBOARD_VIZ` also pass that result's `visualization_id` in `visualization_ids` (else the request is rejected); it fetches via the parent Liveboard. For an answer from `get_session_updates`, pass `ANALYTICS_AGENT_ANSWER`.", ), visualization_ids: z .array( z.guid({ error: "Each `visualization_ids` entry must be a visualization GUID from a prior result (`viz_id` from get_data or `visualization_id` from search_objects), not a placeholder or name.", }), ) .optional() .describe( "When `object_id` corresponds to a Liveboard, restrict the fetch to these visualization GUIDs (use to pull a single visualization/answer pinned on a Liveboard). Omit to fetch as many of the Liveboard's visualizations as fit within the time limit. Ignored for standalone Answers.", ), max_rows: z .number() .int() .positive() .optional() .describe( "Maximum number of rows to return per visualization. Defaults to 25. Raise this only when you need the full result set and the object is known to be large.", ), }); const GetDataVizSchema = z.object({ viz_id: z .string() .optional() .describe( "The GUID of the visualization. Present for Liveboard visualizations; omitted for a standalone Answer.", ), viz_name: z .string() .optional() .describe( "The name of the visualization. Present for Liveboard visualizations.", ), columns: z.array(z.string()).describe("The column names, in order."), data_rows: z .array(z.array(z.union([z.string(), z.number(), z.boolean(), z.null()]))) .describe( "The data rows; each row is an array of cell values aligned to `columns` β€” each cell a string, number, boolean, or null. Numeric cells are returned at full precision, exactly as stored.", ), total_row_count: z .number() .optional() .describe( "Total rows available upstream, which may exceed the rows returned when capped by `max_rows`.", ), sampling_ratio: z .number() .optional() .describe( "Sampling ratio between 0 and 1; a value of 1 means the complete result set was returned (not sampled).", ), }); export const GetDataOutputSchema = z.object({ data: z .array(GetDataVizSchema) .describe( "The object's data. A single entry for an Answer; one entry per visualization for a Liveboard.", ), }); export const CheckConnectivityInputSchema = z.object({}); export const CheckConnectivityOutputSchema = z.object({ success: z .boolean() .describe( "Whether the request was successful. If unsuccessful, you can ask the user to verify their MCP server configuration.", ), }); export const CreateAnalysisSessionSpotter3InputSchema = z.object({ data_source_id: z .string() .optional() .describe( 'The ID of the data source to query. You can provide this when the user has specified or confirmed a data source, or when context makes a particular source obvious. Omit it to let the Analytics Agent automatically select the most relevant source based on the question; if the instance does not support automatic selection, the tool returns an error asking for a data source, which you can find with `search_objects`. A valid ID follows the following format: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (for example, "de1b3cfd-1725-400a-b6c7-0cd0f2b70bf1"). If you only have the data source name but not the ID, you can provide it in the `additional_context` field of the `send_session_message` tool instead.', ), }); export const CreateAnalysisSessionOutputSchema = z.object({ analytical_session_id: z .string() .describe( "Identifier for the analytical session. You can use this to send messages or get updates on the session.", ), }); export const SendSessionMessageInputSchema = z.object({ analytical_session_id: z .string() .describe("Identifier of the analytical session to send the message to."), message: z .string() .describe( "A natural language analytical question or follow-up to send to the Analytics Agent.", ), additional_context: z .string() .optional() .describe( 'Extra information which the Analytics Agent should be aware of while interpreting the `message`. You can use this field to provide background or external information relevant to the request, which the Agent would not be aware of. For example, "The user\'s fiscal year starts in April", or "The user is a manager of the West region".', ), }); export const SendSessionMessageSpotterXInputSchema = SendSessionMessageInputSchema.extend({ dashboard_id: z .string() .optional() .describe( 'The ID of a dashboard to ask questions about in this message. You can provide this when the user has specified or confirmed a dashboard, or when context makes a particular dashboard obvious. A valid ID follows the following format: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (for example, "de1b3cfd-1725-400a-b6c7-0cd0f2b70bf1"). If you only have the dashboard name but not the ID, you can search for it using the `search_objects` tool.', ), }); export const SendSessionMessageOutputSchema = z.object({ success: z .boolean() .describe( "Whether the message was successfully sent. If unsuccessful, you can try sending the message again, or creating a new analytical session.", ), }); export const GetSessionUpdatesInputSchema = z.object({ analytical_session_id: z .string() .describe("Identifier of the analytical session to get updates from."), }); export const ConversationUpdateSchema = z.object({ type: z .enum(["text", "text_chunk", "answer", "step_notification"]) .describe( "The type of update: `text` or `text_chunk` for a natural language message from the Analytics Agent, `answer` for a query result, or `step_notification` to announce key progress steps which the Agent is working through. Determines which other fields are populated.", ), is_thinking: z .boolean() .describe( "Whether this update is part of the Analytics Agent's thinking process. You can use this to separate thinking updates from final result updates. You can use the thinking updates to show intermediate status or progress information to the user.", ), text: z .string() .optional() .describe( "The text content of the message. Only present when `type` is `text`, `text_chunk`, or `step_notification`. If `type` is `text_chunk`, concatenate the chunks of text together in the order received to form the complete message. If `type` is `step_notification`, the text will describe the step the Analytics Agent is currently working on, and is not meant to be concatenated with other text-based events.", ), answer_id: z .string() .optional() .describe( "A unique identifier for the answer. Only present when `type` is `answer`. You can use this field to identify this answer when using the `create_dashboard` tool, or pass it to `get_data` with `object_type` `ANALYTICS_AGENT_ANSWER` to fetch the answer's rows.", ), answer_title: z .string() .optional() .describe( "A human-readable title describing what the answer shows. Only present when `type` is `answer`.", ), answer_data_source_id: z .string() .optional() .describe( "The identifier of the data source which the answer is created on. Only present when `type` is `answer`. You can use this to understand which answers were created with the same data source, or to initiate future conversations using the same data source.", ), answer_query: z .string() .optional() .describe( "The search query which the Analytics Agent used to generate the answer. Only present when `type` is `answer`. You can use this to explain to the user what data was queried, or to diagnose unexpected results.", ), iframe_url: z .string() .optional() .describe( "An embeddable URL for displaying the answer as an interactive visualization. Only present when `type` is `answer`, and only if embedded visualizations are enabled for this connection. If your environment supports iframes, you can use this URL as-is (do not modify it) to display an interactive chart or table. If your environment does not support iframes, you can modify the link (remove `?tsmcp=true` if present) and share it with the user to let them view the interactive visualization in a browser.", ), }); export const GetSessionUpdatesOutputSchema = z.object({ session_updates: z .array(ConversationUpdateSchema) .describe( "List of incremental new updates from the analytical session. Updates returned in a previous response will not be sent again. This may be an empty list if the Analytics Agent is still thinking. You can instead use the `is_done` flag to know whether the Agent response is complete.", ), is_done: z .boolean() .describe( "Whether the Analytics Agent has finished responding. If `is_done` is false, you can make another `get_session_updates` call to get the next set of updates.", ), }); export const GetSessionUpdatesRawOutputSchema = z.object({ session_updates: z .array(z.unknown()) .describe( "List of incremental new updates from the analytical session. The updates can be in any format, with no guarantees on their structure. Updates returned in a previous response will not be sent again. This may be an empty list if the Analytics Agent is still thinking. You can instead use the `is_done` flag to know whether the Agent response is complete.", ), is_done: z .boolean() .describe( "Whether the Analytics Agent has finished responding. If `is_done` is false, you can make another `get_session_updates` call to get the next set of updates.", ), }); export const CreateLiveboardSchema = z.object({ name: z.string().describe("The name of the liveboard to create"), answers: z .array( z.object({ question: z.string(), session_identifier: z.string(), generation_number: z.number(), }), ) .describe( "The answers to create the liveboard from, these are the answers generated by the getAnswer tool.", ), noteTile: z.string().describe(` Create a summary of the answers to the queries asked by the user along with all the analysis done on the data. The output format is an html note tile which can have custom styles and formatting. Use emojis, styling and icons to make it more visually appealing. Follow these MANDATORY rules for styling: - Put the whole note tile in a single line and no line breaks. Also there should be no unnecessary white spaces. - The html output in the note tile can have white spaces. Use
or if needed to use white spaces in the note tile. - Use padding, margin and line height to create space between the elements in the note tile and make it more readable. Use this as an example(ignore the line breaks and white spaces):

\"Heading of note\"

Comprehensive summary of analysis done and answers to queries asked by user. Use colors and styles in the html to make it more readable and visually appealing. Also add the date and time of the analysis to the note tile in the header of the note tile. The format should be like this: Generated on

`), }); export const GetDataSourceSuggestionsSchema = z.object({ query: z .string() .describe(`The query to get data source suggestions for, this could be a high level task or question the user is asking or hoping to get answered. There can be multiple data sources. Each data source can be used to get the data for the user's query using the other tools getRelevantQuestions and getAnswer.`), }); export const AnswerSchema = z.object({ answer_id: z .string() .describe( "The unique identifier for the answer. Provide the `answer_id` value returned from get_session_updates for an update where `type` is `answer`.", ), title: z .string() .describe( "Title of the answer. Provide a brief description of the answer, or the question which the answer is answering.", ), }); /** * The original `create_dashboard` contract: assemble answers into a liveboard, no design pass. * Served on every API version released before the dashboard designer tools, unchanged, so * existing integrations keep working. */ export const CreateDashboardLegacyInputSchema = z.object({ title: z.string().describe("Title of the dashboard to be created."), note_tile: z .string() .describe( 'Intended to be a summary of the contents of the dashboard. You can fill this with information about the questions asked by the user and the analyses performed to answer those questions. You can include any action items or next steps the user should consider taking. The format for the `note_tile` field is raw unescaped HTML, and can include custom styles, text formatting, and colors. You can include emojis for visual appeal. At the end, you can add a line indicating the date the content was generated. The entire content of the `note_tile` should be in a single line with no line breaks. You can use
or CSS styling to add spacing inside the HTML content where needed, but avoid unnecessary whitespace inside the content. Use unescaped raw HTML such as

and not <p>. Example content: "

Title of Note Tile

Comprehensive summary of questions and answers used to generate the dashboard. Use HTML formatting:
- Text styling to highlight important phrases
- πŸš€ Emojis for visual appeal

Generated on April 15, 2026

".', ), answers: z .array(AnswerSchema) .describe( "List of answers to add to the dashboard. The order of tiles on the dashboard will match the order of answers in this list (top to bottom, left to right).", ), }); export const CreateDashboardLegacyOutputSchema = z.object({ link: z .string() .describe( "A URL link to the created dashboard. You can provide this link to the user to view the dashboard.", ), }); const DATA_SOURCE_ID_GUIDANCE = 'Optional id of a data source, in the format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx". Omit it in most cases: the designer selects the most relevant data source automatically, and when changing a dashboard it uses the data sources the dashboard already has. Only provide it when the user has named or confirmed a specific data source.'; /** * Shared result shape for the dashboard tools. * * Field prose is deliberately sparse. This schema ships on all three tools, so every sentence here * is sent three times on every request. */ export const DashboardResultSchema = z.object({ status: z .enum(["completed", "in_progress", "needs_input", "failed"]) .describe( "Outcome of the request. See the tool description for what to do for each value.", ), dashboard_id: z.string().optional(), dashboard_url: z.string().optional(), task_id: z.string().optional(), changes_applied: z .boolean() .optional() .describe( "Whether the dashboard actually changed. False with `completed` means the request was understood but changed nothing.", ), message: z .string() .optional() .describe( "What the designer reported: what it is doing now (`in_progress`), its summary (`completed`), its plan or question (`needs_input`), or why it failed (`failed`).", ), choices: z .array(z.string()) .optional() .describe("Options the designer offered with its question."), }); export const CreateDashboardInputSchema = z .object({ title: z .string() .optional() .describe( "Title of the dashboard to be created. Required unless you pass `task_id`.", ), task_id: z .string() .optional() .describe( "`task_id` from an earlier `create_dashboard` call that returned a plan. Pass it to confirm the plan, with any changes in `instructions`, so the dashboard is built.", ), instructions: z .string() .optional() .describe( `The user's request for the dashboard, in their words. Do not add charts, metrics, filters or layout the user did not ask for: the designer proposes those in a plan for the user to confirm, so a short request should stay short. Add detail only when the user gave it (for example chart types, grouping, tabs, brand colours as hex codes, a data source they named) or when recreating an existing dashboard from a spec, such as a Tableau workbook. Not supported: changing an existing chart's type or query, or colouring individual data values.`, ), data_source_id: z.string().optional().describe(DATA_SOURCE_ID_GUIDANCE), answers: z .array(AnswerSchema) .optional() .describe( "List of answers to add to the dashboard, from a prior analysis. Omit this when you have no answers yet and want the charts built from `instructions` instead.", ), }) .describe("Pass `answers`, `instructions`, or both."); export const CreateDashboardOutputSchema = DashboardResultSchema; export const ModifyDashboardInputSchema = z.object({ dashboard_id: z .string() .min(1) .describe( "Id of the dashboard to change (a GUID). Find it with `search_objects` or from a dashboard link ending in `/pinboard/`; never pass a name or a guess.", ), task_id: z .string() .optional() .describe( "`task_id` from an earlier `modify_dashboard` call on the same dashboard. Pass it to answer the designer's question or follow up with its earlier context; omit it to start a fresh change.", ), instructions: z .string() .min(1) .describe( "What to change, in the user's words: layout or styling, new charts, or the user's answer to the designer's question. Do not add changes the user did not ask for.", ), data_source_id: z.string().optional().describe(DATA_SOURCE_ID_GUIDANCE), }); export const ModifyDashboardOutputSchema = DashboardResultSchema; export const GetDashboardStatusInputSchema = z.object({ task_id: z .string() .describe( "The `task_id` returned by `create_dashboard` or `modify_dashboard` when `status` was `in_progress`.", ), }); export const GetDashboardStatusOutputSchema = DashboardResultSchema; export const ListOrgsInputSchema = z.object({}); export const ListOrgsOutputSchema = z.object({ orgs: z .array( z.object({ id: z.number().describe("Unique identifier of the Org."), name: z.string().describe("Name of the Org."), description: z.string().optional().describe("Description of the Org."), is_active: z .boolean() .optional() .describe( "Present and true only for the Org currently active for your account. Absent for all other Orgs. Tool calls operate against the active Org.", ), }), ) .describe("The list of Orgs the user can access."), }); export const SwitchOrgInputSchema = z.object({ org_id: z .number() .describe( "The id of the Org to switch to. Use an `id` returned by `list_orgs`. Subsequent tool calls in this session operate against this Org.", ), }); export const SwitchOrgOutputSchema = z.object({ success: z.boolean().describe("Whether the Org switch was successful."), active_org_id: z .number() .describe("The id of the Org now active for the session."), }); export enum ToolName { // V1 Ping = "ping", GetRelevantQuestions = "getRelevantQuestions", GetAnswer = "getAnswer", CreateLiveboard = "createLiveboard", GetDataSourceSuggestions = "getDataSourceSuggestions", // V2 (Spotter 3) CheckConnectivity = "check_connectivity", SearchObjects = "search_objects", GetData = "get_data", CreateAnalysisSession = "create_analysis_session", SendSessionMessage = "send_session_message", GetSessionUpdates = "get_session_updates", CreateDashboard = "create_dashboard", ModifyDashboard = "modify_dashboard", GetDashboardStatus = "get_dashboard_status", ListOrgs = "list_orgs", SwitchOrg = "switch_org", // V3 (Spotter Model β€” agentic model creation) CreateModelSession = "create_model_session", SendModelMessage = "send_model_message", GetModelUpdates = "get_model_updates", FinalizeModel = "finalize_model", } /** * The Spotter Model tools. They all create or edit data models, so they are offered and accepted * as a group, gated on the user's data-modeling privileges. */ export const MODEL_TOOL_NAMES: string[] = [ ToolName.CreateModelSession, ToolName.SendModelMessage, ToolName.GetModelUpdates, ToolName.FinalizeModel, ]; // ── Spotter Model (V3) schemas ───────────────────────────────────────────── export const CreateModelSessionInputSchema = z.object({ connection_identifier: z .string() .optional() .describe( "GUID of the data-warehouse connection to build a NEW model on (e.g. " + "'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'). You should ask the user which connection to " + "build on and quote the exact GUID back to them for confirmation before calling this " + "tool. It should not be guessed, reused from a previous model, or assumed from a " + "default β€” even if you used a connection earlier in the conversation, ask again for " + "each new model. Omit this when editing an existing model.", ), model_identifier: z .string() .optional() .describe( "GUID of an EXISTING model to open and edit, instead of building a new one. The model " + "already knows which connection it is built on, so omit connection_identifier. You should " + "confirm the exact model with the user first; a GUID should not be guessed. finalize_model then " + "saves back to the same model without renaming it unless you pass a name.", ), }); export const CreateModelSessionOutputSchema = z.object({ model_session_id: z .string() .describe( "Identifier for the model session. Pass it to send_model_message, get_model_updates and " + "finalize_model for the rest of this model's work.", ), }); export const SendModelMessageInputSchema = z.object({ model_session_id: z .string() .describe("Identifier of the model session to send the instruction to."), message: z .string() .optional() .describe( "A natural-language instruction for the model builder (e.g. 'create a model for sales from " + "the ORDERS and CUSTOMERS tables' or 'add a revenue formula'). Omit only when answering a " + "clarification with selected_option_ids.", ), selected_option_ids: z .array(z.string()) .optional() .describe( 'When answering a clarification (a type=choice update), the `id` values (e.g. "1", "2") ' + "of the options the user selected. Pass the option `id`s, not the table_guid. Omit when " + "sending a plain instruction.", ), }); export const SendModelMessageOutputSchema = z.object({ success: z .boolean() .describe( "Whether the instruction was accepted. Call get_model_updates to read the builder's " + "response. If unsuccessful, the previous instruction may still be running β€” keep " + "calling get_model_updates until is_done is true, then try again.", ), }); export const ModelUpdateSchema = z.object({ type: z .enum([ "text", "notification", "choice", "model_state", "todo", "action", "message_end", "mrd", ]) .describe( "Kind of update from the model builder. `mrd` means the builder produced a plan (Model " + "Requirements Document) and stopped for the user's approval β€” the model is NOT built yet; " + "present the plan and let the user approve or request changes before building.", ), text: z .string() .optional() .describe( "Message text for text/notification updates, and the full plan markdown for an mrd update.", ), choice: z .any() .optional() .describe( "A clarification the builder needs the user to answer (type=choice).", ), generation_no: z .number() .optional() .describe( "Present on model_state updates: the model draft advanced to this generation.", ), tasks: z .array(z.any()) .optional() .describe( "Present on todo updates: the builder's task list with per-task status " + "(e.g. Tables/Joins/Columns, PENDING/IN_PROGRESS/COMPLETED) and result descriptions.", ), actions: z .array(z.any()) .optional() .describe( "Present on action updates: suggested next actions the user can take (not required).", ), status: z .string() .optional() .describe( "Present on message_end updates: the turn's terminal status (e.g. 'completed').", ), }); export const GetModelUpdatesInputSchema = z.object({ model_session_id: z .string() .describe("Identifier of the model session to get updates from."), }); export const GetModelUpdatesOutputSchema = z.object({ updates: z .array(ModelUpdateSchema) .describe( "Incremental new updates from the model builder. Updates returned in a previous response " + "will not be sent again. This may be an empty list while the builder is still working β€” " + "use `is_done` to know whether its response is complete.", ), is_done: z .boolean() .describe( "Whether the builder finished responding to the current instruction. If false, call " + "get_model_updates again with the same model_session_id for the next set of updates.", ), }); export const FinalizeModelInputSchema = z.object({ model_session_id: z .string() .describe("Identifier of the model session to finalize."), name: z .string() .optional() .describe( "Name for the saved model. Required when building a NEW model. When editing an existing " + "model, omit it to keep the model's current name β€” pass it only if the user asked to " + "rename the model.", ), description: z .string() .optional() .describe( "Optional description for the saved model. When editing an existing model, omit it to " + "keep the current description.", ), confirm: z .boolean() .optional() .describe( "Set true to actually save, only after the user has reviewed the summary and explicitly " + "chose to save (rather than make more changes). If omitted/false, the tool only returns " + "the model summary for review and does not save.", ), }); export const FinalizeModelOutputSchema = z.object({ summary: z .string() .optional() .describe("Human-readable summary of the model, returned for review."), saved: z .boolean() .describe("Whether the model was saved (true only when confirm was set)."), model_identifier: z .string() .optional() .describe("GUID of the saved model (when saved)."), url: z .string() .optional() .describe("Link to open the saved model (when saved)."), }); export const toolDefinitionsV1 = [ { name: ToolName.Ping, description: "Simple ping tool to test connectivity and Auth", inputSchema: z.toJSONSchema(PingSchema), annotations: { title: "Test Connection", readOnlyHint: true, destructiveHint: false, openWorldHint: false, }, }, { name: ToolName.CreateLiveboard, description: "Create a liveboard from a list of answers", inputSchema: z.toJSONSchema(CreateLiveboardSchema), annotations: { title: "Create Liveboard from Answers", readOnlyHint: false, destructiveHint: false, openWorldHint: false, }, }, { name: ToolName.GetDataSourceSuggestions, description: "Get data source suggestions for a query. Use this tool only if there is not datasource id provided in the context or the users query. If mulitple data sources are returned, and the confidence difference between the top two data sources is less than 0.3, ask the user to select the most relevant data source. Otherwise use the data source with the highest confidence to get the relevant questions and answers for the query.", inputSchema: z.toJSONSchema(GetDataSourceSuggestionsSchema), annotations: { title: "Get Data Source Suggestions for a Query", readOnlyHint: true, destructiveHint: false, openWorldHint: false, }, }, { name: ToolName.GetRelevantQuestions, description: "Get relevant data questions from ThoughtSpot database", inputSchema: z.toJSONSchema(GetRelevantQuestionsSchema), outputSchema: z.toJSONSchema(GetRelevantQuestionsOutputSchema), annotations: { title: "Get Relevant Questions for a Query", readOnlyHint: true, destructiveHint: false, openWorldHint: false, }, }, { name: ToolName.GetAnswer, description: "Get the answer to a question from ThoughtSpot database", inputSchema: z.toJSONSchema(GetAnswerSchema), annotations: { title: "Get Answer for a Question", readOnlyHint: true, destructiveHint: false, openWorldHint: false, }, }, ]; const GET_SESSION_UPDATES_SHARED_TOOL_DEFINITION = { name: ToolName.GetSessionUpdates, description: "Get the latest updates from the Analytics Agent. You can call this after `send_session_message` to retrieve the Agent's response. If `is_done` is false, you can call this tool again to continue polling, as the Agent is still generating a response. Even if `is_done` is false, you can use the updates to show status updates or progress to the user, so that they are informed about the ongoing process. An empty `session_updates` list while `is_done` is false is normal; it means the Agent is still thinking. When `is_done` is true, the Agent has finished and the results in `session_updates` are complete, so you can present them to the user. You can also send a follow-up message in the same session after `is_done` is true. If the completed response indicates that no data or no results were found, AND the `list_orgs` tool is available to you, the requested data may live in a different org or the user may not have access to it in the current org: tell the user this and that they can call `list_orgs` to see their orgs (the active one is marked `is_active`) and `switch_org` to switch to another org, then retry. If `list_orgs` is not available, do not mention orgs.", inputSchema: z.toJSONSchema(GetSessionUpdatesInputSchema), annotations: { title: "Get Analysis Session Updates", readOnlyHint: true, destructiveHint: false, openWorldHint: false, }, }; export const toolDefinitionsV2 = [ { name: ToolName.CheckConnectivity, description: "Ping tool to test connectivity and authentication. You can use this if other tool calls are failing to verify if the connection is working.", inputSchema: z.toJSONSchema(CheckConnectivityInputSchema), outputSchema: z.toJSONSchema(CheckConnectivityOutputSchema), annotations: { title: "Check Connectivity", readOnlyHint: true, destructiveHint: false, openWorldHint: false, }, }, { name: ToolName.SearchObjects, description: [ "Search for objects (Answers, Liveboards, Worksheets) matching a given search term. Supports optional filters (types, owner, tag, modified_since, verified_only) and pagination (limit, cursor). Returns `results` (ranked), plus `next_cursor`. Each result carries: object_id, title, type (LIVEBOARD | ANSWER | LIVEBOARD_VIZ | WORKSHEET; LIVEBOARD_VIZ is a viz pinned on a Liveboard β€” render it as 'Liveboard viz'), author_name, description, tags, last_modified (ISO-8601), verified, external_link, query (the saved question text for Answers/vizzes; null for Liveboards) and confidence. Returns identifiers and metadata only β€” never the object's data or contents, and it does not run queries.", "", "Explaining an object is best grounded in its actual DATA, not this metadata: the fields here (title, description, `query` text, tags) describe an object, not its contents. `description` and `query` text are authoring metadata β€” they can be stale and are often copied verbatim across sibling vizzes, so two objects can share a byte-identical description while their data differs, which makes them unreliable for telling objects apart or explaining them.", "", "How to present the results:", "β€’ Render as a table with fixed columns in this order: Object (the name, linked to `external_link`) Β· Type Β· Owner Β· Verified (βœ“ or β€”) Β· Last Modified.", "β€’ Put the description and, for an Answer/viz, the `query` text as sub-lines under the name (e.g. '↳ sales by region, last 3 months') β€” never as their own columns.", "β€’ Render `last_modified` as a plain date (2026-05-15), never the raw timestamp.", "β€’ Lead with the top match; if the top 2–3 are close, present them as ranked candidates.", "β€’ Never surface `next_cursor` or the numeric `confidence` in your prose.", "", "Outcomes other than a hit list:", 'β€’ `status: "no_results"` β€” the search ran but nothing matched. Tell the user nothing matched, and suggest broadening the term or dropping a filter. Do not invent results.', 'β€’ `status: "error"` β€” the search failed. Tell the user briefly using `error.message`; if `error.retryable` is true, offer to try again. Never show `error.code`.', ].join("\n"), inputSchema: z.toJSONSchema(SearchObjectsInputSchema), outputSchema: z.toJSONSchema(SearchObjectsResponseSchema), annotations: { title: "Search Objects", readOnlyHint: true, destructiveHint: false, openWorldHint: false, }, }, { name: ToolName.CreateAnalysisSession, description: "Start an analytical session with the Analytics Agent. This is the first step in a three-step workflow: create a session, send a message, then poll for updates. Once created, you can use the returned `analytical_session_id` to send analytical questions via `send_session_message` and retrieve answers via `get_session_updates`. Sessions are conversational, so you can ask follow-up questions in the same session without creating a new one. Using a single analytical session is preferable, because it reuses the same data source selection. When the user's intent is to create a dashboard, use the first message in this session to plan: ask the Analytics Agent what data and metrics are available for the topic, what trends or breakdowns would be most meaningful, and what chart types best fit the data. Use the Agent's response to form a dashboard plan before requesting any specific charts.", inputSchema: z.toJSONSchema(CreateAnalysisSessionSpotter3InputSchema), outputSchema: z.toJSONSchema(CreateAnalysisSessionOutputSchema), annotations: { title: "Create Analysis Session", readOnlyHint: true, destructiveHint: false, openWorldHint: false, }, }, { name: ToolName.SendSessionMessage, description: "Send a message to a session with the Analytics Agent. The Agent may take some time to think and generate a response, so the response will not be returned immediately. Instead, you can use the `get_session_updates` tool to query for the latest updates on the session. After the Agent finishes responding (when `get_session_updates` returns `is_done: true`), you can send another message to the same session to ask follow-up questions without creating a new session. Do not send a new message until the Agent has finished responding to the previous message (when `get_session_updates` returns `is_done: true`). If the user wants to create a dashboard, do not send a message with that request; instead use the `create_dashboard` tool.", inputSchema: z.toJSONSchema(SendSessionMessageInputSchema), outputSchema: z.toJSONSchema(SendSessionMessageOutputSchema), annotations: { title: "Send Analysis Session Message", readOnlyHint: true, destructiveHint: false, openWorldHint: false, }, }, // There are two versions of the get_session_updates tool; we will filter the tool list to pick // only the version we want based on whether the raw session updates flag is enabled or not { ...GET_SESSION_UPDATES_SHARED_TOOL_DEFINITION, outputSchema: z.toJSONSchema(GetSessionUpdatesOutputSchema), }, { ...GET_SESSION_UPDATES_SHARED_TOOL_DEFINITION, description: `${GET_SESSION_UPDATES_SHARED_TOOL_DEFINITION.description} The \`session_updates\` are returned in their raw and unmodified form. The shape of each update may be different, and there are no guarantees on what fields may be present. For \`answer\` updates, an \`answer_id\` field is added: pass it verbatim to the \`create_dashboard\` tool, or to \`get_data\` with \`object_type\` \`ANALYTICS_AGENT_ANSWER\`.`, outputSchema: z.toJSONSchema(GetSessionUpdatesRawOutputSchema), }, { name: ToolName.CreateDashboard, description: "Create a dashboard from a list of answers, allowing the user to revisit the results later. You can use this if the user asks for a dashboard or liveboard, or asks to save the results from the analysis. This can be a useful way to save the results to revisit later, or present them to other users.", inputSchema: z.toJSONSchema(CreateDashboardLegacyInputSchema), outputSchema: z.toJSONSchema(CreateDashboardLegacyOutputSchema), annotations: { title: "Create Dashboard", readOnlyHint: false, destructiveHint: false, openWorldHint: false, }, }, { name: ToolName.ListOrgs, description: "List the Orgs the authenticated user can access on the ThoughtSpot instance, including the ID, name, and description of each Org. The Org marked `is_active: true` is the one currently active for your account, which all tool calls operate against. Use this to tell the user which Org they are in. Only available when authenticated via OAuth. If the list is large , summarize or show only the most relevant orgs (e.g. the active one and a few others) rather than listing all of them, unless the user explicitly asks to see all orgs.", inputSchema: z.toJSONSchema(ListOrgsInputSchema), outputSchema: z.toJSONSchema(ListOrgsOutputSchema), annotations: { title: "List Orgs", readOnlyHint: true, destructiveHint: false, openWorldHint: false, }, }, { name: ToolName.SwitchOrg, description: "Switch the active Org. After switching, all subsequent tool calls (analysis sessions, answers, data sources, dashboards) operate against the selected Org. Pass an `org_id` returned by `list_orgs`. If you do not have access to the Org, the switch fails and the active Org is unchanged. The selection is durable and shared across all of your sessions β€” it persists across reconnects and applies to your other active conversations; it resets only on re-authentication or after prolonged inactivity. Only available when authenticated via OAuth.", inputSchema: z.toJSONSchema(SwitchOrgInputSchema), outputSchema: z.toJSONSchema(SwitchOrgOutputSchema), annotations: { title: "Switch Org", readOnlyHint: true, destructiveHint: false, openWorldHint: false, }, }, ]; // V3 β€” Spotter Model (agentic model creation). Includes all V2 tools plus the model tools. export const toolDefinitionsV3 = [ ...toolDefinitionsV2, { name: ToolName.CreateModelSession, description: "Start a session with the ThoughtSpot model builder, to build a NEW data model or to EDIT " + "an existing one. Returns a model_session_id used by send_model_message, get_model_updates " + "and finalize_model.\n" + "- NEW model: pass `connection_identifier`, the warehouse connection to build on. Ask the " + "user which connection to use and confirm the exact GUID with them before calling this; " + "it should not be guessed, reused from a previous model, or assumed from a default.\n" + "- EDIT an existing model: pass `model_identifier` instead (confirm which model with the " + "user first).\n" + "Creating a session does not build anything β€” send the first instruction with " + "send_model_message.", inputSchema: z.toJSONSchema(CreateModelSessionInputSchema), outputSchema: z.toJSONSchema(CreateModelSessionOutputSchema), annotations: { title: "Start Model Session", readOnlyHint: false, destructiveHint: false, openWorldHint: false, }, }, { name: ToolName.SendModelMessage, description: "Send an instruction to the model builder β€” a description of the model to build (e.g. " + "'create a model for sales from the ORDERS and CUSTOMERS tables'), a follow-up correction, " + "or `selected_option_ids` to answer a clarification it asked. Returns as soon as the " + "instruction is accepted; call get_model_updates to read the builder's response.\n" + "The builder drives the conversation β€” don't invent your own questions.\n" + "BEFORE ADDING FORMULAS: first tell the user the specific formulas you intend to add and " + "get their confirmation β€” never have formulas added without the user signing off on them.\n" + "Only one instruction runs at a time per session: keep calling get_model_updates until " + "is_done is true before sending the next one.", inputSchema: z.toJSONSchema(SendModelMessageInputSchema), outputSchema: z.toJSONSchema(SendModelMessageOutputSchema), annotations: { title: "Build Model", readOnlyHint: false, destructiveHint: false, openWorldHint: false, }, }, { name: ToolName.GetModelUpdates, description: "Get the model builder's new updates for the instruction in progress. Call it repeatedly " + "until is_done is true. A full build takes 1–2 minutes, so an empty batch with " + "is_done=false means it is still working, not stalled.\n" + "React to the update types:\n" + "- `mrd` β€” a proposed plan (Model Requirements Document). This is a HARD STOP: show the plan " + "to the user and WAIT for their explicit approval (or edits). NEVER auto-approve it or send " + "a 'build it'/'yes' message yourself. (If a build starts without any `mrd` β€” a backend " + "config that skips the plan step β€” tell the user the plan step was skipped rather than " + "treating it as approved.)\n" + "- `choice` β€” a clarifying question: present the options to the user and answer with " + "send_model_message using selected_option_ids.\n" + "- `todo` β€” the build's task tracker (e.g. Tables β†’ Joins β†’ Columns, each PENDING/" + "IN_PROGRESS/COMPLETED). SHOW it as a live progress checklist and update it as new `todo` " + "updates arrive, so the user can watch the build proceed.\n" + "- `notification` β€” a short progress line (e.g. 'Adding joins to model'): surface each one " + "as it arrives.\n" + "- `text` / `model_state` β€” results/progress: relay the meaningful parts.\n" + "Relay the builder's output in plain, non-technical terms and keep mechanics (is_done, " + "generation numbers, IDs, polling) internal. Once the model is built and the user is happy, " + "call finalize_model to save.", inputSchema: z.toJSONSchema(GetModelUpdatesInputSchema), outputSchema: z.toJSONSchema(GetModelUpdatesOutputSchema), annotations: { title: "Building Model…", readOnlyHint: true, destructiveHint: false, openWorldHint: false, }, }, { name: ToolName.FinalizeModel, description: "Save the model. Call first WITHOUT confirm to get a summary for review, then let the user " + "decide: to make more changes, go back to send_model_message; to save, call again with " + "confirm=true to persist and get the URL. confirm=true is the only step that saves. Don't " + "finalize until the model is actually built β€” if the builder has only returned a plan (an " + "mrd update) and nothing has been built, there is nothing to save.", inputSchema: z.toJSONSchema(FinalizeModelInputSchema), outputSchema: z.toJSONSchema(FinalizeModelOutputSchema), annotations: { title: "Save Model", readOnlyHint: false, destructiveHint: false, openWorldHint: false, }, }, ]; export const GET_DATA_ANALYTICS_AGENT_ANSWER_DESCRIPTION = "It can also fetch the rows behind an answer from the Analytics Agent: pass the answer's `answer_id` from `get_session_updates` verbatim as `object_id`, with `object_type` `ANALYTICS_AGENT_ANSWER` (`visualization_ids` is ignored). By default, present the Agent's answer with the visualization it provides and do not build your own chart. Call this for an answer only when the user asks to chart it yourself, reshape or modify it, combine it with other answers or data, or build a dashboard or visualization of your own from the results."; // With the undocumented `suppress-iframes` URL flag, answers carry no // visualization, so get_data's description swaps this in for the default one. export const GET_DATA_ANALYTICS_AGENT_ANSWER_SUPPRESSED_IFRAMES_DESCRIPTION = "It can also fetch the rows behind an answer from the Analytics Agent: pass the answer's `answer_id` from `get_session_updates` verbatim as `object_id`, with `object_type` `ANALYTICS_AGENT_ANSWER` (`visualization_ids` is ignored). Answers from the Analytics Agent come with no visualization of their own, so whenever a chart or table would help the user understand an answer, or the user asks to chart, reshape, combine, or build a dashboard from results, call this and build the visual from the returned rows."; // The get_data tool (fetch full data for a saved Answer/Liveboard). Gated behind // the data-download privilege at runtime in listTools/callGetData. const getDataToolDefinition = { name: ToolName.GetData, description: [ "Fetch the full data (columns and rows) of a saved Answer or Liveboard, identified by its GUID β€” typically an object found via `search_objects`. Use this to explain, describe, summarize, analyze, or interpret what a ThoughtSpot object, Liveboard, Answer, or visualization actually shows.", "When the user wants to explain, describe, summarize, analyze, or interpret what a specific object contains or shows, an accurate answer comes from this tool's data, so you should fetch it first with the object's `id` and answer from the returned rows.", "Runs the object's saved question (its existing filters and columns, unchanged) against the current data and returns the result, so the rows reflect the latest data and may differ from when the object was first saved. The result is shaped to the object's type: an Answer returns a single tabular result, a Liveboard returns one tabular result per visualization (each with its visualization id and name). To pull a single visualization pinned on a Liveboard, pass the Liveboard GUID as `object_id` and the visualization GUID in `visualization_ids`. Each result includes the column names and data rows. Use the optional `max_rows` to bound the rows returned per visualization (defaults to 25).", "Liveboard fetches are time-bound: they return as many visualizations as can be fetched within the time limit, so not every requested visualization is guaranteed to come back, even when `visualization_ids` is given. A typical call handles about 25 visualizations. If a visualization you need is missing from the result, request it by GUID in a follow-up call. If `visualization_ids` is omitted, the call returns as many of the Liveboard's visualizations as fit within the time limit.", GET_DATA_ANALYTICS_AGENT_ANSWER_DESCRIPTION, ].join("\n"), inputSchema: z.toJSONSchema(GetDataInputSchema), outputSchema: z.toJSONSchema(GetDataOutputSchema), annotations: { title: "Get Data", readOnlyHint: true, destructiveHint: false, openWorldHint: false, }, }; // V4 β€” get_data (object data fetch). Includes all V3 tools plus get_data. export const toolDefinitionsV4 = [...toolDefinitionsV3, getDataToolDefinition]; /** One-line result contract, for tools other than create_dashboard, which carries the full one. */ const DASHBOARD_RESULT_CONTRACT_BRIEF = "Check `status`: `completed` (give the user `dashboard_url`), `in_progress` (call `get_dashboard_status` again), `needs_input` (show `message` to the user and wait for their reply, then pass the reply in `instructions` to whichever tool started the task, with the same `task_id`: `create_dashboard`, or `modify_dashboard` plus its `dashboard_id`), `failed` (`message` says why; tell the user and ask before trying again, so you do not build a duplicate)."; const createDashboardToolDefinition = { name: ToolName.CreateDashboard, description: `Create a dashboard, organise it, and save it, so the user can revisit the results later or share them with others. Use this whenever the user asks for a dashboard or a liveboard, asks to save the results of an analysis, or asks to recreate a dashboard they have elsewhere. There are two ways to call it: 1. From analysis you already did: pass \`answers\` from \`get_session_updates\`, plus optional \`instructions\` on layout and style. The charts you already have are organised, styled and saved. 2. From a description: pass \`instructions\` describing the dashboard. Use this when the user asks for a dashboard before any analysis, or wants one recreated from a spec or another tool (for example a Tableau workbook). Call this directly; do not run the analysis yourself first. The designer first replies with \`needs_input\`: the data source it chose and its plan for the dashboard. Nothing is built yet. Show the plan to the user and wait for their reply; never confirm it on their behalf, even if it looks complete. When the user confirms or asks for changes, call \`create_dashboard\` again with the same \`task_id\`, putting their changes in \`instructions\`. It can take a few minutes, so it may return \`in_progress\` before it is finished. Check \`status\` on the result and act on it: - \`completed\`: the dashboard is saved. Give the user \`dashboard_url\`. - \`needs_input\`: the designer has a plan or a question for the user, and nothing has changed yet. \`message\` holds it, and \`choices\` any options it offered. Show it to the user and wait for their reply; do not answer or confirm it on their behalf. Then call \`create_dashboard\` again with the same \`task_id\`, putting the user's reply in \`instructions\`. Do not report the request to the user as finished. - \`in_progress\`: still working. \`message\`, when present, says what the designer is doing now; relay it to the user as progress. Call \`get_dashboard_status\` with \`task_id\`, and keep calling it until you get another status. - \`failed\`: nothing usable was produced. \`message\` explains why. Tell the user and ask before trying again, so you do not build a duplicate.`, inputSchema: z.toJSONSchema(CreateDashboardInputSchema), outputSchema: z.toJSONSchema(CreateDashboardOutputSchema), annotations: { title: "Create Dashboard", readOnlyHint: false, destructiveHint: false, openWorldHint: false, }, }; const modifyDashboardToolDefinition = { name: ToolName.ModifyDashboard, description: `Change an existing dashboard. It can rearrange and restyle what is already there, add new charts, add short explanatory text, and organise charts into groups or tabs. \`dashboard_id\` is always required. Add \`task_id\` as well to continue something you already started, which is how you answer a question the designer asked you or send a follow-up instruction about the same dashboard. Pass the change in \`instructions\` in the user's words. If it is too vague to act on, the designer comes back with a question. New charts use the data sources the dashboard already has unless you say otherwise. Changes are saved to the user's real dashboard, so only call this when the user has asked for the dashboard to change. Changing a dashboard can take a few minutes, so this may return before it is finished. ${DASHBOARD_RESULT_CONTRACT_BRIEF}`, inputSchema: z.toJSONSchema(ModifyDashboardInputSchema), outputSchema: z.toJSONSchema(ModifyDashboardOutputSchema), annotations: { title: "Modify Dashboard", readOnlyHint: false, destructiveHint: false, openWorldHint: false, }, }; const getDashboardStatusToolDefinition = { name: ToolName.GetDashboardStatus, description: `Continue waiting for a dashboard that is still being built or changed. Call this when \`create_dashboard\` or \`modify_dashboard\` returned \`status: "in_progress"\`, passing the \`task_id\` they gave you. Each call waits a short while before returning, so calling it repeatedly is the correct way to wait. Keep calling until \`status\` is \`completed\`, \`needs_input\` or \`failed\`. Do not start a new \`create_dashboard\` or \`modify_dashboard\` call for the same work, or you will create duplicate dashboards. ${DASHBOARD_RESULT_CONTRACT_BRIEF}`, inputSchema: z.toJSONSchema(GetDashboardStatusInputSchema), outputSchema: z.toJSONSchema(GetDashboardStatusOutputSchema), annotations: { title: "Get Dashboard Status", readOnlyHint: true, destructiveHint: false, openWorldHint: false, }, }; /** * Adds the dashboard designer: `create_dashboard` gains a design pass and a description-only mode, * and `modify_dashboard` / `get_dashboard_status` are new. Earlier versions keep the original * `create_dashboard` contract. */ export const toolDefinitionsV5 = [ ...toolDefinitionsV4.map((tool) => { if (tool.name === ToolName.CreateDashboard) { return createDashboardToolDefinition; } return tool; }), modifyDashboardToolDefinition, getDashboardStatusToolDefinition, ]; // SendSessionMessage has a slightly different contract for SpotterX export const sendSessionMessageToolDefinitionSpotterX = { name: ToolName.SendSessionMessage, description: "Send a message to a session with the Analytics Agent. The Agent may take some time to think and generate a response, so the response will not be returned immediately. Instead, you can use the `get_session_updates` tool to query for the latest updates on the session. After the Agent finishes responding (when `get_session_updates` returns `is_done: true`), you can send another message to the same session to ask follow-up questions without creating a new session. Do not send a new message until the Agent has finished responding to the previous message (when `get_session_updates` returns `is_done: true`). You can also send a message in the context of a dashboard by providing `dashboard_id`, to ask questions about that dashboard or a visualization within it. If sending followup messages, include the same `dashboard_id` for subsequent requests. If the user wants to create a dashboard, do not send a message with that request; instead use the `create_dashboard` tool.", inputSchema: z.toJSONSchema(SendSessionMessageSpotterXInputSchema), outputSchema: z.toJSONSchema(SendSessionMessageOutputSchema), annotations: { title: "Send Analysis Session Message", readOnlyHint: true, destructiveHint: false, openWorldHint: false, }, };