> For the complete documentation index, see [llms.txt](https://docs.datalogz.io/guides/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.datalogz.io/guides/datalogz-mcp-servers/tools-reference.md). # Tools Reference ## MCP tool reference The Control Tower MCP server gives your AI assistant access to Datalogz inventory, usage, similarity, health, and governance data. This page covers all 19 tools, grouped by the questions they help answer. Ask using natural language and your assistant selects the tools and supplies the inputs. The tool names below help you understand what it can retrieve. To get connected, see [Connecting to an MCP Server](https://docs.datalogz.io/guides/datalogz-mcp-servers/connecting-to-an-mcp-server). ### Before you start * **Data freshness:** Results reflect data already collected by Control Tower. BI metadata and activity are as fresh as the latest connector scan. * **Read-only access:** Tools retrieve information. Make changes, resolve alerts, and run workflows in Control Tower. * **Account scope:** The connection provides access to the authenticated account's connectors. MCP operates at connector level; it does not apply team or workspace restrictions. * **Choosing a connector:** Start with `list_connectors`. Inventory queries and tools prefixed with `powerbi_` or `tableau_` work with one connector at a time. If several are available, your assistant must pass the relevant `account_connector_key`. ### Connectors and inventory #### `list_connectors` Lists the connectors available to the connection, including each connector's name, platform, active status, and asset count when available. It also returns the connector key used by other tools to select a data source. **Example:** “Which connectors can I query, and how many assets does each contain?” #### `describe_catalog` Shows what can be queried for one connector: available asset and record types, fields, allowed values, and relationships. It also provides query syntax and examples. Your assistant uses this before `run_dsl_query` to build a query that matches the connector's available data. **Example:** “What information can I query about our Tableau assets?” #### `run_dsl_query` Searches, filters, counts, and retrieves records using the Datalogz query language (DSL). Use it to find assets by name or ID, inspect ownership and metadata, or follow relationships and lineage. It returns matching rows and a total count when available, even when only a sample is shown. The query runs against one connector. Available fields and relationships come from `describe_catalog`; upstream and downstream lineage depend on the platform and collected data. **Example:** “Which reports depend on the Finance semantic model?” ### Data sources These tools use the shared inventory and can cover all available connectors or one selected connector. #### `data_source_breakdown` Counts inventory assets by data-source type, helping you understand which source technologies feed your BI estate. An optional `source_filter`, such as `snowflake`, adds a matching asset count based on source type or connection details while retaining the overall breakdown. Counts represent inventory assets. **Example:** “How many assets use Snowflake, and what other data sources do we use?” #### `list_data_sources` Lists assets with recorded data-source information, including asset name, type, source type, workspace, and owner when available. Filter by source type or connection details to investigate the assets behind a breakdown. **Example:** “Show the assets that use Snowflake, with their workspaces and owners.” ### Report usage These tools support **Power BI**. Start with the report ranking to discover an asset, then use its ID to inspect usage or viewers. #### `powerbi_top_viewed_reports` Ranks reports by view count over a chosen period, with a default of 30 days. Results include views, downloads, distinct viewers, and available report, workspace, and owner details. Use it to identify widely used reports before investigating an individual report. **Example:** “What are our 10 most-viewed Power BI reports in the last 90 days?” #### `powerbi_view_counts` Returns view counts and distinct-viewer counts for one report across several lookback periods, plus totals across the available history. The default periods are 30, 60, and 90 days; custom periods, such as 7 and 45 days, are supported. Requires the report's `asset_id`. **Example:** “Compare views and unique viewers for the Sales Overview report over 30, 60, and 90 days.” #### `powerbi_report_viewers` Lists viewers of one report, with their view counts and last-viewed dates, over a chosen period. The default is 30 days. Names and emails appear when they can be matched to directory data; unmatched viewers are marked as unresolved. Requires the report's `asset_id`. **Example:** “Who viewed Sales Overview in the last 30 days, and are any viewers unresolved?” ### Similarity and duplication These tools surface potentially overlapping assets for review. Each searches within one connector and uses a minimum similarity score (`min_score`) of **0.7** by default. Increase the threshold to focus on closer matches. #### `powerbi_find_similar` Finds assets similar to a specific Power BI report or semantic model, ordered by similarity score. Returns matching asset IDs, names, owners when available, and scores. Supply the source `asset_id` and choose `asset_type`: `report` (default) or `dataset` for semantic models. **Example:** “Find reports similar to Sales Overview so we can review possible duplicates.” #### `powerbi_top_similar_assets` Ranks Power BI assets by how many similar assets meet the score threshold. Use it to prioritize consolidation reviews across a connector. Choose `asset_type`: `report` (default) or `dataset` for semantic models. Results include each asset's similar-asset count. **Example:** “Which Power BI semantic models have the most potential duplicates?” #### `tableau_find_similar` Finds assets similar to a specific Tableau dashboard or data source, ordered by similarity score. Returns matching asset IDs, names, owners when available, and scores. Supply the source `asset_id` and choose `asset_type`: `dashboard` (default) or `datasource`. **Example:** “Which Tableau dashboards are most similar to Executive Overview?” #### `tableau_top_similar_assets` Ranks Tableau assets by how many similar assets meet the score threshold. Choose `asset_type`: `dashboard` (default) or `datasource`. Use the returned counts to identify where a duplication review could have the greatest impact. **Example:** “Which Tableau data sources have the most similar alternatives?” ### Refresh and capacity health #### `refresh_health` Summarizes successful, failed, and total refreshes, plus the success ratio, for connectors with recorded refresh activity. Uses the latest available snapshot containing refresh counts for each connector. It can cover multiple platforms or one selected connector and provides a connector-level health overview. **Example:** “Which connectors have the lowest refresh success rates?” #### `powerbi_capacity_health` Lists **Power BI** capacities with their recorded state, region, capacity type, and Premium or Fabric indicators. Use it to check capacity configuration and state when investigating an issue. CPU utilization and other live performance measurements are outside this tool's scope. **Example:** “List our Power BI capacities and show which are active or paused.” ### Users and workspace access #### `powerbi_workspace_access` Shows recorded **Power BI** workspace membership and roles. Supply either a `workspace_id` to list its members, or a `user_query` containing a name or email fragment to find that user's workspaces and roles. Choose one mode per request. **Example:** “Which Power BI workspaces can access, and with what roles?” #### `user_activity` Builds a user overview from a name or email search: owned or created assets, activity counts and recent actions, and workspace access. Ownership can span connected platforms; action history and workspace roles are **Power BI only**. Use a full email address to reduce ambiguous matches. Activity covers the available history, with a sample of recent events. **Example:** “What does own, what have they done recently, and which Power BI workspaces can they access?” ### Alerts and platform changes #### `alerts` Finds monitor alerts by creation date or date range, status, priority, or asset name. Returns the total matching count, breakdowns by priority and status, a sample of the newest matching alerts, and the available alert date range. Searches across the authenticated account. **Example:** “Show this week's alerts for Finance assets, grouped by priority and status.” #### `platform_timeline` Lists monitors created and connectors added during an optional date range. Includes daily monitor-creation counts and monitor details to help explain changes in monitoring coverage. An optional `name_query` filters monitor names; connector additions remain filtered by date. Searches across the authenticated account. **Example:** “Which monitors and connectors were added last week?” #### `day_summary` Summarizes one date: alerts raised by priority and asset type, assets created, and connectors and monitors added. It also shows how many alerts came from monitors created that day, helping put an alert spike in context. Supply a `date` and optionally select one connector. **Example:** “Summarize September 15, 2026, including alerts generated by monitors added that day.” ### Getting useful answers * **Be specific:** Include the platform, connector, asset or user, and time period relevant to your question. Your assistant can look up asset and workspace IDs through the inventory tools. * **Use clear dates:** Date inputs use `YYYY-MM-DD`; date ranges include both endpoints. Usage tools accept lookback periods in days. * **Distinguish totals from samples:** Most tools that accept `limit` default to 25 rows, with a configured maximum of 200. The report-viewer tool defaults to 100. A returned list may be a sample; use a separate total when the response provides one. Deployment settings can change these limits. * **Check data coverage:** Empty results can reflect missing scan data, unavailable platform fields, or filters that match nothing. Use connector discovery and the catalog to confirm what is available. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.datalogz.io/guides/datalogz-mcp-servers/tools-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.