Skip to main content

AI Agent Runtime: How LLMs Understand Available Tools and Tool Definitions

Calculating read time…

Imagine a procurement employee asking an AI assistant to check the delivery status of an order. The assistant has access to two business capabilities: look up an order and update an order. Both capabilities deal with orders, but only one is appropriate when the employee simply wants to know whether a shipment has arrived.

How does the Large Language Model (LLM) distinguish these capabilities? How does it know which operation to request, what identifier to provide, and when it should ask the employee for more information instead of guessing?

The answer begins with tool definitions. In Oracle Integration 3 (OIC Gen3) project AI Agents, an integration can be registered as an agentic AI tool. Its registration includes a human-readable Name, a machine-facing Identifier, a Description, optional Guidelines, and parameter configuration. These elements provide the information the agent uses to understand available capabilities and construct tool requests. Understanding what each element does, and what it does not guarantee, is essential to designing reliable integrations for AI Agents.

1. What You Will Build

We will design and assess an order lookup tool that an OIC project AI Agent can use to retrieve order information.

Practical outcome

  • Understand how tool definitions communicate available business capabilities to an LLM.
  • Distinguish a tool's Name, Identifier, Description, Guidelines, and parameter configuration.
  • Design an order lookup capability with a required order identifier.
  • Compare precise and ambiguous tool definitions.
  • Understand the differences between OpenAI Chat Completions, OCI Generic Chat SDK, and OCI Responses API function-definition formats.
  • Understand which aspects of OIC parameter configuration are documented and which provider-specific conversion details remain unverified.

Scope: This is a tool-definition and architecture tutorial, not a complete order-management integration deployment. We will define the integration contract and registration metadata, then examine the information made available to an LLM. The actual order-management backend, an OIC integration export, and a trace of the provider-specific request generated by OIC are not supplied.

Completion evidence: You should be able to inspect a registered tool and explain what information is exposed to the LLM, which parameters it is expected to populate, what information is missing, and which checks must still happen outside the model.

2. In This Post

3. What Is a Tool Definition?

3.1 Understanding tools before understanding tool definitions

In this article, an AI Agent is a software system that uses a large language model (LLM) to interpret a task and request external capabilities when useful. The surrounding runtime manages those requests and their results. This is a general explanation; the OIC-specific settings are identified separately below.

A tool is one of those external capabilities. It allows an agent to interact with something beyond the model's generated text. For example, a tool might retrieve an order, check inventory, obtain an invoice, or submit a business transaction.

An LLM does not automatically discover every integration available in an enterprise environment. The agent must be provided with information describing the capabilities made available to it.

A tool definition is a structured description of a callable capability. Depending on the tool framework, it can communicate information such as:

  • What the capability does.
  • Which operation is available.
  • Which inputs the operation accepts.
  • Which inputs are mandatory.
  • What values or data types are expected.

An argument is the actual value supplied for a parameter in a particular call. The runtime is the software that coordinates model requests and tool execution. Metadata describes a tool; it is separate from the live business data returned by that tool.

Kid-friendly analogy

Imagine a school library containing thousands of books. Each book has a catalogue entry explaining its title, subject, and location. A student uses the catalogue to find the right book instead of opening every shelf.

In this OCI AI integration, this means: The tool definition acts like a catalogue entry that tells the LLM which business operation is available and what information is needed to request it.

3.2 How the definition participates in a tool call

Consider this request:

Employee: What is the delivery status of order ORD-45021?

The agent has access to a registered capability with the illustrative Identifier get-order-status.

At a conceptual level, the interaction involves several distinct stages:

Employee request
Check delivery status of ORD-45021

↓

LLM receives tool information
Identifier metadata, Description, Guidelines and exposed parameters

↓

Tool selection and argument generation
A request for the order lookup operation with orderId = ORD-45021

↓

OIC agent runtime
Handles invocation of the registered integration

↓

Tool result
A representative order status is returned for further processing

Conceptual illustration of an OIC tool interaction, not an assertion about undocumented internal message serialization.

There are two important distinctions in this flow.

First, the LLM does not directly execute the integration. It determines whether a tool is appropriate and generates a request containing the tool selection and arguments. In OIC project AI Agents, the agent runtime handles invocation of the registered integration.

Second, a generated tool request is not proof that the integration completed successfully. The tool invocation and its returned result are separate runtime events.

Oracle documents that the Identifier is sent to the LLM as tool metadata. The Description and Guidelines are sent as part of the system prompt, while the Visible parameter setting controls which integration inputs are sent to the LLM.

See Register an Integration as an Agentic AI Tool.

3.3 What does the LLM actually decide?

For this example, the model must make two important decisions:

  1. Whether the order lookup tool is relevant to the employee's request.
  2. Whether it has enough information to construct the required orderId argument.

If the employee provides an order identifier, the model may use that value when generating the tool request. If the identifier is missing, our intended agent behavior is to ask the employee for clarification rather than invent an identifier.

That intended behavior should be communicated through the tool Description and Guidelines and then tested with the configured agent. A Required setting does not prove that the model will always ask a clarification question instead of generating an incorrect value.

An identifier can also have the expected format but still refer to a nonexistent order. That is a business-validation problem, not something a tool description can resolve.

4. Understanding Tool Names and Descriptions

4.1 Display Name versus machine Identifier

One of the most important distinctions in OIC tool registration is the difference between Name and Identifier.

Oracle documents the following behavior:

  • Name: Required. Automatically populated from the integration name. It is not sent to the LLM. Oracle documents that it cannot be changed after the tool has been created.
  • Identifier: Required. Uniquely identifies the tool in the project. By default, it is automatically populated from the tool Name. It is sent to the LLM as tool metadata and helps the agent understand the tool's purpose and when to use it. Oracle also documents that it cannot be changed after creation.

The Identifier is therefore the important model-facing identifier. The Name is a management-facing label rather than the identifier supplied to the model.

Kid-friendly analogy

A school bus may have the name "Science Trip Bus" displayed on its side, while the transport office identifies it using vehicle number BUS-17. The name helps people recognize it; the number identifies the vehicle in the records.

In this OCI AI integration, this means: The OIC Name is the management-facing label, while the Identifier is the machine-facing tool identifier supplied to the LLM.

For the order lookup prototype, use the following values:

OIC fieldExample valuePurpose
NameLookup Order StatusHuman-readable tool label, populated from the integration name
Identifierget-order-statusMachine-facing tool identifier

Implementation detail: Because the Name is populated from the integration name and cannot be changed after tool creation, give the integration the intended name before registering it as a tool. The Identifier is also immutable after creation, so review it before selecting Create.

Oracle's registration documentation shows a hyphenated Identifier example, such as validate-invoice-data. The complete OIC Identifier validation pattern should not be inferred from the examples alone.

OCI's Python SDK has a separate FunctionDefinition model. Its function name has its own documented validation rule: letters, digits, underscores, or hyphens, with a maximum length of 64 characters.

That OCI SDK naming constraint belongs to the OCI FunctionDefinition contract. Do not automatically assume that it is the complete validation rule for the OIC Identifier field. The use of get-order-status in this tutorial is a hyphenated example, not a claim about every permitted OIC Identifier character.

4.2 Why the Description matters

The Description explains what the tool does and when it should be selected. Oracle documents that the Description is sent to the LLM as part of the system prompt and helps the model decide when to use the tool.

Compare two descriptions:

Ambiguous description

Gets order information.

The description does not clearly distinguish whether this capability retrieves order status, order details, payment information, or shipment information.

Improved description

Retrieves the current status and shipment information for an existing sales order using its order identifier. Use this tool when a user asks whether an order has been processed, shipped, or delivered. This tool only retrieves information and does not create, modify, or cancel orders.

The improved description provides three useful pieces of information:

  1. Capability: Retrieves order status and shipment information.
  2. Selection condition: Use when someone asks about order progress or delivery.
  3. Boundary: Retrieval only; no order modification.

Kid-friendly analogy

Imagine two school helpers. One finds books in the library, while the other changes the library register. If both are simply described as "helps with books," a student may ask the wrong person to perform a task.

In this OCI AI integration, this means: A specific Description gives the LLM better information for distinguishing similar integrations by explaining their business responsibility and intended usage.

Architectural lesson: Tool descriptions should describe business capabilities, not implementation details such as the REST Adapter connection name, integration instance ID, or internal database procedure.

When multiple tools have overlapping responsibilities, describe their differences explicitly. For example:

  • get-order-status retrieves current order and shipment information.
  • update-order-address changes the delivery address after the required business checks.
  • cancel-order requests order cancellation subject to applicable cancellation rules.

These descriptions improve the information available for tool selection. They do not technically enforce authorization or guarantee that the LLM will always select the correct tool.

5. Understanding Parameters and JSON Schema

5.1 What is a tool parameter?

A parameter is an input value required by a tool to perform its operation.

For the order lookup tool, the integration needs an order identifier. Without it, the integration cannot reliably determine which order should be retrieved.

A tool definition must therefore communicate more than the existence of an operation. It must also describe the inputs needed by that operation.

Kid-friendly analogy

Imagine filling in a library request slip. You must provide the book title before the librarian can find the correct book. The librarian should not guess which book you meant.

In this OCI AI integration, this means: The required parameter tells the LLM which input it is expected to provide when requesting the order lookup operation.

5.2 Understanding the parameter structure

JSON Schema is a standard way to describe the expected structure and data types of JSON values.

A function parameter definition can describe:

  • type: The expected data type, such as object or string.
  • properties: The named fields accepted inside an object.
  • required: The names of fields that must be supplied.
  • description: Additional information explaining the meaning of a field.

Here is an illustrative JSON Schema parameter object for the order lookup operation:

{
  "type": "object",
  "properties": {
    "orderId": {
      "type": "string",
      "description": "Unique sales order identifier, such as ORD-45021."
    }
  },
  "required": [
    "orderId"
  ]
}

Interpret the structure:

  • The root value is an object.
  • The object declares an orderId property. The separate required array makes its presence mandatory.
  • The value must be a string.
  • The required array identifies orderId as mandatory.

This schema gives the model a clearer description of the expected argument than a vague instruction such as "provide the order information." It still permits an empty string and additional properties because it declares no minimum string length or restriction on extra fields. Schema keywords also need support from the selected API and model; perform business validation separately.

Important distinction: This is an illustrative JSON Schema representation. It explains the structure of a function definition, but it is not evidence that OIC serializes its registered integration parameters into this exact JSON object. The precise OIC-to-provider representation requires the corresponding generated artifact or request payload.

5.3 What happens when a required input is missing?

Consider two employee requests:

Request A

Check the status of order ORD-45021.

Available input: orderId = "ORD-45021"

Request B

Can you check my order status?

Missing input: No order identifier is supplied.

For Request A, the model has a value from which it can construct the argument.

For Request B, our intended behavior is for the agent to ask which order the employee means. The tool Guidelines can express this requirement, and the behavior should be tested with the configured model.

There is an important OIC-specific detail here. Oracle's parameter documentation says that when a parameter is marked Required, the LLM must assign a value to it. Oracle further documents that this setting ensures there will be a value for that parameter when the AI Agent calls the tool.

This is useful for ensuring parameter presence, but it must not be interpreted as proof that the value is correct, belongs to the requesting employee, or identifies an existing business object. A value can be present and still be wrong.

For production integrations, validate the supplied value independently.

5.4 OIC parameter configuration

OIC provides a parameter configuration table when an integration is registered as an agentic AI tool. Oracle documents that the integration's input parameters are automatically populated in this table and that the tool designer configures how those parameters are presented to the LLM.

The documented settings are:

SettingDocumented purposeOrder lookup decision
VisibleControls whether the parameter is sent to the LLM. Parameters without the Visible checkmark are not sent to the LLM.Enable.
TypeAutomatically populated from the integration.String, assuming that is the integration input type.
RequiredIndicates that the LLM must assign a value. Oracle documents that a value will be present when the agent calls the tool.Enable.
ConstantSpecifies a fixed value for the parameter that the LLM does not decide.Leave empty.
DefaultProvides a configured default when no value is assigned, where a safe fallback is known.Leave empty; do not invent an order ID.
Enum ValuesAllows comma-separated alternatives to be specified when there are several possible values.Not applicable to free-form order identifiers.
DescriptionExplains the parameter to the LLM. Oracle marks this field as required.Explain the identifier and its business meaning.

The table uses Default, the column label described in Oracle's page illustration. The explanatory list on the same page calls it Default Values; these refer to the same fallback-value setting.

Important: Visible and Required are different settings. Visible controls whether a parameter is sent to the LLM. Required communicates that a value must be assigned for the tool call. Do not treat the two settings as interchangeable.

A Required setting also does not automatically mean the model can see or independently determine every possible input. For this example, the order identifier is both Visible and Required. For hidden parameters, do not assume that the LLM can supply a value; determine how the value is obtained and verify the actual configuration.

A Constant or Default is not interchangeable with a model-generated value. Use a Constant for a value the integration should receive without the model deciding it. Use a Default only when the fallback is genuinely safe for the business operation.

Oracle describes Enum Values as comma-separated alternatives that may be sent to the LLM. Do not automatically interpret this setting as a hard validation rule enforced by the backend or as proof that every generated argument will conform to the choices. Validate business-critical values in the integration or target application.

For this order lookup example, the order identifier should be supplied from the employee's request or another established application context. A fixed or generic default would risk querying the wrong order.

See Oracle's parameter configuration documentation.

6. Tool Guidelines Versus Structured Definitions

6.1 Why are Guidelines needed if the parameters already exist?

A structured definition describes the available operation and its inputs. Tool Guidelines provide additional natural-language instructions explaining how and when the tool should be used.

These are complementary mechanisms.

Kid-friendly analogy

A school examination paper contains structured questions with spaces for answers. The teacher also provides instructions such as "Answer every question" and "Do not write outside the boxes." The questions define what must be answered; the instructions explain how to complete the task.

In this OCI AI integration, this means: The parameter definition describes the accepted inputs, while the Guidelines give the LLM additional usage instructions and business context.

6.2 Structured tool definition

For our order lookup tool, the structured portion describes:

  • Tool Identifier: get-order-status.
  • Input property: orderId.
  • Input type: string.
  • Required input: orderId.

This communicates the shape of the request.

6.3 Textual tool Guidelines

Now consider these Guidelines:

Use this tool only when the user asks to retrieve
the status or shipment information of an existing order.

Use an order identifier explicitly supplied by the user
or established in the current conversation.

If the order identifier is missing or ambiguous,
ask the user to clarify before requesting the lookup.

Do not use this tool to create, modify, or cancel orders.

These instructions add selection and usage context that is not expressed merely by declaring a string parameter.

Oracle documents that Guidelines are optional, sent to the LLM as part of the system prompt, and intended to influence tool usage. They can express constraints and corporate-policy-related instructions.

However, there is a critical architectural boundary.

Guidelines are not an authorization mechanism.

A guideline saying "Never access another department's orders" does not independently enforce data isolation. The integration, identity configuration, and target application must enforce the actual authorization rule.

The same applies to read-only instructions. A Description that says an integration only retrieves data does not technically prevent a backend from performing writes if that backend or integration has been incorrectly designed.

Engineering principle: Use structured parameters to describe the input contract, Guidelines to communicate usage expectations, and deterministic application controls to enforce business rules.

7. Provider-Specific Function Definitions and OIC Conversion

7.1 Why does a function definition need a provider-specific format?

Different LLM providers and APIs can expose function-calling capabilities using different request structures and naming conventions.

A definition created for one API should not automatically be assumed to be identical to the representation accepted by another API.

There is an additional distinction that is easy to miss: even one provider can expose more than one function-calling request format. OpenAI Chat Completions and OpenAI Responses API, for example, do not use the same outer structure for a function tool.

The provider-specific examples in this section explain those differences. They are not evidence that OIC uses a particular provider request structure internally.

Kid-friendly analogy

Imagine receiving a shopping list written in English and converting it into a format understood by a different shop's ordering system. The items may remain the same, but the labels and arrangement may need to change.

In this OCI AI integration, this means: A provider adapter can translate a business capability's definition into the structure supported by the selected API. The actual mapping must be established from the implementation, not inferred from similar field names.

7.2 OpenAI Chat Completions-style example

The following is an illustrative OpenAI Chat Completions-style function tool definition for our order lookup capability.

{
  "type": "function",
  "function": {
    "name": "get-order-status",
    "strict": false,
    "description": "Retrieves the current status and shipment information for an existing order using its order identifier.",
    "parameters": {
      "type": "object",
      "properties": {
        "orderId": {
          "type": "string",
          "description": "Unique sales order identifier."
        }
      },
      "required": [
        "orderId"
      ]
    }
  }
}

Notice that this particular representation has two layers:

  1. The outer object identifies the tool type as a function.
  2. The nested function object describes the callable operation and its accepted parameters.

This is a Chat Completions-style representation. It should not be described as the universal format for all OpenAI APIs.

The example explicitly sets strict: false for best-effort argument generation. OpenAI strict mode has additional schema requirements, including additionalProperties: false on each object and making every declared property required. Schema adherence still does not prove that an order exists or that a caller may access it. Do not infer OCI support for every OpenAI strict-mode option from API compatibility alone.

For the current distinction between function-tool formats, see the OpenAI Function Calling guide.

7.3 OCI Generic Chat function definition

OCI's Python SDK documents a FunctionDefinition model for a function that the model may call.

In the OCI SDK reference, the FunctionDefinition model includes:

  • type: The function tool type. The documented value is FUNCTION.
  • name: The name of the function to be called.
  • description: A description used by the model to choose when and how to call the function.
  • parameters: The function's input parameters, described using a JSON Schema object.

The following illustrates the OCI SDK FunctionDefinition model for the same business capability:

{
  "type": "FUNCTION",
  "name": "get-order-status",
  "description": "Retrieves the current status and shipment information for an existing order using its order identifier.",
  "parameters": {
    "type": "object",
    "properties": {
      "orderId": {
        "type": "string",
        "description": "Unique sales order identifier."
      }
    },
    "required": [
      "orderId"
    ]
  }
}

This is an illustrative representation of the OCI SDK model, not evidence that OIC serializes its registered integration tools into exactly this object.

The OCI Python SDK's GenericChatRequest model includes a tools collection. Its documentation describes this as a list of tools the model may call and specifies that a maximum of 128 functions are supported in that collection.

There is an important scope boundary: the SDK model describes an OCI request contract. It does not establish that every OCI model, serving mode, region, or OIC agent configuration supports the same function-calling behavior.

Also note that FunctionDefinition and GenericChatRequest are separate SDK model references. The standalone function-definition example above does not represent a complete Generic Chat HTTP request.

Relevant references:

7.4 Do not confuse OCI Generic Chat with OCI Responses API

The FunctionDefinition and GenericChatRequest SDK references above describe one OCI request-model surface. OCI also provides the Responses API, which is a separate API contract for tool-based and multi-step workflows.

Oracle recommends starting with the Responses API for most new applications using OCI Generative AI's API capabilities. It supports function calling and other documented tool types through its tools property. However, tool and feature availability varies by region and model.

This recommendation concerns the OCI Generative AI API surface. It must not be interpreted as evidence that OIC Project AI Agents internally use the Responses API or that every OIC LLM connection supports every OCI Responses API feature.

The OCI Responses API uses an OpenAI Responses-compatible tool definition. For comparison, the same order lookup capability can be described using this flatter function-tool object. This is an illustrative entry in a request's tools array, not a complete request or an executed OIC-generated payload:

{
  "type": "function",
  "name": "get-order-status",
  "description": "Retrieves the current status and shipment information for an existing order using its order identifier.",
  "parameters": {
    "type": "object",
    "properties": {
      "orderId": {
        "type": "string",
        "description": "Unique sales order identifier."
      }
    },
    "required": [
      "orderId"
    ]
  }
}

For a direct OCI implementation, configure OCI authentication and project context, choose a supported model and region, and implement the function execution loop before using this definition. OpenAI documents API-specific strict-mode defaults; this fragment does not establish the selected OCI model's schema-enforcement behavior.

Notice the difference from the earlier Chat Completions-style example: the function's name, description, and parameters appear directly in the tool object rather than inside a nested function object.

Oracle's function-calling documentation also explains the execution responsibility in this direct API pattern: the model returns a function name and arguments, the application runs the function, and the application sends the result back so the model can continue.

This is an important distinction when comparing the two environments:

  • Direct OCI Responses API implementation: The application calling the API is responsible for implementing the requested function and returning its result.
  • OIC project AI Agent: A registered integration is made available as an agentic AI tool, and OIC's agent runtime handles the integration invocation.

The direct API example does not establish which endpoint, SDK, or internal conversion path OIC uses for its registered tools.

Read the OCI Responses API documentation and Oracle's Quick Start Guide — Function Calling section.

7.5 Comparing the documented representations

ConceptOpenAI Chat Completions-styleOCI Generic Chat SDK modelOCI Responses API
Tool typetype: functiontype: FUNCTIONtype: function
Function namefunction.namenamename
Descriptionfunction.descriptiondescriptiondescription
Parameter schemafunction.parametersparametersparameters
Request modelChat CompletionsOCI GenericChatRequest SDK modelOCI Responses API

The important observation is that the business meaning can remain the same while the request envelope and field placement change.

7.6 Documented visibility and the boundary of API evidence

In OIC, configure parameter exposure using the documented Visible checkbox in Parameters configuration. Oracle describes this as controlling which input fields are sent to the LLM. It is an OIC registration setting, not a field you must add to the provider examples above.

The public registration page does not specify the internal serialization or provider transformation used to implement that setting. Do not infer that implementation from a checkbox label or from similar JSON field names.

The Retrieve an Agent Tool in a Project API documents parameters as an object that permits additional properties. That openness does not establish any particular nested property, its meaning, or how a provider adapter processes it.

For an authorized inspection, the documented resource path is GET /ic/api/integration/v1/projects/{projectId}/ai/tools/{id}, with the required integrationInstance query parameter and no request body. Obtain the actual project and tool resource identifiers from your environment. The response separately defines id and code; the inspected reference does not establish that either one is interchangeable with the UI Identifier.

Evidence boundary: A retrieved registration object can show saved configuration. It cannot, by itself, prove what was sent to the model. That requires the relevant generated request or implementation evidence, which was not supplied. This tutorial therefore makes no claim about an internal OIC conversion algorithm.

7.7 Format conversion is not full schema validation

This is a particularly important distinction.

Format conversion changes the representation of a definition so that it follows the target provider's structure.

Schema validation checks whether the definition and its arguments conform to the applicable contract.

For example, a provider-specific definition might contain:

{
  "type": "FUNCTION",
  "name": "get-order-status",
  "description": "Retrieves order status.",
  "parameters": {
    "type": "object",
    "properties": {
      "orderId": {
        "type": "string"
      }
    },
    "required": [
      "orderId"
    ]
  }
}

The presence of this structure does not prove all of the following:

  • Every source field was preserved correctly.
  • Every required field was interpreted correctly.
  • All unsupported schema keywords were handled correctly.
  • The selected model supports every schema feature.
  • The model will always generate valid arguments.
  • The integration will accept the generated values.

OCI's SDK describes parameters as a JSON Schema object. That establishes the intended parameter representation, but it does not establish that a specific OIC converter performs comprehensive validation of every JSON Schema feature.

For a robust implementation, perform separate checks:

  1. Validate the source definition against its intended source contract.
  2. Validate the converted structure against the selected target contract and supported schema features.
  3. Test generated arguments against the integration's actual input contract.
  4. Validate business values inside the integration or target application.

Remember: A definition that looks correct in JSON is not proof of a successful tool invocation.

8. Practical Prototype: Define an Order Lookup Tool

Now we will apply the concepts to a small procurement and order-management example.

8.1 Define the business capability first

Our requirement is straightforward:

Business requirement

An employee should be able to ask an AI Agent for the current status of an existing sales order. The agent should identify the requested order and use the lookup capability to retrieve its status.

Before registering the integration, define its expected request. In this fictional example, a procurement employee is checking a supplier-facing sales order; the identifier is not an Oracle Procurement purchase-order schema. The chosen POST operation only retrieves data in the intended implementation. POST by itself does not imply a write operation.

{
  "orderId": "ORD-45021"
}

The integration's response contract can use a synthetic result such as:

{
  "orderId": "ORD-45021",
  "orderStatus": "SHIPPED",
  "shipmentStatus": "IN_TRANSIT"
}

These are tutorial-defined example contracts, not Oracle-provided order-management schemas or evidence of a live backend. SHIPPED and IN_TRANSIT are illustrative business codes: they do not mean the order has been delivered. Define the real status vocabulary and error contract with your backend team before implementation.

8.2 Prepare the OIC integration

Environment prerequisites: Confirm authorized access to the project and a licensed edition that includes Agentic AI. Oracle's edition comparison lists Agentic AI for Enterprise and Healthcare, and excludes it from Standard. The current AI Feature Availability page lists Agentic AI in all regions; do not confuse this with the narrower region coverage of some AI assistant features. A separately selected OCI model or API still has its own availability requirements.

Oracle's registration documentation specifies the following prerequisites for an integration to be registered as an agentic AI tool:

  • The integration belongs to a project.
  • The integration is Active.
  • The first connection in the integration is a REST trigger connection using the REST Adapter.
  • The REST trigger uses OAuth authentication.
  • The REST trigger uses a JSON payload.
  • The REST trigger uses a verb supported by the REST Adapter: GET, POST, PUT, DELETE, or PATCH.

For this prototype, we will choose a POST request with a JSON input containing the orderId string and a JSON response containing the order status.

Documentation discrepancy: The general registration page permits the REST verbs listed above, while Create the Integration: Auto Approve Expense Report and the AI Agent build sequence state a POST requirement. These sources do not fully reconcile the broader registration rule with the native AI Agent tutorial. This prototype uses POST with JSON input and output, which fits both. Do not infer from the broader page that every verb has been verified in the native agent workflow. Other verbs require confirmation for the intended tenant and agent path.

The order-management lookup itself is outside this article's deployment boundary. Before registration, implement and directly test the integration against an approved backend or a clearly labelled mock. Check that the received order identifier reaches the lookup, that the response maps the returned identifier and statuses, and that invalid input, not-found results, authorization failures and backend faults have defined outcomes. Do not return the sample status as though it came from a live order system.

8.3 Register the integration as a tool

Follow this documented navigation path:

  1. In the OIC navigation pane, select Projects.
  2. Select the project in which your integration is located.
  3. In the Integrations section, find the integration.
  4. Confirm that the integration is Active. If it is not, use its Actions menu and select Activate.
  5. Open the integration's Actions menu.
  6. Select Create agentic AI tool.
  7. In the Create Tool panel, enter the Identifier and Description. The Name is populated from the integration name.
  8. Select Create.
  9. Review the tool details, including its Description, Guidelines, and Parameters configuration.
  10. Configure the required settings and select Save.

These labels and registration steps follow Oracle's published OIC procedure: Register an Integration as an Agentic AI Tool.

Use the following metadata for the prototype:

FieldPrototype value
Integration nameLookup Order Status
Tool NameReview the value populated from Lookup Order Status; use the exact displayed value.
Identifierget-order-status
DescriptionRetrieves the current status and shipment information for an existing sales order using its order identifier. Use this tool when the user asks about order processing, shipment, or delivery. This tool only retrieves information and does not create, modify, or cancel orders.

Name configuration: Choose a meaningful integration name before registration, then review the populated tool Name. Oracle documents that the tool Name cannot be changed after creation. The inspected page does not specify every normalization rule, so this article does not promise an exact generated spelling.

Identifier configuration: Oracle documents that the Identifier is automatically populated from the tool Name by default and cannot be changed after creation. Review it carefully and enter the intended value before selecting Create.

8.4 Configure the parameter

After the tool is created, inspect its Parameters configuration section.

For this example, assume that the integration's generated input parameter is named orderId and has type String. Confirm that this is actually what appears in your tool's parameter table. The precise generated parameter names depend on the integration's input definition and design; they cannot be established from the example JSON alone.

For orderId, configure:

  • Visible: Enabled.
  • Type: String, if that is the type populated from the integration.
  • Required: Enabled.
  • Constant: Empty.
  • Default: Empty.
  • Enum Values: Empty.
  • Description: Unique sales order identifier supplied by the user, such as ORD-45021. Do not invent an identifier if it is missing.

The intended business mapping is:

Business inputTool parameterOIC integration input
Sales order numberorderIdorderId, provided the generated integration input has that exact name

If OIC displays a different generated input parameter name, use that actual name when describing and configuring the tool. Do not assume that every request-body property becomes an identically named tool parameter without inspecting the integration's generated inputs.

Save the tool configuration.

At this point, the tool definition describes the capability and its inputs. Saving it does not establish that the underlying order lookup has successfully executed.

8.5 Add a usage guideline

Use the following guideline for this prototype:

Use this tool only to retrieve information about an
existing order.

Use an order identifier explicitly provided by the user
or already established in the current conversation.

If the identifier is missing or ambiguous, ask for
clarification instead of guessing.

Do not use this tool to create, update, or cancel orders.

Save the configuration. The Description explains what the tool does, while the Guidelines explain how the agent should use it.

These instructions influence the LLM's decision process. They are not a replacement for integration-level validation or authorization.

8.6 Compare the precise and ambiguous definitions

Now consider a second hypothetical definition:

Ambiguous version

Identifier: lookup

Description: Gets order details.

Parameter: id

Parameter Description: Empty

What is missing?

  • The Identifier does not clearly identify the operation.
  • The Description does not distinguish order status from other order information.
  • The parameter name id does not explain which identifier is expected.
  • The parameter Description does not explain its meaning or format.
  • The definition does not clearly communicate the mandatory input.

The empty parameter Description makes this hypothetical version incomplete under Oracle's documented required fields. It is not a second valid OIC configuration to save unchanged. Even if a tenant allows saving it, that would not make it a well-described tool. Compare selection behavior only after supplying all required metadata.

8.7 Inspect the expected model-facing argument

For the request:

What is the delivery status of order ORD-45021?

A representative argument object is:

{
  "orderId": "ORD-45021"
}

Interpretation:

  • The intended operation is the order lookup capability identified by get-order-status.
  • The argument supplies the required order identifier.
  • The intended mapping passes that value to the corresponding integration input; verify the actual received payload during testing.

This is a representative expected argument, not an observed execution trace or a guarantee that every model will generate exactly this value.

8.8 What happens if the model supplies a wrong argument?

Suppose the model produces:

{
  "orderId": "ORD-4502"
}

The JSON is structurally valid. The value is a string. The required property is present.

But it might be the wrong order number.

This demonstrates three different levels of correctness:

  1. Structural correctness: Does the argument match the expected JSON structure?
  2. Business correctness: Does the identifier refer to the intended order?
  3. Execution correctness: Did the backend retrieve the correct order successfully?

One level does not prove the next. A production integration must validate the identifier and enforce the caller's access rights before returning business data.

8.9 Associate the tool before testing an agent

A saved tool is not automatically available to every agent. For a native OIC project AI Agent, first configure and activate an appropriate thinking pattern and its LLM connection using Oracle's Configure the Agentic AI Thinking Pattern. ReAct means reasoning and acting in repeated steps. The page distinguishes ReAct for OCI GenAI from the ReAct recipe for other providers; select the recipe that matches the intended provider. This article does not supply connection credentials or a verified tenant configuration.

Oracle's Add and Configure the AI Agent documents creating the agent within the project's AI Agents area, selecting an already activated Thinking pattern, and configuring the agent's Role and Guidelines. On its details page, under Tools, click +, select the registered order lookup tool, click Add, and click Save. Return with Back; in the Agents box, use Actions → Activate. These are documented steps, not observations from your tenant.

Identity check: Decide how the integration identifies the employee and authorizes access to the requested order. An order ID in conversation is not proof of ownership. Do not assume that the employee's identity automatically propagates to a backend connection that uses a shared service account.

Use this when: You want a native OIC agent to choose among registered integrations. A direct OCI API application has its own setup and execution responsibilities; the provider examples in section 7 are not a substitute for this OIC configuration.

9. How to Evaluate a Tool Definition

A useful tool definition should be assessed from the perspective of the information the model needs to select the correct operation and construct its arguments.

Use this assessment table when reviewing a newly registered tool:

Review areaQuestionExpected evidence
IdentifierDoes it identify the business operation?Stable, distinct identifier.
DescriptionDoes it explain what the tool does and when to use it?Specific capability and usage conditions.
Parameter visibilityCan the model see the inputs it must supply?Relevant parameters marked Visible.
Parameter typeDoes each input have the correct type?Matches the integration input type.
Required inputsAre mandatory values identified?Required configuration and an appropriate input contract.
Parameter descriptionsDoes the model understand each field?Business meaning and useful constraints.
GuidelinesAre tool-selection boundaries clear?Appropriate usage instructions.
Execution controlsAre authorization and business rules enforced?Independent integration and target-system controls.

9.1 Why valid definitions do not guarantee successful execution

Consider this sequence:

  • The tool has a valid identifier.
  • The Description clearly explains its purpose.
  • The required parameter is configured.
  • The model generates a structurally valid argument.

Even then, the integration might fail because:

  • The supplied order does not exist.
  • The caller is not authorized to retrieve that order.
  • The backend system is unavailable.
  • The integration has a mapping defect.
  • The target application rejects the request.

Tool definitions improve the information available to the model. They do not replace the enterprise controls that protect and operate business integrations.

10. Testing and Troubleshooting

10.1 Where to test an OIC AI Agent

Registering a tool is not the same as executing it. To test the behavior of an agent using the tool, you must first have an activated AI Agent configured with its LLM connection, activated thinking pattern, and associated tools, as explained in section 8.9.

Oracle's published Run and Test procedure provides this navigation path:

  1. In the navigation pane, select Projects.
  2. Select the project containing your AI Agent.
  3. In the left navigation pane, select AI Agents.
  4. In the Agents box, find the agent you want to test.
  5. Open its Actions menu and select Run.
  6. On the Test Agent page, enter a natural-language prompt and submit it to the agent.
  7. Inspect the actions displayed after the run.

Oracle documents the following action information on the Test Agent page:

  • System: Shows information sent to the LLM in the system prompt. Oracle's documented example includes the agent role, agent Guidelines, and AI Agent pattern Guidelines.
  • User: Shows the prompt entered by the user.
  • Tool: Shows the response returned by the tool.
  • Assistant: Shows the assistant output and explanation displayed by the configured pattern. Oracle's tutorial calls this agent reasoning; it is not proof that the interface exposes the model's complete internal reasoning.

Oracle also documents the following monitoring procedure:

  1. From the Test Agent page, click Back to return to the AI Agents page.
  2. Select Observe.
  3. In Integrations, check the integrations that ran.
  4. Inspect the Received, Processed, Succeeded, Errored, and Aborted information.
  5. If an error is reported, click its Errored count to open the Instances tab.
  6. In the Instances tab, select View Details to inspect the error description.

The Observe view may include both the business integration and system-generated integrations used in the agent workflow. Oracle's guided example, for instance, displays ReAct Pattern Intg and Get Tool Data Intg alongside the registered business integration. Treat these names as examples from that documented workflow, not as a guarantee that every project will show exactly the same integration names.

See Oracle's Run and Test the AI Agent documentation for the published test and monitoring procedure.

10.2 Test the definition with representative requests

Use a small test set to evaluate whether the agent has enough information to select the order lookup tool and construct its arguments.

CaseExpected behavior to testEvidence to inspect
Explicit order IDSelect lookup and supply the provided ID.Selected tool, argument value, and tool result.
Missing order IDAsk the employee for clarification rather than inventing an ID.Agent response and whether a tool call was incorrectly generated.
Ambiguous order referenceAsk which order is intended.Clarification behavior and generated arguments, if any.
Request to cancel an orderDo not treat the read-only lookup as a cancellation operation.Tool selection and the agent's response.
Malformed identifierReject or request correction according to the integration contract.Integration validation and fault evidence.
Valid-looking but nonexistent IDReturn the backend's not-found outcome without inventing order data.Backend response and agent interpretation.
Unauthorized order IDDo not disclose order information when the caller lacks access.Authorization decision and integration/backend evidence.

For each test, record the prompt, selected tool and available argument evidence, the relevant integration instance, its outcome, and the returned result. Use New run for independent cases. A total Succeeded count alone does not prove that the intended order ID was used or that the business result was correct. If arguments or payloads are not exposed by your configuration, record that verification gap rather than treating assistant text as execution evidence.

Execution status: Not executed. These are prescribed test cases and expected observations, not claimed runtime results. In particular, asking for clarification when an identifier is missing is a behavior to test with the configured agent; it is not a guaranteed outcome merely because the parameter is Required.

10.3 Troubleshooting common definition problems

SymptomPossible causeTargeted correction
Wrong tool selectedOverlapping descriptions or unclear identifiers.Differentiate business responsibilities and retest similar requests.
Missing argumentParameter is hidden, has unclear metadata, or is not configured as required.Review Visible, Required, and the parameter Description.
Incorrect argumentWeak parameter description or ambiguous user request.Clarify the parameter meaning and add integration validation.
Tool used for the wrong purposeInsufficient Description or Guidelines.Explain when the tool should and should not be selected.
Conversion discrepancyProvider-specific mapping or an unsupported schema feature.Inspect the source definition, conversion evidence, and serialized target definition.
Valid argument but failed integrationBackend, authorization, mapping, or business-validation failure.Inspect OIC instance tracking and the target response.

11. Completion Checklist and What Comes Next

Before considering the tool-definition exercise complete, verify the following:

  • The business capability is clearly defined.
  • The integration name is set before tool creation.
  • The tool has a meaningful machine Identifier.
  • The Description explains what the integration does and when to use it.
  • The exposed parameters are relevant to the model's task.
  • The mandatory order identifier is configured as Required and Visible.
  • The parameter type matches the integration input contract.
  • The parameter Description explains its business meaning.
  • The Guidelines communicate the intended usage boundaries.
  • Integration and target-system authorization are enforced independently.
  • The ambiguous definition has been compared against the precise version.
  • Provider conversion claims have been separated from verified target-contract facts.
  • The registered tool is associated with the intended agent, and its thinking pattern and agent are activated.
  • Representative requests have been tested using the configured AI Agent.
  • Tool results and integration execution evidence have been inspected.

12. Five Useful FAQs

1. Does the LLM execute an OIC integration directly?

No. The LLM receives information describing available capabilities and may request a tool call with arguments. In OIC project AI Agents, the OIC agent runtime handles invocation of the registered integration. The integration performs the business operation. Model selection is not the same as successful integration execution.

2. What is the difference between Name and Identifier in OIC tool registration?

Name is the required management-facing label automatically populated from the integration name. Oracle documents that it is not sent to the LLM and cannot be changed after tool creation. Identifier uniquely identifies the tool within the project and is sent as tool metadata. Oracle also documents that Identifier cannot be changed after creation.

3. Are tool Guidelines the same as parameter definitions?

No. Parameter configuration describes the inputs and their requirements. Guidelines are natural-language instructions that influence when and how the agent should use the tool. Neither should replace deterministic authorization and business validation.

4. Does converting an OpenAI-style function definition to OCI format guarantee that it is valid?

No. First identify the relevant API contract. OpenAI Chat Completions, OpenAI Responses API, OCI Generic Chat SDK, and OCI Responses API do not all use the same function-definition envelope. Conversion and validation are separate concerns. A definition must conform to the selected API contract and supported features. OIC's exact conversion behavior must be established from the relevant implementation evidence.

5. Does a Required parameter guarantee that the LLM will always provide a correct value?

No. Oracle documents that Required indicates that the LLM must assign a value and ensures that a value is present when the AI Agent calls the tool. It does not prove that the value identifies the intended business object, that the object exists, or that the caller is authorized to access it. Validate the value in the integration and target application.

13. Official References

The following primary documentation pages were inspected for the documented OIC, OCI, and OpenAI behavior discussed in this article.

  1. Oracle Integration 3 — Register an Integration as an Agentic AI Tool
    Open official documentation
    Registration prerequisites, project membership, Active status, REST trigger requirements, registration navigation, Name, Identifier, Description, Guidelines, Visible, Type, Required, Constant, Default, Enum Values, and parameter descriptions.
  2. Oracle Integration 3 — Run and Test the AI Agent
    Open official documentation
    Test Agent navigation, action information displayed in the test interface, and integration execution monitoring.
  3. Oracle Integration 3 — Steps to Build an AI Agent
    Open official documentation
    Overall AI Agent build sequence and the POST/JSON integration design used in Oracle's guided workflow.
  4. Oracle Integration 3 — Retrieve an Agent Tool in a Project
    Open official REST API reference
    Agent Tool resource and response properties, including name, code, description, guidelines, parameters, annotations, and endpoint URL. The path parameter id is described as the Agent Tool identifier, while the response schema separately identifies the code property as Tool code. The API operation also requires the integrationInstance query parameter.
  5. OCI Generative AI — FunctionDefinition
    Open official OCI SDK reference
    OCI SDK function-definition fields, the FUNCTION type, function-name restrictions, and JSON Schema parameter representation. The inspected reference displayed SDK version 2.190.0.
  6. OCI Generative AI — GenericChatRequest
    Open official OCI SDK reference
    The Generic Chat request model, its tools collection, and its documented 128-function limit. The inspected reference displayed SDK version 2.190.0.
  7. OCI Generative AI — Responses API
    Open official documentation
    OCI Responses API purpose, OpenAI compatibility, supported tool types, authentication, model and regional availability considerations, and the separation between API request structure and application-managed function execution.
  8. OCI Generative AI — Quick Start Guide (Function Calling section)
    Open official documentation
    Function-calling execution flow, function tool definitions, application responsibility for function execution, and returning the function result to the model.
  9. Oracle Integration 3 — Create the Integration: Auto Approve Expense Report
    Open official documentation
    POST/JSON trigger design, response mapping, and the narrower POST requirement stated by the native-agent tutorial.
  10. Oracle Integration 3 — Configure the Agentic AI Thinking Pattern
    Open official documentation
    Thinking-pattern activation and provider-specific ReAct recipe distinctions.
  11. Oracle Integration 3 — Add and Configure the AI Agent
    Open official documentation
    Activated thinking-pattern prerequisite, agent Role and Guidelines, tool association, and agent activation.
  12. Oracle Integration 3 — Editions and AI Feature Availability
    Edition comparison; AI Feature Availability
    Agentic AI licensing and region coverage, distinguished from AI assistant and model-specific availability.
  13. OpenAI API — Function Calling
    Open official documentation
    Provider-specific function-calling examples and the distinction between Chat Completions-style and Responses API tool structures, including strict-mode considerations.

14. Finally — Summary

A tool definition provides the information an LLM needs to understand which business capabilities are available and what arguments those capabilities require. In OIC Gen3, the registered tool has a Name, Identifier, Description, optional Guidelines, and configured parameters. The management-facing Name is not sent to the LLM, while the Identifier is supplied as tool metadata.

Structured parameter configuration communicates input requirements. Visible determines which parameters are sent to the LLM, while Required communicates the value requirement and ensures a value is present when the agent calls the tool. Guidelines add natural-language usage instructions, but they do not enforce authorization or business rules.

Provider-specific function definitions must also be treated carefully. OpenAI Chat Completions, OpenAI Responses API, OCI Generic Chat SDK, and OCI Responses API have distinct request contracts. Configure parameter exposure with the documented Visible setting. The internal mapping from saved OIC metadata to a provider request is not established by the examples in this article.

The order lookup design demonstrates why precise identifiers, descriptions, and required inputs matter. However, correct-looking metadata does not guarantee correct arguments or successful execution. Validate each layer independently. That is the foundation for understanding how OIC ReAct agents select tools, execute integrations, and use the returned results.

Comments