Gainsight

Answer user questions using Staircase AI's knowledge base. Use this tool as a starting point for the user interaction. This tool leverages Staircase AI's capabilities to provide accurate and context-aware answers to user queries. The tool returns an answer string and an optional list of evidences (communications) supporting the answer. Optionally, use the staircase_fetch_evidence tool to retrieve complete documents for detailed analysis.

Retrieve complete evidence content by ID for detailed analysis and citation. Use this tool to get the full content of a specific evidence returned by staircase_query.

Resolve a customer / account name (or partial name) to one or more Staircase account_ids. Use this when the user refers to an account by name and you need the corresponding account_id — typically before calling staircase_account_info (factual lookups) or staircase_analyze_account (questions that require reading communications). Matching is fuzzy; each returned match has a confidence of "high" or "low".

Answer a user question scoped to a single Staircase account. Use this when the user asks about a specific account and you have its account_id (from staircase_account_lookup if you only have the name). Returns an answer and a list of supporting evidences; use staircase_fetch_evidence to retrieve full evidence content.

Return structured data about accounts, contacts, or customer events as a CSV. PREFER staircase_run_report over this tool: build the report config yourself from staircase_report_metadata and run it directly (deterministic, pageable, and it skips the extra backend LLM compile this tool pays for). Use this natural-language tool as the fallback — when you'd be guessing at the config (an ambiguous or vague request, or an org-specific field you can't confidently map), or when you can't fetch the schema. Use this tool ONLY for cross-account questions (questions that span many accounts): - Lists and filters: "List all active Enterprise accounts in EMEA", "Show accounts with no engagement" - Counts and aggregations: "How many accounts are at churn risk?", "Total ARR of churned accounts?", "Average health score by segment" - Rankings: "Top 10 customers by ARR last quarter" - Cross-account AI-insight fields — these live in structured tables, use this tool (not staircase_query): - Churn risk analysis (which active accounts are at risk of churning): "Which accounts are at churn risk?", "Show churn risk analysis" - Churn summary (which accounts already churned): "Show churned accounts" - Expansion opportunities (which accounts have upsell potential): "Show expansion opportunities", "Which accounts have upsell potential?" - Sales-to-CS handoff (across recently handed-off accounts): "What are the primary objectives from the handoff accounts joined last quarter?" - Dark accounts (which accounts have had no engagement): "Show dark accounts", "Which accounts have had no engagement?" For a SINGLE account, do NOT use this tool: - Factual lookups (health score, owner, revenue, renewal date, churn risk, expansion for one named account): use staircase_account_lookup + staircase_account_info. - Analytical questions about one account (what was said, summaries, drivers): use staircase_account_lookup + staircase_analyze_account. Use staircase_query for open-ended questions, conversation analysis, or narrative summaries. Returns ReportResult: csv is a UTF-8 string (row 0 = header), message is set only on failure. The result includes a `truncated` flag. If truncated=true, the backend returned the first `row_count` rows of a larger result set, capped at `row_cap`. Tell the user explicitly that results were truncated and offer to narrow the query (filter, sort+limit) or switch to an aggregation (COUNT, SUM, GROUP BY) instead of a per-row list. Do not present truncated results as complete.

Return the report schema for the current organization: the entities you can report on and, for each, the fields usable as columns or filters. Call this ONCE before staircase_run_report, then build a ReportConfig from what it returns. The schema is already scoped to what you are allowed to query — never reference an entity or field that is not present here, and match field IDs exactly. Also returns `current_user_id`: the numeric id of the logged-in user. Use it for "my accounts" / "me" filters — e.g. {"field": {"id": "customer.owner"}, "operator": "In", "values": [current_user_id]} — which is exact, unlike matching the owner by name. Response: `entities`, a list of `{entity, label, fields}`. `entity` is the technical id used as ReportConfig.entity (e.g. "customer"). Each field has: - id: dot-separated path used in ReportConfig (e.g. "customer.name"). - label, type. - isColumn: may be used in `columns`. - isFilterable: may be used in a filter condition (fields with isFilterable=false must never appear in a filter). - requiredArguments: arguments the field needs — a `dateRange` here means the field is a metric that must carry an `arguments.dateRange` wherever it is used. - aggregations: aggregation functions valid for the field. - options: for Picklist fields only, the allowed `{id, label}` values — filter using the option `id`, not the label.

Run a structured report you built yourself and return the rows as CSV. This is the deterministic, no-LLM path: you supply the exact `config`, so it is cheaper and more predictable than staircase_generate_report and it can page through large result sets. Same data domain as staircase_generate_report (cross-account accounts / contacts / events). Call staircase_report_metadata first to get valid entities and field IDs. PREFER this tool over staircase_generate_report whenever you can name the entity and every column/filter field from staircase_report_metadata. Only fall back to the natural-language staircase_generate_report when you'd be guessing at the config (an ambiguous or vague request, or an org-specific field you can't confidently map), when you can't fetch the schema, or when a config here failed with an error you can't fix. `config` is a ReportConfig object. Pass the object itself — do NOT wrap it in a {"report": ...} envelope, and there is no `groupBy`; to group, select the grouping column and aggregate the returned rows yourself. ReportConfig fields: - entity (required): the entity id from staircase_report_metadata, e.g. "customer". - columns (required): list of {field, key, label?}. `key` must be unique per column. `field` is {"id": "<field path>"} for a normal field; for a field whose metadata lists a required `dateRange`, use {"id": "<path>", "arguments": {"dateRange": "[PastMonth]"}}; for a summary column use an aggregation object (see below). Always include a human-readable name column (e.g. customer.name) so rows are identifiable. For account reports a raw numeric `customer_id` column is prepended automatically so you can chain follow-up calls. - filter (optional): a condition group {"operator": "And" | "Or", "conditions": [...]}. `operator` defaults to "And" when omitted — every condition must match; use "Or" to match rows satisfying ANY condition in the group. A condition in the list may itself be a nested group (with its own "operator"/"conditions"), so mix AND and OR by nesting — e.g. an outer "And" whose conditions include an inner {"operator": "Or", "conditions": [...]} group. Each leaf condition is {"field": {"id": "<path>"}, "operator": "<op>", "value": <scalar> | "values": [<array>]}. Operators by type: Defined/NotDefined/Equal/NotEqual (any field); Contains for text and name searches (copy the user's value verbatim, do not change its capitalization); LessThan/LessOrEqual/GreaterThan/GreaterOrEqual (numbers); In/NotIn with an array (picklists — use the option `id` from metadata, not the label); InRange/NotInRange (dates); Include with an array (array fields). Reference fields filter through a sub-field: picklist refs like tier/journey use ".name" (e.g. customer.tier.name Equal "Enterprise"); user-reference fields use ".full_name" with Contains. For account list reports add {"field": {"id": "customer.status"}, "operator": "In", "values": ["Active"]} by default — EXCEPT when the user names one specific account (filter customer.name Contains "<name>", no status filter) or explicitly asks for non-active accounts. "My accounts" / "me": filter the owner by the numeric current_user_id from staircase_report_metadata, e.g. {"field": {"id": "customer.owner"}, "operator": "In", "values": [<current_user_id>]}. This is an exact id match — prefer it over matching the owner by name. Only if current_user_id is absent, fall back to {"field": {"id": "customer.owner.full_name"}, "operator": "Contains", "value": "<user's name>"} (or customer.owner.email). Child-entity conditions (insights, lifecycle events): match rows that HAVE a related child record with an EXISTS aggregation — the condition's `field` names the child entity and carries a nested `condition`, and the outer operator/value assert the EXISTS is true. Insights (current-state signals — at risk, dark, single-threaded, no QBR): no date range, insights are current, not time-bounded: {"field": {"rootEntityPath": "customer", "childEntity": "insight", "referenceField": "insight.customer", "aggregation": "EXISTS", "condition": {"conditions": [ {"field": "insight.type", "operator": "Equal", "value": "ChurnRisk"}]}}, "operator": "Equal", "value": true} Use the insight.type id from the insight.type picklist in staircase_report_metadata (e.g. "ChurnRisk" for at-risk, "CustomerDark" for dark). For "at risk" prefer this insight over a lifecycle churn_risk event — nothing to date-bound. Lifecycle events (renewal, churn, qbr, expansion — point-in-time): same EXISTS form on `lifecycle_event`, plus a date bound in the nested condition: {"field": {"rootEntityPath": "customer", "childEntity": "lifecycle_event", "referenceField": "lifecycle_event.customer", "aggregation": "EXISTS", "condition": {"conditions": [ {"field": "lifecycle_event.type", "operator": "Equal", "value": "renewal"}, {"field": "lifecycle_event.date", "operator": "InRange", "value": "[Past3Months]"}]}}, "operator": "Equal", "value": true} Use the lifecycle_event.type id from the picklist in staircase_report_metadata (e.g. "churn_risk", "renewal"); always bound lifecycle_event.date with InRange + a dateRange enum. - sortBy (optional): list of {"columnKey": "<a column key>", "direction": "Asc"|"Desc"}. Use [] when not sorting (never null). For "top N" sort by the relevant column and add pagination. - pagination (optional): {"from": <0-indexed start>, "to": <end, exclusive>}, e.g. {"from": 0, "to": 10} for the top 10. Advance `from`/`to` to page through a large result set (see the `truncated` flag below). Metric/date fields: any field whose metadata lists a required `dateRange` MUST carry `arguments.dateRange` set to one of the enum values below — never null or omitted. Use the relative enum, not a computed date array, for relative periods; use a fixed ["YYYY-MM-DD","YYYY-MM-DD"] array only for explicitly named calendar periods with no enum. Relative: [Yesterday] [PastWeek] [Past2Weeks] [PastMonth] [Past3Months] [Past6Months] [PastYear] [Next7Days] [Next30Days] [Next90Days] Calendar: [Today] [ThisWeek] [ThisMonth] [ThisQuarter] [ThisYear] Previous/next calendar: [LastWeek] [LastMonth] [LastQuarter] [LastYear] [NextWeek] [NextMonth] [NextQuarter] [NextYear] Default to [Past3Months] when a date range is required but unspecified. Scalar aggregations — for a single summary number ("how many...", "total ARR", "average health score"), make the column `field` an aggregation object: {"aggregation": "COUNT"} (no aggregatedField), or {"aggregation": "SUM"|"AVG"|"MIN"|"MAX", "aggregatedField": "<numeric field path>"}. Such a report returns ONE summary row: do not mix it with row-level columns, set sortBy to [], and omit pagination. Apply the same filters (status, etc.) as a normal report. Examples (each is the `config` value): "Top 10 active Enterprise accounts by revenue" { "entity": "customer", "columns": [ {"field": {"id": "customer.id"}, "key": "id"}, {"field": {"id": "customer.name"}, "key": "name"}, {"field": {"id": "customer.revenue"}, "key": "revenue"} ], "filter": {"operator": "And", "conditions": [ {"field": {"id": "customer.tier.name"}, "operator": "Equal", "value": "Enterprise"}, {"field": {"id": "customer.status"}, "operator": "In", "values": ["Active"]} ]}, "sortBy": [{"columnKey": "revenue", "direction": "Desc"}], "pagination": {"from": 0, "to": 10} } "How many active accounts are there?" { "entity": "customer", "columns": [{"field": {"aggregation": "COUNT"}, "key": "count"}], "filter": {"operator": "And", "conditions": [ {"field": {"id": "customer.status"}, "operator": "In", "values": ["Active"]} ]}, "sortBy": [] } "Sentiment score and emails sent last month for active accounts" { "entity": "customer", "columns": [ {"field": {"id": "customer.id"}, "key": "id"}, {"field": {"id": "customer.name"}, "key": "name"}, {"field": {"id": "customer.buckets.sentiment.numeric_score"}, "key": "sentiment"}, {"field": {"id": "customer.email.sent_count", "arguments": {"dateRange": "[PastMonth]"}}, "key": "emails_sent"} ], "filter": {"operator": "And", "conditions": [ {"field": {"id": "customer.status"}, "operator": "In", "values": ["Active"]} ]}, "sortBy": [] } "List my accounts that are at risk" (current_user_id 4820 from staircase_report_metadata) { "entity": "customer", "columns": [ {"field": {"id": "customer.id"}, "key": "id"}, {"field": {"id": "customer.name"}, "key": "name"}, {"field": {"id": "customer.risk.risk_level"}, "key": "risk_level"}, {"field": {"id": "customer.risk.analysis"}, "key": "risk_analysis"} ], "filter": {"operator": "And", "conditions": [ {"field": {"id": "customer.status"}, "operator": "In", "values": ["Active"]}, {"field": {"id": "customer.owner"}, "operator": "In", "values": [4820]}, {"field": {"rootEntityPath": "customer", "childEntity": "insight", "referenceField": "insight.customer", "aggregation": "EXISTS", "condition": {"conditions": [ {"field": "insight.type", "operator": "Equal", "value": "ChurnRisk"} ]}}, "operator": "Equal", "value": true} ]}, "sortBy": [{"columnKey": "risk_level", "direction": "Desc"}] } Returns ReportResult: csv is a UTF-8 string (row 0 = header); message is set only on failure and, for an invalid config, echoes the backend's reason so you can fix and retry. If truncated=true the backend returned only the first `row_count` rows (capped at `row_cap`) of a larger set — tell the user, and either page with pagination or switch to an aggregation. Do not present truncated results as complete.

Retrieve pre-computed structured data for a single account as CSV. Returns account metadata and AI-insight fields: health score, sentiment score, revenue, renewal date, churn risk, expansion readiness, owner, tier, journey, last engagement, and more. Use this for factual lookups that do not require analyzing communications. For questions that require reading emails, calls, tickets, or meetings (e.g. "what did the customer say about X?", "summarize the last call"), use staircase_analyze_account instead.

Retrieve communications by topic or theme and return matching threads as ranked raw evidence (thread_id, comm_type, snippet, similarity score, matched topic, account). Built for cross-account discovery — e.g. "which customers mention churn", "accounts asking for this feature", "pricing disputes this quarter". It does not synthesize an answer; each result's source is "semantic". For a SINGLE account, prefer staircase_account_lookup + staircase_analyze_account (it reads that account's raw communications and is more thorough) — EXCEPT in these cases, where this tool is the better fit even for one account: - Long horizon: the relevant thread may be older than the recent window staircase_analyze_account reads. - Vague wording or a very specific term: you want semantic matching, not the exact keywords staircase_analyze_account ranks on. - You need ranked evidence to cite or process yourself, not a written answer or report. account_ids optionally narrows to a candidate set of accounts (resolve names via staircase_account_lookup first); omit to span the whole org. start_date / end_date optionally bound the time window.