MCP Server - MCP Tools

Intended audience: USERS

AO Platform: 5.0

MCP Tools - Details

list-ontologies

• Purpose: Discover ontologies and get the correct uid for ontologyUid.

• Description: Returns the complete list of ontologies available to the current user, including each ontology's UID, display name, description, and schema prefix. Use this as the very first call in any session where the target ontology is unknown or ambiguous — for example, when the user asks a data question without specifying which ontology to use, or when multiple ontologies exist and the right one needs to be identified. Do not skip this step and guess the ontologyUid; always confirm the correct UID before querying any MSO (Managed Semantic Object) or table. Takes no input parameters.

• API Endpoint: GET /api/ontology/all

• Inputs: None.

• Output: JSON list with ontology metadata (including uid).

• Tips: Run first when the user did not specify an ontology.

list-msos

• Purpose: See which MSOs ("tables") exist in an ontology without loading full column lists.

• Description: Returns the names of all MSOs (Managed Semantic Objects) — also referred to as tables or entity types — available in a given ontology, without loading any column definitions or metadata. Use this as the first call in any schema discovery workflow to understand what MSOs/tables exist before drilling into individual ones. Prefer this over export-ontology-schema when you only need to know what MSOs are available — it uses a fraction of the tokens. Returns a flat list of MSO/table names. Requires ontologyUid.

• API Endpoint: GET /api/sor/semanticSchema/msos

• Inputs: ontologyUid; optional excludeLlmPriorityNever (default true — hides MSOs with platform llmPriority: Never).

• Output: JSON list of MSOs.

• Tips: Preferred over export-ontology-schema for discovery.

describe-mso

• Purpose: Column-level schema for one MSO (names, types, descriptions).

• Description: Returns the full column-level schema for a single named MSO (Managed Semantic Object / table / entity) in an ontology — including column names, data types, nullability, and descriptions. Use this when you need to verify field names before writing a query, or when nlq-to-semantic-sql produces a query referencing columns you want to confirm exist in that MSO/table. Call this per-MSO rather than loading the full schema — each call costs ~200–500 tokens vs ~42,000 for the full export. The column names returned match the table-level references used in Semantic SQL queries. Requires ontologyUid and msoName.

• API Endpoint: GET /api/sor/semanticSchema/mso

• Inputs: ontologyUid, msoUid (from list-msos or search-schema — not display name alone).

• Output: JSON schema for that MSO.

• Tips: Column names align with Semantic SQL table-level references.

search-schema

• Purpose: Find MSOs/tables/columns matching a keyword.

• Description: Searches across all MSO (Managed Semantic Object) names, table names, and column names in an ontology for entries matching a keyword or phrase. Returns only the matching MSOs/tables and columns, not the full schema. Use this when you know what concept you're looking for (e.g., "billing", "install date", "zone") but don't know which MSO, table, or column name it maps to. Much more token-efficient than exporting the full schema — ideal for resolving ambiguous field references in natural language questions. Results include both MSO/entity names and their underlying table references to aid query construction. Requires ontologyUid and a search keyword.

• API Endpoint: GET /api/sor/semanticSchema/search

• Inputs: ontologyUid, keyword; optional excludeLlmPriorityNever (default true).

• Output: Filtered JSON hits.

• Tips: Use when the user names a business concept, but not a table name.

list-relationships

• Purpose: See how MSOs join — before writing multi-table Semantic SQL.

• Description: Returns the join relationships (foreign keys, associations) between MSOs (Managed Semantic Objects / tables / entities) in an ontology — optionally scoped to a single MSO. Use this before writing queries that require JOINs across multiple MSOs or tables, to understand how they connect without loading full schema definitions. For example, use it to discover that a ServiceOrder MSO/table links to a Meter MSO/table via meterId before writing a joined query. Relationship references are returned using table names as they appear in Semantic SQL, ensuring query compatibility. Requires ontologyUid; msoName is optional to scope results to one MSO's relationships.

• API Endpoint: GET /api/sor/semanticSchema/joinRelationships

• Inputs: ontologyUid; optional msoName to narrow; optional excludeLlmPriorityNever (default true).

• Output: JSON join/relationship graph (filtered client-side when defaults apply).

• Tips: Relationships use table names as Semantic SQL expects.

get-mso-sample-data

• Purpose: Example rows to understand real values (e.g., status strings).

• Description: Executes a lightweight SELECT * FROM <MSO/table> LIMIT N internally and returns sample rows. Use this to infer the shape, data types, and actual values of an MSO's columns from real data rather than metadata — especially useful when describe-mso is unavailable or when you want to understand what values a field contains (e.g., what strings appear in a "status" column). The returned rows use table-level column names as they appear in Semantic SQL, making it easy to map sample data back to query construction. The default limit is 5 rows. Requires ontologyUid and msoName; limit is optional.

• API Endpoint: GET /api/sor/semanticSchema/msoSampleRows

• Inputs: ontologyUid, msoUid (same uid as describe-mso); optional limit.

• Output: JSON sample rows.

• Tips: Use the MSO uid from list-msos or search-schema, not the display name alone.

validate-semantic-sql

• Purpose: Validate Semantic SQL without executing it.

• Description: Validates a Semantic SQL query against the ontology schema without executing it. Returns whether the query is syntactically and semantically valid, and surfaces specific errors (e.g., unknown MSO/table reference, invalid column name, type mismatch) if it is not. Use this before running expensive or complex queries to catch mistakes early and avoid wasted execution. Particularly useful when queries reference MSO/table or column names discovered via schema tools, and you want to confirm correctness before execution. Requires ontologyUid and the semanticSql string.

• API Endpoint: POST /api/sor/semanticSchema/validateSemanticSql

• Inputs: ontologyUid, semanticSql.

• Output: Platform validation result (OK or errors).

• Tips: Use before expensive execute-semantic-sql runs.

get-mso-column-details

• Purpose: Deep metadata for a single column (enums, constraints, etc.).

• Description: Returns detailed metadata for a single column within a specific MSO (Managed Semantic Object / table / entity) — including data type, allowed enum values, nullability, default value, description, and any known constraints. Use this when a column's type or allowed values are critical to query correctness (e.g., before filtering on a status field, to confirm the exact string values it accepts in the underlying table). More targeted than describe-mso when you only need one field's details. Column names are returned as they appear in the MSO's table schema for direct use in Semantic SQL. Requires ontologyUid, msoName, and columnName.

• API Endpoint: GET /api/sor/semanticSchema/msoColumns (+ filter)

• Inputs: ontologyUid, msoUid, columnName.

• Output: JSON for the matching column (server filters from MSO columns).

• Tips: Narrower than describe-mso when you need one field.

get-mso-statistics

• Purpose: Row counts, null rates, distributions, etc.

• Description: Returns statistical summaries for a specified MSO (Managed Semantic Object / table / entity) or one of its columns within an ontology — including row counts, null rates, distinct value counts, min/max/avg for numeric columns, and most frequent values for categorical columns. Use this to quickly understand the volume, completeness, and distribution of data in an MSO/table before writing analytical queries, or to validate data quality assumptions (e.g., checking whether a column is sparsely populated before filtering on it). Statistics are scoped to the MSO's underlying table and reflect current data in the ontology. Requires ontologyUid and msoName; columnName is optional to scope statistics to a single column.

• API Endpoint: GET /api/sor/semanticSchema/msoStatistics

• Inputs: ontologyUid, msoUid; optional columnName.

• Output: JSON statistics (optionally scoped to one column).

• Tips: Same msoUid convention as describe-mso / msoSampleRows / msoColumns.

export-ontology-schema

• Purpose: Full ontology schema JSON.

• Description: Exports the full schema of a given ontology as a JSON array — including all MSOs (Managed Semantic Objects), their underlying table references, columns, data types, and relationships. WARNING: This tool regularly returns outputs exceeding 40,000 tokens, which can consume most or all of the available context window in a single call. Do NOT use this tool for general schema discovery or to answer routine data questions. Only use it as a last resort when incremental MSO/table schema tools (describe-mso, search-schema, get-mso-sample-data) are unavailable, and a comprehensive schema dump is explicitly required. When this tool is invoked, use the table-level names in the returned JSON for constructing Semantic SQL queries — MSO names and table names may differ, and the table references are what the query engine resolves against. Requires ontologyName (not UID).

• API Endpoint: GET /api/schemaExport

• Inputs: ontologyName only (not UID).

• Output: Very large JSON — can exceed typical assistant context.

• Tips: Last resort; prefer incremental SOR tools.

nlq-get-data

• Purpose: One-shot path from a natural-language question to tabular data. Recommended primary tool for any data question — a single call performs NL understanding, schema resolution, Semantic SQL generation, execution, and pagination. Falls back to nlq-to-semantic-sql + execute-semantic-sql only when the SQL must be inspected/edited first or when this tool fails.

• Inputs:

  • Required: question, ontologyUid, conversationId (reuse across every call in the same chat), workflowId (fresh UUIDv4 per call — including ambiguity loops and pagination), useQueryCache (default true), useDataCache (default true).

  • Optional: queryMode (Balanced default, Controlled, Freeform), solutionUid, feedback (after a thumbs-down or refinement), generateDataSummary (omit / false on page > 1 — server forces it off there), page (1-based), pageSize, previousQuestion, replaceTokens (JSON array of objects), and the four ambiguity fields (ambiguityClarification, ambiguityClarificationMessage, ambiguityFeedbackMso, ambiguityFeedbackMsoProperty) — same JSON-map semantics as nlq-to-semantic-sql.

• Output: Formatted summary, optional generated Semantic SQL, ambiguityMessage (Clarify vs Continue), pagination metadata (totals, page, page size), and data rows.

• Tips: On Clarify ambiguity, present token options to the user and re-call with the same conversationId, fresh workflowId, and the matching ambiguityFeedbackMso / ambiguityFeedbackMsoProperty JSON-string map (token → display name). MSO and MSO_PROPERTY ambiguities arrive as separate Clarify responses — handle one type at a time. On tool failure, do not silently fall back — surface the error and let the user pick the recovery path. Pagination = same conversationId, fresh workflowId, increment page. Requires the platform's agora agent module to be present.

nlq-to-semantic-sql

• Purpose: Two-step flow: produce Semantic SQL and/or ambiguity, resolving MSO/table/column names without loading full schema into context (saves tokens). Use this when the user must review or edit the SQL before it runs; otherwise prefer nlq-get-data. Not for validating SQL — use validate-semantic-sql.

• Description: Converts a natural language question into a valid Semantic SQL query for a given ontology, resolving MSO (Managed Semantic Object) names, table references, and column mappings internally without loading the schema into context. Use this as the standard first step for any data question — it produces an optimized, schema-aware query without consuming tokens on MSO/table schema discovery. Always review the generated SQL before executing it — particularly the MSO/table names and column references used — especially for aggregations, JOINs, or filtered queries. Show the generated query to the user if the question was ambiguous or the MSO/table referenced looks unexpected. Do not use this tool to validate queries — use validate-semantic-sql for that. Requires ontologyUid and a natural language question string.

• API Endpoint: POST /api/easyAnswers/getSemanticSql

• Inputs: question, ontologyUid (sent to platform as ontology). Optional: queryMode, useCache, solutionId, feedback, ambiguityClarification / ambiguityClarificationMessage, ambiguityFeedbackMso / ambiguityFeedbackMsoProperty (each a JSON string holding one object: token → display name, sent as ambiguityFeedback.MSO / MSO_PROPERTY — see src/error.log).

• Output: Formatted text including SQL and/or ambiguity (qnTokens, clarification, etc.) when substantive; threadId may appear for correlation only (not a parameter you pass back on this API).

• Tips: Review generated SQL before execute-semantic-sql, especially for aggregations, JOINs, and filters. If there is no SQL and only ambiguity, resolve with the user before executing.

execute-semantic-sql

• Purpose: Run Semantic SQL and return data rows (paginated).

• Description: Executes a Semantic SQL query against a specified ontology and returns the results as paginated rows. This is the primary tool for retrieving data from any MSO (Managed Semantic Object) or table — use it after generating a query with nlq-to-semantic-sql, or when writing a query manually using known MSO/table and column names. Results include total row count, current page, and data rows. Semantic SQL uses table-level names as defined in the ontology schema — ensure MSO/table references in the query match those returned by describe-mso or list-msos. If the query fails, capture the exact error message and surface it to the user before retrying — do not silently modify and re-run the query without user confirmation. Requires ontologyUid and the full semanticSql string.

• API Endpoint: POST /api/easyAnswers/getDataBySemanticSQL

• Inputs: ontologyUid, semanticSql; optional limit, isPassThrough.

• Output: Total size, page size, current page, optional summary, then rows or “No rows returned.”

• Tips: On failure, use the exact error message before changing the query. Use table/column names consistent with describe-mso / list-msos.

MCP Tools - Quick Reference

SOR paths use query parameter `ontologyUid` unless noted. `export-ontology-schema` uses `ontologyName` only.

Contact App Orchid | Disclaimer