Add to container MCP response

Returned by: Add to container MCP tool
Response type: Structured status snapshot

Response Shape

The tool returns a text message plus the same status details as structured content.

Field	Type	Notes
`status`	string	Operation status. Values are `in_progress`, `completed`, or `failed`.
`message`	string	Human-readable status message for the current snapshot.
`container_id`	string	GovTribe container owner identifier for the operation.
`oai_container_id`	string	Hosted OpenAI container identifier when one exists.
`requested_file_count`	integer	Number of files requested for the container operation.
`completed_file_count`	integer	Number of requested files already attached.
`pending_file_count`	integer	Number of requested files still being attached.
`failed_file_count`	integer	Number of requested files that failed attachment.
`completed_file_names`	string array	File names already available in the hosted container.
`pending_file_names`	string array	File names still being uploaded or attached.
`failed_file_names`	string array	File names that failed attachment.
`skipped_file_names`	string array	File names skipped by the tool before upload.
`hosted_tool_ready`	boolean	Whether the hosted `shell` tool can use the completed files now.
`retry_with_same_arguments`	boolean	Whether the agent should call the same tool again later with identical arguments.
`next_actions`	object array	Structured guidance for the next MCP call or hosted shell workflow step. Each item includes `action`, `tool`, and `reason`.
`failure_reasons`	object array	Detectable failure or skipped-file reasons with `code`, `message`, and `retry_hint`. Empty when no repair guidance is needed.
`container_files`	object array	Completed file references for hosted shell use. Each item includes `name` plus nullable `oai_file_id`, `container_file_id`, `path_hint`, and `sandbox_uri_hint` values.

Follow-up Behavior

When status is in_progress and retry_with_same_arguments is true, follow next_actions and call Add_To_Container again later with the same arguments to get a fresh status snapshot.

For a search-result request, the pending file is the hidden JSON materialization associated with the supplied search_results_id. Repeating the same request reuses that file and does not rerun completed or terminal failed work.

Do not use hosted shell files while status is in_progress or hosted_tool_ready is false.

When status is completed and hosted_tool_ready is true, follow next_actions and use the container_files values in hosted shell workflows. When available, use container_file_id as the most precise shell_file_identifier for Show_Document, with oai_file_id as a fallback. Use path_hint for shell commands and sandbox_uri_hint when a response needs a sandbox link.

When status is failed, inspect failure_reasons before retrying. The response can distinguish no supported files, unsupported file types, invalid or unauthorized search replay, search materialization failure, and upload or container attachment failure when that information is available. Mixed requests can contain completed ordinary files alongside a failed search JSON file.

Example

{
  "status": "completed",
  "message": "Container CONTAINER_ID has 2 requested supported file(s): 2 completed, 0 pending, 0 failed. Completed files: \"pricing-summary.pdf\", \"requirements.xlsx\". Requested files are ready for hosted shell access under /mnt/data.",
  "container_id": "CONTAINER_ID",
  "oai_container_id": "OAI_CONTAINER_ID",
  "requested_file_count": 2,
  "completed_file_count": 2,
  "pending_file_count": 0,
  "failed_file_count": 0,
  "completed_file_names": ["pricing-summary.pdf", "requirements.xlsx"],
  "pending_file_names": [],
  "failed_file_names": [],
  "skipped_file_names": [],
  "hosted_tool_ready": true,
  "retry_with_same_arguments": false,
  "next_actions": [
    {
      "action": "use_hosted_shell",
      "tool": null,
      "reason": "The requested files are ready for hosted shell access. Use container_files path_hint or sandbox_uri_hint values."
    }
  ],
  "failure_reasons": [],
  "container_files": [
    {
      "name": "pricing-summary.pdf",
      "oai_file_id": "file_...",
      "container_file_id": "cfile_pricing_summary",
      "path_hint": "/mnt/data/pricing-summary.pdf",
      "sandbox_uri_hint": "sandbox:/mnt/data/pricing-summary.pdf"
    },
    {
      "name": "requirements.xlsx",
      "oai_file_id": "file_...",
      "container_file_id": "cfile_requirements_workbook",
      "path_hint": "/mnt/data/requirements.xlsx",
      "sandbox_uri_hint": "sandbox:/mnt/data/requirements.xlsx"
    }
  ]
}

Response Shape

Follow-up Behavior

Example

On this page