Vizro-MCP ist ein Model Context Protocol (MCP) -Server, der zusammen mit einem LLM arbeitet, um Sie bei der Erstellung von Vizro-Dashboards und -Diagrammen zu unterstützen.
Vizro-MCP bietet Tools und Vorlagen zur schrittweisen Erstellung eines funktionierenden Vizro-Diagramms oder Dashboards. Vorteile:
✅ Ein konsistentes Framework für Diagramme und Dashboards mit einer gemeinsamen Designsprache.
✅ Validierte Konfigurationsausgabe, die lesbar und einfach zu ändern oder zu warten ist.
✅ Live-Vorschau des Dashboards, um das Design zu iterieren, bis das Dashboard perfekt ist.
✅ Nutzung lokaler oder Remote-Datensätze durch einfache Angabe eines Pfades oder einer URL.
Wenn Sie ohne Vizro-MCP versuchen, ein Dashboard mit einem LLM zu erstellen, könnte es jedes beliebige Framework auswählen und ohne spezifische Anleitung, Designprinzipien oder Konsistenz verwenden. Die Ergebnisse sind:
❌ Eine zufällige Auswahl eines Frontend-Frameworks oder einer Diagrammbibliothek.
❌ Ein Vibe-codiertes Durcheinander, das vielleicht läuft oder nicht, aber sicherlich nicht sehr wartbar ist.
❌ Keine Möglichkeit, eine einfache Vorschau des Dashboards anzuzeigen.
❌ Keine einfache Möglichkeit, eine Verbindung zu echten Daten herzustellen.
Related MCP server: ML Research MCP
Wenn Sie Entwickler sind und Anweisungen zum Ausführen von Vizro-MCP aus der Quelle oder zum Ausführen des Servers aus einem Docker-Container benötigen, springen Sie zum Ende dieser Seite zu „Entwicklung oder Ausführen aus der Quelle“ .
Jede LLM-Anwendung, die MCP unterstützt. Claude Desktop und Cursor sind beliebte Optionen.
🐛 Hinweis: Es gibt derzeit einige bekannte Probleme mit VS Code, aber wir arbeiten daran und hoffen, dass Copilot bald funktioniert.
⚠️ Warnung: Bei einigen Hosts (wie Claude Desktop) ist der kostenlose Tarif möglicherweise weniger leistungsfähig, was bei zu komplexen Anfragen zu Problemen führen kann. Sollte die Anfrage einen Absturz der Benutzeroberfläche verursachen, wählen Sie einen kostenpflichtigen Tarif oder reduzieren Sie die Komplexität Ihrer Anfrage.
Die allgemeine Serverkonfiguration ist für alle Hosts größtenteils gleich:
{
"mcpServers": {
"vizro-mcp": {
"command": "uvx",
"args": [
"vizro-mcp"
]
}
}
}Der Vizro MCP-Server funktioniert grundsätzlich mit allen MCP-fähigen LLM-Anwendungen, wir empfehlen jedoch Claude Desktop oder Cursor als beliebte Optionen (siehe ausführlichere Anweisungen unten). Verschiedene KI-Tools verwenden möglicherweise unterschiedliche Einrichtungsmethoden oder Verbindungseinstellungen. Weitere Informationen finden Sie in der Dokumentation der einzelnen Tools.
Fügen Sie Folgendes zu Ihrer claude_desktop_config.json hinzu , die Sie über die Entwicklereinstellungen finden .
{
"mcpServers": {
"vizro-mcp": {
"command": "uvx",
"args": [
"vizro-mcp"
]
}
}
}⚠️ Warnung: In manchen Fällen müssen Sie den vollständigen Pfad zu Ihrer
uvxProgrammdatei angeben. Verwenden Sie daher anstelle vonuvxbeispielsweise/Users/<your-username>/.local/bin/uvx/.local/bin/uvx . Um den Pfad vonuvxauf Ihrem Computer zu ermitteln, geben Sie in Ihrer Terminal-App „which uvxein.
Wenn Sie Claude Desktop verwenden, starten Sie es neu. Nach einigen Augenblicken sollte beim Öffnen des Einstellungs-/Kontextmenüs das Menü „vizro-mcp“ angezeigt werden:
Fügen Sie Folgendes zu mcp.json hinzu , das Sie über die Cursoreinstellungen finden .
{
"mcpServers": {
"vizro-mcp": {
"command": "uvx",
"args": [
"vizro-mcp"
]
}
}
}⚠️ Warnung: In manchen Fällen müssen Sie den vollständigen Pfad zu Ihrer
uvxProgrammdatei angeben. Verwenden Sie daher anstelle vonuvxbeispielsweise/Users/<your-username>/.local/bin/uvx/.local/bin/uvx . Um den Pfad vonuvxauf Ihrem Computer zu ermitteln, geben Sie in Ihrer Terminal-App „which uvxein.
Wenn Sie den Cursor verwenden, sollten Sie nach einer kurzen Pause ein grünes Licht im MCP-Menü sehen:
Eingabeaufforderungsvorlagen sind nicht in allen MCP-Hosts verfügbar. Wenn sie jedoch verfügbar sind, können Sie sie verwenden, um schnell auf bestimmte Dashboards zuzugreifen. Um darauf zuzugreifen (z. B. in Claude Desktop), klicken Sie auf das Plus-Symbol unter dem Chat und wählen Sie Add from vizro-mcp .
Der einfachste Weg, mit Vizro-Dashboards zu beginnen, besteht darin, die Vorlage create_starter_dashboard auszuwählen und einfach die Eingabeaufforderung zu senden. Dadurch wird ein supereinfaches Dashboard mit einer Seite, einem Diagramm und einem Filter erstellt. Von dort aus geht’s weiter!
Sie können den LLM auch bitten, spezifische Dashboards basierend auf lokalen oder Remote-Daten zu erstellen, wenn Sie bereits eine Vorstellung davon haben, was Sie möchten. Beispiele hierfür könnten sein:
Erstellen Sie ein Vizro-Dashboard mit einer Seite, einem Streudiagramm und einem Filter basierend auf
<insert absolute file path or public URL>-Daten.
Erstellen Sie ein einfaches zweiseitiges Vizro-Dashboard, wobei die erste Seite eine Korrelationsanalyse der
<insert absolute file path or public URL>-Daten und die zweite Seite eine Kartendarstellung der<insert absolute file path or public URL>-Daten ist.
Eine Reihe von Beispiel-CSVs zum Ausprobieren finden Sie im Plotly-Repository .
Sie können sogar ein Dashboard anfordern, ohne Daten bereitzustellen:
Erstellen Sie ein Vizro-Dashboard mit einer Seite, einem Streudiagramm und einem Filter.
Im Allgemeinen ist es hilfreich, Vizro in der Eingabeaufforderung anzugeben und es so präzise (und einfach) wie möglich zu halten.
Wenn das LLM das Tool validate_model_config verwendet und dieses erfolgreich ausgeführt wird, gibt das LLM einen Link zu einer Live-Vorschau des Dashboards zurück, sofern nur öffentliche Daten über eine URL verwendet werden. Standardmäßig öffnet das LLM den Link sogar in Ihrem Browser, sofern Sie dies nicht ausdrücklich ablehnen. In Claude Desktop können Sie die Ausgabe des Tools sehen, indem Sie das Tool einklappen und ganz nach unten scrollen.
Sie können das Modell auch bitten, Ihnen den Link zu geben, es wird jedoch versuchen, ihn neu zu generieren, was sehr fehleranfällig und langsam ist.
Wenn Sie kein komplettes Vizro-Dashboard erstellen möchten, können Sie Vizro-MCP verwenden, um den Code für ein einzelnes Diagramm zu erstellen. Wenn Sie sich nicht sicher sind, welche Art von Diagramm Sie benötigen, finden Sie Anregungen im Vizro Visual Vocabulary .
Der einfachste Weg, ein Vizro-Diagramm zu erstellen, besteht darin, die Vorlage create_vizro_chart auszuwählen und die Eingabeaufforderung zu senden. Dadurch wird ein einfaches Diagramm erstellt, das Sie anpassen können. Weiter geht’s!
Alternativ kannst du auch einfach im Chat fragen, zum Beispiel:
Erstellen Sie eine Streuung basierend auf dem Iris-Datensatz.
Erstellen Sie ein Balkendiagramm basierend auf
<insert absolute file path or public URL>-Daten.
MCP-Server sind ein relativ neues Konzept. Daher ist Transparenz über die Leistungsfähigkeit der Tools wichtig, damit Sie als Benutzer eine fundierte Entscheidung treffen können. Der Vizro MCP-Server liest lediglich Daten und schreibt, löscht oder verändert niemals Daten auf Ihrem Rechner.
Der kritischste Teil des Prozesses ist im Allgemeinen das Tool load_and_analyze_data . Dieses Tool, das auf Ihrem Rechner läuft, lädt lokale oder Remote-Daten in einen Pandas-DataFrame und bietet eine detaillierte Analyse von Struktur und Inhalt. Es verwendet ausschließlich pd.read_xxx , sodass Sie sich im Allgemeinen keine Sorgen um Datenschutz oder Datensicherheit machen müssen. Sie sollten Vizro-MCP jedoch nur lokal und nicht als gehosteten Server ausführen, da derzeit keine Authentifizierung zur Zugriffsverwaltung vorhanden ist.
Der zweitwichtigste Teil ist das Tool validate_model_config . Dieses Tool versucht, die Vizro-Modellkonfiguration zu instanziieren und gibt den Python-Code und den Visualisierungslink für gültige Konfigurationen zurück. Ist die Konfiguration gültig, wird außerdem ein Link zu einer Live-Vorschau des Dashboards zurückgegeben und versucht, diesen zu öffnen. Dieser führt Sie zu PyCafe . Wenn Sie den Link nicht öffnen möchten, können Sie das LLM anweisen, dies nicht zu tun.
Der Vizro MCP-Server stellt die folgenden Tools zur Verfügung. Normalerweise müssen Sie diese nicht direkt verwenden. In besonderen Fällen können Sie den LLM jedoch bitten, sie direkt aufzurufen, um den Weg zu finden.
get_vizro_chart_or_dashboard_plan – Erhalten Sie einen strukturierten Schritt-für-Schritt-Plan zum Erstellen eines Diagramms oder Dashboards. Bietet Anleitungen für den gesamten Erstellungsprozess.
get_model_JSON_schema – Ruft das vollständige JSON-Schema für jedes angegebene Vizro-Modell ab. Dies ist nützlich, um erforderliche und optionale Parameter zu verstehen.
validate_model_config – Testet Vizro-Modellkonfigurationen durch den Versuch, sie zu instanziieren. Gibt Python-Code und Visualisierungslinks für gültige Konfigurationen zurück.
load_and_analyze_csv – Lädt eine CSV-Datei von einem lokalen Pfad oder einer URL in einen Pandas-DataFrame und bietet eine detaillierte Analyse ihrer Struktur und ihres Inhalts.
validate_chart_code – Validiert den für ein Diagramm erstellten Code und gibt Feedback zu seiner Richtigkeit zurück.
get_sample_data_info – Bietet Informationen zu Beispieldatensätzen, die für Tests und Entwicklung verwendet werden können.
create_starter_dashboard – Verwenden Sie diese Eingabeaufforderungsvorlage, um mit Vizro-Dashboards zu beginnen.
create_EDA_dashboard – Verwenden Sie diese Eingabeaufforderungsvorlage, um ein Dashboard für die explorative Datenanalyse (EDA) basierend auf einem lokalen oder Remote-CSV-Datensatz zu erstellen.
create_vizro_chart – Verwenden Sie diese Eingabeaufforderungsvorlage, um ein Plotly-Diagramm im Vizro-Stil basierend auf einem lokalen oder Remote-CSV-Datensatz zu erstellen.
Wenn Sie Entwickler sind oder Vizro-MCP aus der Quelle ausführen, müssen Sie das Vizro-Repository klonen. Vizro-MCP unterstützt zwei Konfigurationsoptionen: uv und docker .
uvSo konfigurieren Sie die Vizro-MCP-Serverdetails:
Für Claude : Fügen Sie Ihrer claude_desktop_config.json , die Sie über die Entwicklereinstellungen finden, Folgendes hinzu:
Für den Cursor : Fügen Sie Folgendes zu mcp.json hinzu , das Sie über die Cursoreinstellungen finden :
{
"mcpServers": {
"vizro-mcp": {
"command": "uv",
"args": [
"run",
"--directory",
"<PATH TO VIZRO>/vizro-mcp/",
"vizro-mcp"
]
}
}
}Ersetzen Sie <PATH TO VIZRO> durch den tatsächlichen Pfad zu Ihrem Vizro-Repository. Möglicherweise müssen Sie auch den vollständigen Pfad zu Ihrer uv Programmdatei angeben. Verwenden Sie daher anstelle von "uv" beispielsweise "/Users/<your-username>/.local/bin/uv" . Um den Pfad von uv auf Ihrem Computer zu ermitteln, geben Sie in Ihrer Terminal-App „ which uv ein.
dockerSie können Vizro-MCP in einem Docker-Container für eine kontrollierte Laufzeitumgebung ausführen.
Erstellen Sie im Stammverzeichnis des Verzeichnisses vizro-mcp das Docker-Image mit:
docker build -t vizro-mcp .Fügen Sie Ihrer Konfigurationsdatei Folgendes hinzu:
{
"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"
]
}
}
}Um lokale Daten mit Vizro-MCP zu verwenden, mounten Sie Ihr Datenverzeichnis in den Container. Ersetzen Sie </absolute/path/to/allowed/dir> oder </absolute/path/to/data.csv> durch den absoluten Pfad zu Ihren Daten auf Ihrem Rechner. Aus Konsistenzgründen wird empfohlen, dass der dst mit dem src übereinstimmt.
Benutzer sind für alles verantwortlich, was über ihre Host-LLM-Anwendung getan wird.
Die Benutzer sind dafür verantwortlich, alle erforderlichen Rechte für den Zugriff auf generative KI-Tools von Drittanbietern zu erwerben und alle geltenden Bedingungen einzuhalten.
Die Benutzer sind voll verantwortlich für die Verwendung und Sicherheit der generativen KI-Tools von Drittanbietern und von Vizro.
Die Benutzer erkennen an und stimmen Folgendem zu:
Alle Ergebnisse, Optionen, Daten, Empfehlungen, Analysen, Codes oder sonstigen Informationen („Ausgaben“), die von generativen KI-Tools von Drittanbietern („GenAI-Tools“) generiert werden, können Ungenauigkeiten, Verzerrungen, unrechtmäßige, möglicherweise verletzende oder anderweitig unangemessene Inhalte enthalten, die fehlerhaft, diskriminierend oder irreführend sein können.
McKinsey & Company:
(i) lehnt ausdrücklich die Richtigkeit, Angemessenheit, Aktualität, Zuverlässigkeit, Marktgängigkeit, Eignung für einen bestimmten Zweck, Nichtverletzung, Sicherheit oder Vollständigkeit jeglicher Ergebnisse ab,
(ii) haftet nicht für Fehler, Auslassungen oder andere Mängel, Verzögerungen oder Unterbrechungen dieser Ergebnisse oder für Maßnahmen, die im Vertrauen darauf ergriffen werden, und
(iii) haftet nicht für angebliche Verletzungen oder Verstöße gegen Rechte Dritter, die sich aus der Nutzung der GenAI-Tools und der Ergebnisse durch die Benutzer ergeben.
Die Ergebnisse müssen von den Benutzern überprüft und validiert werden und dürfen nicht ohne menschliche Aufsicht und als alleinige Grundlage für Entscheidungen verwendet werden, die sich auf Einzelpersonen auswirken.
Die Nutzer sind allein für die Nutzung der Ergebnisse verantwortlich. Insbesondere müssen sie den erforderlichen Grad menschlicher Aufsicht im Kontext und Anwendungsfall bestimmen und ihr Personal und andere betroffene Nutzer über die Art der GenAI-Ergebnisse informieren. Sie tragen außerdem die volle Verantwortung für ihre Entscheidungen, Handlungen, die Nutzung von Vizro und Vizro-MCP sowie die Einhaltung geltender Gesetze, Regeln und Vorschriften, insbesondere für die Sicherstellung, dass die Ergebnisse keine Rechte Dritter verletzen.
Vizro-MCP wird von generativen KI-Modellen verwendet, da große Sprachmodelle (LLMs) bedeutende Fortschritte im KI-Bereich darstellen. Wie bei jedem leistungsstarken Tool birgt die Verbindung mit einem generativen KI-Modell jedoch potenzielle Risiken.
Wir empfehlen Benutzern, sich vor der Verwendung von Vizro-MCP über das ausgewählte Modell zu informieren und es zu verstehen.
Benutzer werden aufgefordert, KI-generierte Inhalte als ergänzend zu betrachten, stets menschliches Urteilsvermögen anzuwenden, mit Vorsicht vorzugehen, die entsprechende Haftungsausschlussseite zu überprüfen und Folgendes zu beachten:
Den Anbietermodellen fehlen möglicherweise Echtzeitdaten oder Ereignisse nach den letzten Updates. Die Vizro-MCP-Ausgabe kann variieren, daher sollten Sie kritische Informationen stets überprüfen. Es liegt in der Verantwortung des Benutzers, die Genauigkeit, Konsistenz und Zuverlässigkeit der generierten Inhalte zu überprüfen.
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.
