Interactive MCP apps

Choose when to render GovTribe interactive MCP apps, which Show_* tool to use, and when to read canonical state with Interaction_State.

Use an interactive MCP app when the user needs to inspect, select, review, or submit structured information inside the conversation. Use normal Markdown when a direct answer, short table, or brief explanation is clearer.

The MCP tool pages remain the source of truth for exact payload fields and response contracts.

Choose Markdown first

Do not render an app just because one is available. Markdown is usually better when:

the answer is short and does not need interaction
a small comparison table is enough
the user only needs a summary or recommendation
the next step is a search, retrieval, or workflow action rather than an interactive review surface

Use an app when the interaction materially improves review, selection, inspection, or comprehension.

Output apps

Output apps help the user inspect information you already have.

Tool	Use when	Avoid when
Show stats display	The answer is a compact set of headline metrics, KPI cards, scorecards, or rollups.	The output is mainly a trend, comparison, or ranked visual.
Show chart	The result fits a standard `trend`, `comparison`, or `leaderboard` chart.	The user needs bespoke graphics, heavy annotations, long-label polish, source notes, or presentation layout.
Show geo map	Geography is the primary review surface, such as buyer offices, vendor locations, field sites, routes, or marker selection.	The user needs trends, grouped comparisons, ranked categories, choropleths, polygons, or heatmaps.
Show document	The user should preview a specific user file, government file, or current GovTribe OAI shell file inside chat.	The task is text extraction or semantic file review; use file search or vector-store retrieval instead.

Use Show_Document annotation mode only when the user needs human markup or review comments. Annotations do not modify the source file. If submitted annotation text asks for an edit, treat it as an instruction to create an updated artifact through the appropriate document workflow.

Input apps

Input apps collect structured choices from the user.

Tool	Use when	Avoid when
Show option list	The user needs to choose from one bounded option set.	The clarification has multiple stages or branches.
Show question flow	The user needs staged or branching choices before a search, workflow, or artifact step.	A direct lookup can resolve the missing context.
Show preferences panel	The user should review or change durable settings, recurring filters, workflow preferences, or adjustable defaults.	The input is a one-time intake with no durable preference value.

Prefer input apps over free-text replies when the missing information is structured, bounded, and likely to be reused by a tool call or workflow.

State handling

Use Interaction state when an app returns an interactionId and the next response depends on submitted selections, answers, preferences, annotations, or map state.

Preserve returned interactionId values exactly. Common prefixes identify the app family:

Prefix	App family
`geo_map:*`	`Show_Geo_Map`
`option_list:*`	`Show_Option_List`
`question_flow:*`	`Show_Question_Flow`
`preferences_panel:*`	`Show_Preferences_Panel`

Read canonical state before using submitted choices to search, update records, create artifacts, or summarize a decision. If state is missing, expired, unauthorized, or not bootstrapped, ask the user to resubmit or render a fresh app.

Common routing decisions

Situation	Use
KPI cards or scorecards	`Show_Stats_Display`
Trend, grouped comparison, or single-metric leaderboard	`Show_Chart`
Point-based map, route overlay, dense marker review, or location selection	`Show_Geo_Map`
In-chat file preview or annotation review	`Show_Document`
One bounded choice	`Show_Option_List`
Multi-step or branching intake	`Show_Question_Flow`
Durable workflow settings or saved preferences	`Show_Preferences_Panel`
Submitted app selections or persisted app state	`Interaction_State`

Switch away from interactive apps when the hard part is constructing a search, retrieving file text, producing a document, or designing a bespoke presentation graphic.

Examples

KPI cards from an aggregation result:

Tool: Show_Stats_Display

{
  "id": "opportunity-summary",
  "title": "Open opportunity summary",
  "description": "Filtered to current search criteria.",
  "stats": [
    {
      "key": "open_count",
      "label": "Open opportunities",
      "value": 126,
      "format": {
        "kind": "number",
        "compact": true
      }
    },
    {
      "key": "small_business_share",
      "label": "Small-business set-aside share",
      "value": 0.42,
      "format": {
        "kind": "percent",
        "basis": "fraction",
        "decimals": 1
      }
    }
  ]
}

Leaderboard chart from aggregation buckets:

Tool: Show_Chart

{
  "id": "top-agencies-for-training",
  "kind": "leaderboard",
  "title": "Top agencies by matching opportunity count",
  "rows": [
    {
      "agency": "Department of the Army",
      "opportunities": 42
    },
    {
      "agency": "Department of Veterans Affairs",
      "opportunities": 31
    }
  ],
  "labelKey": "agency",
  "series": [
    {
      "key": "opportunities",
      "label": "Opportunities"
    }
  ],
  "valueFormat": {
    "kind": "number",
    "compact": true
  },
  "maxItems": 10
}

Map a small set of selected records:

Tool: Show_Geo_Map

{
  "id": "facility-modernization-map",
  "title": "Facility modernization locations",
  "viewport": {
    "mode": "fit_all",
    "padding": 48
  },
  "series": [
    {
      "id": "opportunity-locations",
      "label": "Opportunity locations",
      "style": {
        "color": "#125475",
        "size": "md",
        "icon": "circle"
      },
      "markers": [
        {
          "id": "opp-1-location",
          "lat": 38.883,
          "lng": -77.016,
          "label": "Washington, DC",
          "subLabel": "Place of performance",
          "recordRef": {
            "entityType": "federal_contract_opportunity",
            "entityId": "example-opportunity-id",
            "title": "Facility modernization support"
          }
        }
      ]
    }
  ]
}

Ask the user to choose a bounded next step:

Tool: Show_Option_List

{
  "id": "next-search-step",
  "title": "Choose the next review step",
  "description": "Select the direction you want to pursue next.",
  "options": [
    {
      "id": "narrow-by-agency",
      "label": "Narrow by agency",
      "description": "Add agency filters before reviewing individual records."
    },
    {
      "id": "compare-categories",
      "label": "Compare categories",
      "description": "Build a category rollup from the current result set."
    }
  ]
}

Read submitted state before acting on a selection:

Tool: Interaction_State

{
  "interactionId": "option_list:next-search-step"
}

MCP tools: Browse the full GovTribe MCP tool reference.
Show chart: Render standard trend, comparison, or leaderboard charts.
Show stats display: Render KPI summary cards from structured stat values.
Show geo map: Render marker maps, routes, and marker-selection workflows.
Interaction state: Read or persist canonical app state for interactive app workflows.