PeopleSoft APIs as tools

The Assistant can only do what its tools allow. Each tool is one operation of a PeopleSoft application service, and the tool catalog lists the operations the Assistant may use. If a question needs data that no tool provides, the Assistant says so, and points the user to the page where they can find it.

Where tools come from

The Application Services Framework (ASF) generates an OpenAPI description for each application service. The Assistant service reads those descriptions, and turns each operation you list in the catalog into a tool:

In the OpenAPI description	In the tool
The operation’s summary and description	The tool’s description, which the LLM reads to decide when to use it
The operation’s query and path parameters	The tool’s input schema
The operation’s method and path	The request the service makes when the LLM calls the tool

The LLM sees each tool as a name, a description, and an input schema in JSON Schema. The service converts them to the format your LLM provider expects.

The tool catalog

The catalog is a file that names each tool, the operation behind it, and the progress message the chat page shows while it runs:

tools.yaml

services:
  # OpenAPI descriptions downloaded from ASF, so the
  # tool set only changes when you change this file
  - openapi: specs/zz_assistant_hr.json
  - openapi: specs/zz_assistant_fin.json

tools:
  get_absence_balances:
    operation: GET /absence/balances
    progress: Checking your absence balances
  find_page:
    operation: GET /navigation/pages
    progress: Looking for the right page
  list_pending_approvals:
    operation: GET /approvals
    progress: Looking for approvals waiting on you
  get_requisition_status:
    operation: GET /requisitions/{requisitionId}
    progress: Looking up the requisition

The service accepts only GET operations as tools, so no tool can change data. Changes happen on PeopleSoft pages, where the user reviews and saves them.

An example tool

Here’s get_absence_balances as the LLM sees it, built from the operation’s OpenAPI description:

The tool definition

{
  "name": "get_absence_balances",
  "description": "Get the signed-in user's absence balances, in hours, as of today. Use it for questions about how much time off the user has left.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "plan": {
        "type": "string",
        "description": "Only this absence plan, such as Vacation"
      }
    },
    "additionalProperties": false
  }
}

The application service returns only what the answer needs, and a link to the page with the details:

The result

{
  "balances": [
    { "plan": "Vacation", "hours": 46.5, "asOf": "2026-09-24" },
    { "plan": "Sick", "hours": 30, "asOf": "2026-09-24" }
  ],
  "page": {
    "label": "Absence Balances",
    "url": "https://hr.example.com/psc/ps/EMPLOYEE/HRMS/c/ZZ_ABSENCE.ZZ_ABS_BAL_FL.GBL"
  }
}

The application class behind the operation builds the link with PeopleCode’s GenerateComponentContentURL function, so it points to the right portal and node.

Rules for good tools

• One kind of question per tool. get_absence_balances is easier for the LLM to choose, and easier to secure, than a general “get HR data” tool. Each tool is one permission-list decision.
• Read-only. Tools read; people change data on PeopleSoft pages.
• Scoped to the user. Tools about the user’s own data take no employee ID: the token says who the user is. Tools that take one, such as a manager’s view of a team member, rely on the API to check that the user may see that person.
• Only what the answer needs. Return a few fields, not whole records. Smaller results cost less, answer faster, and send less personal data to the LLM.
• A link to the page. Include the page where the user can see more, or make the change the question was leading to.
• Written for the LLM. Say when to use the tool and what it returns, including units, such as hours or days, and dates, such as “as of today”.
• Clear errors. An error such as “This user has no absence plans” lets the LLM give a useful answer.

The example catalog

Tool	Answers questions like
get_absence_balances	“How many vacation hours do I have left?”
find_page	“Where do I update my direct deposit?”
list_pending_approvals	“Which of my team’s timesheets are still waiting for approval?”
get_requisition_status	“What’s the status of requisition 0000012345?”
list_purchase_orders	“Show me the open purchase orders for Acme Corporation.”
describe_field	“What does this field mean?”, from a Magic Button

find_page is the tool behind navigation questions. Its application service searches the portal registry for pages whose labels match the question, and returns only the pages the user is authorized to open, with their URLs.

Add a tool

1. Build the API. Create a GET operation in an application service. It should return what the answer needs, apply row-level security, and include a page link.

2. Secure it. Add the application service to the permission lists of the roles that should use it. Users without access get an error, which the Assistant explains.

3. Update the catalog. Download the service’s OpenAPI description into specs/, and add the tool to tools.yaml with its operation and progress message.

4. Check the description. Read the tool’s description as the LLM will see it. Is it clear when to use this tool rather than another?

5. Test it. Ask questions as users with different roles, including one without access, and check the answers and the audit log.

Keep the catalog small

Every tool definition is sent to the LLM with every question. A catalog of tens of focused tools works well; hundreds make it harder for the LLM to choose, and cost more per question. Retire tools that the audit log shows nobody uses.