Skip to main content

OIC AI Agent: Add Multiple Tools and Control Their Use

Calculating read time…

An AI agent becomes more capable when it can use multiple tools, but adding more tools also creates a new engineering challenge: how does the agent choose the right tool, provide the correct inputs, and know when not to make another call? Making tools available is only the first step. Their responsibilities, selection criteria, dependencies, and failure behavior must also be designed carefully.

In Project AI Agents, tool identifiers, descriptions, guidelines, parameter settings, and agent instructions help the model determine which capability to use. However, these settings guide model behavior; they do not guarantee correct tool selection or enforce business rules. Input validation, authorization, and mandatory execution sequences must be enforced in the appropriate integration or backend layer.

01. What You Will Build

In this module, you will extend a Procurement Exception Assistant to investigate a purchase-order exception using two read-only tools: one looks up purchase-order and shipment status; the other retrieves receiving events for a shipment. You will define their responsibilities, register their metadata, associate both tools with an agent, and test whether the agent uses the second tool only when the first tool provides the required evidence.

Use this example request as the target outcome:

Example investigation

Investigate purchase order PO-48217. The order says it was shipped, but the receiving team cannot find a receipt. Check the available evidence and report any information that is missing.

The intended tool sequence is:

  1. Read the purchase-order record and obtain its shipment identifier.
  2. Use that exact identifier to retrieve receiving events.
  3. Compare the two source results and report what each source actually established.

The result should distinguish shipped with no matching receipt event returned from receipt information unavailable. Those are different findings.

02. In This Post

  1. Before You Begin
  2. Concepts That Affect This Build
    1. 4.1 — Multi-Tool Architecture
    2. 4.2 — Model-Driven Tool Selection
    3. 4.3 — Dependent Tool Calls
    4. 4.4 — Partial Failures and Missing Evidence
    5. 4.5 — Iteration Limits and Execution Budgets
    6. 4.6 — Advanced Planning Approaches
  3. Build and Configure
  4. Test and Prove It
  5. Troubleshooting and Recovery
  6. Enterprise Considerations
  7. Completion Checklist and What Comes Next
  8. Five Useful FAQs
  9. Verified References
  10. Finally — Summary

03. Before You Begin

This module focuses on multi-tool behavior, not on creating an ordinary OIC REST integration from scratch. However, the tool contracts are included below so that the exercise does not depend on an undocumented starter asset.

Core prerequisites

  • An Oracle Integration 3 project with Project AI Agents available.
  • An activated ReAct thinking pattern, its working LLM connection, and an agent that can be run in the Test Agent interface.
  • A project integration that can provide purchase-order lookup results. If your previous module's single-tool agent is not available, use the first contract in this article to build and test the initial read-only tool before adding the second.
  • Permission and connectivity to activate the integrations and configure agentic AI tools in your environment.

Just-in-time technical prerequisite: each integration registered as an agentic AI tool must be part of a project and active. Oracle's registration documentation requires the integration's REST trigger to use the REST Adapter, OAuth authentication, and a JSON payload. Supported REST verbs include GET, POST, PUT, DELETE, and PATCH. This lab uses POST with JSON for both tool contracts. See the official tool-registration requirements.

Blocked until supplied or configured: the actual tenant, region, existing agent, model connection, source-system endpoints, and runtime traces. The examples below use fictional procurement data and do not require exposing business secrets. Whether Project AI Agents and a particular provider/model are available in your specific tenancy must be confirmed there.

04. Concepts That Affect This Build

4.1 — Multi-Tool Architecture

A tool is a capability the agent can request through a registered integration. A multi-tool agent has access to more than one capability and uses the available descriptions, conversation context, instructions, and returned information to decide what to invoke.

For procurement investigation, split capabilities by the information each source owns:

  • Purchase-order lookup: authoritative order status, supplier, and any shipment identifier recorded against the order.
  • Receiving-event lookup: receipt events recorded for a specific shipment identifier.

This separation prevents the agent from treating a purchase-order record as proof of physical receipt. The tool boundaries should follow data ownership and responsibility, not merely split operations into as many integrations as possible.

Kid-friendly analogy

Imagine a school trip. One teacher checks the bus booking, while another checks which children actually boarded. A confirmed booking is useful, but it cannot prove who got on the bus.

In the agent, this means: Give each tool one well-defined source responsibility so that the order record and the receiving record remain distinct pieces of evidence.

When should you not use a multi-tool agent? If every request must always call the same systems in the same order, with fixed validation and branching rules, ordinary deterministic integration orchestration may be preferable. It provides explicit sequencing in the integration itself rather than asking a model to decide the sequence on every run.

Use an agent when the next read genuinely depends on what the previous tool returns, the question varies, or the investigation benefits from adapting to new evidence. A hybrid is often practical: deterministic integrations enforce required business steps, while the agent interprets evidence and explains the outcome.

4.2 — Model-Driven Tool Selection

Oracle's Project AI Agents tool metadata helps the LLM determine which integration to use. The tool identifier is sent to the LLM as tool metadata; the description and optional guidelines help explain the capability and its intended use. The tool's display name is not sent to the LLM. Input-parameter configuration also controls which parameters are visible to the model and which values it must supply.

This is a model-selection mechanism, not a guaranteed routing rule. A vague description or overlapping tool responsibilities may lead to an irrelevant tool choice, an unnecessary call, or an incorrect argument. Better metadata reduces ambiguity but does not eliminate model error.

Kid-friendly analogy

A school library has two shelves: one for books currently borrowed and another for books returned today. Labels that explain the difference help you choose the right shelf; labels saying only “books” make mistakes more likely.

In the agent, this means: Descriptive identifiers, non-overlapping tool descriptions, and clear parameter definitions help the model choose the source that can answer the request.

Important distinction between fields: a tool's description explains its purpose; its guidelines describe usage constraints for the model; the agent's role and guidelines explain overall behavior; and the thinking-pattern guidelines describe the reasoning approach. These instructions influence decisions but do not replace enforced integration authorization, payload validation, or business rules.

Visible and required parameter settings also serve different purposes. A visible field is sent to the LLM. A required field tells the model it must assign a value when invoking the tool. A constant supplies a value the model should not decide. A default supplies a fallback value when appropriate. None of these settings proves that a supplied business identifier is valid.

For example, the receiving tool should accept the exact shipment identifier returned from purchase-order lookup. Its description should explicitly say that it does not accept a purchase-order number. The receiving integration must still validate the identifier and restrict the records that can be queried.

4.3 — Dependent Tool Calls

A dependent tool call uses information from a previous result to decide whether to make a subsequent call and, when appropriate, to construct its input. In this lab, the first tool returns shipmentId; the second tool needs that same identifier.

With ReAct, the agent observes the first tool's result before deciding what to do next. The dependency is therefore model-mediated: the model must read the output, recognize whether it contains a usable shipment identifier, and select the receiving tool with the correct argument.

Kid-friendly analogy

Imagine that a coach gives you a team number, and the equipment desk asks for that exact number before checking the team's kit. If the coach never gives you a number, you must not invent one and pretend the desk checked the right team.

In the agent, this means: Pass the shipment identifier returned by the first tool to the second tool only when the first response establishes that the identifier exists and is usable.

A dependent sequence needs intermediate validation, not just a correctly shaped JSON object. Before the second call, the model should establish all of the following:

  1. The first tool returned a usable response with resultStatus = "SUCCESS".
  2. The returned purchase-order result indicates that a shipment exists for the investigation being performed.
  3. The returned shipmentId is present and non-empty.

If any necessary prerequisite is missing, stop the dependent branch and report what is missing. Do not manufacture an identifier from an order number or a previous unrelated conversation.

Boundary: an LLM instruction is not a hard execution dependency. The model can still select a tool incorrectly. If the order of operations is mandatory for compliance or transaction correctness, implement the dependency in a deterministic integration or workflow and expose that controlled operation as a tool.

4.4 — Partial Failures and Missing Evidence

A tool investigation can produce different outcomes that must not be collapsed into a generic “nothing found” response:

  • Successful positive result: the requested record or event exists in the queried source.
  • Successful negative result: the lookup completed successfully, but the requested record or event was not found in that source.
  • Unavailable result: the source could not provide reliable evidence, so its business state remains unknown.
  • Tool execution failure: the integration or invocation failed. Whether the model receives a usable error payload depends on the actual runtime behavior and must be inspected rather than assumed.

Kid-friendly analogy

Imagine checking a classroom attendance sheet. A clear sheet with no name is evidence that the name was not recorded there. If the sheet is missing, you cannot conclude that the student was absent.

In the agent, this means: Treat an empty successful lookup as a source-specific negative result, but treat unavailable or failed lookups as missing evidence rather than proof of absence.

For this prototype, the tools return an explicit resultStatus field in their JSON contracts. In this tutorial, resultStatus describes whether the lookup completed and returned a usable response; separate fields such as orderFound and receiptFound describe the business result. A controlled UNAVAILABLE response lets you test the agent's interpretation independently of an actual transport failure. It does not simulate every runtime failure mode.

Do not ask the model to keep retrying until it receives a favorable answer. For a read-only investigation, use an explicit retry policy: retry only where the integration contract and error handling establish that the failure is retryable, set a bounded limit in the appropriate execution layer, and preserve the original failure evidence. The example below does not authorize automatic retries.

4.5 — Iteration Limits and Execution Budgets

The ReAct pattern alternates between reasoning and action, using the observed results to inform the next decision. The Max iterations pattern setting limits the agent's reasoning/action steps before it provides a final answer or exits. It is a guard against runaway or unnecessarily repeated execution, not a guarantee that every requested investigation will complete.

Kid-friendly analogy

Imagine a puzzle club with a fixed number of turns to solve a clue. Too few turns can stop the team before it checks the answer; too many can let it repeat unhelpful guesses and waste the club's time.

In the agent, this means: Max iterations caps the agent's reasoning/action progression, so choose the budget from representative traces rather than setting it equal to the number of tools.

Do not equate iterations with tool calls. A conceptual ReAct cycle may involve reasoning, a tool action, and observation, but Oracle's documentation does not specify a universal one-tool-call-per-iteration accounting rule or state precisely how final-answer generation is counted. Consequently, two registered tools do not imply that a limit of two is sufficient.

The current Oracle pattern-selection guidance recommends 10–15 iterations for most tasks and 20–25 for deeper investigations, and advises using no more than 5–8 tools to manage reasoning overhead. These are documented guidelines, not proof of the correct budget for every tenant or agent. The ReAct tutorial also illustrates a value of 10, but that screenshot should not be treated as a universal required default.

For this two-tool lab, begin with the value configured in your development pattern, using Oracle's current guidance as a reference. Run representative prompts and inspect the traces. Increase the budget only when the evidence demonstrates premature stopping that additional iterations could reasonably address. Reduce unnecessary repetition by improving descriptions, branch rules, and result handling before simply increasing the limit.

A higher limit can permit additional reasoning/action steps, but it can also increase latency, LLM usage, repeated lookups, and the opportunity for irrelevant calls. A low limit can stop execution before the dependent lookup or before the agent adequately communicates what remains unknown.

Evidence: compare the tool-call sequence, arguments, error records, and final answer across repeated test cases. Oracle's public documentation does not define all iteration-counting details or a universal allowed minimum and maximum; confirm the actual field behavior from your configured pattern and its runtime traces.

4.6 — Advanced Planning Approaches

Oracle documents two relevant approaches: ReAct and Plan & Execute. ReAct is adaptive: the agent takes an action, observes the result, and decides what to do next. Plan & Execute uses two AI agents: a Planner that creates an ordered plan and an Acting agent that executes that plan in sequence.

Kid-friendly analogy

For a treasure hunt, one team might examine each clue and decide where to search next. Another team might agree on a complete route before starting and then follow that route. The first adapts more easily; the second is easier to review when the route is fixed.

In the agent, this means: ReAct adapts after each tool result, while Plan & Execute separates plan generation from prescribed execution by a second agent.

For the current prototype, prefer ReAct because the receiving lookup depends on the purchase-order result. Some orders may not have a shipment identifier, so the second call is conditional. Oracle's pattern-selection guidance recommends prototyping with ReAct first for branching and exploratory workflows.

Plan & Execute is more suitable when the required steps and their order are known upfront and the organization needs an explicit, repeatable plan. Oracle describes it as a two-agent arrangement: the Planner uses the Plan pattern and the Acting agent uses ReAct. The plan can name the exact tools, inputs, and expected outputs, but its correctness still depends on the quality of the generated plan.

Do not confuse planning with enforced business sequencing. Neither a model-generated plan nor an agent instruction replaces backend authorization, mandatory validation, or a deterministic workflow where those are required. If an operation must never run before a particular check succeeds, enforce that dependency in the integration or workflow.

The exact pattern and model configuration must also match the intended provider. Oracle's Plan-pattern documentation specifies provider-specific choices: use Plan for OpenAI, Anthropic, or Azure LLMs, and Plan for OCI GenAI for OCI Generative AI. The Plan pattern itself does not use tools; it is used as the Planner component of a multi-agent Plan & Execute arrangement. Do not treat the Plan recipe as a drop-in replacement for this single-agent, two-tool ReAct prototype.

05. Build and Configure — Step by Step

Phase 1 — Define Both Read-Only Tool Contracts

The first tool is the starting point for the investigation. The second is the new tool this module adds. The payloads below are tutorial-defined JSON contracts and fictional fixture values, not exported Oracle integration artifacts. In this tutorial, resultStatus describes lookup execution, not whether the business record exists: use SUCCESS when the lookup completed and returned a valid response, and use a separate business field to represent a no-match result. Use UNAVAILABLE when no reliable lookup result could be obtained.

Tool A — Purchase-order lookup

Use a clear, exact request key. For this lab, the input is a purchase-order number; the output includes the order status and the shipment identifier when one is available.

{
  "orderNumber": "PO-48217"
}

Illustrative successful response:

{
  "resultStatus": "SUCCESS",
  "orderFound": true,
  "orderNumber": "PO-48217",
  "poStatus": "SHIPPED",
  "supplierName": "Northstar Components",
  "shipmentId": "SHIP-1001",
  "sourceUpdatedAt": "2026-10-23T08:30:00Z",
  "sourceReference": "PROCUREMENT_ORDER_LOOKUP"
}

For the first tool, use a distinct identifier such as LOOKUP_PURCHASE_ORDER_TOOL, a description that says it reads purchase-order status and any recorded shipment identifier, and a guideline that it must not claim receipt status. Configure orderNumber as visible and required if that matches your integration schema. These are suggested lab values, not Oracle-prescribed identifiers.

Illustrative successful response when the purchase order is not found:

{
  "resultStatus": "SUCCESS",
  "orderFound": false,
  "orderNumber": "PO-99999",
  "poStatus": "NOT_FOUND",
  "shipmentId": null,
  "sourceReference": "PROCUREMENT_ORDER_LOOKUP"
}

In this example, the query succeeded but no matching purchase order was found. If the source cannot be queried, return a separate unavailable/error outcome according to the implemented contract; do not represent a source failure as orderFound: false alone.

Tool B — Receiving-event lookup

The new tool accepts a shipment identifier, not a purchase-order number. A successful empty result means that no matching receiving events were returned by this lookup; it does not prove that the goods were physically never received or that every potentially relevant system has been checked.

{
  "shipmentId": "SHIP-1001"
}

Illustrative successful response with no matching receipt:

{
  "resultStatus": "SUCCESS",
  "shipmentId": "SHIP-1001",
  "receiptFound": false,
  "receiptEvents": [],
  "sourceUpdatedAt": "2026-10-23T08:45:00Z",
  "sourceReference": "RECEIVING_EVENT_LOOKUP"
}

Illustrative unavailable response (the exact error schema should match your integration's contract):

{
  "resultStatus": "UNAVAILABLE",
  "shipmentId": "SHIP-FAIL-009",
  "errorCode": "RECEIVING_SOURCE_UNAVAILABLE",
  "message": "The receiving lookup did not return a reliable result.",
  "sourceReference": "RECEIVING_EVENT_LOOKUP"
}

In a real implementation, map each contract to the actual source API or database operation. Validate the input, preserve meaningful source status and timestamps, and return a predictable JSON shape. If the underlying receiving source fails, do not manufacture a successful empty array to make the response appear complete.

Phase 2 — Specify the Behavior of the Second Tool

The receiving tool needs usage metadata that makes its responsibility unmistakable. The tool description and parameter descriptions become part of the model's decision context; they are not merely documentation for developers.

Use the following tutorial-defined metadata for the new tool:

Field Value or decision
Name Lookup Receiving Events
Identifier LOOKUP_RECEIVING_EVENTS_TOOL
Description Read-only lookup of receiving events for one exact shipmentId. Use only after the purchase-order lookup succeeds and returns a non-empty shipmentId. Returns resultStatus, receipt events, and source evidence. An empty receiptEvents array means no matching event was returned only when resultStatus is SUCCESS. This tool does not return purchase-order status and does not accept a purchase-order number.
Guidelines Use only the exact shipment identifier returned by the successful purchase-order lookup for the current investigation. Do not infer, construct, or substitute an identifier. Treat UNAVAILABLE as missing evidence, not as proof that no receipt exists.
Input parameter shipmentId

The tool's display name and identifier are important design-time choices, but they serve different purposes. Oracle's registration documentation states that neither can be changed after the tool is created. The display name is not sent to the LLM; the identifier is sent as tool metadata. Choose a readable name for people and a meaningful identifier for model-facing metadata before registering the tool.

Phase 3 — Implement and Independently Test the Second Integration

Starting location: Oracle Integration 3 project containing the integration you intend to register as the receiving tool.

Implement a read-only REST-triggered integration using the contract from Phase 1. Map the request's shipmentId to the authoritative receiving lookup. Return a structured JSON result and source timestamp when available. Include input validation and a meaningful failure path.

For a self-contained lab without a connected procurement or receiving system, a controlled test fixture can provide the synthetic responses shown above. Keep it separate from production source logic, label it as test data, and do not mistake a fixture response for a verified enterprise record.

Independently test this integration before registering it as a tool. At minimum, verify that a valid shipment identifier returns the expected JSON and that a missing or invalid identifier is handled intentionally. Confirm that an empty successful result and a failed lookup have different representations.

Configuration checkpoint: the integration must meet the tool-registration prerequisites: be part of the project, be active, and use a REST trigger with OAuth authentication and a JSON payload. This lab uses POST. The response contract should match the schema the integration actually returns; do not assume the model's later interpretation has validated the backend payload.

Phase 4 — Register the Receiving Integration as a Tool

Starting location: Projects → your project → Integrations → the receiving integration.

  1. Confirm that the receiving integration is active and satisfies the REST-trigger, authentication, and JSON requirements.
  2. Open its Actions menu and select Create agentic AI tool.
  3. Enter a descriptive name, identifier, and description. Use the metadata specified in Phase 2, adapting the wording to your actual contract.
  4. Create the tool and review the tool details page.
  5. Configure the description, guidelines, and parameter settings. Save the tool configuration.

The consequential parameter settings are summarized below. The parameter table is populated from the integration input schema; the exact fields shown depend on that schema.

Parameter setting Decision for this lab
Visible Enable for shipmentId because the model must supply the lookup key.
Required Enable if the integration contract requires shipmentId for every invocation. This tells the model it must assign a value; it does not prove that the value is valid.
Constant Leave unset for shipmentId; it must come from the current lookup result rather than a fixed identifier.
Default Leave unset for the shipment identifier. A fabricated or arbitrary fallback would be unsafe.
Description Explain that shipmentId is the exact identifier returned by the successful purchase-order lookup. Do not expose irrelevant technical fields to the LLM.

Checkpoint: the project contains the receiving integration as a registered tool with a clear description and only the required model-visible input. The expected source status, receipt-event schema, and backend validation must be independently confirmed.

Phase 5 — Associate Both Tools with the Agent

Starting location: Projects → your project → AI Agents → open your Procurement Exception Assistant.

The agent's tool list determines which registered capabilities are available during model-driven selection. Registering an integration as a tool does not, by itself, mean that every agent in the project automatically uses it. The intended agent must have the tool associated with it.

  1. Open the existing agent details page.
  2. In the Tools area, click the add control (+ in Oracle's documented interface).
  3. Select the purchase-order lookup tool and the newly registered receiving-event lookup tool.
  4. Add the tools, save the agent, and confirm that both appear in its associated tool list.
  5. Check the agent's activation state and follow the activation action required by the current UI if necessary.

For a compact prototype, keep the existing ReAct pattern unless the observed trace demonstrates a reason to adjust it. If the pattern is shared with other agents, do not casually change its iteration limit or guidelines: create a dedicated development pattern when isolation from other agents is needed.

Checkpoint: both tools are listed for the intended agent. This is design-time evidence of association, not proof that the model will select or execute either tool correctly.

Phase 6 — Configure Agent-Level Investigation Rules

Keep the agent's role focused on the job the user needs completed. Put tool-specific input semantics in the relevant tool metadata, and put the investigation's overall decision policy in the agent guidelines.

Use the following as a tutorial-defined starting point, adapting status names to the actual source system:

Role:
You are a Procurement Exception Assistant.
Investigate purchase-order and receiving discrepancies
using the available read-only tools and their returned evidence.

Guidelines:
1. For a purchase-order investigation, call the purchase-order
   lookup with the exact order number supplied by the user.
2. Inspect the lookup result before deciding whether a second
   tool is appropriate.
3. Call the receiving-event lookup only when the first tool
   returns resultStatus = SUCCESS, orderFound = true, and a
   non-empty shipmentId for this investigation.
4. Pass the exact shipmentId returned by the first tool.
   Never construct, guess, or substitute an identifier.
5. Treat resultStatus = SUCCESS with orderFound = false (or a
   documented source-specific not-found field) as a successful
   lookup with no matching purchase order. Do not call the
   receiving lookup in that case.
6. Treat UNAVAILABLE, malformed responses, and tool execution
   failures as missing evidence. Do not describe them as proof
   that the requested business record does not exist.
7. If no usable shipmentId is returned, do not call the
   receiving tool. Explain why the investigation could not continue.
8. If receiving lookup returns resultStatus = SUCCESS and
   receiptFound = false with receiptEvents = [], say that no
   matching receipt event was returned by that lookup. Do not
   claim that the goods were never received.
9. Include relevant returned identifiers, statuses, and source
   timestamps when available. Do not invent a source timestamp.
10. Do not claim an operation succeeded unless the relevant
    tool result supports that claim. Do not perform write actions.

These are behavioral instructions to the model. They improve clarity and provide a basis for testing, but they do not enforce permissions or transaction correctness. Implement read-only authorization and input validation in the integrations and target systems.

Checkpoint: the agent has the two registered tools and explicit guidance about sequencing, missing identifiers, negative results, and incomplete evidence. Save the configuration and verify its activation state in the tenant.

Phase 7 — Revisit the Iteration Limit Using Evidence

Open the thinking pattern associated with the agent and review its Max iterations field. The exact number displayed in your tenant is the starting configuration; do not infer the number from the number of tools.

For this short investigation, first run the two-tool scenario using the existing setting. Then inspect the trace. If it ends before the receiving lookup, determine whether the pattern limit actually stopped the run or whether the model selected the wrong tool, supplied a bad argument, or encountered an integration failure. Raising the limit cannot repair an invalid tool contract or a failing endpoint.

If you adjust the budget, record the original value and compare the same set of test prompts under the new value. Confirm that the setting produces better completion without unnecessary repeat calls, and that a failure still leads to an appropriately incomplete answer. Use a development-only pattern when the production agent or other agents share the existing pattern.

Checkpoint: the chosen setting has a documented reason based on repeatable traces. Do not declare it optimal without runtime evidence.

Phase 8 — Run the Prototype

Starting location: Projects → your project → AI Agents. Oracle's documented interface uses the agent's Actions menu and a Run action.

  1. Run the agent to open the Test Agent page.
  2. Enter the procurement investigation request from the opening section.
  3. Inspect the displayed agent actions and tool responses.
  4. Return to the project and open Observe. Inspect the integrations involved in the run and investigate any errored instances.

Oracle's documented test workflow identifies the system, user, tool, and assistant messages as useful parts of the agent action view. Its monitoring procedure also directs you to Observe to see which integrations ran and to inspect errored instances.

For this module, the most important evidence is not just a plausible final paragraph. You need to establish which tool was called, which key it received, what it returned, whether the dependent call was appropriate, and whether the conclusion accurately reflects both results.

06. Test and Prove It

The following results are expected behaviors for the tutorial contracts, not recorded test outcomes. Execution status for every case below is Not executed because no tenant or runtime trace was supplied.

Case Expected behavior Evidence to inspect
1. Normal two-tool path PO-48217 is looked up first; receiving lookup uses SHIP-1001; the final answer reports the successful but empty receipt lookup accurately. Both tool calls, exact arguments, response bodies, source references and timestamps, final claims.
2. No shipment identifier Use a fixture with resultStatus SUCCESS and orderFound true but no shipment identifier. Do not call the receiving tool. One PO lookup, no receiving invocation, and an explanation that the next lookup could not proceed.
3. Unknown purchase order Return resultStatus SUCCESS and orderFound false (with poStatus NOT_FOUND if used by the implementation). Report no matching order for the queried key and do not call the receiving tool. The first result, absence of an unsupported second call, and appropriately scoped wording.
4. Controlled partial failure Configure a development fixture to return resultStatus UNAVAILABLE for shipment SHIP-FAIL-009. The agent must not claim there are no receipts. The structured failure response, tool call arguments, final answer, and evidence of whether an unjustified retry occurred.
5. Missing input A request such as “Check the shipment” without a usable order or shipment identifier should lead to a clarification request or an explicit inability to identify the record. No fabricated identifier. Tool invocation history and the exact arguments, or confirmation that neither tool was called.
6. Out-of-scope write request A request to create or approve a purchase order must not cause either read-only lookup to be represented as a write operation. Available tool list, requested action, calls actually made, and final scope statement.
7. Actual invocation failure In an isolated development test, make the receiving integration fail through a controlled fault. The run must not be interpreted as a successful empty lookup. The exact model-facing behavior must be observed. Agent action trace, integration instance state, error details, final answer, and whether the run stopped or continued.
8. Execution budget boundary With a development pattern, compare a deliberately tighter limit against a baseline. Observe whether the dependent lookup completes or the agent stops early. Do not predict an exact iteration count per tool. Configured limit, trace sequence, repeat calls, integration failures, latency or usage indicators available to you, and final answer quality.

Evidence standard: a tool response proves what that tool returned. An assistant message proves only what the model said. To establish that an integration ran successfully, inspect the corresponding runtime record. To establish that the conclusion is justified, compare the final claims against both tool results and their source-status fields.

07. Troubleshooting and Recovery

Symptom Likely layer or cause Targeted check and correction
The second tool is never selected. Tool not associated, poor description, no usable shipment identifier, or the agent stopped early. Confirm association and inspect the first response. If the identifier exists, refine the description and instructions, then retest the same prompt.
The second tool receives a purchase-order number. Ambiguous tool metadata or incorrect argument selection. Inspect the exact tool arguments. Differentiate the two identifiers in the description, parameter metadata, and agent guidance. Add backend validation for the expected identifier type.
The agent says no receipt exists when the lookup failed. Failure represented as an empty result, or model misinterpretation of the source status. Separate SUCCESS with an empty list from UNAVAILABLE and runtime faults. Correct the integration response contract, update guidance, and repeat the negative and failure tests.
The agent repeats a lookup. Unclear completion criteria, ambiguous source responses, or an iteration budget that permits unhelpful repetition. Inspect the repeated arguments and outputs. Clarify stopping conditions and result statuses. Adjust Max iterations only after determining whether the repetition is a reasoning or integration problem.
The run stops after the first result. Premature stopping, absent shipment identifier, tool selection error, or a failed pattern integration. Inspect the first payload and the pattern/tool integration instances. Increase the budget only if the evidence points to a budget constraint rather than missing data or an invocation error.
A registered tool is not callable. Integration eligibility, activation, authentication, tool association, or runtime failure. Check the registration prerequisites and tool association. Use Observe and instance details to identify the failing integration instead of diagnosing from the final model response alone.

After each correction, rerun the original positive path and the relevant negative or failure path. Keep the evidence for each run distinct; a successful retest of the normal path does not establish that the failure path was fixed.

08. Enterprise Considerations

Enforce access below the model. The prototype uses read-only tools, but the authorization and target operations must actually enforce that boundary. Model instructions, tool descriptions, and hidden parameters do not provide a security guarantee. The connected account or identity should be limited to the records and operations the use case requires.

Keep evidence provenance visible. Return source status, record identifiers, and timestamps when available. An old successful lookup may still be stale. An empty result is scoped to the system and query that produced it; it is not universal proof that no relevant business event exists.

Keep tool responsibilities distinct. Avoid several tools with almost identical descriptions and overlapping parameters unless their differences are essential and testable. Reduce exposed model-visible inputs to those needed for the task.

Make failures observable. Retain the tool outputs and relevant integration instance details available to the authorized operator. The agent's final response is not a substitute for runtime monitoring.

Move fixed business sequencing into deterministic logic. If the order lookup must always pass a validation step, or if some downstream action must be prohibited until a trusted status has been confirmed, enforce it in an integration, target authorization rule, or workflow. Do not rely on a model-generated plan as the only control.

Protect the existing agent configuration. Changing a shared thinking pattern can influence the agents that use it. Isolate experimentation when adjusting pattern guidelines or iteration settings, and retest the affected agents before promoting a change.

09. Completion Checklist and What Comes Next

Mark a result complete only after you have collected the corresponding evidence from your environment.

  • ☐ Both integrations have explicit, non-overlapping read-only responsibilities.
  • ☐ The receiving integration returns independently verified JSON for a valid lookup and distinguishes no matching event from source unavailability.
  • ☐ The receiving integration is registered with a descriptive identifier, clear metadata, and an appropriate input-parameter configuration.
  • ☐ The intended agent has both tools associated with it.
  • ☐ The positive path shows the correct shipment identifier passing from the first response to the second tool.
  • ☐ No-shipment and not-found cases stop before an invalid dependent call.
  • ☐ The controlled unavailable result and the real invocation-failure path do not become false claims about receipt absence.
  • ☐ The Max iterations setting has been evaluated using trace evidence rather than inferred from the number of tools.

Deferred to a later module: implement and evaluate a supported Plan & Execute configuration after the core two-tool ReAct scenario works. That extension should use a Planner and an Acting agent, with explicit plan-step inputs and expected outputs, followed by tests for skipped steps, incorrect arguments, and missing evidence.

10. Five Useful FAQs

1. Does registering a second tool automatically make the agent use it?

No. Register the integration as an agentic AI tool, associate the registered tool with the intended agent, save the configuration, and verify the result through a test run. Availability does not guarantee selection.

2. How do I ensure that the second tool receives the exact output of the first?

For a model-mediated ReAct sequence, describe the dependency clearly and inspect the actual call argument against the first response. Validate it in the integration as well. If exact sequencing is mandatory, enforce the hand-off in deterministic orchestration rather than relying on prompt instructions alone.

3. Is an empty receiving-event list proof that goods were never received?

No. An empty list from a successful lookup establishes only that the queried source returned no matching events for that key and query. An unavailable source or failed invocation establishes no such negative business result.

4. Should I set Max iterations to the number of tools?

No. The setting limits reasoning/action steps, and Oracle does not document a universal one-to-one mapping between iterations and tool calls. Start from the configured pattern and the documented guidance, then calibrate with traces from representative requests, including negative and failure paths.

5. When should I move from ReAct to Plan & Execute?

Begin with ReAct when the next action depends on new information, such as whether a shipment identifier exists. Consider Plan & Execute when the steps are known beforehand and require a repeatable, reviewable sequence. It uses a Planner and an Acting agent; a model-generated plan is still not an authorization or business-validation control.

11. Verified References

  1. Register an Integration as an Agentic AI Tool — project and activation prerequisites; REST trigger, OAuth and JSON requirements; tool identifier, description, guidelines and parameter settings.
  2. Configure the Agentic AI Thinking Pattern — ReAct behavior, the pattern's Max iterations field, guidelines and LLM connection.
  3. Determine Which Agentic AI Pattern to Use — documented ReAct recommendations and the two-agent Plan & Execute approach.
  4. Add the Plan Agentic AI Pattern — Plan-pattern implementation and provider-specific pattern choices.
  5. Add and Configure the AI Agent — agent role and guidelines, registered-tool association and activation procedure.
  6. Run and Test the AI Agent — Test Agent action records and the Observe workflow for integration status and error investigation.
  7. Oracle Integration 3 — September 2026 (26.10) Release Notes — release context for 26.10. The notes announce the Oracle Integration MCP Gateway for version 26.10; this tutorial does not require MCP Gateway to run the in-project Project AI Agents prototype.

Verification boundary: public documentation establishes the documented product mechanics, not that the corresponding feature is enabled in a specific tenancy. No tenant UI inspection, runtime call, integration activation, or test execution was performed for this article.

12. Finally — Summary

Adding a second tool is not simply a matter of giving an agent another integration. The important work is defining non-overlapping responsibilities, explaining each tool's purpose in its metadata, and testing how the agent uses one source's result to decide whether another lookup is justified.

In this prototype, purchase-order lookup establishes the shipment identifier; receiving-event lookup investigates that specific shipment. A successful empty result is different from an unavailable source, and neither tool's output should be replaced by an unsupported model claim.

Three engineering principles carry forward: verify arguments rather than trusting plausible summaries, enforce security and mandatory sequencing in the appropriate backend layer, and calibrate Max iterations from observed behavior instead of counting registered tools.

Comments