LLMs.txt: Complete documentation index for AI agents
MCP tool reference (Spotter 3)

MCP tool reference (Spotter 3)

Analysis, dashboard creation, and model building each follow the same pattern, start the work β†’ poll for updates until it finishes. The analysis workflow is create a session β†’ send a message β†’ poll for updates. The search_objects and get_data tools are independent of these workflows and can be called at any time.

Note
  • The new and updated tools are available by default on the MCP server endpoint with ?api-version=latest. To pin your integration to the release that includes them, use the release date, for example ?api-version=2026-10-14. For information about the available API versions and release dates, see the MCP Server changelog.

  • The server lists get_data only for users who have the privilege to download data.

  • The server lists the model builder tools only for users who have the data management privilege and the privilege to create or edit data models.

create_analysis_sessionπŸ”—

Start an analytical session with ThoughtSpot’s analytics agent. This is the required first step before sending any questions.

Sessions are conversational. Once created, you can send multiple follow-up questions to the same session without calling create_analysis_session again.

Input parameterπŸ”—

The data_source_id is optional. Provide this when the user has specified or confirmed a data source, or when context makes a particular source obvious. Omit to let ThoughtSpot automatically select the most relevant source based on the question. If the instance does not support automatic selection, the tool returns an error that asks for a data source. Find the GUID with search_objects, using types: ["WORKSHEET"]. If you have only the data source name, you can pass it in the additional_context field of send_session_message instead.

The data_source_id must be a GUID in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Example callπŸ”—

const session = await callMCPTool("create_analysis_session", {
    data_source_id: "model-guid-123" // Optional. GUID of the ThoughtSpot model to query. Omit to let ThoughtSpot automatically select the most relevant data source.
});
call_mcp_tool(
    "create_analysis_session",
    {
        "data_source_id": "model-guid-123"  # Optional. GUID of the ThoughtSpot model to query.
    },
)

ResponseπŸ”—

{
  "analytical_session_id": "session-guid-abc123"
}
  • analytical_session_id: Session ID. Pass this to send_session_message and get_session_updates.

  • Always capture the returned analytical_session_id. It is required for all subsequent calls.

send_session_messageπŸ”—

Send a natural language analytical question or follow-up to an existing session. The agent processes requests asynchronously, so this tool does not return the answer directly; use get_session_updates to retrieve the response.

Input parametersπŸ”—

FieldDescription

analytical_session_id

The session to send the message to. Obtained from the create_analysis_session call.

message

A natural language analytical question or follow-up to send to the ThoughtSpot agent.

additional_context
Optional

Can be used to provide external information relating to the question. For example, "The user’s fiscal year starts in April," or "The user is a manager of the West region."

Example callπŸ”—

const sendMessage = await callMCPTool("send_session_message", {
    analytical_session_id: "session-guid-abc123", // Session ID from create_analysis_session.
    message: "What were total sales by region last quarter?", // User's natural language question.
    additional_context: "The user's fiscal year starts in April. " +
        "Focus on underperforming regions only." // Optional. External information to influence the analysis.
});
call_mcp_tool(
    "send_session_message",
    {
        "analytical_session_id": "session-guid-abc123",  # Session ID from create_analysis_session.
        "message": "What were total sales by region last quarter?", # User's natural language question.
        "additional_context": (  # Optional. External information
            "The user's fiscal year starts in April. "
            "Focus on underperforming regions only." # to influence the analysis.
        ),
    },
)

ResponseπŸ”—

{
  "success": true
}
  • success: Confirms whether the message was successfully received by the agent.

Note
  • After a successful send, immediately begin polling with get_session_updates.

  • Do not send a second message until get_session_updates returns is_done: true. The agent processes one message at a time per session.

  • To ask a follow-up question, reuse the same analytical_session_id. There is no need to create a new session.

  • Do not send a dashboard request through this tool. To create a dashboard, use create_dashboard.

get_session_updatesπŸ”—

Poll for the latest response from a ThoughtSpot analytics session. Call this repeatedly after send_session_message until is_done is true.

Important: A single call to get_session_updates will rarely contain the full response. Spotter streams its work incrementally, including intermediate thinking steps, across multiple polling calls. You must accumulate updates from every poll and combine them to get the complete picture.

Input parametersπŸ”—

Send the analytical_session_id to specify the session to retrieve updates for.

Example callπŸ”—

const updates = await callMCPTool("get_session_updates", {
    analytical_session_id: "session-guid-abc123" // Session ID from the `create_analysis_session` call.
});
call_mcp_tool(
    "get_session_updates",
    {"analytical_session_id": "session-guid-abc123"},  # Session ID from create_analysis_session.
)

ResponseπŸ”—

Each poll returns a wrapper object with an is_done flag and a session_updates array. Session updates stream across multiple polling calls. Accumulate them all before rendering the final answer.

session_updates objects use three type values:

Typeis_thinkingDescription

step_notification

true

A short heading announcing the step Spotter is about to start, such as Searching data models or Running query. Step headings arrive as soon as Spotter begins each step, before the narration text for that step. Render these immediately so the user sees progress in real time.

text_chunk

true (thinking) or false (final)

A fragment of Spotter’s narration. Concatenate chunks to form the complete narration string. When is_thinking is false, the chunk is part of the final answer narration, not an intermediate thinking step.

answer

true or false

The analytical result. Contains a title, the ThoughtSpot search query used, an embeddable iframe_url, and an answer_id for creating dashboards. The same answer can arrive twice in one response, once with is_thinking: true and once with is_thinking: false. Both updates carry the same answer_id. Render the answer once, and use the answer_id to remove duplicates.

Poll returning intermediate updates:

{
  "is_done": false,
  "session_updates": [
    {
      "is_thinking": true,
      "type": "step_notification",
      "text": "Searching data models"
    },
    {
      "is_thinking": true,
      "type": "text_chunk",
      "text": " to find the most relevant dataset for your question..."
    }
  ]
}

Poll returning the final answer:

{
  "is_done": true,
  "session_updates": [
    {
      "is_thinking": true,
      "type": "step_notification",
      "text": "Running query"
    },
    {
      "is_thinking": true,
      "type": "text_chunk",
      "text": "Running the query against the sales data model..."
    },
    {
      "is_thinking": true,
      "type": "answer",
      "answer_id": "{\"session_id\":\"1a3d...\",\"gen_no\":2}",
      "answer_title": "Total sales by region",
      "answer_data_source_id": "cd252e5c-...",
      "answer_query": "[sales] [region]",
      "iframe_url": "https://your-instance.thoughtspot.cloud/?tsmcp=true#/embed/conv-assist-answer?..."
    },
    {
      "is_thinking": false,
      "type": "text_chunk",
      "text": "I'm interpreting 'last quarter' as Q4 2025 (October–December), based on a fiscal year starting in April."
    },
    {
      "is_thinking": false,
      "type": "answer",
      "answer_id": "{\"session_id\":\"1a3d...\",\"gen_no\":2}",
      "answer_title": "Total sales by region",
      "answer_data_source_id": "cd252e5c-...",
      "answer_query": "[sales] [region]",
      "iframe_url": "https://your-instance.thoughtspot.cloud/?tsmcp=true#/embed/conv-assist-answer?..."
    }
  ]
}
Note

The step_notification type was introduced alongside the default response format. Step headings always arrive before the narration text for that step.

Handling streamed responsesπŸ”—

Spotter queries are processed asynchronously and streamed in real time. This means the full response is never contained in a single get_session_updates call.

Each call to get_session_updates returns only the updates generated since the previous call. The session_updates array may indicate that Spotter is still processing with an is_thinking state, may include intermediate updates, or may contain several updates at once. Updates typically arrive as step_notification or text_chunk types, reflecting Spotter’s ongoing reasoning, before the final answer update is provided. This intermediate content shows Spotter’s step-by-step thought process and should be preserved and presented to the user for transparency into how the answer is derived.

A typical response sequence might look like:

  1. Step headings: step_notification updates announcing each step Spotter is about to start.

  2. Thinking narration: text_chunk updates with is_thinking: true describing what Spotter is doing.

  3. The answer: an answer update containing the visualization title, the underlying query, the answer_id, and the embeddable iframe URL. The same answer can arrive again with is_thinking: false.

  4. Final narration: text_chunk updates with is_thinking: false. This text can explain assumptions, filters applied, or ambiguities in the question, and can include a Markdown summary of the results, such as key takeaways. It can arrive before and after the answer update, so the answer is not always the last update.

This means a complete response might span 5–20+ get_session_updates calls and contain many session_update objects before is_done becomes true. All of this content, the thinking, the narration, and the final answer, should be accumulated and presented together to give the user the full picture.

Default response formatπŸ”—

Includes three types, step_notification, text_chunk, answer. Flat, fixed keys, is_thinking as the top-level flag that distinguishes intermediate reasoning from the final answer.

{"is_thinking":true,"type":"step_notification","text":"Searching data models"}
{"is_thinking":true,"type":"text_chunk","text":" to find the most relevant dataset..."}
{"is_thinking":false,"type":"answer",
 "answer_id":"{\"session_id\":\"1a3d...\",\"gen_no\":2}",
 "answer_title":"Total sales by region",
 "answer_data_source_id":"cd252e5c-...",
 "answer_query":"[sales] [region]",
 "iframe_url":"https://your-instance.thoughtspot.cloud/?tsmcp=true#/embed/conv-assist-answer?..."}

Type definition: session_updateπŸ”—

Each item in the session_updates list is a session_update object. The type field determines which other fields are present.

FieldTypeDescription

type

"step_notification"

A short heading announcing the step Spotter is about to start, such as Searching data models or Running query.

"text_chunk"

A streaming fragment of Spotter’s narration. Concatenate all chunks to reconstruct the full text.

"answer"

Populates answer_title, answer_query, answer_data_source_id, iframe_url fields. A data visualization result with a title, the underlying query, and an embeddable URL.

is_thinking

Boolean

true for intermediate reasoning (step_notification updates and thinking text_chunk updates). false for the final narration and the answer.

answer_id

String

Identifier of the answer. Present only when type is "answer". Pass it as is to create_dashboard.

text

String

The text content of the message. Present only when type is "step_notification" or "text_chunk". For "text_chunk" updates, concatenate all chunks to form the complete message.

answer_title

String

A human-readable title describing what the answer shows. Present only when type is "answer".

answer_data_source_id

String

GUID of the data source used to generate the answer. Present only when type is "answer".

answer_query

String

The search query ThoughtSpot used to generate the answer. Present only when type is "answer". Useful for explaining to users what data was queried or for diagnosing unexpected results.

iframe_url

String

An embeddable URL for rendering the answer as an interactive visualization. Present only when type is "answer". Use this to display a live chart or table if your environment supports iframes.

Full response (raw event stream)πŸ”—

By default, get_session_updates returns a simplified response optimized for host agent understanding. For integrations that need granular metadata about Spotter’s internal tool calls, you can enable the full raw event stream.

For guidance on when to use the full response and how to enable it, see Accessing full tool responses.

Full response format (raw upstream events)πŸ”—

When enable-raw-session-updates=true is appended to your MCP endpoint URL, get_session_updates returns the raw Spotter event stream. The full response does not include a preconstructed iframe_url. You must build it yourself. For guidance, see Accessing full tool responses.

{"type":"ack","node_id":"pvzWZ8wdaL0w"}
{"type":"conv_title","title":"Total revenue by region","conv_id":"iZ87F742SMkA"}
{"type":"notification","group_id":"5aOOckJ31v8d","code":"TOOL_CALL_NOTIFICATION",
 "metadata":{"type":"thinking","tool_name":"search_datasets",
             "tool_args":{"keywords":["revenue","region","sales"]},
             "tool_code":"SEARCHING_DATASETS","tool_title":"Searching for Datasets"}}
{"id":"m2xDLBXcPF5D","type":"text-chunk","group_id":"br31Y9vnKmDp",
 "metadata":{"format":"markdown","type":"thinking"},"content":" to find a"}
{"id":"SpzpcgHBt_Pm","type":"answer","group_id":"TlhE-TPW05tu",
 "title":"total sales by region",
 "answer_id":"{\"session_id\":\"fc3bd346-...\",\"gen_no\":2}",
 "metadata":{"sage_query":"[sales] [region]","session_id":"fc3bd346-...","gen_no":2,
             "transaction_id":"8e5654f3-...","generation_number":1,
             "warning_details":[{"warningType":"CHART_INTENT_APPLIED"},
                                {"warningType":"CHART_INTENT_DETECTED"}],
             "ambiguous_phrases":null,"query_intent":null,
             "tml_phrases":["[sales] [region]"],"cached":false,
             "sub_queries":null,"worksheet_id":"cd252e5c-...","type":"thinking"}}

For the complete event schema, see the Spotter Agent API.

create_dashboardπŸ”—

Create a ThoughtSpot dashboard and save it, so that users can revisit or share the results. SpotterViz, the ThoughtSpot dashboard designer, builds the dashboard. Use this tool when a user asks for a dashboard or Liveboard, asks to save analysis results, or wants to recreate a dashboard from another tool.

You can call the tool in two ways:

  1. From completed analysis: Pass answers collected from get_session_updates, with optional instructions for layout and style. SpotterViz organizes, styles, and saves the charts. Call this only after get_session_updates returns is_done: true, because you need the answer ID values from completed answer updates.

  2. From a description: Pass instructions that describe the dashboard. Use this when the user asks for a dashboard before any analysis, or wants one recreated from a specification. In this case, do not run the analysis first. SpotterViz replies with needs_input, which contains the data source it chose and its plan. Nothing is built until the user confirms the plan.

Dashboard creation can take a few minutes, so the call can return in_progress before the dashboard is ready.

Input parametersπŸ”—

Pass answers, instructions, or both.

FieldDescription

title
Optional

Title of the dashboard. Required unless you pass task_id.

answers
Optional

List of answer objects from a prior analysis. Each object requires an answer_id and a title. Pass the answer_id exactly as returned by get_session_updates for an update where type is answer. Omit answers when you build the dashboard from instructions only.

instructions
Optional

The user’s request for the dashboard, in their words. Add detail only when the user gave it, such as chart types, grouping, tabs, brand colors as hex codes, or a data source they named. Do not add charts, metrics, filters, or layout that the user did not ask for, because SpotterViz proposes those in a plan for the user to confirm. Changing an existing chart’s type or query, and coloring individual data values, are not supported.

task_id
Optional

The task_id from an earlier create_dashboard call that returned a plan. Pass it to confirm the plan, with any changes in instructions, so that the dashboard is built.

data_source_id
Optional

GUID of a data source. Omit it in most cases, because SpotterViz selects the most relevant data source automatically. Provide it only when the user named or confirmed a specific data source.

If you pass neither answers nor instructions, the tool returns an error.

Example callsπŸ”—

From completed analysis:

const dashboard = await callMCPTool("create_dashboard", {
    title: "Q4 2025 Regional Sales Analysis",
    answers: [
        {
            answer_id: "{\"session_id\":\"1a3d...\",\"gen_no\":2}", // answer_id from an answer update in get_session_updates.
            title: "Total Sales by Region, Q4 2025"
        },
        {
            answer_id: "{\"session_id\":\"1a3d...\",\"gen_no\":3}",
            title: "Underperforming Regions, Q4 2025 vs Q4 2024"
        }
    ],
    instructions: "Put the regional total at the top and use two tabs." // Optional. Layout and style.
});
dashboard = call_mcp_tool(
    "create_dashboard",
    {
        "title": "Q4 2025 Regional Sales Analysis",
        "answers": [
            {
                "answer_id": '{"session_id":"1a3d...","gen_no":2}',  # answer_id from an answer update in get_session_updates.
                "title": "Total Sales by Region, Q4 2025",
            },
            {
                "answer_id": '{"session_id":"1a3d...","gen_no":3}',
                "title": "Underperforming Regions, Q4 2025 vs Q4 2024",
            },
        ],
        "instructions": "Put the regional total at the top and use two tabs.",  # Optional. Layout and style.
    },
)

From a description, then confirming the plan:

// First call: SpotterViz returns a plan with status "needs_input".
const plan = await callMCPTool("create_dashboard", {
    title: "Customer Retention Overview",
    instructions: "A dashboard showing churn and retention by segment."
});

// After the user reviews the plan, confirm it with the same task_id.
const result = await callMCPTool("create_dashboard", {
    task_id: plan.task_id,
    instructions: "Looks good, but add a monthly trend."
});
# First call: SpotterViz returns a plan with status "needs_input".
plan = call_mcp_tool(
    "create_dashboard",
    {
        "title": "Customer Retention Overview",
        "instructions": "A dashboard showing churn and retention by segment.",
    },
)

# After the user reviews the plan, confirm it with the same task_id.
result = call_mcp_tool(
    "create_dashboard",
    {
        "task_id": plan["task_id"],
        "instructions": "Looks good, but add a monthly trend.",
    },
)

ResponseπŸ”—

create_dashboard, modify_dashboard, and get_dashboard_status return the same result object.

{
  "status": "completed",
  "task_id": "9f1c2d3e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "dashboard_id": "0c4734a8-a06b-40ac-bbfe-6ba2cee7c803",
  "dashboard_url": "https://your-instance.thoughtspot.cloud/#/insights/pinboard/0c4734a8-a06b-40ac-bbfe-6ba2cee7c803",
  "changes_applied": true,
  "message": "Created a dashboard with two tabs."
}
FieldTypeDescription

status

String

Outcome of the request. One of completed, in_progress, needs_input, or failed. Always present.

task_id

String

Identifier of the dashboard task. Pass it to get_dashboard_status, or back to the tool that started the task, to continue.

dashboard_id

String

GUID of the dashboard. Present when the dashboard exists.

dashboard_url

String

Link to the dashboard in ThoughtSpot. Present when the dashboard exists.

changes_applied

Boolean

Whether the dashboard actually changed. false with completed means that SpotterViz understood the request but changed nothing.

message

String

What SpotterViz reported: its current step (in_progress), its summary (completed), its plan or question (needs_input), or why it failed (failed).

choices

Array of strings

Options that SpotterViz offered with its question. Present only when it offered options.

Act on each status as follows:

statusMeaningWhat to do

completed

The dashboard is saved.

Give the user the dashboard_url.

needs_input

SpotterViz has a plan or a question for the user, in message. Nothing has changed yet.

Show it to the user and wait for the reply. Never confirm on the user’s behalf. Call create_dashboard again with the same task_id, and put the user’s reply in instructions.

in_progress

SpotterViz is still working. message, when present, describes the current step.

Show the progress to the user. Call get_dashboard_status with the task_id until the status changes.

failed

Nothing usable was produced. message explains why.

Tell the user and ask before you try again, so that you do not create a duplicate dashboard.

modify_dashboardπŸ”—

Change an existing dashboard. The tool can rearrange and restyle existing content, add new charts, add short explanatory text, and organize charts into groups or tabs.

Changes are saved to the user’s actual dashboard, so call this tool only when the user has asked for a change. New charts use the dashboard’s existing data sources unless you specify otherwise. If the instructions are too vague to act on, SpotterViz responds with a question. A change can take a few minutes, so the call can return before it finishes.

Input parametersπŸ”—

FieldDescription

dashboard_id
Required

GUID of the dashboard to change. Get it from search_objects, or from a dashboard link that ends in /pinboard/<id>. Do not pass a name. Every call must include dashboard_id, even when you pass task_id.

instructions
Required

The change in the user’s words: layout or styling, new charts, or the user’s answer to SpotterViz’s question. Must not be empty. Do not add changes that the user did not ask for.

task_id
Optional

The task_id from an earlier modify_dashboard call on the same dashboard. Pass it to answer SpotterViz’s question or to follow up with the same context. Omit it to start a new change.

data_source_id
Optional

GUID of a data source for new charts. Omit it in most cases. Provide it only when the user named or confirmed a specific data source.

Example callπŸ”—

const change = await callMCPTool("modify_dashboard", {
    dashboard_id: "0c4734a8-a06b-40ac-bbfe-6ba2cee7c803",
    instructions: "Move the quota attainment chart into a new tab called Field Sales."
});

// If SpotterViz asks a question (status "needs_input"), reply with the same task_id.
const followUp = await callMCPTool("modify_dashboard", {
    dashboard_id: "0c4734a8-a06b-40ac-bbfe-6ba2cee7c803",
    task_id: change.task_id,
    instructions: "Yes, keep the existing filters on the new tab."
});
change = call_mcp_tool(
    "modify_dashboard",
    {
        "dashboard_id": "0c4734a8-a06b-40ac-bbfe-6ba2cee7c803",
        "instructions": "Move the quota attainment chart into a new tab called Field Sales.",
    },
)

# If SpotterViz asks a question (status "needs_input"), reply with the same task_id.
follow_up = call_mcp_tool(
    "modify_dashboard",
    {
        "dashboard_id": "0c4734a8-a06b-40ac-bbfe-6ba2cee7c803",
        "task_id": change["task_id"],
        "instructions": "Yes, keep the existing filters on the new tab.",
    },
)

ResponseπŸ”—

The tool returns the same result object as create_dashboard. For the fields, see create_dashboard response. Act on each status in the same way. When you answer a needs_input question, call modify_dashboard again with the same dashboard_id and task_id.

Note
  • A dashboard can have only one change in progress. If you send a second change while one is running, the tool returns an error that includes the task_id of the running change. Call get_dashboard_status with that task_id.

  • A task_id belongs to one dashboard. Passing a task_id with the dashboard_id of a different dashboard returns an error.

  • A task_id can expire. If the tool reports that the task_id could not be found, call modify_dashboard again with only the dashboard_id and your full instruction to start a new change.

get_dashboard_statusπŸ”—

Wait for a dashboard task that is still running. Call this tool when create_dashboard or modify_dashboard returns status: "in_progress". Each call waits briefly before it returns, so calling it repeatedly is the intended 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, because that creates duplicate dashboards.

Input parametersπŸ”—

FieldDescription

task_id
Required

The task_id returned by create_dashboard or modify_dashboard when status was in_progress.

Example callπŸ”—

let result = await callMCPTool("create_dashboard", { title: "Sales Overview", answers });

while (result.status === "in_progress") {
    result = await callMCPTool("get_dashboard_status", { task_id: result.task_id });
}
// result.status is now "completed", "needs_input", or "failed".
result = call_mcp_tool("create_dashboard", {"title": "Sales Overview", "answers": answers})

while result["status"] == "in_progress":
    result = call_mcp_tool("get_dashboard_status", {"task_id": result["task_id"]})
# result["status"] is now "completed", "needs_input", or "failed".

ResponseπŸ”—

The tool returns the same result object as create_dashboard. For the fields, see create_dashboard response. On needs_input, pass the user’s reply in instructions to the tool that started the task, with the same task_id. That tool is create_dashboard, or modify_dashboard with its dashboard_id. If the task_id is unknown, the tool returns an error.

search_objectsπŸ”—

Search for existing ThoughtSpot content by name or description, and return the matching objects with their metadata and deep links.

Use this tool when a user refers to content that already exists. For example, "open the regional sales Liveboard" or "what dashboards has Priya built". The search_objects tool is independent of the analysis session workflow. It does not require a session and does not need to be called before create_analysis_session.

search_objects returns identifiers and metadata only. It never returns the object’s data or contents, and it does not run queries.

To fetch the rows of a saved Answer or Liveboard that you found, pass its object_id as object_id and its type as object_type to get_data. To answer a new data question, use the session workflow instead.

Input parametersπŸ”—

FieldDescription

query
Required

The search term, matched against object names and descriptions. Must be non-empty.

types
Optional

Restrict results to these object types. Accepts an array of LIVEBOARD, LIVEBOARD_VIZ, ANSWER, WORKSHEET. Omit to search all types.

author_name
Optional

Restrict results to objects authored by this user, matched against the author’s display name. Case-insensitive substring match.

tag
Optional

Restrict results to objects carrying this tag or sticker, matched by tag name. Case-insensitive substring match.

modified_since
Optional

Return only objects last modified on or after this epoch-millisecond timestamp.

verified_only
Optional

If true, return only objects marked as verified.

limit
Optional

Maximum number of results to return. Positive integer. Defaults to 10.

cursor
Optional

Opaque pagination cursor returned as next_cursor by a previous call. Omit on the first page.

Object typesπŸ”—

The types input parameter and the type field on each result use the same tokens. Any value returned in a result can be passed back as a types filter.

ValueMeaning

LIVEBOARD

A Liveboard.

LIVEBOARD_VIZ

A single visualization pinned on a Liveboard. Distinct from a standalone Answer. Render this as "Liveboard viz".

ANSWER

A saved Answer.

WORKSHEET

A data model object.

Example callπŸ”—

const results = await callMCPTool("search_objects", {
    query: "regional sales",  // Required. Search term matched against object names and descriptions.
    types: ["LIVEBOARD", "LIVEBOARD_VIZ"], // Optional. Restrict to these object types.
    author_name: "Priya", // Optional. Case-insensitive substring match on author display name.
    tag: "Certified", // Optional. Case-insensitive substring match on tag name.
    verified_only: true, // Optional. Return only verified objects.
    limit: 5 // Optional. Maximum results to return. Defaults to 10.
});
call_mcp_tool(
    "search_objects",
    {
        "query": "regional sales", # Required. Search term matched against object names and descriptions.
        "types": ["LIVEBOARD", "LIVEBOARD_VIZ"], # Optional. Restrict to these object types.
        "author_name": "Priya", # Optional. Case-insensitive substring match on author display name.
        "tag": "Certified", # Optional. Case-insensitive substring match on tag name.
        "verified_only": True, # Optional. Return only verified objects.
        "limit": 5, # Optional. Maximum results to return. Defaults to 10.
    },
)

ResponseπŸ”—

A call returns one of three outcomes.

Successful matchπŸ”—

status is omitted when the search returned results.

{
  "results": [
    {
      "object_id": "b2c4e6a8-1234-4f5a-9abc-def012345678",
      "title": "Regional Sales Performance",
      "type": "LIVEBOARD",
      "author_name": "Priya Raman",
      "description": "Weekly sales tracking by region and rep.",
      "tags": ["Sales", "Certified"],
      "last_modified": "2026-05-15T14:30:00.000Z",
      "verified": true,
      "external_link": "https://your-instance.thoughtspot.cloud/#/insights/pinboard/b2c4e6a8-1234-4f5a-9abc-def012345678",
      "query": null,
      "confidence": 128.9
    },
    {
      "object_id": "b2c4e6a8-1234-4f5a-9abc-def012345678",
      "visualization_id": "77f1a0d3-5678-4b21-8e90-aa1122334455",
      "title": "Sales by Region",
      "type": "LIVEBOARD_VIZ",
      "author_name": "Priya Raman",
      "tags": ["Sales"],
      "last_modified": "2026-05-15T14:30:00.000Z",
      "verified": false,
      "external_link": "https://your-instance.thoughtspot.cloud/#/insights/pinboard/b2c4e6a8-1234-4f5a-9abc-def012345678/77f1a0d3-5678-4b21-8e90-aa1122334455",
      "query": "sales by region monthly",
      "confidence": 117.1
    }
  ],
  "next_cursor": "10"
}

No resultsπŸ”—

The search ran successfully but nothing matched.

{
  "status": "no_results",
  "results": [],
  "next_cursor": null
}

Tell the user that nothing matched and suggest broadening the search term or removing a filter. Do not synthesize results.

ErrorπŸ”—

The search could not be completed.

{
  "status": "error",
  "results": [],
  "error": {
    "code": "RATE_LIMITED",
    "message": "ThoughtSpot rate limit reached. Try again shortly.",
    "retryable": true
  }
}

If retryable is true, wait briefly and retry the same call. If retryable is false, surface the message to the user and do not retry automatically.

Response fieldsπŸ”—

FieldTypeDescription

status

String

Omitted on a successful hit list. no_results means the search ran but matched nothing. error means the search failed and error is populated.

results

Array

Ranked list of matching objects, most relevant first. Empty for no_results and error.

next_cursor

String

Cursor to pass back as cursor to retrieve the next page. null when there are no more results. Omitted on error.

error

Object

Present only when status is error. Contains code, message, and retryable.

Fields on each resultπŸ”—

FieldTypeDescription

object_id

String

GUID of the object. For a LIVEBOARD_VIZ result, this is the GUID of the parent Liveboard, not the visualization.

visualization_id

String

Present only on LIVEBOARD_VIZ results. GUID of the specific visualization pinned on the Liveboard identified by object_id.

title

String

Display name of the object.

type

String

Object type: LIVEBOARD, LIVEBOARD_VIZ, ANSWER, or WORKSHEET. Can be passed back as a types filter.

author_name

String

Display name of the user who authored the object.

description

String

Description of the object. Omitted when the object has none.

tags

Array of strings

Names of the tags or stickers applied to the object.

last_modified

String

ISO 8601 timestamp of the last modification. For example, 2026-05-15T14:30:00.000Z. Omitted when unavailable. Render as a plain date.

verified

Boolean

Whether the object is marked as verified.

external_link

String

Deep link to open the object in the ThoughtSpot UI. This link opens in a browser tab. It is not an embeddable iframe URL.

query

String

For an Answer or Liveboard viz, the search tokens that define it. For example, sales by region monthly. null for a Liveboard.

confidence

Number

Relevance score for the search term. Higher is more relevant. The scale is not bounded to 0 to 1, so compare scores only within one response. Use it for ranking only. Do not display this value to the user.

Note

The description and query fields are authoring metadata. They can be out of date and are often copied across sibling visualizations, so do not use them to tell objects apart.

PaginationπŸ”—

search_objects returns up to limit results per call (default 10). When more results are available, the response includes a next_cursor value. Pass this value back as cursor in the next call to retrieve the following page. When next_cursor is null, there are no further results.

// Fetch the first page
let response = await callMCPTool("search_objects", { query: "sales" });

// Fetch the next page if a cursor was returned
if (response.next_cursor) {
    response = await callMCPTool("search_objects", {
        query: "sales",
        cursor: response.next_cursor
    });
}

get_dataπŸ”—

Fetch the columns and rows of a saved Answer or Liveboard by its GUID. Use this tool when a user wants to explain, describe, summarize, or analyze what an existing object shows.

The tool runs the object’s saved query, with its existing filters and columns unchanged, against current data. The rows reflect the latest data and can differ from what the object showed when it was saved. An Answer returns a single tabular result. A Liveboard returns one tabular result for each visualization.

Typically, you call search_objects first, and pass the object_id of a result as object_id and its type as object_type to get_data.

Important

The get_data tool is available only to users who have the privilege to download data. The MCP Server does not list the tool for other users. If a user without the privilege calls the tool anyway, the request fails with a permission error.

Input parametersπŸ”—

FieldDescription

object_id
Required

GUID of the Answer or Liveboard, typically the object_id from a search_objects result. For a Liveboard visualization, pass the GUID of the parent Liveboard.

object_type
Required

Type of the object: ANSWER, LIVEBOARD, or LIVEBOARD_VIZ. Pass the type from the search_objects result as is. The WORKSHEET type is not supported.

visualization_ids
Optional

Array of visualization GUIDs on a Liveboard. Required when object_type is LIVEBOARD_VIZ, otherwise the request is rejected. Each entry must be a visualization GUID, such as the visualization_id from search_objects or the viz_id from an earlier get_data result, not a name. If you omit it for a Liveboard, the tool returns as many of the visualizations as fit within the time limit. Ignored for standalone Answers.

max_rows
Optional

Maximum number of rows to return for each visualization. Positive integer. Defaults to 25. Raise it only when you need the full result set and know that the object is large.

Example callπŸ”—

const data = await callMCPTool("get_data", {
    object_id: "a6b47acc-c391-4b78-9901-36235fd07809", // GUID of the parent Liveboard, from search_objects.
    object_type: "LIVEBOARD_VIZ", // The type from the search_objects result.
    visualization_ids: ["473f787a-bf3f-4366-a58e-4905a1329017"], // The visualization_id from search_objects.
    max_rows: 3 // Optional. Defaults to 25.
});
call_mcp_tool(
    "get_data",
    {
        "object_id": "a6b47acc-c391-4b78-9901-36235fd07809",  # GUID of the parent Liveboard, from search_objects.
        "object_type": "LIVEBOARD_VIZ",  # The type from the search_objects result.
        "visualization_ids": ["473f787a-bf3f-4366-a58e-4905a1329017"],  # The visualization_id from search_objects.
        "max_rows": 3,  # Optional. Defaults to 25.
    },
)

ResponseπŸ”—

{
  "data": [
    {
      "viz_id": "473f787a-bf3f-4366-a58e-4905a1329017",
      "viz_name": "Sales Monthly",
      "columns": ["Month(date)", "Total sales"],
      "data_rows": [
        [1775001600, 16202999.75],
        [1777593600, 17906780.6],
        [1780272000, 17077681.7]
      ],
      "total_row_count": 7,
      "sampling_ratio": 1
    }
  ]
}
FieldTypeDescription

data

Array

The object’s data. An Answer returns one entry. A Liveboard returns one entry for each visualization.

viz_id

String

GUID of the visualization. Present for Liveboard visualizations. Omitted for a standalone Answer.

viz_name

String

Display name of the visualization. Present for Liveboard visualizations.

columns

Array of strings

Column names, in the same order as the values in each row.

data_rows

Array of arrays

The data rows. Each row is an array of cell values that line up with columns. A cell is a string, number, boolean, or null. Numeric cells are returned at full precision, as stored.

total_row_count

Number

Total number of rows available, before max_rows is applied. Compare it with the number of returned rows to detect truncation.

sampling_ratio

Number

A value from 0 to 1. A value of 1 means that the complete result set was returned and was not sampled.

Liveboard time limitπŸ”—

Liveboard fetches are time-bound. A call returns as many visualizations as it can fetch within the time limit. A typical call handles about 25 visualizations. Not every requested visualization is guaranteed to come back, even when you pass visualization_ids. If a visualization that you need is missing from the result, request it by GUID in a follow-up call.

Model builder toolsπŸ”—

The model builder tools let an agent build a new ThoughtSpot data model from warehouse tables, or edit an existing model, through conversation. The pattern mirrors the analysis workflow, with two user checkpoints: the builder’s plan and the final save.

  1. The agent calls create_model_session with a connection GUID (new model) or a model GUID (edit).

  2. The agent sends an instruction with send_model_message.

  3. The agent polls get_model_updates until is_done is true. If the builder returns a plan or a question, the agent shows it to the user and sends the user’s reply with send_model_message.

  4. The agent calls finalize_model without confirm to get a summary for review.

  5. After the user approves, the agent calls finalize_model with confirm: true to save the model.

Important

The model builder tools require the data management privilege and the privilege to create or edit data models. The MCP Server does not list these tools for other users.

create_model_sessionπŸ”—

Start a model builder session. Creating a session does not build anything. Send the first instruction with send_model_message.

Input parametersπŸ”—

FieldDescription

connection_identifier
Optional

GUID of the data warehouse connection for a new model. Ask the user which connection to use, and confirm the exact GUID with the user before you call the tool. Do not guess it, reuse one from a previous model, or assume a default. Omit it when you edit an existing model.

model_identifier
Optional

GUID of an existing model to edit. Omit connection_identifier in this case, because the model already has a connection. Confirm the exact model with the user first, and do not guess the GUID.

Pass one of the two fields.

ResponseπŸ”—

{
  "model_session_id": "session-guid-abc123"
}
  • model_session_id: Identifier of the model session. Pass it to send_model_message, get_model_updates, and finalize_model.

send_model_messageπŸ”—

Send an instruction to the model builder, such as a description of the model, a correction, or an answer to a clarification. The call returns as soon as the instruction is accepted. Read the builder’s response with get_model_updates.

Input parametersπŸ”—

FieldDescription

model_session_id
Required

Session ID from create_model_session.

message
Optional

Natural language instruction, for example, Create a model for sales from the ORDERS and CUSTOMERS tables. Omit it only when you answer a clarification with selected_option_ids.

selected_option_ids
Optional

When you answer a choice update, the id values (such as "1" or "2") of the options that the user selected. Pass the option IDs, not table GUIDs.

ResponseπŸ”—

{
  "success": true
}
  • success: Whether the instruction was accepted. If it is false, the previous instruction can still be running. Keep calling get_model_updates until is_done is true, then try again.

Note
  • The builder drives the conversation. Do not invent your own questions.

  • Before the builder adds formulas, list the formulas that you intend to add and get the user’s confirmation.

get_model_updatesπŸ”—

Poll for the builder’s updates on the current instruction. Call it repeatedly until is_done is true. A full build takes 1 to 2 minutes, so an empty batch with is_done: false means that the builder is still working.

Input parametersπŸ”—

FieldDescription

model_session_id
Required

Session ID from create_model_session.

ResponseπŸ”—

The response contains an updates array and an is_done flag. Each call returns only the updates that arrived since the previous call. The array can be empty while the builder is still working.

{
  "updates": [
    {
      "type": "notification",
      "text": "Adding joins to model"
    }
  ],
  "is_done": false
}

Each update has a type:

TypeWhat it meansWhat to do

mrd

A proposed plan (Model Requirements Document). The full plan is in text. The model is not built yet.

Stop. Show the plan to the user and wait for explicit approval or edits. Never approve the plan on the user’s behalf.

choice

A clarifying question with options, in choice.

Show the options. Send the user’s selection with selected_option_ids.

todo

The build’s task tracker, in tasks. For example, Tables, Joins, and Columns, each marked PENDING, IN_PROGRESS, or COMPLETED.

Show it as a progress checklist, and update it as new todo updates arrive.

notification

A short progress line in text, such as Adding joins to model.

Show each one as it arrives.

text

A message from the builder, in text.

Relay the meaningful parts in plain language.

model_state

The model draft advanced to a new generation, in generation_no.

Use it as progress information.

action

Suggested next actions, in actions. The user does not have to take them.

Offer them to the user if they are relevant.

message_end

The turn ended. status has the terminal status, such as completed.

No action is required.

If a build starts without an mrd update, the plan step was skipped. Tell the user, and do not treat the plan as approved.

finalize_modelπŸ”—

Review and save the model. Saving takes two calls. The first call, without confirm, returns a summary for review. The second call, with confirm: true, saves the model and returns its link. Do not finalize if the builder has returned only a plan and nothing has been built.

Input parametersπŸ”—

FieldDescription

model_session_id
Required

Session ID to finalize.

confirm
Optional

Set to true to save, only after the user has reviewed the summary and chosen to save. If you omit it or set it to false, the tool returns the summary only and does not save.

name
Optional

Name for the model. Required when you save a new model. When you edit an existing model, omit it to keep the current name, and pass it only if the user asked to rename the model.

description
Optional

Description for the model. When you edit an existing model, omit it to keep the current description.

ResponseπŸ”—

The first call, without confirm, returns the summary and saved: false:

{
  "summary": "Sales model with 2 tables, 1 join, and 14 columns.",
  "saved": false
}

The second call, with confirm: true, saves the model and also returns its GUID and link:

{
  "summary": "Sales model with 2 tables, 1 join, and 14 columns.",
  "saved": true,
  "model_identifier": "7d2f1c4e-9b3a-4e58-a1f6-0c8b5e2d9a31",
  "url": "https://your-instance.thoughtspot.cloud/#/data/tables/7d2f1c4e-9b3a-4e58-a1f6-0c8b5e2d9a31"
}
FieldTypeDescription

summary

String

Human-readable summary of the model, returned for review.

saved

Boolean

Whether the model was saved. It is true only when you set confirm to true.

model_identifier

String

GUID of the saved model. Present when the model was saved.

url

String

Link to open the saved model. Present when the model was saved.

ExampleπŸ”—

const { model_session_id } = await callMCPTool("create_model_session", {
    connection_identifier: "de1b3cfd-1725-400a-b6c7-0cd0f2b70bf1" // Confirmed with the user.
});

await callMCPTool("send_model_message", {
    model_session_id,
    message: "Create a model for sales from the ORDERS and CUSTOMERS tables."
});

// Poll until is_done. Each call returns only new updates, so keep every batch.
const allUpdates = [];
let batch;
do {
    batch = await callMCPTool("get_model_updates", { model_session_id });
    allUpdates.push(...batch.updates);
} while (!batch.is_done);

// If allUpdates contains an mrd update, show the plan to the user and wait for approval.
// Send the user's reply with send_model_message, and poll again until is_done.

// Without confirm, finalize_model returns a summary for review and does not save.
const summary = await callMCPTool("finalize_model", { model_session_id, name: "Sales Model" });

// Save only after the user has reviewed the summary and chosen to save.
const saved = await callMCPTool("finalize_model", { model_session_id, name: "Sales Model", confirm: true });
session = call_mcp_tool(
    "create_model_session",
    {"connection_identifier": "de1b3cfd-1725-400a-b6c7-0cd0f2b70bf1"},  # Confirmed with the user.
)
model_session_id = session["model_session_id"]

call_mcp_tool(
    "send_model_message",
    {
        "model_session_id": model_session_id,
        "message": "Create a model for sales from the ORDERS and CUSTOMERS tables.",
    },
)

# Poll until is_done. Each call returns only new updates, so keep every batch.
all_updates = []
while True:
    batch = call_mcp_tool("get_model_updates", {"model_session_id": model_session_id})
    all_updates.extend(batch["updates"])
    if batch["is_done"]:
        break

# If all_updates contains an mrd update, show the plan to the user and wait for approval.
# Send the user's reply with send_model_message, and poll again until is_done.

# Without confirm, finalize_model returns a summary for review and does not save.
summary = call_mcp_tool("finalize_model", {"model_session_id": model_session_id, "name": "Sales Model"})

# Save only after the user has reviewed the summary and chosen to save.
saved = call_mcp_tool(
    "finalize_model",
    {"model_session_id": model_session_id, "name": "Sales Model", "confirm": True},
)

Visualizations embedded in iframeπŸ”—

When displaying the embedded visualization using the iframe_url property, the following user interaction features are included by default:

AreaOptionVisibility

Primary actions and actions in the More (…​) options menu

Pin

Visible

Save

Visible

Download

Visible

Edit

Not visible

Add to Coaching

Not visible

Context menu actions

Aggregate

Visible

Filter

Visible

Sort

Visible

Position

Visible

Conditional formatting

Not visible

Rename

Not visible

Edit

Not visible

Remove

Not visible

Axis menu

Exclude

Visible

Only include

Visible

Drill down

Visible

Show underlying data

Visible

The following features are not supported directly in visualizations embedded in an iframe. However, you can use the Make a Copy option to access these capabilities:

  • Changing filters

  • Changing chart type or chart configuration

  • View query SQL or query visualizer

  • SpotIQ analysis

Org switching toolsπŸ”—

Some ThoughtSpot deployments use Orgs, the isolated tenant workspaces within a single instance, each with its own users, data models, and resources. A user may have membership in one or several Orgs and want to analyze data from a different Org without ending the session, closing the connection, or re-authenticating. When connecting to the MCP Server over OAuth on an Org-enabled instance, users can discover and switch between Orgs during a session using list_orgs and switch_org.

Org switching is a two-step pattern:

  1. The agent calls list_orgs to retrieve the Orgs the user can currently access. The response identifies which Org is active and returns the id of the Orgs to switch.

  2. The agent calls switch_org with the target org_id. ThoughtSpot switches the active Org for the session and confirms the new active Org ID.

Important
  • The list_orgs and switch_org tools are available on OAuth MCP server endpoints only. Bearer-token MCP Server endpoints do not expose these tools.

  • The switch_org is a state-changing operation. Host applications that gate state-changing tools behind user confirmation will prompt the user before this tool runs.

  • list_orgs reflects the user’s current org membership at call time, not a snapshot taken at connection. Orgs granted or revoked mid-session appear immediately.

  • Data models and resources in a target Org are not visible until after switching. Use list_orgs to discover Org names, then switch_org to enter an Org and explore its contents.

list_orgsπŸ”—

Returns the id, name, and description of each Org that the authenticated user has access to, and flags the Org that the user is currently logged in to.

Use the list_orgs tool to discover which Orgs you can reach before switching. The list always reflects your live access at call time, not a snapshot taken when you connected, so orgs granted or revoked since your session started are reflected immediately.

Example callπŸ”—

const orgs = await callMCPTool("list_orgs", {});
call_mcp_tool("list_orgs", {})

ResponseπŸ”—

{
  "orgs": [
    {
      "id": 1001,
      "name": "Finance",
      "description": "Finance org β€” Q3 revenue models and budget data.",
      "is_active": true
    },
    {
      "id": 1002,
      "name": "Staging",
      "description": "Staging environment for testing new data models."
    }
  ]
}
FieldDescription

id

Unique identifier for the Org. Pass this value to switch_org to switch to this Org.

name

Display name of the Org.

description

Description of the Org.

is_active

Set to true if the user’s current session is in this Org (the active Org). If the user’s current session is not in this Org, this field is omitted from the response.

switch_orgπŸ”—

Switches the active Org for the current session.

After a successful switch, all subsequent tool calls including create_analysis_session and data source lookups run against the Org to which the user is switched. This switch persists across all active sessions without requiring re-authentication or logging out.

Important
  • switch_org is annotated readOnlyHint: false. For more information, see the note at the start of this section about confirmation prompts.

  • After switching Orgs, the list of data model resources will stay static unless the LLM client provides dynamic resource lists.

  • The active Org selection persists across sessions and applies across all your active sessions. It resets only on re-authentication or after prolonged inactivity.

Input parametersπŸ”—

FieldDescription

org_id
Required

The ID of the org to switch to. Obtain this value from list_orgs.

Example callπŸ”—

const result = await callMCPTool("switch_org", {
    org_id: 1002 // ID of the org to switch to, obtained from list_orgs.
});
call_mcp_tool(
    "switch_org",
    {"org_id": 1002},  # ID of the org to switch to, obtained from list_orgs.
)

ResponseπŸ”—

{
  "success": true,
  "active_org_id": 1002
}
  • success: true if the org switch completed successfully. If the user lacks access to the requested Org, it is set as false and the active Org remains unchanged.

  • active_org_id: The ID of the active Org.

Known limitations for OAuth connectionsπŸ”—

  • Signing in currently relies on a browser cookie from your ThoughtSpot cluster. If your browser blocks third-party cookies, the connection may fail to complete.

  • Re-authentication is required in the following scenarios:

    • If connection remains idle for 14 days, the session expires and requires reauthentication.

    • If your ThoughtSpot instance is temporarily unreachable when your session token renews, you may be signed out and prompted to reconnect.

check_connectivityπŸ”—

Runs a basic health check to verify that the ThoughtSpot Spotter MCP Server is reachable and responding. Use this tool to confirm your connection before starting an analytical session.

Note

check_connectivity is the Spotter 3 equivalent of the ping tool in the legacy MCP version.

Example callπŸ”—

const result = await callMCPTool("check_connectivity", {});
call_mcp_tool("check_connectivity", {})

ResponseπŸ”—

{
  "success": true
}
  • success: Returns true if the Spotter MCP Server is reachable and operational.

Additional resourcesπŸ”—

Β© 2026 ThoughtSpot Inc. All Rights Reserved.