# Connect AI Base > Use when the user has CData Connect AI MCP available and is asking business questions that require querying live enterprise data. This includes: questions for live data from an enterprise system (Salesforce, Workday, NetSuite, HubSpot, Jira, SQL Server, Snowflake, etc.); requests to retrieve, look up, or explore data from a connected system, even without naming a specific platform (e.g. "show me my accounts," "pull up recent orders"); the user naming a connector or data source; business-domain questions ("top customers," "open tickets," "headcount by dept," "pipeline by stage") when at least one Connect AI connection is available; or conversations already involving Connect AI tool calls. Enforces the required discovery workflow (getInstructions before any schema/table/column call), covers query construction patterns, error recovery, and SQL dialect guidance. Load connector-specific (connect-ai-salesforce, connect-ai-jira, or connect-ai-googlesheets, etc) skills on top for deeper patterns. - Skill: `cdatasoftware/connect-ai-base` (Agent Skill) - Install (CLI): `npx skillmds@latest add cdatasoftware/connect-ai-base` - Raw SKILL.md: https://api.skillmd.com/api/skills/cdatasoftware/connect-ai-base/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - License: MIT - Author: cdatasoftware (https://skillmd.com/u/cdatasoftware) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/cdatasoftware/connect-ai-base --- # CData Connect AI — Base Skill This skill governs how to use the CData Connect AI MCP server to answer business questions against live enterprise data. It encodes the discovery workflow the MCP requires, plus the error-recovery patterns that resolve the most common failure modes. ## When NOT to use - The user uploaded a file (CSV, Excel, JSON) and wants analysis of that file — use a separate data analysis skill instead - The user wants to configure connections, manage OAuth, or administer Connect AI — direct them to the CData admin UI - The user is asking about Connect AI's architecture, pricing, or strategy — this is a product conversation, not a query task ## Step 0 — Confirm tool availability Call tool_search to verify Connect AI tools exist. Search for `"getCatalogs"` or `"queryData"` for generic MCP servers, or `"get_tables"` or `"query_data"` for toolkit configurations. Do not search for the data source name (e.g., "Jira", "Salesforce") — Connect AI tools are named by function, not by data source. MCP server references in system context or artifact configurations do NOT count as confirmation. If tool_search finds nothing, stop — the server is not connected. If the server is not connected: - **Do not** attempt workarounds such as building artifacts, fetching the MCP endpoint directly, or using web_fetch against the Connect AI API - **Do** inform the user that the CData Connect AI MCP server is not currently connected - **Do** suggest they enable it in their MCP settings, connected apps, or integration settings - **Do not** infer that Connect AI is connected based on MCP server references in system context or artifact configurations. Only confirm availability through tool_search results. **If you are running in Claude Code** and the user wants to set Connect AI up for the first time (no account, no MCP server registered, or asking how to connect), hand off to the onboarding skill: invoke `connect-ai-onboarding-claude-code`. It walks through sign-up, registering the MCP server, connecting a data source, and a first query. Once the user completes it and restarts, re-running the original request will find the tools via this Step 0 and proceed normally. On any other surface — or if the user only wants documentation — direct them to the CData Connect AI integration documentation: https://docs.cloud.cdata.com/en/Integrations#ai-tools. To configure a data source connection within Connect AI, refer to: https://docs.cloud.cdata.com/en/Sources#add-a-connection ## Connect AI MCP — Core Discovery Workflow ### Step 1: Decide how you will answer the request Before any discovery or data retrieval, ask: **what is the best tool set to answer this prompt?** **Option 1 — Specific action tools** Does the available toolset include named action tools that directly address the request? (Examples: `list_accounts`, `update_contact`, `create_task`, `get_opportunity`.) If yes, prefer these. They are purpose-built for the operation and require no discovery workflow. Proceed directly to calling the relevant action tool. Do not run the discovery flow below. **Option 2 — Universal tools** If no specific action tool fits the request — or if the request requires ad-hoc querying, exploration, or cross-object work that action tools don't cover — use the universal tools (`queryData`, `getTables`, `getColumns`, etc.) and follow the discovery path below. --- ### Query Naming Convention All queries in Connect AI use a three-part fully-qualified name: ``` [Catalog].[Schema].[Table] ``` Where: - `[Catalog]` = the user-defined connection name (discovered via `getCatalogs` or toolkit tool names) - `[Schema]` = the schema name. For single-schema drivers, this is named after the driver itself (e.g., `Jira`, `QuickBooksOnline`, `BullhornCRM`). Multi-schema sources expose multiple options (e.g., Workday exposes `REST`, `WQL`, `Reports`, and `SOAP`) - `[Table]` = the target table Example: ```sql SELECT * FROM [MyJiraConnection].[Jira].[Issues] LIMIT 10 ``` --- ### Universal Tool Discovery Paths Once you have chosen Option 2, identify which discovery path applies by checking what tools are available. --- #### Path A: Generic MCP Server *Signal: a `getCatalogs` tool is present.* 1. **`getCatalogs`** — list available connections. Call once per conversation. Cache the result; do not re-call. **Connection disambiguation:** If `getCatalogs` returns multiple connections and the user has not specified which data source to use, do NOT guess. Instead: - If the user named a platform (e.g. "Salesforce," "SQL Server"), filter the catalog list to matching connections and ask which specific connection to use if there are multiple - If the user's question is ambiguous (e.g. "show me accounts" without naming a system), present a brief summary of available connection types and ask which one they want to query - Do not default to a connection based on assumed domain mapping (e.g. "accounts" does not always mean CRM) 2. **Check for a loaded skill** — before calling any schema/table/column tool for a driver, ask: *do I have a driver-specific skill already loaded for this data source?* - If **yes** → follow that skill's instructions and proceed to step #4. - If **no** → call `getInstructions` before proceeding. 3. **`getInstructions(driverName=)`** — REQUIRED before any `getSchemas`, `getTables`, or `getColumns` call for a driver with no loaded skill. The payload contains driver-specific hints not in the Agent's training data: quoting rules, SQL dialect quirks, required scope parameters, known-unsupported operations, and column-naming idioms. Call once per driver per conversation and read the output carefully — it is the highest-leverage context available. 4. **`getSchemas` / `getTables` / `getColumns`** — discover structure. Do not guess table or column names, even for well-known systems (Salesforce, Workday, SQL Server). Tenants may have custom objects, renamed fields, disabled tables, or non-standard schemas. Call `getColumns` before any `queryData` that references specific columns for the first time. 5. **`queryData`** — execute SQL. Always use the fully-qualified name `[Catalog].[Schema].[Table]`. Always apply `LIMIT` on exploratory queries unless the user explicitly requested full results. For stored procedures: `getProcedures` → `getProcedureParameters` → `executeProcedure`. The `getInstructions`-first rule applies here too. --- #### Path B: Toolkit — Universal Tools (connections or workspaces) *Signal: no `getCatalogs`.* **Connection targeting:** If the toolkit exposes tools for multiple connections (e.g. `jira1_*`, `confluence_*`, `bullhorn_*`), identify which connection is relevant to the user's request before calling any tools. If ambiguous, ask the user which data source they mean. Do not assume — tools that work on one connection may not exist or may be disabled on another. 1. **Check for a loaded skill** — do I have a driver-specific skill already loaded for this data source? - If **yes** → follow that skill's instructions and proceed to step #3. - If **no** → check to see if there is a tool `_get_instructions`. If there is, proceed to step #2; if not, proceed to step #3. 2. **`_get_instructions`** *(if present)* — same purpose as Path A. Call once per conversation and read the output carefully before continuing. 3. **`_get_schemas`** *(if present)* — only available when the source has multiple schemas. If `_get_schemas` is not present, skip directly to `_get_tables`. 4. **`_get_tables` / `_get_columns`** *(if present)* — discover structure. Same rules as Path A: do not guess names; call `_get_columns` before referencing specific columns in `_queryData`. **File-transfer tools** *(if present)* — a toolkit may also expose tools that move file content into or out of the source. Uploading is a three-part handshake: call `request_upload` to get an upload target and a token, transfer the bytes to that target out of band, then call the connector's upload tool with that token to complete the transfer. Downloading is a single call. In both directions the bytes travel out of band and never enter the conversation — do not inline or base64-encode file content. Once an upload has completed, do not repeat it. --- ### Precondition Decision Tree (Paths A and B) Before calling tools to retrieve schemas, tables, and columns for any driver: ``` Do I have a driver-specific skill loaded for this source? ├── YES → follow that skill └── NO → Is getInstructions available? ├── YES → call getInstructions first, then proceed └── NO → proceed directly to get schemas or get tables ``` --- ### Universal Rules (all paths) - Never guess table or column names, regardless of how well-known the source system is. - Always apply `LIMIT` on exploratory or diagnostic queries unless the user explicitly requested full results. - Cache catalog and instruction results mentally for the conversation — do not re-call unnecessarily. - For multi-schema sources, always qualify names as `[Catalog].[Schema].[Table]`. ## SQL Dialect & Supported Functions CData Connect AI drivers are SQL-92 compliant and also support functions from other SQL dialects (e.g., T-SQL). Before assuming a function is unsupported, consult the CData SQL Reference: https://docs.cloud.cdata.com/en/SQL-Reference/SQL-Reference When a user asks whether a specific function is supported (e.g., DATEADD, ISNULL, CONVERT), either check the reference above or test empirically with a simple query against a known table. ## Common error recovery patterns ### `Column '' not found` The column name is almost always wrong, not missing. Do NOT retry with a close variant — the combinatorial space is too large. Instead: 1. Call `getColumns` for the table if not already done 2. Find the actual column — watch for casing (`AnnualRevenue` vs `annualrevenue`), prefixes (`c_`, `custom_`), and suffixes (`__c` on Salesforce custom fields) 3. Re-issue `queryData` with the verified name ### Empty result set from `queryData` Before assuming there's no data: 1. Run a bounded count: `SELECT COUNT(*) FROM [Catalog].[Schema].[Table]` — does the table have rows at all? 2. Check filter value casing and whitespace — string comparisons are usually case-sensitive 3. Verify the connection's access scope with the user — some tenants restrict visibility by user/role at the connector level ### Timeout or very slow query 1. Add `LIMIT` — most business questions want top-N, not everything 2. Set filters in queries early — prefer date fields like CreatedDate or LastModifiedDate for large tables 3. Avoid `SELECT *` — specify only the relevant fields needed for the task 4. Remove unnecessary JOINs — simplify to only the joins required to answer the question 5. Check the driver instructions for result-size and pagination hints specific to that connector — some drivers (e.g. SAP, API Connector) support configurable page sizes or require explicit pagination handling ### `getTables` returns an incomplete or empty list Almost always means `getInstructions` was skipped, or that the driver needs a scope/database parameter that was revealed in the instructions output. Re-read `getInstructions` for that driver. ### User says "that's the wrong " Do not guess a correction. Run `getColumns` on the source table, show the user the column list, and ask which field they expected the query to filter or return on. Tenant-specific column naming is the most common root cause. ### Unexpected results or empty tables on a connection you chose If a query returns 0 rows on a table you expect to have data, or the data doesn't match what the user described: 1. Before trying alternative tables or queries on the same connection, ask the user: "I'm currently querying [connection name]. Is this the right data source for what you're looking for?" 2. If the user didn't originally specify a connection and you selected one, this is especially important — your initial selection may have been wrong 3. Do not adapt indefinitely within a connection that isn't producing the expected results ## Connector-specific skills Individual connectors have their own skills that compose on top of this base skill. They are named `connect-ai-` (e.g. `connect-ai-salesforce`, `connect-ai-jira`) and each carries a `family:` tag grouping it by domain (`crm`, `accounting`, `hcm`, `ticketing`, `files`, `collaboration`, …). Composition pattern: - If a connector-specific skill is available for the data source, load it — it carries quirks and query patterns beyond this base workflow. Load the most specific skill available; it layers on top of this one. - If no connector-specific skill exists, this base skill plus `getInstructions` (which supplies connector-specific guidance at runtime) is sufficient. This base skill does not maintain a catalog of connector skills — each connector skill declares its own trigger conditions, so it surfaces on its own when relevant.