IBM Content Assistant – Query Best Practices
Introduction
IBM® Content Assistant provides natural language insights about business content in your IBM FileNet® Content Manager repository. The Content Assistant includes generative AI capabilities that can provide accurate answers to questions within the context of selected business content, helps you to quickly find information across large volumes of content and saves time by avoiding manual, repetitive review of document content. These capabilities are based on Large Language Models (LLMs) that are coupled with context-specific Retrieval-Augmented Generation (RAG). The RAG augments the LLM with context-specific knowledge base and information that is hosted in the IBM FileNet Content Manager repository.
IBM Content Assistant leverages Retrieval-Augmented Generation (RAG) to provide accurate, context-aware responses from your FileNet Content Manager repository. The quality of your queries directly impacts the accuracy and relevance of responses.
This Technical Guide helps you craft effective queries by:
- Understanding what makes a query specific and actionable
- Avoiding common pitfalls that lead to vague or incorrect responses
- Learning from real-world examples across different use cases
Target Audience
Content managers, business analysts, developers, and end-users working with IBM Content Assistant.
Sample Queries
The most common mistake in RAG queries is vagueness. LLMs will fill in ambiguity with assumptions — and those assumptions often don't match intent. Specify audience, desired length, scope, tone, and any constraints upfront.
The following sections are some examples of good queries and why they work. Also listed are examples of poor queries and why they don’t work.
Factual Information Queries
|
Good Queries
|
Comments
|
|
What is the deductible amount for water damage coverage in policy number 12345-ABC?
|
Specific policy number, specific coverage type, specific data point requested.
|
|
What are the exclusions listed in John Smith's home insurance contract dated January 15, 2024?
|
Named entity, document type, specific date, clear information type.
|
|
What are the system requirements for installing IBM FileNet Content Manager version 5.7.0?
|
Specific product, specific version, clear technical requirement.
|
|
List all the configuration parameters for the Gen AI connector in the deployment YAML file.
|
Specific component, specific file type, actionable request.
|
|
What is the notice period required for contract termination according to clause 8.3?
|
Specific clause reference, specific legal requirement.
|
|
Poor Queries
|
Comments
|
|
Tell me about Focus Insurance Company’s insurance policies.
|
- Too broad - "insurance policies" covers many of topics (auto, home, life, health, etc.)
- No specific information goal - could mean definitions, coverage types, pricing, claims,
|
|
What does the contract say?
|
- No contract identifier - could be any of hundreds of contracts in the system
- No specific clause or topic - contracts contain dozens of sections
|
|
How do I install the FileNet software?
|
- No version specified - installation steps vary significantly between versions
- No environment context - Windows? Linux? Cloud? On-premises?
- No installation aspect - initial setup? upgrade?
|
Analytical/Comparison Queries
|
Good Queries
|
Comments
|
|
Compare the coverage limits for fire damage between policy A-2024-001 and policy A-2024-002.
|
Specific policies, specific coverage type, clear comparison request.
|
|
What are the differences in premium amounts between the basic and premium plans in the 2024 rate sheet?
|
Specific plans, specific document, specific comparison point.
|
|
What are the differences between the authentication methods described in sections 3.2 and 4.1 of the security guide?
|
Specific sections, specific document type, clear comparison.
|
|
Compare the performance benchmarks for Llama 4 and Granite 4 models in the evaluation report.
|
Specific models, specific document, measurable comparison.
|
|
How does the Q4 2024 revenue compare to Q3 2024 revenue according to the financial statements?
|
Specific time periods, specific metric, specific document type.
|
|
|
|
|
Poor Queries
|
Comments
|
|
Which option is better?
|
- No comparison subjects identified - better than what?
- No evaluation criteria - better in what way? (cost, coverage, performance?)
- No context - which documents or items are being compared?
|
|
Compare the documents.
|
- No comparison dimensions - compare what aspects? (content, dates, values, terms?)
|
Calculation/Quantitative Queries
|
Good Queries
|
Comments
|
|
Calculate the total claim amount for incident #2024-567 including the base damage ($15,000) and the deductible ($500) as stated in the claim document.
|
Specific incident, all values provided, clear calculation request.
|
|
What is the monthly premium for a 35-year-old male with the standard health plan according to the 2024 rate table?
|
Specific parameters, specific document, calculable result.
|
|
What is the total project cost breakdown shown in the budget document for Project Phoenix?
|
Specific project, specific document, specific financial data.
|
|
Calculate the year-over-year growth rate using the revenue figures from the 2023 and 2024 annual reports.
|
Specific time periods, specific documents, specific calculation.
|
|
Poor Queries
|
Comments
|
|
How much premium will I pay?
|
- No policy or product specified - premium for what?
- No personal details - age, location, coverage level all affect pricing
- No time period - monthly? annually? one-time?
|
|
Calculate the total cost.
|
- No values specified - total cost of what?
- No calculation type - sum? average? weighted total?
- No context - total for what purpose? (claim, premium, cost, revenue?)
|
Process/Procedural Queries
|
Good Queries
|
Comments
|
|
What are the steps to file a claim for vehicle theft according to the Focus Insurance Company’s claims processing guide?
|
Specific claim type, specific document, clear process request.
|
|
What documents are required to process a life insurance payout as listed in section 5 of the Focus Insurance Company policy?
|
Specific section, specific process, specific document type.
|
|
What are the deployment steps for the GenAI connector on OpenShift as described in the Content Assistant installation guide?
|
Specific component, specific platform, specific document.
|
|
List the troubleshooting steps for connection timeout errors in the technical support document.
|
Specific error type, specific document, actionable steps.
|
|
What is the approval workflow for expense reports over $5,000 according to the employee handbook?
|
Specific threshold, specific process, specific document.
|
|
|
|
|
Poor Queries
|
Comments
|
|
Explain the claim process.
|
- No process identified - which of potentially many claims processes?
- No detail level - high-level overview or step-by-step instructions?
|
|
What are the install steps?
|
- Steps for what task or process?
- No starting point or prerequisites mentioned
|
Conditional/Scenario-Based Queries
|
Good Queries
|
Comments
|
|
Is water damage from a burst pipe covered under policy #ABC-2024-789 if the incident occurred during a vacation?
|
Specific policy, specific scenario, specific coverage question.
|
|
According to the contract, what happens if the premium payment is 15 days late?
|
Specific scenario, specific timeframe, specific document.
|
|
What are the penalties for breach of confidentiality clause 12.4 if the breach is unintentional?
|
Specific clause, specific scenario, specific consequence.
|
|
What is the system behavior when the database connection fails during document indexing, as described in the error handling section?
|
Specific failure scenario, specific process, specific documentation section.
|
|
Poor Queries
|
Comments
|
|
What if something goes wrong?
|
- "Something" is completely non-specific
- No system or process identified - wrong with what?
- No severity or type of failure specified
|
|
Can I do this step?
|
- "This" has no referent - do what step?
- No policy or rule context - according to which document or regulation?
- No conditions specified - under what circumstances?
- No role or authorization context - who is "I"?
|
Multi-Document Synthesis Queries
|
Good Queries
|
Comments
|
|
Based on the client profile, policy contract, and claim report, is this claim eligible for full reimbursement?
|
Multiple specific documents, clear synthesis request, specific outcome.
|
|
What is the complete timeline of events from the police report, witness statement, and claim form for incident #2024-123?
|
Multiple documents, specific incident, clear synthesis goal.
|
|
Summarize the key risks identified across the Q1, Q2, and Q3 2024 risk assessment reports.
|
Multiple specific documents, clear synthesis request, specific focus.
|
|
What are the common configuration requirements mentioned in both the installation guide and the security best practices document?
|
Two specific documents, clear intersection request.
|
|
|
|
|
Poor Queries
|
Comments
|
|
What do all the documents say?
|
- "All documents" is very broad
- No topic focus - say about what subject?
- No synthesis goal - what insight or conclusion is needed?
|
|
Summarize everything.
|
- "Everything" has no boundaries
- No topic or theme to synthesize around
- No output length or format specified
- No priority or importance criteria
|
Temporal/Historical Queries
|
Good Queries
|
Comments
|
|
What changes were made to the coverage terms between the 2023 and 2024 versions of policy ABC-Standard?
|
Specific versions, specific policy, clear temporal comparison.
|
|
List all claims filed by client ID 12345 between January 1, 2024 and March 31, 2024.
|
Specific client, specific date range, specific data type.
|
|
How has the pricing structure evolved from Q1 to Q4 2024 according to the quarterly pricing updates?
|
Specific time period, specific document series, clear evolution request.
|
|
What features were added in version 2.0.0 compared to version 1.5.0 according to the release notes?
|
Specific versions, specific document type, clear comparison.
|
|
Poor Queries
|
Comments
|
|
What changed?
|
- No subject specified - what entity or document changed?
- No timeframe - changed between when and when?
- No aspect defined - changed in what way? (terms, pricing, coverage?)
- No document versions identified
|
|
Show me the history.
|
- No subject - history of what? (policy, claim, account, product?)
- No timeframe - how far back? which period?
- No document type - history from what records?
- No event type - history of what kind of changes or events?
|
Verification/Validation Queries
|
Good Queries
|
Comments
|
|
Verify if client John Doe (ID: 45678) has active coverage for earthquake damage as of April 1, 2024.
|
Specific client, specific coverage, specific date, clear verification.
|
|
Is the claim amount of $25,000 within the policy limit for property damage in contract #XYZ-2024?
|
Specific amount, specific coverage, specific policy, clear validation.
|
|
Does the current data retention policy comply with the GDPR requirements outlined in the compliance checklist?
|
Specific policy, specific regulation, specific document.
|
|
Confirm whether the server configuration in the deployment file meets the minimum requirements specified in the system requirements document.
|
Specific configuration, specific requirements, clear verification.
|
|
|
|
|
Poor Queries
|
Comments
|
|
Is this correct?
|
- "This" is undefined - what information or value is being verified?
- No reference standard - correct according to what document or rule?
- No verification criteria - correct in what way?
- Assumes visual or prior context that RAG doesn't have
|
|
Check if it's valid.
|
- "It" has no referent - validate what item or value?
- No validation criteria specified - valid according to what rules?
- No document reference - which policy or specification to check against?
- No validation type - format? range? compliance? authorization?
|
Extraction/List Queries
|
Good Queries
|
Comments
|
|
List all the exclusions mentioned in the home insurance policy section 4.2.
|
Specific section, specific policy type, specific data type.
|
|
Extract all the contact information for claims adjusters from the claims processing guide.
|
Specific data type, specific document, clear extraction request.
|
|
List all the environment variables required for the GenAI connector deployment from the configuration guide.
|
Specific data type, specific component, specific document.
|
|
Extract all error codes and their descriptions from the troubleshooting section of the user manual.
|
Specific data types, specific section, clear extraction.
|
|
List all action items assigned to the engineering team in the Q4 2024 board meeting minutes.
|
Specific data type, specific team, specific document.
|
|
Poor Queries
|
Comments
|
|
Give me the list of variables.
|
- No document reference - list from which source?
- No criteria or filter - all items or specific subset?
- No context - list for what purpose?
|
|
Show me the action items.
|
- No document or section reference
- No selection criteria - which items? all items?
- Assumes context that RAG doesn't have
|
Summarization Queries
|
Good Queries
|
Comments
|
|
Summarize the key coverage points and exclusions in the comprehensive auto insurance policy #CAR-2024-567.
|
Specific policy, specific aspects to summarize, clear scope.
|
|
Provide a brief summary of the claim resolution for incident #2024-890, including the outcome and payment amount.
|
Specific incident, specific summary elements, clear scope.
|
|
Summarize the main findings and recommendations from the 2024 annual security audit report.
|
Specific document, specific summary elements, clear focus.
|
|
Summarize the breaking changes introduced in version 3.0.0 according to the migration guide.
|
Specific version, specific document, specific focus.
|
|
Summarize the key decisions and action items from the April 15, 2024 project status meeting.
|
Specific meeting, specific date, specific summary elements.
|
|
|
|
|
Poor Queries
|
Comments
|
|
Summarize this document.
|
- No summary focus - summarize what aspects?
- No length constraint - brief or detailed summary?
|
|
Give me the main points.
|
- No document specified - main points from what?
- No topic focus - main points about what subject?
- "Main" is subjective without criteria - main for what purpose?
- No output format specified
|
Query Optimization Tips
· Be Specific
- Include document names, IDs, dates, or section numbers
- Specify exact data points or metrics needed
- Name entities (people, products, policies) explicitly
Provide Context
- Reference specific documents or document types
- Include relevant dates or time periods
- Specify the domain or subject area
· Use Structured Language
- Start with action verbs (List, Compare, Calculate, Summarize, Extract)
- Use clear, unambiguous terminology
- Break complex queries into specific sub-questions
· Include Constraints
- Specify date ranges when relevant
- Include thresholds or limits
- Define scope boundaries
Reference Source Material
- Cite section numbers or clause references
- Mention document versions
- Specify document types (contract, policy, guide, report)
Query Patterns by Industry
· Insurance
- "What is the [coverage type] limit in policy [policy_number]?"
- "Is [specific scenario] covered under [policy_type] according to [document]?"
- "Calculate the [claim amount/premium] for [specific case] using [rate table/policy]."
- "List all exclusions for [coverage type] in [policy document]."
· Financial Services
- "What is the [metric] for [time period] according to [financial document]?"
- "Compare [metric A] and [metric B] between [period 1] and [period 2]."
- "Calculate [financial calculation] using values from [document]."
- "What are the risk factors mentioned in [risk assessment document]?"
· Legal/Compliance
- "What does clause [number] state about [specific topic]?"
- "What are the penalties for [specific violation] according to [contract/policy]?"
- "List all obligations under section [number] of [agreement]."
- "What is the notice period for [action] in [contract]?"
· Technical Documentation
- "What are the system requirements for [product] version [version]?"
- "List the configuration steps for [component] in [environment]."
- "What is the troubleshooting procedure for [error type]?"
- "Compare features between version [X] and version [Y]."
· Healthcare
- "What is the treatment protocol for [condition] according to [clinical guideline]?"
- "List all contraindications for [medication] in [drug reference]."
- "What are the dosage instructions for [patient type] in [prescription guide]?"
- "Summarize the patient history for [patient ID] from [date range]."
Content Assistant Queries
There are three types of queries supported in Content Assistant as described in this section.
Single document queries
As of February 2026, there are two modes available for single document query
- RAG mode: a vector search is first performed to find the top 8 chunks of the document. Then only those 8 chunks are sent to the LLM to process the question.
- In this mode, document citations are provided, referencing the document excerpts that were provided to the LLM, and were deemed most relevant to the question. Requests that ask for answers based on specific values present in the document will work.
- Only document chunks which are relevant to the users question will be used.
- Limitation: Requests like “What is the main point of the document” or “Please summarize the document” may work for small documents, but they will fail for larger documents. Content Assistant will search for document chunks most closely matching “Please summarize the document” and will likely not find any, causing a “No relevant documents error”. Even if it does find some, they will likely fail.
- In this mode, precise queries are very important, to make sure that the portions of the document which contain the answer are sent to the LLM
- Send entire document mode: this is now the default mode. In this mode, the entire document will be sent to the LLM, without performing a vector search. This will normally result in better results.
- In this mode, you can sometimes get away with more vague questions
- You can also ask general questions like “What is the main point of the document” or “Please summarize the document”
- Limitation: In Send entire document mode, no document citations are provided, because the entire document is sent
- Limitation: In this mode, no checks for document relevancy to the question are performed
- Limitation: Note however, that if the size of the extracted text of the document exceeds 400,000 characters, then Content Assistant will revert to RAG mode, and the limitations from the RAG mode section will apply
Multiple document queries
Currently multiple document queries always use RAG mode, as described in the previous section, with the same benefits and limitations.
Starting in June 2026, Content Assistant will offer three query modes for Multiple document query via the Content Navigator plugin:
|
Mode
|
Proposed Name for ICN
(Admin tool + Plug-In)
|
Proposed Description for Admin Experience
|
Proposed Description for User Experience
(upon clicking information icon in plug-in)
|
|
RAG mode
|
Precision Mode
|
Leverages a simple RAG query: top document excerpts are retrieved from vector database and passed to an LLM. Will always return document excerpts.
|
Use this when you need to pinpoint specific information hidden in many documents.
Finds the most relevant sections only in your selected documents.
|
|
Adaptive full text mode
|
Full Context Mode (default)
|
Sends the full text of documents selected to the LLM. If the selection exceeds the context window of LLM, this mode will default to Precision mode. Will not return document excerpts if documents fit in the context window.
|
Use this when you want to query across a small document selection.
Uses full documents when they fit, or auto switches to Precision mode if they don't.
|
|
Adaptive RAG mode
|
Extended Precision Mode
|
Finds the relevant excerpts related to the query, retrieves the documents from which the excerpts came from, and sends the full text of the documents to the LLM. If documents retrieved don't fit, the full text sent to the LLM could be truncated. Will always return document excerpts.
|
Use this when you are searching across many documents and need an answer that depends on broad context.
Finds relevant content and also includes source
document context, with citations.
|
Ask Your Repository queries
In Ask Your Repository, a RAG query is always performed to find the most relevant documents, querying all documents in the object store that have been vector indexed. Therefore:
- For these queries, precise questions are very important, to make sure that the correct documents are found and provided to the LLM
- Information that will narrow the search down to a handful of documents is necessary. If there are more than a few documents which have relevant information, then the chances that the right documents are found will drop considerably
- Document citations are provided, referencing the document excerpts that were provided to the LLM, and were deemed most relevant to the question. Requests that ask for answers based on specific values present in the document will work.
- Only document chunks which are relevant to the users question will be used. If no document chunks which pass relevancy score checking are found, then an error will be returned
- Limitation: Requests like “What is the main point of the document” or “Please summarize the document” will never work
Enhancement to Ask Your Repository: In a Q2 release of Content Assistant, the algorithm will be updated to send additional information. In addition to sending the most relevant document chunks to the LLM, the full text of the documents which those document chunks were found in will also be sent. While this may increase response times a bit it will generally result in better answers.
Document summaries
Summaries for documents in Content Assistant can be generated in the following three ways.
Auto generated summaries
These summaries are automatically generated for new documents when document summarization subscriptions are in place. These summaries are stored in the Watsonx Summary property of the document and can be viewed from the Properties pane in Navigator.
Limitations: These summaries are intentionally brief, and are not HTML formatted.
More information about these summaries is available here:
https://www.ibm.com/docs/en/content-assistant?topic=assistant-accessing-watsonx-summary-document
Ad hoc summary actions
These summaries are generated on the fly by using the “Please summarize this selected document” or “Please summarize these selected documents” actions using the Content Assistant widget in Content Navigator.
Limitations:
- These summaries are intentionally brief, and are not HTML formatted
- No opportunity to tailor the information contained in the summary
Refer to this documentation page for more information:
https://www.ibm.com/docs/en/content-assistant?topic=uca-accessing-watsonx-ad-hoc-summary-your-document-selection
Asking the assistant to summarize
Many users attempt to request a summary of one or more documents by selecting the documents, and then typing in the request to “Please summarize these documents”. This will work well in certain circumstances, but not in others:
Advantages
- Produces more structured HTML formatted output
- Can produce longer summaries
- Users can tailor the summary request to focus on certain elements
Limitations
- Does not work well when in RAG mode
o Note that the new “Full Context mode” and “Extended precision mode” options that will become available in June 2026 will help to address this limitation
- Does not work well when total size of all documents exceeds 400,000 characters
o Note that the “Extended precision mode” option that will become available in June 2026 will help to address this.
Compare Documents
The feature to compare two documents is available in the newer versions of FileNet Content Manager. The compare can be done be across two different documents or across two major versions of the same document.
Additional information about the compare feature is available here:
https://www.ibm.com/docs/en/content-assistant?topic=assistant-comparing-two-documents
https://www.ibm.com/docs/en/content-assistant?topic=assistant-comparing-two-versions-document
Note: Whenever possible, include additional instructions to have the comparison focus on the aspects that are most important