Vizro-MCP 是一个模型上下文协议 (MCP)服务器，它与 LLM 一起工作来帮助您创建 Vizro 仪表板和图表。
Vizro-MCP 提供工具和模板，帮助您逐步创建功能齐全的 Vizro 图表或仪表板。其优势包括：
✅ 一个用于图表和仪表板的一致框架，具有一种通用的设计语言。
✅ 经过验证的配置输出易于阅读且易于更改或维护。
✅ 实时预览仪表板，以迭代设计，直到仪表板完美为止。
✅ 只需提供路径或 URL 即可使用本地或远程数据集。
如果没有 Vizro-MCP，如果你尝试使用 LLM 制作仪表板，它可能会选择任何框架，并且在没有特定指导、设计原则或一致性的情况下使用它。结果是：
❌ 随机选择前端框架或图表库。
❌ 一种氛围编码的混乱，可能会运行也可能不会运行，但肯定不太易于维护。
❌ 无法轻松预览仪表板。
❌ 没有简单的方法来连接真实数据。
Related MCP server: ML Research MCP
如果您是开发人员，需要从源代码运行 Vizro-MCP 或从 Docker 容器运行服务器的说明，请跳至本页末尾的开发或从源代码运行。
🐛注意： VS Code目前存在一些已知问题，但我们正在努力解决这些问题，并希望 Copilot 能够尽快恢复正常运行。
⚠️**警告：**在某些主机（例如 Claude Desktop）中，免费方案的性能可能较低，当请求过于复杂时可能会导致问题。如果请求导致 UI 崩溃，请选择付费方案或降低请求的复杂度。
所有主机的通用服务器配置大致相同：
{
"mcpServers": {
"vizro-mcp": {
"command": "uvx",
"args": [
"vizro-mcp"
]
}
}
}原则上，Vizro MCP 服务器可与任何支持 MCP 的 LLM 应用程序兼容，但我们推荐 Claude Desktop 或 Cursor 作为热门选择（请参阅下文的详细说明）。不同的 AI 工具可能使用不同的设置方法或连接设置。详情请参阅每个工具的文档。
将以下内容添加到通过开发人员设置找到的claude_desktop_config.json中。
{
"mcpServers": {
"vizro-mcp": {
"command": "uvx",
"args": [
"vizro-mcp"
]
}
}
}⚠️**警告：**在某些情况下，你可能需要提供
uvx可执行文件的完整路径，因此不要使用uvx，而应该使用类似/Users/<your-username>/.local/bin/uvx的路径。要在你的机器上查找uvx的路径，请在终端应用中输入which uvx。
如果您正在使用 Claude Desktop，请重新启动它，片刻之后，您应该会在打开设置/上下文菜单时看到 vizro-mcp 菜单：
将以下内容添加到通过 Cursor Settings 找到的mcp.json中。
{
"mcpServers": {
"vizro-mcp": {
"command": "uvx",
"args": [
"vizro-mcp"
]
}
}
}⚠️**警告：**在某些情况下，你可能需要提供
uvx可执行文件的完整路径，因此不要使用uvx，而应该使用类似/Users/<your-username>/.local/bin/uvx的路径。要在你的机器上查找uvx的路径，请在终端应用中输入which uvx。
同样，使用 Cursor 时，短暂暂停后，您应该会在 MCP 菜单中看到绿灯：
并非所有 MCP 主机都提供提示模板，但如果提供，您可以使用它们快速获取特定的仪表板。要访问它们（例如在 Claude Desktop 中），请点击聊天下方的加号图标，然后选择*Add from vizro-mcp* 。
开始使用 Vizro 仪表板最简单的方法是选择模板create_starter_dashboard ，然后发送提示即可。这将创建一个非常简单的仪表板，其中包含一个页面、一个图表和一个筛选器。从这里开始吧！
如果你已经有了明确的目标，也可以要求法学硕士（LLM）根据本地或远程数据创建特定的仪表板。示例提示如下：
创建一个 Vizro 仪表板，其中包含一个页面、一个散点图和一个基于
<insert absolute file path or public URL>数据的过滤器。
创建一个简单的两页 Vizro 仪表板，第一页是
<insert absolute file path or public URL>数据的相关性分析，第二页是<insert absolute file path or public URL>数据的地图图
您可以在Plotly 存储库中找到一组示例 CSV 进行尝试。
您甚至可以在不提供数据的情况下请求仪表板：
创建一个包含一页、一个散点图和一个过滤器的 Vizro 仪表板。
一般来说，它有助于在提示中指定 Vizro 并使其尽可能精确（和简单）。
当 LLM 选择使用工具validate_model_config ，并且该工具成功执行时，如果仅使用通过 URL 访问的公共数据，LLM 将返回一个指向仪表板实时预览的链接。默认情况下，除非您设置不要打开，否则 LLM 甚至会在浏览器中打开该链接。在 Claude Desktop 中，您可以通过打开可折叠工具并向下滚动到最底部来查看该工具的输出。
您也可以要求模型为您提供链接，但它会尝试重新生成它，这很容易出错并且速度很慢。
如果您不想创建完整的 Vizro 仪表板，仍然可以使用 Vizro-MCP 创建单个图表的代码。如果您不确定想要哪种图表，可以查看Vizro 可视化词汇表来获取灵感。
创建 Vizro 图表最简单的方法是选择模板create_vizro_chart ，然后发送提示即可。这将创建一个您可以修改的简单图表。从这里开始吧！
或者，您也可以直接在聊天中询问，例如：
根据鸢尾花数据集创建散点图。
根据
<insert absolute file path or public URL>数据创建条形图。
MCP 服务器是一个相对较新的概念，因此，务必明确了解这些工具的功能，以便用户做出明智的选择。总而言之，Vizro MCP 服务器仅读取数据，绝不会写入、删除或修改您计算机上的任何数据。
一般来说，该过程中最关键的部分是load_and_analyze_data工具。此工具在您的计算机上运行，会将本地或远程数据加载到 pandas DataFrame 中，并对其结构和内容进行详细分析。它仅使用pd.read_xxx ，因此通常无需担心隐私或数据安全问题。但是，您应该仅在本地运行 Vizro-MCP，而不是将其作为托管服务器运行，因为目前没有身份验证来管理访问权限。
第二个最关键的部分是validate_model_config工具。此工具将尝试实例化Vizro模型配置，并返回有效配置的Python代码和可视化链接。如果配置有效，它还将返回并尝试打开一个指向仪表板实时预览的链接，该链接将带您进入PyCafe 。如果您不想打开该链接，可以告诉LLM不要这样做。
Vizro MCP 服务器提供以下工具。通常情况下，您不需要直接使用它们，但在特殊情况下，您可以要求 LLM 直接调用它们来帮助其找到路径。
get_vizro_chart_or_dashboard_plan - 获取创建图表或仪表板的结构化分步计划。提供整个创建过程的指导。
get_model_JSON_schema - 检索任何指定 Vizro 模型的完整 JSON 模式，有助于理解必需和可选参数。
validate_model_config - 通过尝试实例化 Vizro 模型配置来测试它们。返回有效配置的 Python 代码和可视化链接。
load_and_analyze_csv - 将 CSV 文件从本地路径或 URL 加载到 pandas DataFrame 中，并对其结构和内容进行详细分析。
validate_chart_code - 验证为图表创建的代码并返回有关其正确性的反馈。
get_sample_data_info - 提供可用于测试和开发的示例数据集的信息。
create_starter_dashboard - 使用此提示模板开始使用 Vizro 仪表板。
create_EDA_dashboard - 使用此提示模板基于本地或远程 CSV 数据集创建探索性数据分析 (EDA) 仪表板。
create_vizro_chart - 使用此提示模板根据本地或远程 CSV 数据集创建 Vizro 风格的 plotly 图表。
如果您是开发人员，或者您正在从源代码运行 Vizro-MCP，则需要克隆 Vizro 仓库。Vizro-MCP 支持两种配置选项： uv和docker 。
uv进行配置要配置 Vizro-MCP 服务器详细信息：
对于 Claude ：将以下内容添加到通过开发人员设置找到的claude_desktop_config.json中：
对于游标：将以下内容添加到通过游标设置找到的mcp.json中：
{
"mcpServers": {
"vizro-mcp": {
"command": "uv",
"args": [
"run",
"--directory",
"<PATH TO VIZRO>/vizro-mcp/",
"vizro-mcp"
]
}
}
}将<PATH TO VIZRO>替换为 Vizro 存储库的实际路径。您可能还需要提供uv可执行文件的完整路径，因此，不要使用"uv"而应该使用类似"/Users/<your-username>/.local/bin/uv"的路径。要查找uv在您的计算机上的路径，请在终端应用中输入which uv 。
docker进行配置您可以在 Docker 容器内运行 Vizro-MCP 以获得受控的运行时环境。
在vizro-mcp目录的根目录中，使用以下命令构建 Docker 映像：
docker build -t vizro-mcp .将以下内容添加到您的配置文件中：
{
"mcpServers": {
"vizro-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--mount",
"type=bind,src=</absolute/path/to/allowed/dir>,dst=</absolute/path/to/allowed/dir>",
"--mount",
"type=bind,src=</absolute/path/to/data.csv>,dst=</absolute/path/to/data.csv>",
"vizro-mcp"
]
}
}
}要将本地数据与 Vizro-MCP 结合使用，请将数据目录挂载到容器中。将</absolute/path/to/allowed/dir>或</absolute/path/to/data.csv>替换为您计算机上数据的绝对路径。为了保持一致性，建议dst路径与src路径一致。
用户对通过其主机 LLM 应用程序所做的任何事负责。
用户有责任获取访问任何第三方生成 AI 工具所需的所有权利，并遵守其任何适用的条款或条件。
用户对第三方生成 AI 工具和 Vizro 的使用和安全负全部责任。
用户承认并同意：
任何第三方生成式人工智能工具（“GenAI 工具”）生成的任何结果、选项、数据、建议、分析、代码或其他信息（“输出”）可能包含一些不准确、偏见、不合法、潜在侵权或其他不适当的内容，这些内容可能是错误的、歧视性的或误导性的。
麦肯锡公司:
（i）明确否认任何输出的准确性、充分性、及时性、可靠性、适销性、适用于特定用途、非侵权性、安全性或完整性，
(ii) 对于该等输出中的任何错误、遗漏或其他缺陷、延迟或中断，或依赖该等输出采取的任何行动，概不负责；
（iii）对于因用户使用 GenAI 工具和输出而导致的任何第三方权利的涉嫌侵犯或侵害，GenAI 不承担任何责任。
输出应由用户验证和确认，不得在无人监督的情况下使用，也不得作为影响个人的决策的唯一依据。
用户对输出的使用负全部责任，特别是，用户需要根据具体情况和用例确定所需的人工监督级别，并告知用户人员和其他受影响用户有关 GenAI 输出的性质。用户还应对其决策、行为、Vizro 和 Vizro-MCP 的使用以及遵守适用法律、法规和规章负全部责任，包括但不限于确认输出不侵犯任何第三方权利。
Vizro-MCP 被生成式 AI 模型所采用，因为大型语言模型 (LLM) 代表了 AI 领域的重大进步。然而，与任何强大的工具一样，连接到生成式 AI 模型也存在潜在风险。
我们建议用户在使用 Vizro-MCP 之前研究并了解所选型号。
鼓励用户将人工智能生成的内容视为补充，始终运用人类判断，谨慎处理，查看相关免责声明页面，并考虑以下事项：
供应商模型可能缺乏除最新更新之外的实时知识或事件。Vizro-MCP 的输出可能有所不同，您应始终验证关键信息。用户有责任确认生成内容的准确性、一致性和可靠性。
Get the JSON schema for the specified Vizro model. Server Vizro version: 0.1.62
| Name | Required | Description | Default |
|---|---|---|---|
| model_name | Yes | Name of the Vizro model to get schema for (e.g., 'Card', 'Dashboard', 'Page') |
| Name | Required | Description |
|---|---|---|
| model_name | Yes | |
| json_schema | Yes | |
| additional_info | Yes |
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 adds the useful server-version context ('Server Vizro version: 0.1.62'), which is genuinely beyond structured fields. However, it doesn't disclose whether this is a pure read (implied by 'Get' but not declared), whether it errors on unknown model names, or what the returned schema covers.
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?
Two short clauses, front-loaded with the purpose and followed by version context. The trailing version sentence is useful but slightly clipped in phrasing, keeping it just under a 5.
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?
Output schema exists, so the description needn't explain return values, and the single param is well documented. Missing only when-to-use guidance and any failure-mode context for an invalid model_name.
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 100% and the parameter's own description ('Name of the Vizro model to get schema for', with examples 'Card', 'Dashboard', 'Page') fully documents it. The tool description adds no additional parameter meaning; baseline 3 is correct.
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?
States a specific verb (Get) and resource (JSON schema for a Vizro model), and names the server version, which is a distinguishing detail. No sibling tool shares this purpose, so an agent can route to it unambiguously.
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 this is used to obtain a schema for a named model, but gives no explicit when-to-use, prerequisites, or alternatives relative to siblings like validate_dashboard_config. Usage is only inferable from the verb+resource.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
If user provides no data, use this tool to get sample data information.
Use the following data for the below purposes:
- iris: mostly numerical with one categorical column, good for scatter, histogram, boxplot, etc.
- tips: contains mix of numerical and categorical columns, good for bar, pie, etc.
- stocks: stock prices, good for line, scatter, generally things that change over time
- gapminder: demographic data, good for line, scatter, generally things with maps or many categories
Returns:
Data info object containing information about the dataset.
| Name | Required | Description | Default |
|---|---|---|---|
| data_name | Yes | Name of the dataset to get sample data for |
| Name | Required | Description |
|---|---|---|
| file_name | Yes | |
| file_path_or_url | Yes | |
| column_names_types | No | |
| file_location_type | Yes | |
| read_function_string | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description bears full burden. It discloses return type ('Data info object') and implies read-only behavior, but lacks details on permissions, rate limits, or side effects. Adequate for a simple retrieval tool.
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?
Well-structured with a bullet list for dataset descriptions. Condition ('If user provides no data') is front-loaded. Slightly verbose but 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 existence of an output schema (not shown), description correctly focuses on input semantics and use case. It adequately covers the tool's role among siblings, which handle user-provided data or code validation.
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 coverage is 100% (single parameter with enum). Description adds significant meaning beyond schema by explaining each dataset's suitability for different visualizations (e.g., 'iris: mostly numerical... good for scatter, histogram').
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: to get sample data information when no data is provided. It lists four specific datasets (iris, tips, stocks, gapminder) and their characteristics, distinguishing it from sibling tools that handle user-provided data or schemas.
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?
Explicitly states when to use ('If user provides no data'). Provides guidance on dataset selection based on chart types (scatter, bar, line, etc.). Does not explicitly exclude alternatives but usage condition is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get instructions for creating a Vizro chart or dashboard. Call FIRST when asked to create Vizro things.
Must be ALWAYS called FIRST with advanced_mode=False, then call again with advanced_mode=True
if the JSON config does not suffice anymore.
Returns:
Instructions for creating a Vizro chart or dashboard
| Name | Required | Description | Default |
|---|---|---|---|
| user_host | Yes | The host the user is using, if 'ide' you can use the IDE/editor to run python code | |
| user_plan | Yes | The type of Vizro thing the user wants to create | |
| advanced_mode | No | Only call if you need to use custom CSS, custom components or custom actions. No need to call this with advanced_mode=True if you need advanced charts, use `custom_charts` in the `validate_dashboard_config` tool instead. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description explains the two-step calling behavior and the nature of the return (instructions). Some details like auth or rate limits are absent, but the core behavior is clear.
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?
Very concise, front-loaded with purpose, uses bullet points for clarity, every sentence adds value 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?
With output schema present and all parameters described, the description covers the needed context for using the tool correctly, including the call sequence.
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 coverage is 100%, and description adds valuable context for advanced_mode parameter, explaining when to use it. This goes beyond what the schema alone provides.
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 'Get instructions for creating a Vizro chart or dashboard' and specifies it should be called first, making the purpose unambiguous and distinct from sibling tools.
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?
Provides explicit guidance: 'Must be ALWAYS called FIRST with advanced_mode=False, then call again with advanced_mode=True if the JSON config does not suffice anymore.' This tells when to use and how to iterate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use to understand local or remote data files. Must be called with absolute paths or URLs.
Supported formats:
- CSV (.csv)
- JSON (.json)
- HTML (.html, .htm)
- Excel (.xls, .xlsx)
- OpenDocument Spreadsheet (.ods)
- Parquet (.parquet)
Returns:
DataAnalysisResults object containing DataFrame information and metadata
| Name | Required | Description | Default |
|---|---|---|---|
| path_or_url | Yes | Absolute (important!) local file path or URL to a data file |
| Name | Required | Description |
|---|---|---|
| valid | Yes | |
| df_info | Yes | |
| message | Yes | |
| df_metadata | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the burden of behavioral disclosure. It states the action (load and analyze), supported formats, and return type, but does not disclose whether the operation is read-only, potential file size/performance implications, or any side effects. This is adequate but could be more thorough.
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 extremely concise: three lines covering purpose, requirement, formats, and return type. It is front-loaded with the main purpose and includes no redundant information. Every sentence earns its place.
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 simplicity of the tool (one parameter, output schema exists), the description covers the essential aspects: purpose, required input format, supported file types, and return type. It may lack details about remote access authentication or error handling, but overall it is sufficiently complete for an agent to use the tool correctly.
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 input schema has 100% coverage for the single parameter (path_or_url) with a good description. The additional description adds critical usage constraints (absolute paths/URLs) and lists supported file formats, which significantly enhances the parameter semantics beyond what the schema provides.
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 states the tool is used to 'understand local or remote data files' and specifies supported formats and return type. While the verb 'understand' is somewhat vague, the combination with the tool name and listed formats makes the purpose clear. It is distinguishable from sibling tools that handle schema, validation, and chart planning.
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 includes the critical usage constraint 'Must be called with absolute paths or URLs' but provides no explicit guidance on when to use this tool versus alternatives. The siblings are clearly different in function, so it's implicitly appropriate for data loading, but a brief comparison would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate the chart code created by the user and optionally open the PyCafe link in a browser.
Returns:
ValidationResults object with status and dashboard details
| Name | Required | Description | Default |
|---|---|---|---|
| auto_open | No | Whether to automatically open the PyCafe link in a browser | |
| data_info | Yes | Metadata for the dataset to be used in the chart | |
| chart_config | Yes | A ChartPlan object with the chart configuration |
| Name | Required | Description |
|---|---|---|
| valid | Yes | |
| message | Yes | |
| pycafe_url | Yes | |
| python_code | Yes | |
| browser_opened | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only states validation and optional browser opening, but omits details like whether code is executed, what constitutes invalid code, side effects, or authentication requirements. The return type is mentioned but not elaborated.
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 very concise with two sentences plus a return note. It front-loads the primary action. However, it could slightly expand on key behaviors without losing conciseness.
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?
Despite having an output schema (mentioned), the description lacks context about when validation is needed, error handling, or workflow integration with sibling tools. It omits important contextual details for an effective agent invocation.
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 input schema has 100% coverage with detailed descriptions for all parameters, including nested objects. The tool description adds no extra meaning beyond the schema, so it scores the baseline of 3. It does not clarify how parameters relate to validation logic.
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 validates chart code and optionally opens a PyCafe link in a browser. It uses a specific verb ('Validate') and resource ('chart code'), and the purpose is distinct from sibling tools like 'get_vizro_chart_or_dashboard_plan' and 'validate_dashboard_config'.
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, nor does it mention prerequisites, exclusions, or context. It fails to differentiate usage scenarios among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate Vizro model configuration. Run ALWAYS when you have a complete dashboard configuration.
If successful, the tool will return the python code and, if it is a remote file, the py.cafe link to the chart.
The PyCafe link will be automatically opened in your default browser if auto_open is True.
Returns:
ValidationResults object with status and dashboard details
| Name | Required | Description | Default |
|---|---|---|---|
| auto_open | No | Whether to automatically open the PyCafe link in a browser | |
| data_infos | Yes | List of DFMetaData objects containing information about the data files | |
| custom_charts | Yes | List of ChartPlan objects containing information about the custom charts in the dashboard | |
| dashboard_config | Yes | Either a JSON string or a dictionary representing a Vizro dashboard model configuration |
| Name | Required | Description |
|---|---|---|
| valid | Yes | |
| message | Yes | |
| pycafe_url | Yes | |
| python_code | Yes | |
| browser_opened | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses success outputs (Python code, py.cafe link, auto-open behavior) and mentions return type. However, it does not explain what validation entails (syntax checks, data consistency), leaving process details ambiguous.
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 brief (two sentences plus a return line) and front-loads the primary purpose. It avoids unnecessary details, though the second paragraph could be considered an aside. It is appropriately sized for a tool with a comprehensive schema.
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 (nested objects, output schema implied), the description mentions return behavior and auto-open but lacks details on validation scope (e.g., what checks are performed, prerequisites). Output schema existence reduces the need to explain return values, but process details are missing.
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 coverage is 100%, so baseline is 3. The description only adds value by noting the auto_open parameter's effect and the return type, which is marginal. It does not elaborate on the required parameters beyond the 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 explicitly states 'Validate Vizro model configuration' with a clear verb and resource. It differentiates from siblings like 'validate_chart_code' which focuses on individual charts, making the tool's purpose distinct.
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 advises 'Run ALWAYS when you have a complete dashboard configuration', providing strong contextual guidance. While it doesn't explicitly exclude other scenarios, the sibling tools cover individual parts (e.g., chart validation, data loading), implying this is for full config validation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scored across 6 tools
Most tools have distinct purposes (schema retrieval, sample data, planning, data loading, validation). The two validate_* tools overlap somewhat (chart code vs dashboard config), and get_model_json_schema vs get_vizro_chart_or_dashboard_plan could be confused, but descriptions clarify intent.
All six tools follow a consistent snake_case verb_noun pattern (get_*, load_*, validate_*). The long get_vizro_chart_or_dashboard_plan name is verbose but still follows the established convention.
Six tools is well-scoped for a Vizro dashboard-building helper. Each tool covers a distinct phase of the workflow (plan, schema, data, validate), so none feels redundant.
The surface covers the full authoring lifecycle: planning, schema lookup, data loading, and validation. A tool to render/serve the finished dashboard directly (beyond validation output) would close the last gap.
The grounded data layer for any LLM: governed SQL, metrics, lineage and catalog over your data.
Explore your databases, validate SQL, and build & publish data apps in your Mako workspace.
Generate answers & visualizations from your engineering data to track software development health.
Dashboards as data. Author, validate, render, and share dvt dashboards from any MCP client.
