ask_ai_about_documents

Query document content using natural language to find specific information, extract insights, or get direct answers about policies, processes, or other details from your knowledge base.

Instructions

    Queries document content using natural language questions.
    
    Use this tool when you need to:
    - Find specific information across multiple documents
    - Get direct answers to questions about document content
    - Extract insights from your knowledge base
    - Answer questions like "What is our vacation policy?" or "How do we

onboard new clients?"

    Args:
        question: The natural language question to ask
        collection_id: Optional collection to limit the search to
        document_id: Optional document to limit the search to
        
    Returns:
        AI-generated answer based on document content with sources

Input Schema

TableJSON Schema

Name	Required	Description	Default
`collection_id`	No
`document_id`	No
`question`	Yes

Implementation Reference

src/mcp_outline/features/documents/ai_tools.py:56-94 (handler)

The ask_ai_about_documents tool handler function, decorated with @mcp.tool. Implements the logic to query the Outline AI client with the question and optional collection_id/document_id, format the response, and handle errors.

@mcp.tool(
    annotations=ToolAnnotations(
        readOnlyHint=True, openWorldHint=True, idempotentHint=False
    )
)
async def ask_ai_about_documents(
    question: str,
    collection_id: Optional[str] = None,
    document_id: Optional[str] = None,
) -> str:
    """
    Queries document content using natural language questions.

    Use this tool when you need to:
    - Find specific information across multiple documents
    - Get direct answers to questions about document content
    - Extract insights from your knowledge base
    - Answer questions like "What is our vacation policy?"
    - Answer "How do we onboard new clients?" and similar queries

    Args:
        question: The natural language question to ask
        collection_id: Optional collection to limit the search to
        document_id: Optional document to limit the search to

    Returns:
        AI-generated answer based on document content with sources
    """
    try:
        client = await get_outline_client()
        response = await client.answer_question(
            question, collection_id, document_id
        )
        return _format_ai_answer(response)
    except OutlineClientError as e:
        return f"Error getting answer: {str(e)}"
    except Exception as e:
        return f"Unexpected error: {str(e)}"

src/mcp_outline/features/documents/ai_tools.py:48-55 (registration)
The register_tools function that registers AI document tools, including ask_ai_about_documents, to the MCP server.
```
def register_tools(mcp) -> None:
    """
    Register AI tools with the MCP server.

    Args:
        mcp: The FastMCP server instance
    """
```

src/mcp_outline/features/documents/ai_tools.py:17-46 (helper)

The _format_ai_answer helper function that formats the raw AI response into a readable markdown output with answer and source documents.

def _format_ai_answer(response: Dict[str, Any]) -> str:
    """Format AI answer into readable text."""
    # Check if the search field exists (indicates AI answer is available)
    if "search" not in response:
        return (
            "AI answering is not enabled for this workspace or "
            "no relevant information was found."
        )

    search = response.get("search", {})
    answer = search.get("answer", "")

    if not answer:
        return "No answer was found for your question."

    # Format the answer
    output = "# AI Answer\n\n"
    output += f"{answer}\n\n"

    # Add source documents
    documents = response.get("documents", [])
    if documents:
        output += "## Sources\n\n"
        for i, doc in enumerate(documents, 1):
            title = doc.get("title", "Untitled")
            doc_id = doc.get("id", "")
            output += f"{i}. {title} (ID: {doc_id})\n"

    return output

src/mcp_outline/features/documents/ai_tools.py:62-83 (schema)

The tool's input schema (parameters: question, collection_id, document_id) and documentation docstring.

    question: str,
    collection_id: Optional[str] = None,
    document_id: Optional[str] = None,
) -> str:
    """
    Queries document content using natural language questions.

    Use this tool when you need to:
    - Find specific information across multiple documents
    - Get direct answers to questions about document content
    - Extract insights from your knowledge base
    - Answer questions like "What is our vacation policy?"
    - Answer "How do we onboard new clients?" and similar queries

    Args:
        question: The natural language question to ask
        collection_id: Optional collection to limit the search to
        document_id: Optional document to limit the search to

    Returns:
        AI-generated answer based on document content with sources
    """

MCP Outline Server