Skip to content
SparkyaiPeopleSoft

search_definitions

search_definitions finds definitions when you don’t know their exact names. It matches your words against definition names, descriptions, and the labels users see in PeopleSoft navigation, so a search for Job Data finds both the navigation entry and the JOB_DATA component behind it. The LLM usually calls it first, then follows up with one of the describe_ tools.

Use it for

Section titled “Use it for”
  • “Which component opens when I click Job Data?”
  • “Find the records related to direct deposit.”
  • “Is there an Application Engine program that loads training requests?”
  • “List our custom training records. Their names start with ZZ_TRAIN.”

Input

Section titled “Input”
Argument Type Required Description
query string Yes Words, or part of a name, such as direct deposit or ZZ_TRAIN. 2 to 100 characters.
types array of strings No The definition types to search: record, field, page, component, navigation, app_engine, and sql. Default: all of them.
limit integer No The maximum number of matches, from 1 to 100. Default: 25.
Input schema
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 2,
      "maxLength": 100,
      "description": "Words or part of a name, such as 'direct deposit'"
    },
    "types": {
      "type": "array",
      "items": {
        "enum": [
          "record", "field", "page", "component",
          "navigation", "app_engine", "sql"
        ]
      },
      "uniqueItems": true,
      "description": "Definition types to search. Default: all types."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    }
  },
  "required": ["query"],
  "additionalProperties": false
}

Output

Section titled “Output”
Field Description
matches The matching definitions, best matches first
matches[].type The definition type, such as record or navigation
matches[].name The definition’s name. For a navigation entry, the component it opens.
matches[].market The market, for components and navigation entries
matches[].description The definition’s description, or the label of a navigation entry
matches[].path For a navigation entry, its full menu path
matches[].matchedOn What matched: name, description, or label
matches[].lastUpdated, lastUpdatedBy When the definition last changed, and who changed it
truncated true when there are more matches than limit
Example: query 'job data', types navigation and component
{
  "matches": [
    {
      "type": "navigation",
      "name": "JOB_DATA",
      "market": "GBL",
      "description": "Job Data",
      "path": "Workforce Administration > Job Information > Job Data",
      "matchedOn": "label",
      "lastUpdated": "2025-03-14T09:12:44",
      "lastUpdatedBy": "PPLSOFT"
    },
    {
      "type": "component",
      "name": "JOB_DATA",
      "market": "GBL",
      "matchedOn": "name",
      "lastUpdated": "2025-03-14T09:12:40",
      "lastUpdatedBy": "PPLSOFT"
    }
  ],
  "truncated": false
}

How it works

Section titled “How it works”

The tool runs one query for each definition type it searches:

Type Table Columns matched
record PSRECDEFN RECNAME, RECDESCR
field PSDBFIELD, PSDBFLDLABL FIELDNAME, DESCRLONG, LONGNAME
page PSPNLDEFN PNLNAME, DESCR
component PSPNLGRPDEFN PNLGRPNAME, DESCR
navigation PSPRSMDEFN PORTAL_LABEL
app_engine PSAEAPPLDEFN AE_APPLID, DESCR
sql PSSQLDEFN SQLID

Your query is matched in two ways. Against names, spaces count as underscores, so job data matches JOB_DATA. Against descriptions and labels, the words are matched without regard to case. Any % or _ in your query is escaped, so it matches literally. Results are ranked with exact name matches first, then names that start with the query, then other name matches, then description and label matches.

Records (Oracle Database)
SELECT RECNAME, RECDESCR, LASTUPDDTTM, LASTUPDOPRID
  FROM PSRECDEFN
 WHERE RECNAME LIKE :name_pattern ESCAPE '\'
    OR UPPER(RECDESCR) LIKE :text_pattern ESCAPE '\'
 FETCH FIRST :max_rows ROWS ONLY

For job data, :name_pattern is %JOB\_DATA% and :text_pattern is %JOB DATA%.

Navigation entries come from the portal registry. PORTAL_REFTYPE = 'C' limits the search to content references, the entries that open a component; folders have type F:

Navigation entries (Oracle Database)
SELECT PORTAL_OBJNAME, PORTAL_LABEL,
       PORTAL_URI_SEG2 AS COMPONENT,
       PORTAL_URI_SEG3 AS MARKET
  FROM PSPRSMDEFN
 WHERE PORTAL_NAME = :portal
   AND PORTAL_REFTYPE = 'C'
   AND UPPER(PORTAL_LABEL) LIKE :text_pattern ESCAPE '\'

The server then builds each entry’s menu path by walking up the registry through PORTAL_PRNTOBJNAME:

Menu path of a navigation entry (Oracle Database)
SELECT PORTAL_LABEL
  FROM PSPRSMDEFN
 START WITH PORTAL_NAME = :portal
        AND PORTAL_OBJNAME = :objname
CONNECT BY PORTAL_OBJNAME = PRIOR PORTAL_PRNTOBJNAME
       AND PORTAL_NAME = PRIOR PORTAL_NAME
 ORDER BY LEVEL DESC

The walk ends at the registry’s root folder, PORTAL_ROOT_OBJECT, which is left out of the path. On Microsoft SQL Server, the same walk uses a recursive common table expression.

Limits and errors

Section titled “Limits and errors”
  • A call returns at most 100 matches. truncated is true when there are more.
  • Queries shorter than 2 characters are rejected, because they would match almost everything.
  • Navigation entries come from one portal: EMPLOYEE, the standard portal, unless your server is configured to use another.
  • When nothing matches, the result is an empty matches list rather than an error, so the LLM can try different words.
Section titled “Related tools”