Chatbot / Oria tools¶

This catalogue lists tools that are actually attached to the compiled Oria graph. A decorated Python function is not a runtime capability until a specialist agent registers it. The supervisor uses a typed choice request and a graph transition rather than model-facing tools.

Tools receive database repositories, tenant configuration, current user, language, conversation state and AI clients through ChatbotToolRuntime. The model does not provide credentials or database connections. Tenant tool_exclusion settings can remove registered tools at runtime, and MCP subgraphs can impose a narrower allow-list. Prompt suggestions describe only supported agents enabled in the tenant configuration.

Agent-to-tool map¶

All seven specialists also register request_clarification_tool through the shared interaction middleware. It is exposed only for interactive HTTP chat.

Supervisor routing¶

The supervisor selects one of the seven specialists using the mini profile: OpenAI Decisions when supported, or structured generation on the configured provider otherwise. The application validates tenant availability, applies the existing profile-action-plan destination rule, records active_agent and returns a graph Command. It does not expose transfer or confirmation tools. See supervisor routing.

Internal company knowledge¶

transfer_to_knowledge_base¶

Career Chat transfers company-policy and procedure research to a dedicated Knowledge Base Deep Agent. This argument-free tool only records the handoff. Selection requires a specific fact about the company or its configured resources that is needed to answer. Reflective coaching proceeds directly without research; an unavailable profile alone does not justify a transfer. The latest user message, recent conversation and tenant context are supplied by the graph. A supported answer ends the turn unchanged; a miss or failure returns to Career Chat for a limitation explanation and one contextual follow-up. Tenant tool_exclusion can disable the transfer, and only one transfer is allowed per turn. It is also hidden when no enabled RAG chunks or active configured web sources are available. This check uses no LLM or embedding. Personal profiles and uploaded chat documents use their own tools. Explaining a documented capability is a knowledge question, even when the capability handles documents. Retries and corrections use earlier user messages; a previous assistant answer is not evidence.

search_knowledge_sources¶

The Knowledge Base agent uses this tool to retrieve raw RAG passages and public pages concurrently. Optional query refines the RAG query within two searches; the first search reads web entry pages and exposes their allowed links and section titles. Links include allowed paths and bounded nearby context; same-page utility links are omitted in favor of section handles. A contextual retry uses a self-contained query. Refinement reuses retrieved web evidence. The Deep Agent owns the final synthesis and must distinguish the requested operation from related topics.

read_knowledge_page¶

The agent selects an opaque page_id from discovered links. Optional section_id and offset select a listed heading or continue a bounded excerpt. Previously fetched pages are reused without another HTTP request or RAG search. The tool enforces the configured origins/paths and the shared page/depth/time limits. Unavailable pages remain distinguishable from missing evidence; navigation hints alone cannot substantiate an answer. Search/read results expose remaining page and read capacity through web_budget. The agent can use another plausible lead after a tangential result, within the same four model invocations and unchanged page/depth/time limits. See Knowledge Base research for configuration and guarantees.

User and conversation context¶

get_user_profile_selective_tool¶

Inputs are eight boolean selectors for basic information, skills/gaps, objectives, experiences, departments/interests, bookmarks, training history and mandatory training IDs. Call it only when profile information is needed for the current request, with at least one relevant selector set to true. An all-false selection returns an error, not a names-only profile. Successful calls read the current standardized user already in runtime context and return available first/last names, adding only requested sections to control model tokens. A missing application user ID is an explicit error; the tool has no side effect.

Before selecting the tool, the agent must identify a useful category and explicitly enable it; omitted selectors default to false. If no category is needed, it responds directly. An unavailable company knowledge source does not itself justify a lookup: need_basic_info=true may check relevant location context, but a profile cannot establish company policy. Empty calls are not a transition to a final answer.

Career Chat removes this tool before model action selection when the preloaded profile is missing, null or empty. Repeating the lookup cannot reload that fixed request context. Profile-retrieval instructions do not override this limitation: the assistant continues with available conversation context without inventing profile facts or automatically switching to an uploaded document. It mentions the limitation only when relevant, without opening an interaction merely to retry it. A present profile with empty skills, objectives or other categories remains available. Availability is checked from each request's context, so a later request with a loaded profile can use the tool normally.

An explicit conversational closing or pause without a new request goes directly to a brief final acknowledgment. Action selection must not retrieve profile information, call another tool or resume an earlier task for that closing. This is the first decision in the Career Chat prompt and in private action selection, ahead of retrieval guidance. "I want to pause here" ends the current conversation; a question about company career-break policy still requests research. A thank-you followed by a new question does not close that request. This remains model-driven prompt guidance, without an additional classifier call or a deterministic guarantee that every closure will be recognized.

get_document_content_tool¶

Takes file_name and an optional conversation_id; omission uses the current conversation. It reads the extracted document from the PostgreSQL document repository or MongoDB Documents collection using both fields as scope. The complete stored document is returned, {error: "Document not found."} signals a miss, and missing database/conversation context raises an explicit error.

map_jobs_tool¶

Takes a list of free-text job titles. Each title is embedded/searched against the active job repository at threshold 0.91, and only the closest result is retained as original title, mapped title and job code. Individual misses remain in the JSON result; infrastructure failure marks the tool message as an error only when every requested mapping failed.

get_jobs_tool¶

Takes job codes produced by map_jobs_tool. PostgreSQL fetches them in one repository call; MongoDB queries Jobs and projects job code, title, description, ID, creation date and skills. Results are serialized into a tool-call-correlated ToolMessage; empty input and complete backend failure are reported as errors.

map_skills_tool¶

Takes optional free-text skill labels and runs the shared Skills Library mapping against MongoDB or PostgresSkillSearchRepository. It returns original label, best normalized label and skill code for usable matches. There is no persistence side effect.

get_trainings_tool¶

Takes ordered training_ids plus optional card title/subtitle. It fetches the documents from MongoDB or PostgreSQL, removes embeddings, projects presentation fields and rebuilds results in the caller's ID order. Missing IDs are skipped; the tool writes suggested_trainings_message_data into graph state and returns it directly for UI rendering.

get_objective_tool¶

Takes an optional title and include_archived=false. It reads objectives from the current user, keeps only status=current by default, auto-selects the sole remaining objective, asks for disambiguation when several remain, or resolves a provided title through semantic closest-objective matching for noninteractive callers. Interactive chat accepts an exact unique title or pauses with a snapshot of the remaining candidates; an ambiguous title never silently selects the closest one. The selected JSON, a no-objective/not-found message, or a sanitized infrastructure error is returned without mutation.

Opportunity discovery¶

search_opportunities_tool¶

Inputs are the latest natural-language request and a show_more_opportunities flag that must reflect an explicit request for more. The tool can classify profile-relative intent and enrich the query with current-user facts, then uses a strict model schema to extract OpportunitySearchCriteria. The deterministic core applies configured JOM hard filters, structured criteria, full-text/vector search and user-profile scoring through the active repositories.

Previously returned IDs are excluded only for a genuine “show more” turn and new IDs are stored in graph result state. Successful results become structured opportunity cards with localized rationales. An empty search in HTTP chat pauses with a question about which criteria to change; completed search work is cached. It never substitutes unfiltered profile matches. Noninteractive callers receive the localized no-result message. Unexpected errors produce a stable error-status tool message.

suggest_opportunities_based_on_objective_tool¶

Takes objective_id, the current user message and the explicit “show more” flag. It finds that objective in the current profile, extracts its skills and maps/searches relevant opportunities (or invokes the MongoDB objective recommendation workflow). Already returned opportunities are removed, up to the presentation limit are formatted with objective-specific rationales and the new IDs are tracked. Missing objectives/results return localized business messages; infrastructure failures are sanitized.

Training and simulation¶

training_finder_tool¶

Inputs include the natural-language query, required is_learning_plan, explicit “show more”, selective profile flags, optional preloaded user context and plan duration. It merges conversation exclusions with explicit exclusions and expands them to related parent/child training IDs. It loads requested user sections, durable preferences and recent conversation history; learning plans automatically request role, skills, objectives and department context.

For plans, the agent delegates incomplete scope to the tool instead of asking its own preliminary questions. A scope assessment can request clarification before search. HTTP chat uses one persisted LangGraph interrupt with separate questions, a grouped answer/skip submission or whole-request cancellation; see the frontend interaction contract. Completed preparation and scope decisions are cached across node restarts. Compatible OpenAI mini uses independent decisions for target, background, available time, preferences and an explicit request to skip clarification. The application allows the plan when at least two dimensions are known or the user explicitly skips clarification. A general/no-specialization preference counts as answered; plan duration alone does not count as available time. Other chatbot requests also pass a search-or-clarify decision. On the native path, only a request needing clarification generates a structured mini question list (up to three for a plan, one for an uninterpretable search). Other providers and unsupported models retain their existing combined structured mini calls. Both paths use the same question rules: one missing dimension per question, with target, background and available time prioritized when nothing is known. The native path supplies only the first three missing dimensions in that priority order to the question writer; already supplied preferences remain available as context. A time question must not include an additional request for preferences. Fewer questions remain valid. These optional checks preserve search availability on failure without retrying through another provider; cancellation still propagates. Identifier-only callers skip the search-or-clarify check. The search service resolves filters, executes lexical/vector retrieval and returns results directly in weighted RRF order; there is no Cohere rerank. Plan mode additionally builds the time-boxed learning-plan presentation without changing that order. Results update suggested_trainings_message_data and returned-ID state; misses receive a localized fallback and unexpected failures a stable error status.

Search does not generate individual rationales and trainingSuggestionList items have no rationale field. Collection titles, subtitles and learning-plan phase descriptions remain. Request an explanation for one selected learning through Training Matching, optionally passing the user's search as search_query. rationaleContext retains the original and resolved queries for this purpose.

suggest_simulation¶

Takes the practice request and optional counterpart name. It parses the desired scenario, disambiguates a named person against tenant users at threshold 0.55, maps relevant skill names against the skill catalog and generates a strict structured role-play scenario. The returned direct Command contains the simulation card/state used to start the simulation; unresolved optional people do not manufacture an identity.

Expected outcomes describe observable results of the conversation. When an outcome involves understanding, it specifies a visible demonstration, such as the counterpart restating an impact or explicitly confirming a shared interpretation. No fixed wording or additional objective is required.

Each generated skill describes one coherent professional capability. Related behaviors can share a title, such as "Listening and responding to defensiveness"; conjunctions are allowed. Independent capabilities must remain separate skills.

Difficulty and estimated duration primarily reflect the actual conversation: the counterpart's cooperation, stakes, competing constraints and required reasoning or negotiation. Outcome and criterion counts are secondary signals; time ranges are approximate guidance. Clarifying scope, a deadline and next steps with a cooperative colleague may have three outcomes and three criteria while remaining a Beginner scenario of about 10 minutes.

Talent and profile analysis¶

talent_finder_tool¶

Takes a readable natural-language request, a structured TalentSearchIntent and explicit “show more”. Criterion groups are ANDed; values inside a criterion use its any/all operator. Dedicated classification, location, work-arrangement, skill, role, employer and department fields compile deterministically into the active MongoDB/PostgreSQL search. Education, certification and experience duration are intentionally ignored rather than remapped.

The current user and previously returned IDs are excluded. Results include the needed experience, department, classification, location, working-mode and skill fields, and their IDs are tracked for pagination. A no-result response is generated from the readable query without inventing candidates; unexpected failures use a stable error tool message.

Candidate rationales describe only supported matches. When no search criterion is supported by the supplied candidate data, they may invite a focused discussion or review of work examples or other relevant evidence. Work samples are optional; the evaluation judge accepts a concrete discussion-based assessment without them. Neither route establishes skills, experience, proficiency or a match in advance.

person_disambiguation_tool¶

Takes person_name, searches tenant users other than the current user and returns candidates above the 0.55 disambiguation threshold with display names and internal IDs. It is read-only and lets the agent/user choose when multiple people remain.

display_user_profile_tool¶

Takes no model-controlled business parameter. It normalizes the current profile, builds bounded prompt evidence and concurrently generates localized analysis copy, up to six skill-gap objectives, and current-role alignment. The alignment prefers the persisted JPM skill score; if absent and eligible, a per-user/job lock permits one JPM recalculation before falling back to an LLM estimate.

The result is a structured profile-analysis card containing narrative, alignment and prioritized development topics. Objective generation can time out without losing the rest of the card, and copy generation has a deterministic profile-data fallback. Missing profile data and unrecoverable failures return distinct stable error-status tool messages.

task_helper_tool¶

The conversation must identify a concrete task and desired outcome before this tool is called. An unspecified task requires one concise clarification question. Interactive HTTP requests deliver the missing essential details through request_clarification_tool before invoking the guidance tool. Noninteractive callers retain conversational clarification. Neither path guesses missing facts.

Takes the professional user_question plus injected state. It builds a tenant-aware system prompt using bot/company names and specialist instructions, selects a 1,000/1,400/1,800-token budget from question length and calls the configured model at low temperature. Markdown emoji codes are normalized to Unicode and the answer is returned directly. Missing AI context yields general guidance; model failure yields a sanitized retry message.

Guidance is proportionate to the task. After refusing an unsupported outcome guarantee, the tool provides a few concrete, safe, immediately usable actions for the known task before a useful follow-up. Their number is not fixed: judge them by relevance, concision and proportion to the request. For a presentation, it may suggest selecting verifiable accomplishments and explaining their context, contribution and results without promising promotion or inventing assessment criteria. End with one to four useful follow-up questions, presented clearly and naturally. The Follow-up Questions heading is optional for every response, including longer guides. Optional personalization does not block useful initial guidance.

Emojis provide optional visual markers selected for the meaning of the adjacent text: for example, 📄 for a document, 💡 for a tip, 📅 for scheduling, 📊 for metrics and ⚠️ for a risk. These are non-exhaustive examples, not an allowlist or mandatory placements; 📌 can also highlight an important tip and 🧩 can introduce a reusable template. Other Unicode emojis are acceptable when their meaning fits the content and they remain clear and professional. Numbered or bulleted steps need no emoji on every item, while repeated ✅ markers remain acceptable for a clear checklist. No fixed count or quota applies. Markers must not imply that proposed actions are complete, risks are resolved or results are guaranteed. Readability and useful guidance take priority over formatting preferences. Advice must remain grounded and must not guarantee a promotion or other career outcome.

MCP clients receive a separate external tool set, documented under MCP Server. Internal tool behavior is described in the LangGraph tool guides.

The generated chatbot HTTP reference is the authoritative source for parameters, schemas, responses and examples.

request_clarification_tool¶

Specialist agents use this shared tool for essential clarification before a business operation. It returns the generic interaction HTTP output and accepts a questions list with text, single-select or multi-select replies through the grouped resume request. The model sets input_type, grounded options and allow_free_text; the backend assigns question-local option IDs. Agents keep their existing semantic profiles (mini for Career Chat/Task Helper, large for other specialists); no new classifier is introduced. The shared delivery middleware makes clarification a tool action in both JSON and SSE and rejects parallel tool calls before execution in interactive mode.

Every question supports skip, which advances only that frontend step. Skipped questions are not asked again automatically. Skipping a required selection ends the targeted request without choosing an object. Finite topic, document/profile and action-plan choices use structured option IDs preserved in the checkpoint. Closed targets remain single-select; compatible topics may be multi-select, with an alternative text answer when allowed. Invalid IDs or cardinality are rejected before graph resumption, leaving the same pause pending. No number/label parsing is performed. Ordinary coaching questions, role-play dialogue and closing invitations are not interruptions. Interruptions are reserved for blocking gaps: agents reuse known context, group indispensable questions, and proceed as soon as the reply is usable. Optional tone, format, duration or personalization preferences do not trigger another scoping round.

Person and objective lookup tools own their candidate snapshots and selections. Person confirmation retains the exact identifier for simulation; in the main graph, a confirmed choice returns to the supervisor to continue the original request. Opportunity/talent searches cache completed search work before asking which criteria to change. They preserve show-more exclusions and never silently replace a failed filtered search with profile suggestions. Cancellation ends the workflow without another model call. See the HTTP contract.