Box Metadata Extraction

Box Metadata Extraction — Template-Driven (Box MCP)

Purpose

Extract structured metadata from documents stored in a Box folder and write it back using a specified Box metadata template.

This skill is designed to be reusable across document types by taking a template_key as input and using Box AI + Box metadata tools to populate metadata instances on each file.

When to Use

Use this skill when you want to:

• Populate Box metadata for all files in a folder
• Reuse one workflow across many document types
• Drive extraction from an existing Box metadata template (by key or name)

Example prompts:

• “Use the box-metadata-extraction skill on the Box folder with ID using metadata template key identifications.”
• “Use the box-metadata-extraction skill on this Box folder shared link using metadata template name identifications.”

Inputs

Required

Provide ONE of:

• folder_id (string), OR
• folder_shared_link_url (string)

And ONE of:

• template_key (string), OR
• template_name (string)

Optional

• dry_run (boolean, default: false)
  If true, do not write metadata back to Box. Only report what would be written.

• limit (number)
  Maximum number of files to process (useful for demos).

• use_enhanced_extraction (boolean, default: false)
  If true, prefer enhanced Box AI extraction for harder scans.

Guardrails (Hard Rules)

• Documents are stored only in Box. Do not rely on local document files.
• Do not recurse into subfolders (top-level files only).
• Do not overwrite existing metadata values: fill empty fields only.
• Avoid downloading and saving files locally (do not call file download with saving enabled).

Tooling (What to Use)

Use these Box MCP tools as needed:

Resolve folder and list files

• box_shared_link_folder_find_by_shared_link_url_tool (if using a folder shared link)
• box_folder_items_list_tool (list top-level items; keep is_recursive=false)

Read file content (only if needed for fallback)

• Prefer box_file_text_extract_tool to extract readable text/markdown from a file

Load template schema (optional but recommended)

• box_metadata_template_get_by_key_tool (preferred)
• box_metadata_template_get_by_name_tool (fallback)

Extract structured data

• box_ai_extract_structured_using_template_tool (preferred)
• box_ai_extract_structured_enhanced_using_template_tool (if use_enhanced_extraction=true)

Read/write metadata instances

• box_metadata_get_instance_on_file_tool
• box_metadata_set_instance_on_file_tool (if no instance exists)
• box_metadata_update_instance_on_file_tool (update only empty fields)

Workflow

Step 1 — Resolve the target folder

If folder_id is provided:

• Use it directly.

If folder_shared_link_url is provided:

• Resolve the folder using box_shared_link_folder_find_by_shared_link_url_tool.
• Use the returned folder id.

Step 2 — List top-level files

• Call box_folder_items_list_tool(folder_id, is_recursive=false).
• Filter results to files only.
• If limit is provided, process only the first N files.

Step 3 — Resolve template key (if only name provided)

• If template_key is provided, use it.
• Else look up the template using box_metadata_template_get_by_name_tool(template_name) and extract its key.

(Optionally) fetch template definition using box_metadata_template_get_by_key_tool to learn field names/types for normalization.

Step 4 — For each file, check existing metadata

• Call box_metadata_get_instance_on_file_tool(file_id, template_key).
• Determine which template fields are already populated.
• Only attempt to fill missing/empty fields.

Step 5 — Extract structured data for this file

Preferred path:

• Call Box AI template extraction for this file:
  • box_ai_extract_structured_using_template_tool(file_ids=[file_id], template_key=template_key)
  • If use_enhanced_extraction=true, use the enhanced variant.

Fallback path (only if template extraction fails or returns empty):

• Use box_file_text_extract_tool(file_id) to retrieve text.
• Then extract only template-defined fields.

Step 6 — Normalize and filter extracted values

• Normalize dates to YYYY-MM-DD when possible.
• Trim whitespace.
• Preserve casing for names and proper nouns.

Important:

• If a value does not exist in the document, do not write anything for that field.
• Do not invent, infer, or synthesize values.
• Only include fields with non-empty values that are clearly supported by the document content.

Step 7 — Write metadata back (unless dry_run)

• Build metadata_values using only fields that:
  1. were extracted with a real, non-empty value, AND
  2. are currently empty on the file.

If no metadata instance exists:

• Use box_metadata_set_instance_on_file_tool(file_id, template_key, metadata_values)

If an instance exists:

• Use box_metadata_update_instance_on_file_tool(file_id, template_key, metadata_values)

Never overwrite existing non-empty fields.

Step 8 — Output summary

Return a summary table showing:

• file name
• file id
• template_key
• fields written (with full values)
• fields skipped (already present or not found)

Do not redact values in the summary output.

Failure Handling

• If one file fails, continue with the remaining files and report the error.
• If the template cannot be resolved, stop and explain what is required.
• If extraction yields no values for a file, report “no data extracted” and continue.

Expected Output

• Full metadata values written to Box for extracted fields
• Clear visibility of extracted values in both chat output and Box UI
• No local document files required