box_ai_extract_freeform_tool
Extract structured data from Box files using AI by providing a freeform prompt, enabling precise information retrieval from documents in a JSON format.
Instructions
Extract data from files in Box using AI with a freeform prompt. Args: ctx (Context): The context object containing the request and lifespan context. file_ids (List[str]): The IDs of the files to read. prompt (str): The freeform prompt to guide the AI extraction. ai_agent_id (Optional[str]): The ID of the AI agent to use for processing. Returns: dict: The extracted data in a json string format.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ai_agent_id | No | ||
| file_ids | Yes | ||
| prompt | Yes |
Implementation Reference
- src/tools/box_tools_ai.py:82-121 (handler)The MCP tool handler function 'box_ai_extract_freeform_tool' that executes the core logic: retrieves Box client from context and delegates to the underlying 'box_ai_extract_freeform' function from box_ai_agents_toolkit.async def box_ai_extract_freeform_tool( ctx: Context, file_ids: List[str], prompt: str, ai_agent_id: Optional[str] = None, ) -> dict: """ Extract or analyze information from one or more files using a natural language prompt and return a SINGLE response. This tool provides maximum flexibility for data extraction and analysis. Instead of defining structured fields, you simply ask Box AI a question or give it instructions in natural language. When multiple files are provided, Box AI analyzes ALL files together to provide ONE comprehensive answer. This is the most flexible extraction tool but provides unstructured results. Use structured extraction tools (template-based or field-based) when you need consistent, machine-readable output. Use cases: - Single file analysis: "What are the key terms of this contract?" - Multiple files analysis: "Compare the pricing across these three proposals and summarize differences" - Complex questions: "Based on these financial documents, what are the main risk factors?" - Summarization: "Provide a 3-paragraph summary of the main points across these meeting notes" NOT for batch processing: If you need to ask the same question about multiple files separately (e.g., "summarize each report individually"), call this tool once per file in a loop. Args: ctx (Context): The context object containing the request and lifespan context. file_ids (List[str]): A list of file IDs to extract information from, example: ["1234567890", "0987654321"]. prompt (str): The fields to extract. ai_agent_id (Optional[str]): The ID of the AI agent to use for the extraction. If None, the default AI agent will be used. Returns: dict: The AI response containing the extracted information. """ box_client = get_box_client(ctx) response = box_ai_extract_freeform( box_client, file_ids, prompt=prompt, ai_agent_id=ai_agent_id ) return response
- src/tool_registry/ai_tools.py:22-22 (registration)Registration of the 'box_ai_extract_freeform_tool' using the mcp.tool() decorator within the register_ai_tools function.mcp.tool()(box_ai_extract_freeform_tool)
- src/tools/box_tools_ai.py:88-115 (schema)Input/output schema defined in the function docstring, used by MCP to generate tool schema including parameters (ctx, file_ids: List[str], prompt: str, ai_agent_id: Optional[str]) and description.""" Extract or analyze information from one or more files using a natural language prompt and return a SINGLE response. This tool provides maximum flexibility for data extraction and analysis. Instead of defining structured fields, you simply ask Box AI a question or give it instructions in natural language. When multiple files are provided, Box AI analyzes ALL files together to provide ONE comprehensive answer. This is the most flexible extraction tool but provides unstructured results. Use structured extraction tools (template-based or field-based) when you need consistent, machine-readable output. Use cases: - Single file analysis: "What are the key terms of this contract?" - Multiple files analysis: "Compare the pricing across these three proposals and summarize differences" - Complex questions: "Based on these financial documents, what are the main risk factors?" - Summarization: "Provide a 3-paragraph summary of the main points across these meeting notes" NOT for batch processing: If you need to ask the same question about multiple files separately (e.g., "summarize each report individually"), call this tool once per file in a loop. Args: ctx (Context): The context object containing the request and lifespan context. file_ids (List[str]): A list of file IDs to extract information from, example: ["1234567890", "0987654321"]. prompt (str): The fields to extract. ai_agent_id (Optional[str]): The ID of the AI agent to use for the extraction. If None, the default AI agent will be used. Returns: dict: The AI response containing the extracted information. """