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
- What You Will Build
- What Is a Tool Definition?
- Understanding Tool Names and Descriptions
- Understanding Parameters and JSON Schema
- Tool Guidelines Versus Structured Definitions
- Provider-Specific Function Definitions and OIC Conversion
- Practical Prototype: Order Lookup Tool
- How to Evaluate a Tool Definition
- Testing and Troubleshooting
- Completion Checklist and What Comes Next
- Five Useful FAQs
- Official References
- Finally — Summary
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:
Check delivery status of ORD-45021
↓
Identifier metadata, Description, Guidelines and exposed parameters
↓
A request for the order lookup operation with orderId = ORD-45021
↓
Handles invocation of the registered integration
↓
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:
- Whether the order lookup tool is relevant to the employee's request.
- Whether it has enough information to construct the required
orderIdargument.
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 field | Example value | Purpose |
|---|---|---|
| Name | Lookup Order Status | Human-readable tool label, populated from the integration name |
| Identifier | get-order-status | Machine-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:
- Capability: Retrieves order status and shipment information.
- Selection condition: Use when someone asks about order progress or delivery.
- 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-statusretrieves current order and shipment information.update-order-addresschanges the delivery address after the required business checks.cancel-orderrequests 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
objectorstring. - 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
orderIdproperty. The separaterequiredarray makes its presence mandatory. - The value must be a string.
- The
requiredarray identifiesorderIdas 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:
| Setting | Documented purpose | Order lookup decision |
|---|---|---|
| Visible | Controls whether the parameter is sent to the LLM. Parameters without the Visible checkmark are not sent to the LLM. | Enable. |
| Type | Automatically populated from the integration. | String, assuming that is the integration input type. |
| Required | Indicates that the LLM must assign a value. Oracle documents that a value will be present when the agent calls the tool. | Enable. |
| Constant | Specifies a fixed value for the parameter that the LLM does not decide. | Leave empty. |
| Default | Provides a configured default when no value is assigned, where a safe fallback is known. | Leave empty; do not invent an order ID. |
| Enum Values | Allows comma-separated alternatives to be specified when there are several possible values. | Not applicable to free-form order identifiers. |
| Description | Explains 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:
- The outer object identifies the tool type as a function.
- The nested
functionobject 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 isFUNCTION.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
| Concept | OpenAI Chat Completions-style | OCI Generic Chat SDK model | OCI Responses API |
|---|---|---|---|
| Tool type | type: function | type: FUNCTION | type: function |
| Function name | function.name | name | name |
| Description | function.description | description | description |
| Parameter schema | function.parameters | parameters | parameters |
| Request model | Chat Completions | OCI GenericChatRequest SDK model | OCI 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:
- Validate the source definition against its intended source contract.
- Validate the converted structure against the selected target contract and supported schema features.
- Test generated arguments against the integration's actual input contract.
- 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:
- In the OIC navigation pane, select Projects.
- Select the project in which your integration is located.
- In the Integrations section, find the integration.
- Confirm that the integration is Active. If it is not, use its Actions menu and select Activate.
- Open the integration's Actions menu.
- Select Create agentic AI tool.
- In the Create Tool panel, enter the Identifier and Description. The Name is populated from the integration name.
- Select Create.
- Review the tool details, including its Description, Guidelines, and Parameters configuration.
- 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:
| Field | Prototype value |
|---|---|
| Integration name | Lookup Order Status |
| Tool Name | Review the value populated from Lookup Order Status; use the exact displayed value. |
| Identifier | get-order-status |
| Description | Retrieves 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 input | Tool parameter | OIC integration input |
|---|---|---|
| Sales order number | orderId | orderId, 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
iddoes 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:
- Structural correctness: Does the argument match the expected JSON structure?
- Business correctness: Does the identifier refer to the intended order?
- 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 area | Question | Expected evidence |
|---|---|---|
| Identifier | Does it identify the business operation? | Stable, distinct identifier. |
| Description | Does it explain what the tool does and when to use it? | Specific capability and usage conditions. |
| Parameter visibility | Can the model see the inputs it must supply? | Relevant parameters marked Visible. |
| Parameter type | Does each input have the correct type? | Matches the integration input type. |
| Required inputs | Are mandatory values identified? | Required configuration and an appropriate input contract. |
| Parameter descriptions | Does the model understand each field? | Business meaning and useful constraints. |
| Guidelines | Are tool-selection boundaries clear? | Appropriate usage instructions. |
| Execution controls | Are 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:
- In the navigation pane, select Projects.
- Select the project containing your AI Agent.
- In the left navigation pane, select AI Agents.
- In the Agents box, find the agent you want to test.
- Open its Actions menu and select Run.
- On the Test Agent page, enter a natural-language prompt and submit it to the agent.
- 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:
- From the Test Agent page, click Back to return to the AI Agents page.
- Select Observe.
- In Integrations, check the integrations that ran.
- Inspect the Received, Processed, Succeeded, Errored, and Aborted information.
- If an error is reported, click its Errored count to open the Instances tab.
- 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.
| Case | Expected behavior to test | Evidence to inspect |
|---|---|---|
| Explicit order ID | Select lookup and supply the provided ID. | Selected tool, argument value, and tool result. |
| Missing order ID | Ask the employee for clarification rather than inventing an ID. | Agent response and whether a tool call was incorrectly generated. |
| Ambiguous order reference | Ask which order is intended. | Clarification behavior and generated arguments, if any. |
| Request to cancel an order | Do not treat the read-only lookup as a cancellation operation. | Tool selection and the agent's response. |
| Malformed identifier | Reject or request correction according to the integration contract. | Integration validation and fault evidence. |
| Valid-looking but nonexistent ID | Return the backend's not-found outcome without inventing order data. | Backend response and agent interpretation. |
| Unauthorized order ID | Do 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
| Symptom | Possible cause | Targeted correction |
|---|---|---|
| Wrong tool selected | Overlapping descriptions or unclear identifiers. | Differentiate business responsibilities and retest similar requests. |
| Missing argument | Parameter is hidden, has unclear metadata, or is not configured as required. | Review Visible, Required, and the parameter Description. |
| Incorrect argument | Weak parameter description or ambiguous user request. | Clarify the parameter meaning and add integration validation. |
| Tool used for the wrong purpose | Insufficient Description or Guidelines. | Explain when the tool should and should not be selected. |
| Conversion discrepancy | Provider-specific mapping or an unsupported schema feature. | Inspect the source definition, conversion evidence, and serialized target definition. |
| Valid argument but failed integration | Backend, 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.
- 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. - 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. - 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. - 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 parameteridis described as the Agent Tool identifier, while the response schema separately identifies thecodeproperty as Tool code. The API operation also requires theintegrationInstancequery parameter. - OCI Generative AI — FunctionDefinition
Open official OCI SDK reference
OCI SDK function-definition fields, theFUNCTIONtype, function-name restrictions, and JSON Schema parameter representation. The inspected reference displayed SDK version 2.190.0. - 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. - 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. - 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. - 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. - Oracle Integration 3 — Configure the Agentic AI Thinking Pattern
Open official documentation
Thinking-pattern activation and provider-specific ReAct recipe distinctions. - 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. - 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. - 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
Post a Comment