get-apps
ChatGPTRetrieves app (template) definitions from Dashpivot with field-level metadata. Purpose Gateway to form data. Discover apps, review field definitions, select field IDs before calling get-forms. Prerequisites - For browse queries: call get-workspace-structure first to discover the hierarchy, then pass _path values. - For direct lookup: use appIds with any app identifier (FlakeID, ObjectId, or unique app ID). No _path needed — the server resolves it automatically. - If the user provides a Dashpivot URL, extract the ID from the URL path and pass it to appIds. Scoping Rules - Preferred: Use a project/team _path (e.g., "/ws_xxx/p_xxx") for targeted browse results. - Broader: Using a workspace _path ("/ws_xxx") may return many apps — only use for workspace-level apps or when a narrower _path is unavailable. - Combine _path with appName or templateTags to narrow results further. Parameters - appIds: Look up apps by any identifier — FlakeID (app_xxx), MongoDB ObjectId (24 hex chars), or unique app ID (e.g. TDW-C-JK6AQ). No _path needed. - _path: Required for browse queries, optional when appIds is provided. Use the narrowest paths available (e.g., ["/ws_xxx/p_xxx"]). - appName / templateTags: Filter apps - pageSize (default 25, max 25), pageCursor for pagination Key Behaviour - List/browse queries return app metadata with fieldCount only — look up specific apps by appIds to get full field definitions - Each app includes a _path field — use directly as _path in get-forms (e.g., ["/ws_xxx/p_xxx/app_xxx"]) - For workspace-wide queries, use _path: ["/" + workspaceId] (e.g., ["/ws_xxx"]) Field Selection for get-forms When calling get-forms, pass specific field IDs via the optional fieldIds parameter to control which fields are returned. Omitting fieldIds returns ALL fields including media (photo, signature, sketch) which contain large binary data. Select fields based on the task: - For text analysis: use singleLineInput, multiLineInput fields - For date filtering: use date fields - For status checks: use category, yesNoCheckbox fields - Avoid media fields (photo, signature, sketch, attachment) unless specifically needed — they contain large binary data Examples - Browse all apps in a project: { _path: ["/ws_xxx/p_xxx"] } - Find safety templates: { _path: ["/ws_xxx/p_xxx"], templateTags: ["safety"] } - Get field definitions for a specific app: { appIds: ["app_xxx"] } <!-- mcp-router:region-aware-pagination --> Pagination across regions: The response includes pageDetails.regions keyed by region (e.g. au1, uk1). To get the next page, pass pageCursor as a JSON object (not a string) with an entry for each region where isLastPage: false. Example: pageCursor: {"au1": "ws_abc", "uk1": "ws_xyz"}. Omit pageCursor entirely for the first page. pageSize applies per-region — the response may include up to pageSize × N items where N is the number of regions with data.
get-forms
ChatGPTRetrieves form data (filled-in records) for summarization, analysis, and reporting. When to Use - If the user provides a specific _path, call get-forms directly — do NOT call get-workspace-structure or get-apps first. - If the user asks about forms without a path, follow the standard discovery workflow. - If get-forms returns 0 results, check the instructions field for diagnostic guidance before making follow-up calls. Required Parameter - _path: Array of FlakeID paths (max 100). Use _path values from get-apps or get-workspace-structure (e.g., ["/ws_xxx/p_xxx/app_xxx"] or ["/ws_xxx"]). Key Parameters - formName / fieldFilters: Filter forms - workflowStep: Filter by workflow column — accepts position numbers (1, 2) and/or column name strings ("Supervisor Approval"). Case-insensitive. - createdDate: Filter by creation date range ({ after?, before? } — ISO 8601 strings) - fieldIds: Return only specific fields (use IDs from get-apps) - pageSize (default 10, max 10), pageCursor for pagination Response Format (compact) Compressed JSON with ~63% fewer tokens. Field values are lossless. Forms are grouped by app. Structure: - apps: array of app groups, each containing: - appPath: shared app path for this group - fields: array of { name, kind } — field definitions declared once per app - forms: array of { id, name, num, workflowCol, created, by, values } — each form's values array is positionally mapped to fields - Shortened keys: id=itemId, num=automatedFormNumber, workflowCol.pos=workflowColumn.position, workflowCol.name=workflowColumn.name, created=createdAt, by=createdBy.name - Pagination: pass pageDetails.cursor back as pageCursor to fetch the next page. pageDetails.pageNumber is informational only. Example response: `` {"apps":[{"appPath":"/ws_xxx/p_xxx/app_xxx","fields":[{"name":"Inspector","kind":"singleLineInput"},{"name":"Status","kind":"category"}],"forms":[{"id":"form_xxx","name":"Inspection #1","num":"SI-001","workflowCol":{"pos":2,"name":"Supervisor Approval"},"created":"2026-03-20T10:00:00Z","by":"John","values":["Michael",[{"name":"Pass","value":"pass"}]]}]}],"totalFormCount":42,"instructions":["Sending form 1 of 42.","More results available. Pass the cursor value as pageCursor to fetch the next page."],"pageDetails":{"cursor":"form_xxx","size":10,"isLastPage":false,"pageNumber":1}} ` To read a value: apps[i].forms[j].values[k] corresponds to apps[i].fields[k]. Field IDs for fieldFilters/fieldIds are available from get-apps. Key Behaviour - Results are sorted newest first (most recent form at index 0) - Each field has { _id, name, kind, value } — value contains the extracted data - Returns up to 10 forms per response — use pageDetails.cursor for pagination when more results exist - More specific _path values return faster results - Field value structures vary by kind — see get-apps field definitions for type metadata Examples - Get all forms for an app: { _path: ["/ws_xxx/p_xxx/app_xxx"] } - Forms from Q1 2026: { _path: ["/ws_xxx/p_xxx/app_xxx"], createdDate: { after: "2026-01-01T00:00:00Z", before: "2026-04-01T00:00:00Z" } } - Return only text fields: { _path: ["/ws_xxx/p_xxx/app_xxx"], fieldIds: ["fi_xxx", "fi_yyy"] } - Forms in approval step: { _path: ["/ws_xxx/p_xxx/app_xxx"], workflowStep: ["Supervisor Approval"] } - Forms in columns 1 or 2: { _path: ["/ws_xxx/p_xxx/app_xxx"], workflowStep: [1, 2] }`
get-workspace-structure
ChatGPTRetrieves workspace hierarchy (workspaces > projects > teams) with permission filtering. When to Call This is the FIRST tool to call in any workflow. Use it to discover the workspace structure before querying apps or forms. Present the returned structure to the user and let them choose which project or team to explore. Pass the returned _path values directly as the _path parameter to get-apps. Parameters - _path: Optional path(s) to scope the query (e.g., ["/ws_xxx"]) - workspaceName: Filter workspaces by name - pageSize (default 25, max 25), pageCursor for pagination Key Behaviour - Always returns the full hierarchy: workspaces > projects > teams - The response always includes the parent workspace ID (ws_xxx) for context, even for users who only have project/team-level access. Always prefer passing the project/team IDs (p_xxx) to get-apps, not the workspace ID. Search Tips Use short, distinctive substrings for workspaceName (e.g., "Acme" instead of "Acme Construction Pty. Ltd."). The search normalizes punctuation and whitespace for fuzzy matching. Example {} — discover all workspaces (no parameters needed) { workspaceName: "Acme" } — find a specific workspace by short name <!-- mcp-router:region-aware-pagination --> Pagination across regions: The response includes pageDetails.regions keyed by region (e.g. au1, uk1). To get the next page, pass pageCursor as a JSON object (not a string) with an entry for each region where isLastPage: false. Example: pageCursor: {"au1": "ws_abc", "uk1": "ws_xyz"}. Omit pageCursor entirely for the first page. pageSize applies per-region — the response may include up to pageSize × N items where N is the number of regions with data.
