Use search results and user files in the hosted shell

Choose when to reason directly from GovTribe search responses, stage search-result JSON, stage existing workspace User Files, or use vector-store retrieval.

Use Add_To_Container when an agent needs GovTribe data or files as local inputs to the hosted shell. The tool can stage an accessible User File, files attached to another supported GovTribe record, a typed-search result page, or a mixture of those sources.

Normal Search_* calls do not create files or contact the OpenAI Files or Containers APIs. The agent must call Add_To_Container explicitly when shell staging is useful.

Choose the smallest useful path

Need	Best path
Read, compare, summarize, or cite records already returned by a typed search.	Reason directly from the `Search_*` response.
Use a search page in Python, build a chart or spreadsheet, or join it with another local dataset.	Pass the typed search response's `search_results_id` to `Add_To_Container`.
Parse a workbook, CSV, pricing schedule, or another accessible workspace file.	Resolve the file with `Search_User_Files`, then pass its `user_file` ID in `items`.
Retrieve passages semantically from supported PDFs, documents, or a source package.	Use `Add_To_Vector_Store`, then `Search_Vector_Store`.
Combine search rows with one or more files in the same shell workflow.	Pass both `search_results_id` and `items` to one `Add_To_Container` call.

Do not stage a typed search merely to continue reasoning from its returned rows. Shell staging adds file materialization, billing, upload, and container-attachment work and is useful only when the shell needs a local JSON file.

Stage an existing workspace User File

Existing User Files do not need to be uploaded to the current conversation. Search for a file the current user can access, then pass the returned govtribe_id to Add_To_Container.

{
  "tool": "Search_User_Files",
  "arguments": {
    "query": "pricing workbook",
    "fields_to_return": [
      "govtribe_id",
      "name",
      "description",
      "updated_at"
    ]
  }
}

{
  "tool": "Add_To_Container",
  "arguments": {
    "items": [
      {
        "govtribe_type": "user_file",
        "govtribe_id": "<user_file_govtribe_id>"
      }
    ]
  }
}

GovTribe applies the User File's current access policy. A file from another workspace, a deleted file, or a file the caller cannot view is rejected before container work begins.

Stage typed-search JSON

Run the typed search first. Keep its normal search_results_id; there is no second replay ID.

{
  "tool": "Search_Federal_Contract_Awards",
  "arguments": {
    "query": "zero trust",
    "page": 2,
    "per_page": 25,
    "fields_to_return": [
      "govtribe_id",
      "contract_number",
      "awardee",
      "dollars_obligated"
    ],
    "aggregations": [
      "top_awardees_by_dollars_obligated"
    ]
  }
}

{
  "tool": "Add_To_Container",
  "arguments": {
    "search_results_id": "<search_results_id>"
  }
}

The staged JSON preserves the original search_results_id, requested page, selected fields, filters and operators, sort, and aggregations. GovTribe reruns the search against current data, so records and aggregation values can differ from the earlier response. The staged row count never exceeds the number returned by the original search page.

An aggregation-only search produces JSON with its aggregations and no synthetic row array. An empty result page can still be staged when its descriptor remains valid.

Stage a mixed shell input set

Provide both inputs when one analysis needs search rows and files.

{
  "tool": "Add_To_Container",
  "arguments": {
    "search_results_id": "<search_results_id>",
    "items": [
      {
        "govtribe_type": "user_file",
        "govtribe_id": "<pricing_workbook_user_file_id>"
      },
      {
        "govtribe_type": "government_file",
        "govtribe_id": "<solicitation_attachment_id>"
      }
    ]
  }
}

Ordinary files and search materialization run independently. A search replay failure does not undo a successful ordinary file attachment. Read the combined polling response to identify completed, pending, failed, and skipped files.

Poll before using the shell

Add_To_Container returns a status snapshot. When status is in_progress and retry_with_same_arguments is true, call the tool again later with the same items and search_results_id.

Use the hosted shell only after:

status is completed
hosted_tool_ready is true
container_files includes each required input
the shell command uses the returned path_hint instead of guessing a filename

Repeated polling reuses the same hidden materialization file and container attachment. It does not create another search JSON file.

Billing, authorization, and failures

The original typed search is billed and metered normally. Staging its JSON explicitly reruns and meters that typed search once, based on the durable replay output. A retry after JSON creation reuses the same bytes and usage counts, preventing duplicate replay charges.

Before staging, GovTribe checks the current user, workspace, active Analyst response, OAuth tool scopes, typed-search registration, and the live authorization rules of the underlying search. User- and workspace-scoped searches keep their current live restrictions. Public searches can be replayed by an authorized caller who holds a valid ID.

Common failures include:

Failure	Next step
Invalid, expired, or historical `search_results_id` without replay details.	Run the typed search again and use the new ID.
Missing active Analyst response or shell context.	Start or resume an Analyst response that has hosted shell access, then retry.
Missing scope or lost data access.	Reconnect with the required typed-search scope or choose data the current user can access.
Materialization or attachment failure.	Read `failure_reasons`; do not expect polling to redispatch terminal failed work. Run a new typed search when the guidance requests a new ID.

Add to container MCP tool: Review the exact input contract and examples.
Add to container MCP response: Interpret polling, readiness, paths, and failures.
Search user files MCP tool: Resolve accessible workspace files.
Vector-store content retrieval: Choose semantic file retrieval instead of shell staging when appropriate.
Manage search context: Keep search arguments and identifiers consistent across multi-step analysis.