Decide when an agent’s empty search result can support the next workflow step—and when missing pages, restricted access or approximate retrieval must keep the decision open.
An operations assistant checks whether a service request already exists. Its tool returns no matching rows, so it proposes creating a new request. That may be correct. It may also mean the assistant searched only the first page, the wrong date range or an index that cannot see the original record.
AI agent search completeness is a property of the evidence-gathering process, not the confidence of the final sentence. Before a negative finding advances work, establish what was searched, whether the method could find the target, and what prevented full coverage. Then apply the separate business authorization rule.
This guide gives workflow owners and implementation teams a decision matrix, a search-evidence receipt and acceptance tests. The controls below are recommended design practice. The service-request example is illustrative, not a customer deployment or a measured performance result.
Separate a match, a scoped absence and an unknown
Finding one verified record can establish that a match exists. Failing to find one requires a stronger explanation. “No record matched these exact identifiers in this authoritative register at this observation time” is narrower than “there is no duplicate anywhere.” Preserve that difference in both the answer and the workflow state.
| Evidence state | Permitted finding | Next step |
|---|---|---|
| Verified matching record; other results remain unread | A match exists; overall search remains partial | Open a duplicate-review case referencing that record. Do not claim the total number of duplicates. |
| Authoritative exact lookup or complete enumeration; relevant scope and matching rule verified; no match | No match within the declared register, identifiers and observation boundary | Pass the search gate only. Apply approval, freshness and duplicate-creation controls separately. |
| No match in a partial or interrupted traversal | No match in the inspected subset; remainder unknown | Continue within the approved read budget or hold for review. |
| Semantic top-k search returns nothing useful | No supporting match retrieved by this search method | Try an authorized exact lookup or route to an owner. Do not certify absence. |
| Required source unavailable, forbidden or outside known coverage | Required evidence is unavailable | Preserve the gap and assign an evidence-review task; do not broaden access automatically. |
A partial positive finding is not automatically a valid duplicate decision: the retrieved record still needs identity and status checks. Conversely, a complete transport response is not necessarily a complete business search. A perfectly valid JSON array can describe only the newest twenty requests.
Define the search boundary before the model runs
Write the decision as a testable question. For example: “Does the authoritative service-request register contain an active request for this account, external reference and service instance?” Specify how reopened, cancelled and merged records affect the answer. A loose similarity search for the requester’s wording answers a different question.
Assign responsibility explicitly
- AI: interpret the incoming description, suggest candidate references and explain verified evidence. Treat extracted identifiers as proposals until validated.
- Connector and rules: enforce identity scope, normalized filters, matching policy, traversal, result validation, read budgets and evidence-state calculation.
- Human owner: resolve ambiguous identity, missing sources and exceptions to the declared search boundary.
- Execution system: persist the decision and perform only the separately authorized create, link or close operation.
Permission to read a subset does not establish that the subset covers the business question. If the current principal cannot inspect archived requests and archives matter, record the missing coverage. Do not ask the agent to compensate by guessing or by seeking broader credentials.
The existing guide to AI tool calling explains tool schemas, permissions and action boundaries. This control sits inside that boundary: it determines what a particular search result can legitimately support.
Require a search-evidence receipt
Persist a bounded receipt outside the conversational summary. Its fields must come from the connector, source response and validation rules—not from the model’s assessment of whether it “looked everywhere.” Keep sensitive records in their approved store; the receipt can reference them by access-controlled identifiers.
| Field group | What to retain | Why it matters |
|---|---|---|
| Question and identity | Decision ID, authoritative source, principal/tenant scope, validated business identifiers | Prevents a result for another account or question from being reused. |
| Method and filters | Exact lookup, enumeration or approximate search; normalized query, date/status limits and matching-policy version | Shows whether an existing target would be eligible to appear. |
| Observation boundary | Read timestamps; documented snapshot/version guarantee if available; known source or indexing delay | Separates complete-at-observation from current-at-execution. |
| Traversal evidence | Pages read, terminal indicator, unique record IDs/count, reported total when available, truncation and source errors | Distinguishes a finished read from a bounded subset. |
| Verdict and ownership | Match, scoped no-match or unknown; missing coverage, stop reason, evidence references and reviewer | Makes the decision and unresolved work inspectable. |
Do not invent a total if the source does not provide one. Matching counts are a useful check when their semantics are known, but equal counts alone do not prove consistent coverage: records could change between pages. Record the source’s actual consistency behavior and limit the finding accordingly.
Use the source’s actual continuation contract
GitHub’s REST pagination documentation shows that a response can contain only part of a collection and that response links identify additional pages. A successful request therefore does not, by itself, establish traversal completion.
The June 2025 MCP pagination specification describes opaque cursors for listed operations such as tool and resource discovery. It does not automatically define pagination for the business records returned inside an arbitrary tool call. Specify that application-level contract separately; do not infer a universal page size or manufacture a cursor.
Consistency also needs an explicit guarantee. Kubernetes API documentation describes collection chunking with continuation and a consistent resource version, including continuation expiry. That is an example of documented snapshot behavior—not evidence that every cursor-based API gives the same guarantee.
Make incomplete evidence a real workflow state
Use an explicit path such as searching → match-review | scoped-no-match | evidence-hold. A rule may advance scoped-no-match to a separate authorization stage. The model must not turn evidence-hold into permission by producing a persuasive explanation.
- More pages available: continue with the returned token and unchanged scope while the approved read budget permits. An empty page with a continuation is not necessarily the end.
- Repeated token or duplicate-page loop: stop traversal, preserve the last confirmed evidence and assign connector investigation. Deduplicating rows is not proof that nothing was skipped.
- Expired continuation or changed source boundary: invalidate the incomplete traversal. Restart only under the source’s documented rules and an approved retry budget; never silently join two snapshots.
- Timeout, invalid response or missing metadata: record unknown. A read retry may be eligible under the connector policy, but a failed read is not a no-match result.
- Budget exhausted: retain the inspected subset and stop reason. Narrow the question only when the narrower scope still answers the business decision; otherwise route to review.
Preserve the decision ID, query definition, verified records and stop reason during recovery. Persist source tokens only as the particular API permits; some contracts prohibit reuse across sessions. After human review, record either new evidence and a fresh gate result or a separately authorized exception. A reviewer accepting risk does not retroactively make an incomplete search complete.
The context-budget guide covers selecting bounded model inputs. Keep the full authorized evidence outside the prompt and supply a compact receipt plus relevant records. A shorter summary must retain the unknown state, not summarize it away.
Test a duplicate-request decision end to end
Constructed example: a customer sends a second description of a maintenance visit. The AI extracts an account and reference, rules validate them, and the connector searches the active service-request register. Page one has no match; page two contains the existing request.
The correct outcome is match-review with the existing request’s ID, not creation after page one. If page two times out, the correct outcome is evidence-hold. If a complete exact search has no match, that finding passes only the search gate.
Before creation, the execution system must still apply its authorization policy and enforce duplicate protection at the write boundary. Two workers can both observe no match before either creates a record. Use a source-supported uniqueness constraint, atomic create-if-absent operation or another explicitly designed coordination mechanism. An idempotency key for one retried operation alone does not prevent two independently keyed operations from creating the same business request.
| Injected condition | Required result |
|---|---|
| The only exact match is on page two | Find it before issuing a no-match finding; retain its identity. |
| Empty first page still has a valid continuation | Continue or hold; do not declare absence. |
| Same continuation repeats | Evidence-hold with a loop reason; no endless read cycle. |
| Source total or snapshot boundary changes unexpectedly | Reject the assumed coverage guarantee and apply documented restart/review rules. |
| Required source returns a permission error or timeout | Unknown with source and owner recorded; no create-on-empty fallback. |
| Approximate search misses an exact known reference | No global absence claim; use the appropriate exact lookup or review. |
| Complete scoped lookup genuinely has no match | Scoped no-match; preserve the receipt and enter separate authorization. |
| Two authorized workers pass search simultaneously | Write-boundary duplicate control resolves the conflict; search receipts alone do not authorize two records. |
Evaluate the gate and the final user-facing wording. Track unsupported no-match claims among tested negative claims, known-target misses, evidence-hold outcomes, read attempts, time to resolution and duplicate creations. Retain unresolved cases in reporting; excluding held searches makes the process appear more reliable than it is.
Where Workhint fits
The Workhint Workflow Engine describes request and work steps, approval routing to defined roles, and required information before progression. Those building blocks are relevant to the operational handoff from a search-evidence receipt to a named reviewer.
The workflow automation software solution describes structured intake, conditional routing, human decisions, approval stages and tracking owners and next actions. Use that scope to discuss how an evidence-hold case should reach the right person and return with a recorded outcome.
The search connector, completeness validator and write-boundary uniqueness mechanism require their own implementation and testing. These product pages do not establish those specific guarantees. Bring the acceptance cases above into configuration review instead of assuming that an approval stage proves the underlying search was exhaustive.
Frequently asked questions
Does reading every page prove there is no match?
Only within a verified scope and matching method, subject to the source’s consistency and observation limits. Every page of an approximate or restricted search may still fail to cover the business question.
Can a high model confidence score override missing evidence?
No. Confidence is not proof that another page, inaccessible register or delayed index contains no matching record. Keep the evidence gap explicit and apply the declared review path.
Must every search finish before a positive finding is useful?
No. A verified record can support a scoped positive finding before traversal finishes. Do not turn that into an exhaustive count, a uniqueness claim or an authorized business action without the additional checks those conclusions require.
What should the assistant say when its read budget ends?
State that no match was found in the inspected subset, describe the remaining coverage and report the review owner or next permitted step. Do not replace “not established” with “does not exist.”
Leave a Reply