Vizro-MCP es un servidor de Protocolo de Contexto de Modelo (MCP) que funciona junto con un LLM para ayudarlo a crear paneles y gráficos de Vizro.
Vizro-MCP proporciona herramientas y plantillas para crear un gráfico o panel de Vizro funcional paso a paso. Las ventajas incluyen:
✅ Un marco consistente para gráficos y paneles con un lenguaje de diseño común.
✅ Salida de configuración validada que es legible y fácil de modificar o mantener.
✅ Vista previa en vivo del tablero para iterar el diseño hasta que el tablero esté perfecto.
✅ Uso de conjuntos de datos locales o remotos simplemente proporcionando una ruta o URL.
Sin Vizro-MCP, si se intenta crear un panel de control con un LLM, este podría elegir cualquier marco y usarlo sin una guía específica, principios de diseño ni consistencia. Los resultados son:
❌ Una elección aleatoria de marco de interfaz o biblioteca de gráficos.
❌ Un desastre codificado por vibraciones que puede o no funcionar, pero que ciertamente no es muy mantenible.
❌ No hay forma de obtener una vista previa del panel fácilmente.
❌ No hay una forma sencilla de conectarse a datos reales.
Related MCP server: ML Research MCP
Si es un desarrollador y necesita instrucciones para ejecutar Vizro-MCP desde la fuente o ejecutar el servidor desde un contenedor Docker, salte al final de esta página a Desarrollo o ejecución desde la fuente .
Cualquier aplicación LLM compatible con MCP. Claude Desktop y Cursor son opciones populares.
🐛 Nota: Actualmente hay algunos problemas conocidos con VS Code , pero estamos trabajando en ello y esperamos que Copilot funcione pronto.
⚠️ Advertencia: En algunos hosts (como Claude Desktop), el plan gratuito puede tener un rendimiento inferior, lo que puede causar problemas si la solicitud es demasiado compleja. Si la solicitud provoca un bloqueo de la interfaz de usuario, opte por un plan de pago o reduzca la complejidad de su solicitud.
La configuración general del servidor es prácticamente la misma para todos los hosts:
{
"mcpServers": {
"vizro-mcp": {
"command": "uvx",
"args": [
"vizro-mcp"
]
}
}
}En principio, el servidor Vizro MCP funciona con cualquier aplicación LLM compatible con MCP, pero recomendamos Claude Desktop o Cursor como opciones populares (consulte las instrucciones más detalladas a continuación). Cada herramienta de IA puede utilizar diferentes métodos de configuración o configuraciones de conexión. Consulte la documentación de cada herramienta para obtener más información.
Agregue lo siguiente a su claude_desktop_config.json que se encuentra a través de Configuración de desarrollador .
{
"mcpServers": {
"vizro-mcp": {
"command": "uvx",
"args": [
"vizro-mcp"
]
}
}
}⚠️ Advertencia: En algunos casos, podría ser necesario proporcionar la ruta completa del ejecutable
uvx. Por lo tanto, en lugar deuvx, utilice algo como/Users/<your-username>/.local/bin/uvx. Para descubrir la ruta deuvxen su equipo, en la aplicación de terminal, escribawhich uvx.
Si está utilizando Claude Desktop, reinícielo y, después de unos momentos, debería ver el menú vizro-mcp al abrir el menú de configuración/contexto:
Agregue lo siguiente a mcp.json que se encuentra a través de Configuración del cursor .
{
"mcpServers": {
"vizro-mcp": {
"command": "uvx",
"args": [
"vizro-mcp"
]
}
}
}⚠️ Advertencia: En algunos casos, podría ser necesario proporcionar la ruta completa del ejecutable
uvx. Por lo tanto, en lugar deuvx, utilice algo como/Users/<your-username>/.local/bin/uvx. Para descubrir la ruta deuvxen su equipo, en la aplicación de terminal, escribawhich uvx.
De manera similar, al usar el Cursor, después de una breve pausa, debería ver una luz verde en el menú MCP:
Las plantillas de aviso no están disponibles en todos los hosts MCP, pero cuando lo están, puedes usarlas para acceder rápidamente a paneles específicos. Para acceder a ellas (por ejemplo, en Claude Desktop), haz clic en el icono "+" debajo del chat y selecciona Add from vizro-mcp .
La forma más sencilla de empezar a usar los paneles de Vizro es elegir la plantilla create_starter_dashboard y enviar la solicitud. Esto creará un panel súper simple con una página, un gráfico y un filtro. ¡A partir de ahí!
También puede solicitar al LLM que cree paneles específicos basados en datos locales o remotos si ya tiene una idea clara de lo que desea. Algunos ejemplos de indicaciones podrían ser:
Cree un panel de Vizro con una página, un gráfico de dispersión y un filtro basado en datos de
<insert absolute file path or public URL>.
Cree un panel de Vizro simple de dos páginas, donde la primera página sea un análisis de correlación de datos de
<insert absolute file path or public URL>y la segunda página sea un gráfico de mapa de datos de<insert absolute file path or public URL>
Puede encontrar un conjunto de CSV de muestra para probar en el repositorio de Plotly .
Incluso puedes solicitar un panel de control sin proporcionar datos:
Cree un panel de Vizro con una página, un gráfico de dispersión y un filtro.
En general, es útil especificar Vizro en el mensaje y mantenerlo lo más preciso (y simple) posible.
Cuando el LLM elige usar la herramienta validate_model_config y esta se ejecuta correctamente, devolverá un enlace a una vista previa en vivo del panel si solo se utilizan datos públicos a los que se accede mediante URL. De forma predeterminada, el LLM incluso abrirá el enlace en su navegador a menos que usted le indique lo contrario. En Claude Desktop, puede ver el resultado de la herramienta abriendo el desplegable de herramientas y desplazándose hasta el final.
También puedes pedirle al modelo que te dé el enlace, pero intentará regenerarlo, lo cual es muy propenso a errores y lento.
Si no desea crear un panel de Vizro completo, puede usar Vizro-MCP para crear el código de un solo gráfico. Si no está seguro del tipo de gráfico que desea, consulte el Vocabulario Visual de Vizro para obtener ideas.
La forma más sencilla de crear un gráfico Vizro es elegir la plantilla create_vizro_chart y enviar la solicitud. Esto creará un gráfico sencillo que podrás modificar. ¡A partir de ahí!
Alternativamente, puedes simplemente preguntar en el chat, por ejemplo:
Cree una dispersión basada en el conjunto de datos del iris.
Cree un gráfico de barras basado en los datos de
<insert absolute file path or public URL>.
Los servidores MCP son un concepto relativamente nuevo, y es importante ser transparente sobre las capacidades de las herramientas para que el usuario pueda tomar una decisión informada. En general, el servidor MCP de Vizro solo lee datos y nunca escribe, elimina ni modifica datos en su equipo.
En general, la parte más crítica del proceso es la herramienta load_and_analyze_data . Esta herramienta, ejecutándose en su equipo, cargará datos locales o remotos en un DataFrame de Pandas y proporcionará un análisis detallado de su estructura y contenido. Solo utiliza pd.read_xxx , por lo que, en general, no hay que preocuparse por la privacidad ni la seguridad de los datos. Sin embargo, debe ejecutar Vizro-MCP solo localmente, no como un servidor alojado, ya que actualmente no hay autenticación para gestionar el acceso.
La segunda parte más importante es la herramienta validate_model_config . Esta herramienta intentará instanciar la configuración del modelo de Vizro y devolverá el código Python y el enlace de visualización para las configuraciones válidas. Si la configuración es válida, también devolverá e intentará abrir un enlace a una vista previa en vivo del panel, que le llevará a PyCafe . Si no desea abrir el enlace, puede indicarle al LLM que no lo haga.
El servidor MCP de Vizro proporciona las siguientes herramientas. Generalmente, no debería ser necesario usarlas directamente, pero en casos especiales podría solicitar al LLM que las llame directamente para que le ayuden a encontrar la ruta.
get_vizro_chart_or_dashboard_plan : Obtenga un plan estructurado paso a paso para crear un gráfico o un panel. Proporciona orientación sobre todo el proceso de creación.
get_model_JSON_schema : recupera el esquema JSON completo para cualquier modelo Vizro especificado, útil para comprender los parámetros obligatorios y opcionales.
validate_model_config : Prueba las configuraciones del modelo de Vizro intentando instanciarlas. Devuelve código Python y enlaces de visualización para configuraciones válidas.
load_and_analyze_csv : carga un archivo CSV desde una ruta local o URL en un DataFrame de pandas y proporciona un análisis detallado de su estructura y contenido.
validate_chart_code : valida el código creado para un gráfico y devuelve información sobre su corrección.
get_sample_data_info : proporciona información sobre conjuntos de datos de muestra que se pueden usar para pruebas y desarrollo.
create_starter_dashboard : utilice esta plantilla de aviso para comenzar a utilizar los paneles de Vizro.
create_EDA_dashboard : utilice esta plantilla de solicitud para crear un tablero de análisis de datos exploratorios (EDA) basado en un conjunto de datos CSV local o remoto.
create_vizro_chart : utilice esta plantilla de solicitud para crear un gráfico plotly con estilo Vizro basado en un conjunto de datos CSV local o remoto.
Si eres desarrollador o ejecutas Vizro-MCP desde el código fuente, necesitas clonar el repositorio de Vizro. Vizro-MCP admite dos opciones de configuración: uv y docker .
uvPara configurar los detalles del servidor Vizro-MCP:
Para Claude : agregue lo siguiente a su claude_desktop_config.json que se encuentra a través de Configuración de desarrollador :
Para el cursor : agregue lo siguiente a mcp.json que se encuentra a través de la configuración del cursor :
{
"mcpServers": {
"vizro-mcp": {
"command": "uv",
"args": [
"run",
"--directory",
"<PATH TO VIZRO>/vizro-mcp/",
"vizro-mcp"
]
}
}
}Reemplace <PATH TO VIZRO> con la ruta real a su repositorio de Vizro. También podría necesitar proporcionar la ruta completa a su ejecutable uv ; por lo tanto, en lugar de "uv" , use algo como "/Users/<your-username>/.local/bin/uv" . Para descubrir la ruta de uv en su equipo, en la aplicación de terminal, escriba which uv .
dockerPuede ejecutar Vizro-MCP dentro de un contenedor Docker para un entorno de ejecución controlado.
En la raíz del directorio vizro-mcp , cree la imagen de Docker con:
docker build -t vizro-mcp .Agregue lo siguiente a su archivo de configuración:
{
"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"
]
}
}
}Para usar datos locales con Vizro-MCP, monte su directorio de datos en el contenedor. Reemplace </absolute/path/to/allowed/dir> o </absolute/path/to/data.csv> con la ruta absoluta a sus datos en su equipo. Para mantener la coherencia, se recomienda que la ruta dst coincida con la ruta src .
Los usuarios son responsables de todo lo que se haga a través de su aplicación LLM anfitriona.
Los usuarios son responsables de obtener todos los derechos necesarios para acceder a cualquier herramienta de inteligencia artificial generativa de terceros y de cumplir con los términos y condiciones aplicables.
Los usuarios son totalmente responsables del uso y la seguridad de las herramientas de inteligencia artificial generativa de terceros y de Vizro.
Los usuarios reconocen y aceptan que:
Cualquier resultado, opción, dato, recomendación, análisis, código u otra información (“Resultados”) generados por cualquier herramienta de IA generativa de terceros (“Herramientas GenAI”) pueden contener algunas imprecisiones, sesgos, contenido ilegítimo, potencialmente infractor o de otro modo inapropiado que puede ser erróneo, discriminatorio o engañoso.
McKinsey & Company:
(i) renuncia expresamente a la exactitud, idoneidad, puntualidad, confiabilidad, comerciabilidad, idoneidad para un propósito particular, no infracción, seguridad o integridad de cualquier Resultado,
(ii) no será responsable de ningún error, omisión u otros defectos, demoras o interrupciones en dichos Resultados, ni de ninguna acción realizada en base a ellos, y
(iii) no será responsable de ninguna supuesta violación o infracción de cualquier derecho de terceros que resulte del uso por parte de los usuarios de las Herramientas GenAI y los Resultados.
Los resultados deberán ser verificados y validados por los usuarios y no deberán utilizarse sin supervisión humana y como única base para tomar decisiones que afecten a las personas.
Los usuarios son los únicos responsables del uso del Resultado. En particular, deberán determinar el nivel de supervisión humana necesario según el contexto y el caso de uso, así como informar a su personal y a otros usuarios afectados sobre la naturaleza del Resultado de GenAI. Los usuarios también son plenamente responsables de sus decisiones, acciones, uso de Vizro y Vizro-MCP y del cumplimiento de las leyes, normas y regulaciones aplicables, incluyendo, entre otros, la verificación de que los Resultados no infrinjan derechos de terceros.
Vizro-MCP se utiliza en modelos de IA generativa porque los grandes modelos de lenguaje (LLM) representan avances significativos en el campo de la IA. Sin embargo, como con cualquier herramienta potente, existen riesgos potenciales asociados a la conexión con un modelo de IA generativa.
Recomendamos a los usuarios que investiguen y comprendan el modelo seleccionado antes de utilizar Vizro-MCP.
Se recomienda a los usuarios que traten el contenido generado por IA como complementario, apliquen siempre el criterio humano, se acerquen con precaución, revisen la página de exención de responsabilidad correspondiente y consideren lo siguiente:
Los modelos de proveedores podrían carecer de información en tiempo real o de eventos posteriores a sus últimas actualizaciones. La información de salida de Vizro-MCP puede variar, por lo que siempre debe verificar la información crítica. Es responsabilidad del usuario determinar la precisión, consistencia y fiabilidad del contenido generado.
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.
