--- title: "How an agent finds an answer in your documents" description: "An agent answers document questions by choosing between semantic search and exact string match, so corpus shape determines which questions get usable answers." lang: en status: public-preview lastUpdated: 2026-09-04 url: https://duale.ai/en/docs/libraries/what-agents-can-do --- ## AI-generated summary Two questions arrive at the same documents: one by meaning, one by exact string. This page covers how each tool matches and how to read partial answers. - Find uses semantic search; Match uses exact string matching, case-insensitive by default. - A stopped-early answer means the search ran out of effort, not that no match exists. - Passages never cross page boundaries; consecutive passages on one page overlap to keep sentences whole. - Result order is the only signal; relevance numbers are not comparable across different questions. - OCR adds words to searchable text while pictures remain searchable independently of OCR. Summaries were generated by AI. Generative AI is experimental. --- Two questions arrive at the same documents. What does the contract say about termination? Where does invoice 4471 appear? The agent answers the first by meaning and the second by exact string, because it holds a separate tool for each. The shape of the corpus you upload therefore decides which questions come back with a usable answer. Your code calls none of these tools. The model calls them during a task, so what you control is the corpus you build and the Libraries each agent can reach. The rest of this page is corpus design. ## Choose the tool that answers the question Each tool matches something different, and the model chooses one for each call. | Tool | Your question | What it matches | Name you see in a trace | | --------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------- | | **Find** | What does the contract say about termination? | Meaning, in the text of your documents and in the pictures inside them. It does not guarantee a literal string match. | `file_search` | | **Match** | Where does invoice 4471 appear? | An exact string, wherever it sits in the text, case-insensitive by default. It is not a regular expression. | `file_grep` | | **List** | Which documents are in the Libraries I can reach? | Documents in every Library the agent can reach, in any state, filtered by part of a filename | `file_ls` | | **Read** | What do those lines say, word for word? | One document over a line range | `file_cat` | The last column holds the names you see in a task trace. They are not a versioned interface. Read them as current trace output, not as an API. The Find tool is semantic search: it orders passages by what they mean, and it is not a literal keyword search. An invoice number, an error code, or a part reference therefore goes to the Match tool, which matches the string literally. Meaning can also carry across languages. A query written in French can retrieve a passage written in English, and the reverse, so one set of documents can serve readers in several working languages without a translation pass. Retrieval across languages is not equally strong in every language, and Duale AI publishes no per-language figure. If a working language of yours is not among the widely used ones, test it on your own questions before you commit a set of documents to it. ```mermaid flowchart LR accTitle: What a question by meaning reads, and when to ask for an exact string instead accDescr { A question asked by meaning reads both the words in your documents and the pictures inside them, and returns one list of passages in order, best first. It does not perform a literal match. A question that names an exact string, such as an invoice number, goes to the literal match instead, which returns the places that string appears rather than an ordered list. } Query[A question asked by meaning] Words[The words in your documents] Pictures[The pictures inside them] Ordered[One list of passages, best first] Literal[An exact string: the places it appears] Query --> Words Query --> Pictures Words --> Ordered Pictures --> Ordered Query -.->|exact string instead| Literal ``` Two behaviors change how the model works through an answer: - The Match tool reports the first match inside each passage, not every occurrence. It answers where to look, and the Read tool then reads around one of those places. - The List tool lists documents in any state, including the ones the platform is still processing, and reports that state. A document that the Find tool does not return can still be on its way to `ready`. [Manage libraries](https://duale.ai/en/docs/sdk/manage-libraries.md) defines each status and shows how to wait. Each tool returns at most a fixed number of results for one call, and the Read tool reads one document for one call. [Limits](https://duale.ai/en/docs/libraries/limits.md) states each ceiling. Your own code passes none of them. ## Read an answer that stopped early A partial answer is a normal answer. A search and a literal match both report whether they finished, and the platform marks a result incomplete when it stopped before reading everything the agent can reach. So an empty result that reports it stopped means the search ran out of effort, not that your documents hold no match. Read that answer as one pass over part of everything the agent can reach. What an agent can read follows the identity that runs the task, not the documents that the task attached. [Agent harness](https://duale.ai/en/docs/agent-harness.md) states which agent holds which tool. One document search covers every Library the agent can reach, and the effort it is allowed belongs to the call rather than to each Library. A search across more Libraries is therefore more likely to stop before it has read everything. Two actions bring back a complete answer: - Narrow the question. A tighter question reaches its matches sooner. - Reduce the Libraries the agent can reach. [Design your Libraries](https://duale.ai/en/docs/libraries/design.md) covers how to split a corpus so that each agent reaches what its work needs and no more. ## What the platform reads, and what comes back The platform makes extracted text and pictures it can decode searchable. A document can reach `ready` with either kind of content. The platform uses optical character recognition (OCR) to read characters in pictures. The words OCR recovers join the searchable text, while the picture remains searchable as a picture. A picture with no readable OCR can therefore still answer a visual question. ```mermaid flowchart LR accTitle: What the platform reads from a document, and what a question gets back accDescr { You upload a document. The platform extracts its text, runs optical character recognition on its pictures, and keeps the pictures it can decode. It follows a document nested inside the source in the same way. Extracted text, words recovered from pictures, and decoded pictures become searchable. A question searches them together. A text result names its page. A matching picture reaches the model only when the tenant's model pool has an image-capable model that can carry it. } Doc[Your document] Nested[A document inside it] Text[Extracted text] Pictures[Pictures the platform can decode] OCR[Words OCR recovers] Searchable[Text and pictures searchable together] Question[A question from your agent] Answer[The page the text sat on] Images[The pictures that match] Doc --> Text Doc --> Pictures Doc --> Nested Nested --> Text Nested --> Pictures Pictures --> OCR Text --> Searchable OCR --> Searchable Pictures --> Searchable Question --> Searchable Searchable --> Answer Searchable --> Images ``` Four consequences follow: - **Nesting is followed.** A file inside an archive, or a PDF inside a word-processor document, is opened and read the same way as the document that carried it. - **A hit brings its place with it.** An answer names the page the text sat on, so an agent can read around it and quote it. - **OCR and picture search are separate.** OCR can add words to the searchable text. A picture remains searchable when OCR recovers no readable words. - **The model must accept a matching picture.** The tenant's model pool needs an image-capable model whose limits admit the image before the picture itself reaches the answer. [Attach documents](https://duale.ai/en/docs/sdk/attachments.md) covers setup, limits, and the result when no configured model can carry it. Extraction is best effort rather than a fidelity guarantee, especially when meaning is visual. When a document has to be exactly right, [extract it yourself and upload the text](https://duale.ai/en/docs/libraries/patterns.md). ## How a page becomes passages A passage never crosses a page boundary. Keeping one logical record on one page therefore prevents a page break from dividing it, but a long page can still produce several passages. For extracted text, the platform preserves page boundaries and splits each page into passages. Consecutive passages inside one page overlap, so a sentence that lands on a boundary stays whole in one of them. A page with no readable text produces no text passage. If the page contains a picture the platform can decode, that picture remains searchable and the document can still reach `ready`. An extraction failure means the platform produced neither searchable text nor a searchable picture, or extraction stopped with the cause that the error details name. Read the status after each upload. One consequence to design for: a table that breaks across a page becomes two passages that do not share context. Keep one logical record on one page where the source lets you. [Best practices](https://duale.ai/en/docs/libraries/best-practices.md) covers the other source habits that make a document index well, and [Manage libraries](https://duale.ai/en/docs/sdk/manage-libraries.md) covers the upload and the states a document moves through. ## Use the order of the results Order carries the signal. Any relevance number beside it does not. Results come back best first, and that order is the whole of what the platform is telling you. A relevance number attached to a result is not a similarity and not a probability, and two different questions do not produce comparable numbers. So a threshold carried over from another retrieval system does not transfer reliably. Take the first few results in the order they arrive and let the model read them. ## Troubleshoot a missing answer Start from the symptom the agent or Dashboard shows. After each change, ask the same question through the same agent. Recovery means the expected string or passage appears and the answer no longer reports that it stopped early. | Symptom | Likely cause | Next action | | ------------------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | An exact invoice number, error code, or part reference is missing | The agent searched by meaning, which does not guarantee a literal match. | Ask for the exact string so that the agent can use Match, then Read around it. | | List reports `queued` or `processing` | The document is not searchable yet. | Wait for `ready`; do not upload a second copy. [Manage libraries](https://duale.ai/en/docs/sdk/manage-libraries.md#document-states) defines each state. | | The preview of a `ready` document contains only protection metadata | A password or rights label protected the source. | Remove the protection, upload again, and confirm that the preview now contains the source text. [Errors and reliability](https://duale.ai/en/docs/sdk/errors.md#troubleshoot) owns that failure path. | | The preview of a `ready` scan or figure contains no useful text | OCR recovered no readable words. The picture can still be searchable. | Ask a question that only the picture answers, through an agent whose model pool can carry it. If exact words matter, [upload checked text](https://duale.ai/en/docs/libraries/patterns.md#extract-a-critical-document-yourself-then-upload-the-text). | | The preview of a `ready` document differs from the source | Best-effort extraction lost or changed content. | [Report the extraction problem](https://duale.ai/en/docs/libraries/patterns.md#report-a-document-that-extracts-badly), or upload checked text while support investigates. | | The answer reports that it stopped early | One call did not read everything the agent can reach. | Narrow the question or reduce the Libraries the agent can reach, then repeat the question. | | An answer loses context at a page boundary | One logical record became two passages. | Keep the record on one page where the source format permits, then upload the revised document. | ## Plan the corpus for the questions you expect Decide the shape of the corpus before you upload it. Each need below has a pattern that fits these four tools. | What you need | The pattern that serves it | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | An exact reference, such as an invoice number | Keep the string in the document text. The Match tool matches it literally; the Find tool does not guarantee that match. | | A quotation a reader can trace | Keep the words needed to understand the quotation beside it, on the same page. | | An answer about a figure or a chart | Keep the caption on the page that holds the figure. A question by meaning reads the pictures as well as the words. | | A code or configuration corpus | Plan for both: the Match tool for a symbol or a setting name, the Find tool for the prose that explains it. | | An answer that does not stop early | Grant each agent the Libraries its work needs and no more. One call covers every Library the agent reaches. | How many Libraries to create, and which agent reaches each, is the decision that carries the rest. [Design your Libraries](https://duale.ai/en/docs/libraries/design.md) covers it. ## Related content - [Get better answers from a Library](https://duale.ai/en/docs/libraries/best-practices.md) - [The documents your agents can read](https://duale.ai/en/docs/libraries.md) - [How Web search works: delegated research and evidence](https://duale.ai/en/docs/web/how-web-search-works.md) - [Web search: delegated, source-led research for agent tasks](https://duale.ai/en/docs/web.md) - [Design your Libraries by reader group and agent reach](https://duale.ai/en/docs/libraries/design.md) - [Troubleshoot Web search when results are missing or blocked](https://duale.ai/en/docs/web/troubleshooting.md) --- ## Sitemap See the full [Markdown sitemap](https://duale.ai/sitemap.md) for all pages.