Interactive MCP apps

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.

Start with a minimal payload

Use trend for 1–4 line series in supplied row order, comparison for 1–4 grouped vertical bar series in supplied row order, and leaderboard for one horizontal bar series ranked descending. A chart description is optional and appears once after loading; context remains available during loading or errors. Omit it when no extra context is needed. Full labels and non-compact values are available by hovering or focusing chart marks. The chart tool page explains keyboard navigation and scrollable tooltips.

A chart can start with {"kind":"trend","rows":[{"month":"Jan","awards":3}],"labelKey":"month","series":[{"key":"awards"}]}. KPI cards can start with {"stats":[{"label":"Awards","value":3}]}. The tool pages above provide complete minimal and advanced examples for each retained app.

Chart, KPI, map and preference presentation IDs default when omitted or null. Chart series labels default from data keys; map series labels default from stable series IDs. KPI presentation keys also default. Titles, descriptions, footnotes, colors, precision and formatting overrides are optional. Preserve record IDs, setting IDs, choice values, file identifiers and returned interaction IDs exactly. A document preview needs only its valid file identifier; it does not need explanatory text or annotation options.

Plain numbers are the default. Currency formatting requires an explicit currency code, and percentage formatting requires an explicit fraction or unit basis. A KPI percentage-change badge uses percent units (12.4 means +12.4%). Presentation defaults never imply financial units, user answers, saved preferences or approval.

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.

Use Show_Document for read-only preview in GovTribe AI and external MCP clients. For new annotation review or editing in GovTribe AI, use open_in_govtribe_ai and govtribe-document-editing with the file-format skill in the dedicated document pane. External MCP clients can use the authorized download links with their host's document workflow. Historical annotations are read-only, including pending drafts. Unsent marks are labeled separately and do not establish an edit request or approval. Submitted edit instructions remain usable context; clear edit requests still require an updated artifact through the document workflow.

Show_Data_Table replaces the retired search-card tools for new displays. Its sort, text search and local pages operate only on loaded rows. Reference mode shows the current source page and full-search total separately; fetching another source page rechecks current access and uses normal typed-search usage metering. Search-wide filter/order changes require a new search. No table interaction records a selection or approval.

For supported searchable files, use Vector-store content retrieval instead of Show_Document when the task is extraction or semantic review. If vector-store retrieval skips, fails, or cannot reliably cover spreadsheet-like files such as workbooks, CSV/TSV files, pricing schedules, CLIN tables, or staffing matrices, use Add to container and hosted shell extraction for those files.

Clarification and preferences

In attended GovTribe AI, use the existing native Request_User_Input tool when available for bounded choices or question flows. Ask one to three concise questions together. Preserve stable question and option IDs, allow single or multiple selections as needed, and set recommended_option_id to one listed option ID only when justified, otherwise null. Recommendations are never preselected, and free text remains available, including free-text-only questions with options: null.

Actual answers arrive together on the original native call. Drafts survive navigation and reload but are not answers. Use submitted receipts before dependent work; preserve ownership, duplicate-submission, cancellation, timeout and async continuation safeguards. Continue independent work while waiting, then use Wait_For_Tasks when exposed before work that depends on the reply. Pending input, drafts, dismissal and timeout never count as an answer or approval.

External agents use their host's own clarification UI or text. Request_User_Input is native to GovTribe AI and has no external MCP equivalent. Where native input is unavailable, ask concise text questions. In unattended workflows, report missing required input without inventing an answer or taking an action that requires it.

Show option list and Show question flow are retired from all active GovTribe AI and MCP catalogs, including standard, compact and dedicated interactive servers. Cached calls cannot execute them. Their resources, validators, transcript renderers and submitted receipts remain available for historical conversations.

Use Show preferences panel for explicit durable settings, recurring filters or workflow preferences. Read its submitted settings before applying changes. Use native clarification for one-time intake.

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:

Preference controls edit drafts only. Save submits choices to the assistant; new panels have no Cancel action. A submitted or completed preference receipt does not confirm that actual settings changed. Confirm application only after an authorized downstream operation succeeds. Historical cancellation receipts remain readable.

New preference submissions restore unfinished delivery after reload. GovTribe retries reuse the same message acknowledgment without saving choices again. If an external host cannot verify whether a message was accepted, follow up manually in chat using the receipt; the panel does not offer an unsafe resend.

Read canonical state before using submitted choices to search, update records, create artifacts, or summarize a decision. If historical input state is missing, expired, unauthorized, or not bootstrapped, ask for clarification through available native or host UI/text. Never fabricate a selection or invoke a retired input tool. Native answers use their original call, not Interaction_State.

Common routing decisions

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

Maps display locations without collecting selections or requiring agent-supplied provider credentials. Click markers for small popups; pan and zoom to navigate. Existing submitted map selections remain readable as historical receipts.

{
  "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 in attended GovTribe AI:

Native tool: Request_User_Input (not an MCP tool)

{
  "questions": [
    {
      "id": "next-search-step",
      "question": "Which review step should I take next?",
      "options": [
        {"id": "narrow-by-agency", "label": "Narrow by agency"},
        {"id": "compare-categories", "label": "Compare categories"}
      ],
      "multiple": false,
      "recommended_option_id": null
    }
  ]
}

Wait for actual submitted answers on that original call. External hosts ask this question through their own clarification UI or text.

Read an existing historical submitted selection when needed:

Tool: Interaction_State

{
  "interactionId": "option_list:historical-selection-id"
}

Read the returned status and actual selection before acting. A pending or cancelled state is not an answer.

Related articles

• 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: Display marker maps with small popups, routes, and optional clustering.
• Interaction state: Read or persist canonical app state for interactive app workflows.