Tools reference

The AI Assist MCP server exposes eleven tools. All of them are read-only, and each one answers a specific kind of question about your PeopleSoft system. This section documents every tool in detail: its inputs, its output, the PeopleTools tables it reads, the SQL it runs, and its limits.

Tools at a glance

Tool	Answers questions like	Reads
search_definitions	“Which component opens when I click Job Data?”	PSRECDEFN, PSPNLGRPDEFN, PSPRSMDEFN, and other definition tables
describe_record	“What are the keys of the JOB record?”	PSRECDEFN, PSRECFIELD, PSDBFIELD, PSINDEXDEFN, PSKEYDEFN, PSPNLFIELD
describe_component	“Which pages and PeopleCode make up this component?”	PSPNLGRPDEFN, PSPNLGROUP, PSPNLFIELD, PSMENUITEM, PSPRSMDEFN, PSPCMPROG
describe_app_engine	“What does this Application Engine program do?”	PSAEAPPLDEFN, PSAESECTDEFN, PSAESTEPDEFN, PSAESTMTDEFN, PSSQLTEXTDEFN
get_peoplecode	“Show me the FieldChange code on JOB.DEPTID.”	PSPCMTXT, PSPCMPROG
get_sql	“What’s the SQL behind this view?”	PSSQLDEFN, PSSQLTEXTDEFN
search_code	“Where is VOUCHER_LINE referenced?”	PSPCMTXT, PSSQLTEXTDEFN
find_references	“Which pages and components use this record?”	PSPNLFIELD, PSPNLGROUP, PSPNLGRPDEFN, PSRECFIELD, PSRECDEFN, PSQRYRECORD, PSQRYFIELD
get_translate_values	“What are the valid values of EMPL_STATUS?”	PSXLATITEM
get_security	“Which roles can open this component?”	PSMENUITEM, PSAUTHITEM, PSCLASSDEFN, PSROLECLASS, PSROLEUSER
run_select	“How many training requests are still pending?”	Only the application tables you allow

Conventions

These rules apply to every tool.

Names

• Definition names are case-insensitive in inputs, so job and JOB are the same record. Outputs always use uppercase names, as PeopleTools stores them.
• Names are checked against PeopleSoft’s length limits before any query runs: records can be up to 15 characters; fields, pages, and components up to 18; Application Engine programs up to 12; and SQL definitions up to 30.
• PeopleCode event names, such as FieldChange, are also matched without regard to case, and returned in their usual mixed case.

Markets and database platforms

• Components and Application Engine sections are defined per market. Tools that take a market default to GBL, the global market.
• Some definitions have platform-specific versions, such as SQL written separately for Oracle Database and Microsoft SQL Server. Tools return the version for the database the server is connected to, and fall back to the generic version when there’s no platform-specific one.

Results

• Every tool declares an output schema. Results come back as structured JSON in structuredContent, with the same JSON as text for clients that don’t read structured content.
• PeopleSoft stores blank character values as a single space. Tools return them as null.
• Dates and times use ISO 8601 format, such as 2026-07-01 and 2026-07-01T14:32:10.
• Optional flags, such as key or required on a record field, appear only when they’re true.
• Text is returned without control characters, other than tabs and line breaks, and without invisible formatting characters. When any are removed, the result includes removedCharacters, how many were removed. Prompt injection explains why.

Limits and paging

• Each tool has a default and a maximum number of results, and every query runs under a timeout, 30 seconds by default.
• When a result is cut short, it includes "truncated": true, so the LLM knows to narrow its request instead of treating a partial answer as complete.
• MCP’s built-in pagination covers list requests such as tools/list, not tool results. Tools that can return long text, such as get_peoplecode, page through it with their own start_line and max_lines arguments.

Errors

Following the MCP specification, tools report two kinds of errors:

• Tool execution errors come back as a result with isError: true and a message the LLM can act on. They cover invalid arguments, definitions that don’t exist, and queries that time out. Where possible, the message suggests a fix: “Record JOBB doesn’t exist. Closest matches: JOB, JOB_EARNS_DIST, JOBCODE_TBL.”
• Protocol errors are standard JSON-RPC errors, reserved for requests the server can’t process at all, such as a call to a tool that doesn’t exist.

Behavior hints

Every tool is annotated with readOnlyHint: true and openWorldHint: false, which tells the host that it only reads, and only from your PeopleSoft database. Hosts can use these hints to decide which calls need your confirmation. The actual guarantee comes from the database account, which can only read.

Auditing and rate limits

Every call is written to the server’s audit log. Calls are also rate-limited per user, 60 per minute by default, as the MCP specification requires servers to rate-limit tool calls.

How each tool page is organized

• Input lists the tool’s arguments, followed by its complete input schema, which is exactly what the LLM sees.
• Output describes the fields of the result, with an example.
• How it works lists the tables the tool reads and shows its main SQL.
• Limits and errors covers what the tool won’t do and how it reports problems.

About the SQL and examples

SQL on these pages uses Oracle Database syntax, with bind variables such as :record. The server keeps an equivalent version of every query for Microsoft SQL Server. Examples use delivered HCM definitions where their structure is well known, and custom ZZ_ definitions everywhere else.