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.

Container creation recovery returns an MCP error (isError: true) with the same status fields in structuredContent, plus an error object. The optional error fields are:

A recovery error returns empty container identifiers and file lists, zero file counts, and hosted_tool_ready: false. Those empty values are not proof that the provider created no container or that the requested files do not exist.

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.

For image calls, polling waits for generation/persistence or container attachment without generating another image. Image-only pending requests leave the container uncreated. Missing, deleted, cross-workspace, or inaccessible image references are rejected before container work. Repeating a terminal failed call does not restart it.

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 files alongside failed search JSON or image calls. After container replacement, repeat the same staging request and use its newly resolved path.

This attachment snapshot does not report whether prior working files were restored from a checkpoint. In GovTribe AI Analyst conversations, use the native Create_Container tool to inspect manifests, explicitly select files to restore, and check verified per-file outcomes in files. Follow Resume after container replacement before resuming work on earlier files.

Container recovery errors

For container_unavailable, the snapshot has status: failed and a next_actions entry directing the agent to Create_Container. Call Create_Container with action: "ensure", follow its request through status until ready, then repeat Add_To_Container with the same inputs. An expired container does not automatically trigger replacement or restoration.

For container_recovery_pending, GovTribe is reconciling an interrupted creation request. The snapshot has status: in_progress, retry_with_same_arguments: true, and error.retryable: true. Wait for error.retry_after_seconds, then call Add_To_Container again with identical arguments. This reconciliation does not restore historical checkpoint files.

For container_recovery_failed or container_creation_rejected, the snapshot has status: failed, retry_with_same_arguments: false, and error.retryable: false; error.retry_after_seconds is absent. Stop polling and show the returned message and failure_reasons. Repeating the terminal operation does not restart creation. Starting a new conversation is a user decision.

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",
      "govtribe_id": "USER_FILE_ID",
      "govtribe_type": "user_file",
      "mime_type": "application/pdf",
      "image_generation_call_id": null,
      "width": null,
      "height": null,
      "checksum": null,
      "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",
      "govtribe_id": "USER_FILE_ID",
      "govtribe_type": "user_file",
      "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "image_generation_call_id": null,
      "width": null,
      "height": null,
      "checksum": null,
      "oai_file_id": "file_...",
      "container_file_id": "cfile_requirements_workbook",
      "path_hint": "/mnt/data/requirements.xlsx",
      "sandbox_uri_hint": "sandbox:/mnt/data/requirements.xlsx"
    }
  ]
}