The DX MCP Server enables AI applications to interact with your DX Data Cloud database and software catalog. Key capabilities include:
Execute SQL Queries (queryData): Run SQL queries directly against the DX Data Cloud PostgreSQL database, with the ability to explore schema via information_schema when table structures are unknown.
Browse the Software Catalog (listEntities, getEntityDetails): List and search entities (e.g., services, teams) and retrieve comprehensive details including scorecards and operational health.
Manage Scorecards (listScorecards, getScorecardInfo): List all active scorecards and retrieve detailed information including defined levels and checks.
Track Initiatives (listInitiatives, getInitiativeDetails): List initiatives with filtering options (by priority, tags, published status) and retrieve detailed progress reports.
Review & Resolve Tasks (reviewTasks): Review, resolve, or complete outstanding DX tasks (failing checks) for entities by specifying the entity identifier and relevant check IDs.
Explore Teams (listTeams, getTeamDetails): List all teams in DX and retrieve detailed information by team ID, reference ID, or member email addresses.
Allows for the connection to and execution of queries on a PostgreSQL database within the DX Data Cloud, enabling natural language interaction with organizational data and software entity information.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@DX MCP Server show me the top 5 customers by total sales this month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The DX MCP Server is a Python-based tool that empowers AI applications, such as Claude for Desktop and Cursor, to interact with your DX Data Cloud database. The server includes tools to:
establish a connection to your Postgres database, allowing the AI to actively formulate and execute queries on the database
find/utilize context about your software entities and their relationships and scorecards via DX catalog tools
Learn more about the Model Context Protocol (MCP).
Note: DX intends for the CLI to become the primary interface for AI agents and is investing in it as the long-term direction beyond the MCP server. Both interfaces remain supported.
Related MCP server: PostgreSQL MCP Server
https://github.com/user-attachments/assets/c6ce12a5-4562-4b44-b235-2d04871c3142
There are two ways to use the DX MCP Server:
Remote hosting (recommended): Connect to our hosted server at https://ai.getdx.com/mcp
Local hosting: Run the server on your machine
A DX account with access to Data Cloud
For remote hosting:
A DX API token, generated in your DX Account Settings
Admin users can create an organization API token with read scopes granted, and non-admin users can generate personal access tokens to authenticate with the MCP server.
For local hosting:
Python 3.10 or higher
Your database connection URL (configured on DX's DB Users settings page)
A DX API token, generated in your DX Account Settings
Admin users can create an organization API token with read scopes granted, and non-admin users can generate personal access tokens to authenticate with the MCP server.
The hosted MCP server uses streamable HTTP transport and is available at https://ai.getdx.com/mcp. This option requires no local installation; just configure your AI client with the mcp using http transport and provided with a valid DX API Token.
Run this command in your terminal:
claude mcp add --transport http dx-mcp https://ai.getdx.com/mcp --header "Authorization: Bearer [YOUR_DX_API_TOKEN]"Add this configuration to your MCP settings (Cursor > Settings > Cursor Settings > MCP):
{
"mcpServers": {
"dx-mcp": {
"url": "https://ai.getdx.com/mcp",
"headers": {
"Authorization": "Bearer [YOUR_DX_API_TOKEN]"
}
}
}
}If you prefer to run the DX MCP Server locally, you can install it via PyPI or run it from source.
Install the package using pip:
pip install dx-mcp-serverNote for macOS users: If you encounter an "externally-managed-environment" error, use
pipxinstead:pipx install dx-mcp-server
Clone this repository to run from source:
git clone https://github.com/get-dx/dx-mcp-server
cd dx-mcp-serverOnce installed, configure your AI client with the appropriate settings:
Run this command in your terminal (adjust based on your installation method):
# If installed via pip/pipx
claude mcp add dx-mcp-server --env DB_URL=YOUR_DB_URL --env WEB_API_TOKEN=YOUR_DX_API_TOKEN -- $(which dx-mcp-server)Click Claude > Settings > Developer > Edit Config and add:
If you installed via pip:
{
"mcpServers": {
"dx-mcp": {
"command": "dx-mcp-server",
"args": ["run"],
"env": {
"DB_URL": "YOUR-DATABASE-URL",
"WEB_API_TOKEN": "YOUR_DX_API_TOKEN"
}
}
}
}If you're running from source:
{
"mcpServers": {
"dx-mcp": {
"command": "uv",
"args": ["--directory", "/path/to/dx-mcp-server", "run", "-m", "dx_mcp_server", "run"],
"env": {
"DB_URL": "YOUR-DATABASE-URL",
"WEB_API_TOKEN": "YOUR-DX-API-TOKEN"
}
}
}
}Click Cursor > Settings > Cursor Settings > MCP > Add new global MCP Server and add:
If you installed via pip:
{
"mcpServers": {
"dx-mcp": {
"command": "dx-mcp-server",
"args": ["run"],
"env": {
"DB_URL": "YOUR-DATABASE-URL",
"WEB_API_TOKEN": "YOUR-DX-API-TOKEN"
}
}
}
}If you're running from source:
{
"mcpServers": {
"dx-mcp": {
"command": "uv",
"args": ["--directory", "/path/to/dx-mcp-server", "run", "-m", "dx_mcp_server", "run"],
"env": {
"DB_URL": "YOUR-DATABASE-URL",
"WEB_API_TOKEN": "YOUR-DX-API-TOKEN"
}
}
}
}DB_URL (required): Your DX Data Cloud Postgres connection string. Get this from DX DB Users settings.
Format: postgresql://username:password@host:port/database
WEB_API_TOKEN: Your DX API Token (either an organization token or a personal access token). This enables additional catalog and entity tools. Find this in your DX account settings.
After saving the configuration, restart your AI client. You should see "dx-mcp" in the available MCP servers. When you ask questions about your data or catalog, the AI will use these tools to query your database or hit the relevant web apis.
The most common issue involves the MCP client not finding the dx-mcp-server/uv command, as GUI applications don't inherit the same PATH environment variables as the terminal. The solution is to use the full path to the executable in the json config.
Find the full path to dx-mcp-server:
# Find the path on macOS/Linux
which dx-mcp-server
# Find the path on Windows (in Command Prompt)
where dx-mcp-serverThen use the full path in your configuration:
{
"mcpServers": {
"dx-mcp": {
"command": "/full/path/to/dx-mcp-server",
"args": ["run"],
"env": {
"DB_URL": "YOUR-DATABASE-URL",
"WEB_API_TOKEN": "YOUR-DX-API-TOKEN"
}
}
}
}Find the full path to uv:
# Find the path on macOS/Linux
which uv
# Find the path on Windows (in Command Prompt)
where uvThen use the full path in your configuration:
{
"mcpServers": {
"dx-mcp": {
"command": "/full/path/to/uv",
"args": ["--directory", "/absolute/path/to/dx-mcp-server", "run", "-m", "dx_mcp_server", "run"],
"env": {
"DB_URL": "YOUR-DATABASE-URL",
"WEB_API_TOKEN": "YOUR-DX-API-TOKEN"
}
}
}
}If you're still experiencing issues:
Claude Desktop: Check logs at:
macOS: ~/Library/Logs/Claude/
Windows: %APPDATA%\Claude\logs\
Cursor: Check logs at:
macOS: ~/Library/Application Support/Cursor/logs/[SESSION_ID]
Windows: %APPDATA%\Cursor\logs\[SESSION_ID]
The logs will show warning and error messages when starting or running the MCP server.
Get comprehensive details about a specific entity including its information, tasks, and scorecards - we can use this to check operational readiness/health of an entity.
Args: identifier (str): The unique identifier for the entity (e.g., 'payment-processing').
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes a read operation ('Get') but lacks details on permissions, rate limits, error handling, or what 'comprehensive details' entails. The mention of checking 'operational readiness/health' adds some context, but behavioral traits like data freshness or access controls are unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first sentence states the purpose clearly, followed by usage context and parameter details. It avoids redundancy, though the 'Args' section could be integrated more smoothly. Overall, it's efficient with minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which handles return values), a single parameter well-explained in the description, and no annotations, the description is reasonably complete. It covers purpose, usage hint, and parameter semantics, though it could improve by addressing behavioral aspects like permissions or data scope more explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes an 'Args' section that explains the single parameter: 'identifier (str): The unique identifier for the entity (e.g., 'payment-processing').' This adds meaning beyond the input schema, which has 0% description coverage, by providing an example and clarifying it's a unique identifier. Since there's only one parameter, this compensates well for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get comprehensive details about a specific entity including its information, tasks, and scorecards.' It specifies the verb ('Get'), resource ('entity'), and scope ('comprehensive details'), though it doesn't explicitly differentiate from siblings like getInitiativeDetails or getTeamDetails beyond the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage context: 'we can use this to check operational readiness/health of an entity,' suggesting it's for health assessment. However, it doesn't explicitly state when to use this tool versus alternatives like listEntities for listing or getScorecardInfo for focused details, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get initiative details including both the initiative info and its progress report.
Note: This calls two endpoints:
initiatives.info
initiatives.progressReport
Args: id (str): Initiative public ID. entity_type_identifiers (str, optional): Passed through to initiatives.progressReport. limit (int, optional): Passed through to initiatives.progressReport. Maximum 100, defaults to 50. cursor (str, optional): Passed through to initiatives.progressReport.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| entity_type_identifiers | No | ||
| limit | No | ||
| cursor | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool calls two endpoints, which adds behavioral context beyond a simple read operation. However, it lacks details on permissions, rate limits, error handling, or what the combined output looks like. For a tool with no annotations, this is a moderate but incomplete disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, followed by a note on implementation and a clear parameter breakdown. Every sentence adds value: the first states the goal, the note clarifies the backend calls, and the Args section documents parameters efficiently without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (calls two endpoints, 4 parameters), no annotations, and an output schema present, the description is fairly complete. It covers the purpose and parameters well, and the output schema likely handles return values. However, it could improve by addressing behavioral aspects like error cases or usage context relative to siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate fully. It does so by explaining all four parameters: 'id' as the 'Initiative public ID', and the optional parameters with their purposes, defaults, and constraints (e.g., 'limit' with 'Maximum 100, defaults to 50'). This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get initiative details including both the initiative info and its progress report.' It specifies the verb ('Get') and resource ('initiative details'), and mentions it calls two specific endpoints. However, it doesn't explicitly differentiate from sibling tools like 'getEntityDetails' or 'listInitiatives' beyond the resource focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'listInitiatives' for listing or 'getEntityDetails' for other entity types, nor does it specify prerequisites or exclusions. The note about calling two endpoints is technical but doesn't inform usage decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve details about a specific scorecard, including its defined levels and checks. Args: id (str): The unique ID of the scorecard.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states this is a retrieval operation, implying read-only behavior, but doesn't disclose any behavioral traits such as authentication requirements, rate limits, error conditions, or what happens if the ID is invalid. For a tool with no annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first sentence clearly states the purpose, followed by a structured 'Args:' section that efficiently documents the parameter. There is no wasted text, and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter), no annotations, and the presence of an output schema (which handles return values), the description is reasonably complete. It covers the purpose and parameter semantics adequately. However, it could improve by adding more behavioral context, such as error handling or usage guidelines relative to siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful semantics beyond the input schema, which has 0% description coverage. It explains that 'id' is 'The unique ID of the scorecard,' clarifying its purpose and format. With only one parameter and no schema descriptions, this compensates well, though it could provide more context (e.g., where to find the ID).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Retrieve details') and resource ('about a specific scorecard'), and specifies what details are included ('its defined levels and checks'). It distinguishes from listScorecards by focusing on a single scorecard rather than listing multiple. However, it doesn't explicitly differentiate from other get* siblings like getEntityDetails beyond the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying 'a specific scorecard' and the required ID parameter, suggesting this is for retrieving details of a known scorecard. However, it doesn't explicitly state when to use this versus listScorecards (for listing all scorecards) or other get* tools, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve details for an individual team. Note that searching by team_emails will return things like the team name and members, where the search by team_id/reference_id will return more detailed information about the team structure.
Args: team_id (str, optional): The DX team ID. reference_id (str, optional): The team's internal reference ID in your organization. team_emails (str, optional): Comma separated list of team members' email addresses.
| Name | Required | Description | Default |
|---|---|---|---|
| team_id | No | ||
| reference_id | No | ||
| team_emails | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It describes the tool's behavior regarding different parameter usage and the type of information returned, but lacks details on permissions, rate limits, error handling, or response format. This is adequate but has clear gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with two main sentences and a structured Args section. The information is front-loaded with the purpose first, followed by usage notes and parameter details. Minor improvement could be made by integrating the Args section more seamlessly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which handles return values), no annotations, and 3 parameters with 0% schema coverage, the description does well by explaining parameter semantics and usage context. It could be more complete by addressing behavioral aspects like error cases or authentication, but the output schema reduces the burden.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides detailed semantic information for all three parameters: team_id as 'DX team ID', reference_id as 'internal reference ID in your organization', and team_emails as 'comma separated list of team members' email addresses'. This fully explains parameter meanings beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'retrieve' and resource 'details for an individual team', making the purpose specific. It distinguishes between different search methods but doesn't explicitly differentiate from sibling tools like 'listTeams' or 'getEntityDetails', which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use different parameters (team_id/reference_id vs team_emails) and what information each returns. However, it doesn't explicitly state when to use this tool versus alternatives like 'listTeams' or 'getEntityDetails', which would be needed for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List entities from the DX software catalog.
Args: search_term (str, optional): Search term to filter by. type (str, optional): Filter entities by type (e.g., 'service', 'team', etc.). cursor (str, optional): Cursor for pagination. Get from response_metadata.next_cursor in prior requests. limit (int, optional): Number of entities per page - if present, must be between 1 and 50.
| Name | Required | Description | Default |
|---|---|---|---|
| search_term | No | ||
| type | No | ||
| cursor | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal pagination behavior (cursor-based) and rate limiting (limit 1-50), which are important operational details. However, it doesn't mention authentication requirements, error conditions, or what happens when no results match filters - leaving significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening statement followed by parameter documentation. The Args section is organized but could be more concise - some explanations could be tighter. Overall, it's appropriately sized for a 4-parameter tool with no schema descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which handles return values), 4 parameters with 0% schema coverage, and no annotations, the description does a reasonably complete job. It explains all parameters and key behaviors like pagination. The main gap is lack of sibling differentiation, but otherwise it provides sufficient context for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate, and it does so effectively. It explains all 4 parameters: 'search_term' filters by text, 'type' filters by entity category, 'cursor' enables pagination continuation, and 'limit' controls page size with validation rules. This adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('entities from the DX software catalog'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'listInitiatives' or 'listTeams' - it doesn't explain what 'entities' encompasses versus those other list operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. With siblings like 'listInitiatives', 'listTeams', and 'listScorecards', the description doesn't clarify whether this tool is comprehensive (listing all entity types) or how it relates to those more specific list operations. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists all initiatives with summary information.
Args: cursor (str, optional): Cursor for pagination. Get from response_metadata.next_cursor in prior requests. limit (int, optional): Limit the number of initiatives per page. Maximum 100, defaults to 50. published (bool, optional): Filter by published status. priority (int, optional): Filter by priority (0-2, lower numbers are more urgent). tags (str, optional): Comma-separated tags to filter by.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | ||
| limit | No | ||
| published | No | ||
| priority | No | ||
| tags | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions pagination behavior ('cursor for pagination') and constraints ('maximum 100, defaults to 50'), which adds some value. However, it doesn't cover important aspects like whether this is a read-only operation, what authentication is required, rate limits, error conditions, or what 'summary information' specifically includes. For a listing tool with 5 parameters, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement followed by organized parameter documentation. Each parameter explanation is efficient and adds value. The only minor improvement would be integrating the purpose more seamlessly with the parameter section, but overall it's appropriately sized with minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (5 optional parameters, listing operation) and the presence of an output schema (which handles return values), the description is reasonably complete. It covers all parameters thoroughly and mentions key behavioral aspects like pagination and limits. The main gap is lack of sibling differentiation and some behavioral context, but the parameter coverage is excellent and the output schema reduces need for return value documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides excellent parameter semantics despite 0% schema description coverage. It explains all 5 parameters with clear purpose: cursor (pagination mechanism with source location), limit (range and default), published (filter by status), priority (range 0-2 with urgency interpretation), and tags (format and filtering purpose). This fully compensates for the schema's lack of descriptions and adds meaningful context beyond basic type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Lists all initiatives with summary information.' It specifies the verb ('Lists') and resource ('initiatives') with scope ('all') and output type ('summary information'). However, it doesn't explicitly differentiate from sibling tools like 'listEntities' or 'listTeams' which may have similar listing patterns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'getInitiativeDetails' (likely for single initiatives) and 'queryData' (possibly for more complex queries), there's no indication of when this filtered listing tool is preferred over other options. The parameter documentation implies filtering capabilities but doesn't contextualize usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all active scorecards. Args: cursor (str, optional): Cursor for pagination. Get from response_metadata.next_cursor in prior requests. limit (int, optional): Limit the number of scorecards per page. Must be between 1 and 50.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals pagination behavior (cursor-based) and a limit range constraint (1-50), which are valuable. However, it doesn't mention authentication requirements, rate limits, whether the list includes archived/inactive scorecards, or what the output format looks like (though an output schema exists).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with two sentences: one stating the purpose and another explaining parameters in a structured format. Every sentence adds value, though the parameter explanations could be slightly more integrated rather than appearing as a separate 'Args:' section.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no annotations, but with an output schema), the description is partially complete. It covers the basic purpose and parameters well, but lacks usage context relative to siblings and doesn't address behavioral aspects like authentication or filtering. The existence of an output schema reduces the need to explain return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate fully. It successfully explains both parameters: 'cursor' for pagination (including where to get it) and 'limit' with its valid range (1-50). This adds essential meaning beyond the bare schema, though it doesn't cover default values or optionality.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all active scorecards'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'listEntities', 'listInitiatives', or 'listTeams', which appear to follow similar patterns for different resource types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance about when to use this tool versus alternatives like 'getScorecardInfo' or 'queryData'. It mentions pagination parameters but doesn't explain the context for choosing this tool over other listing or querying tools available on the server.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all teams in DX.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It implies a read operation but doesn't disclose pagination, sorting, rate limits, authentication needs, or what 'all teams' entails (e.g., archived teams included?).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, output schema exists), the description is adequate but minimal. It covers the basic purpose but lacks context on usage vs. siblings and behavioral details, which are gaps even for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the schema already fully documents the input (none). The description doesn't need to add parameter details, and it correctly implies no filtering or arguments are required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all teams in DX'), making the purpose immediately understandable. It doesn't explicitly differentiate from siblings like 'listEntities' or 'listInitiatives', but the specific focus on 'teams' provides reasonable distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'listEntities' or 'getTeamDetails'. The description only states what it does, not when it's appropriate or what context it serves.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a SQL query against the DX Data Cloud PostgreSQL database. Always query from information_schema if you are uncertain about which tables and columns to look at. Args: sql (str): SQL query to execute
Returns: str: Formatted query results or error message
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the database type (PostgreSQL) and provides a helpful tip about information_schema, but doesn't address important behavioral aspects like authentication requirements, rate limits, transaction behavior, or whether queries are read-only vs. mutating. The description adds some context but leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly structured and front-loaded: the first sentence states the core purpose, the second provides crucial usage guidance, and the Args/Returns sections are clearly labeled. Every sentence earns its place with zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (direct SQL execution), no annotations, and an output schema that exists, the description does well but has gaps. It explains the parameter meaning and provides database-specific guidance, but doesn't address safety concerns, permissions, or result formatting details that would be important for a SQL execution tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage for the single parameter, the description fully compensates by clearly explaining what the 'sql' parameter is ('SQL query to execute'). It provides essential semantic meaning that the schema alone lacks, though it doesn't give examples or format specifics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Execute a SQL query') and target resource ('DX Data Cloud PostgreSQL database'), distinguishing it from sibling tools that are all named get/list/review operations. It precisely defines what this tool does that others don't.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use this tool ('Always query from information_schema if you are uncertain about which tables and columns to look at'), which gives practical guidance. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Review/resolve/complete outstanding DX tasks (failing checks).
Args: entity_identifier (str): Entity identifier. check_ids (str): Comma-separated list of check IDs to focus on.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_identifier | Yes | ||
| check_ids | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a mutation action ('resolve/complete') but doesn't specify permissions needed, whether changes are reversible, rate limits, or what the response entails. This is a significant gap for a tool that appears to modify data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose, followed by parameter details. The two sentences earn their place by covering action and parameters efficiently, though it could be slightly more structured with bullet points or clearer separation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (a mutation tool with 2 parameters, no annotations, but an output schema exists), the description is minimally adequate. It covers the purpose and parameters but lacks behavioral context and usage guidelines. The output schema mitigates some gaps by handling return values, but overall completeness is limited.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds basic meaning for both parameters (entity_identifier and check_ids), including that check_ids are comma-separated. However, it doesn't explain what an 'entity' is, provide examples, or detail format constraints, leaving gaps in understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('review/resolve/complete') and resource ('outstanding DX tasks (failing checks)'), making the purpose specific. However, it doesn't explicitly differentiate from sibling tools like 'getEntityDetails' or 'queryData', which might also relate to task information but with different functions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, exclusions, or compare to sibling tools like 'listEntities' or 'queryData', leaving the agent to infer usage context from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.3.0getEntityDetailsgetInitiativeDetailsgetScorecardInfogetTeamDetailslistEntitieslistInitiativeslistScorecardslistTeamsqueryDatareviewTasksScored across 10 tools
Most tools have distinct purposes targeting different resources (entities, initiatives, scorecards, teams, tasks, and data queries), but getEntityDetails and getScorecardInfo could potentially overlap if scorecards are part of entity details. The descriptions clarify their focus, but there's minor ambiguity in the entity/scorecard relationship.
Tools follow a consistent verb_noun pattern (getEntityDetails, listEntities, etc.) with clear prefixes (get, list, query, review). The only deviation is queryData which uses 'query' instead of 'get' or 'list', but this is semantically appropriate for SQL execution, maintaining overall readability.
With 10 tools, the count is well-scoped for a DX software catalog and operational readiness server. Each tool serves a clear purpose in managing entities, initiatives, scorecards, teams, tasks, and data queries, avoiding bloat while covering essential operations.
The toolset provides good read/list coverage for entities, initiatives, scorecards, and teams, plus task review and data querying. However, there are notable gaps in write operations (e.g., no create/update/delete tools for these resources) and limited task management beyond review, which may hinder full lifecycle management in the domain.
Query PostgreSQL databases in plain English — LLM-generated, safety-validated SQL.
Ask data questions in natural language. Get SQL, insights, and charts from your databases.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Query BigQuery, Snowflake, Redshift & Azure Synapse with natural language
