Missing enum constraints on categorical parameters. 17 tools use free-form string parameters that should be enums: plot_type, annotation_type, layout, template_style, operation, distribution, agg_type, cmap, etc. Without enums, LLMs hallucinate invalid values.
Output schemas not documented for any tool. LLMs cannot plan multi-step workflows or extract required fields (plot_id, dataset_name) for downstream calls without knowing return structure. This forces the LLM to guess or retry.
Convert all categorical string parameters to JSON Schema enums. For plot_type, formalize: {"type": "string", "enum": ["scatter", "line", "bar", "hist", "box", "heatmap", "contour", "violin", "area", "density"]}. Same for annotation_type, layout, template_style, operation, distribution, agg_type, cmap.
Document output schemas for all tools. Example for create_plot: {"type": "object", "properties": {"plot_id": {"type": "string"}, "html_content": {"type": "string"}, "png_bytes": {"type": "string", "format": "base64"}}, "required": ["plot_id"]}. This enables downstream tool chaining.
For transform_data and annotate_plot, explicitly document parameter dependencies. Example: 'If operation is filter, include column and value. If operation is groupby, include group_by and agg. If operation is join, include other_dataset, on, and how. Providing parameters not relevant to the operation will cause an error.'
Add range constraints to numeric parameters. Example for generate_large_dataset: n_points must be 100 - 10,000,000 (default 100,000). For width/height: 200 - 2000 pixels (defaults sensible).
Document sandbox behavior for execute_code. Example: 'Timeout 30s. Maximum memory 512MB. Variables: df (pandas DataFrame), hv (holoviews module), hvplot available. Must assign result variable. Errors will include traceback.'
Add recovery guidance to discovery tools. Example for analyze_data: 'Returns a data profile (shape, dtypes, missing %, value ranges, correlations). Use this before create_plot to understand column names and types. Then pass results to suggest_visualizations.'
Conditional parameter dependencies are undocumented. For example, transform_data has 14 parameters but only a subset are valid for each operation (column applies to filter/sort, group_by applies to groupby, x_start/x_end apply to vspan, etc.). LLMs will pass invalid parameter combinations.
execute_code tool has minimal safety documentation. No sandbox limits mentioned, no guidance on what code failures look like, no validation that 'result' variable is set. High-risk operation with insufficient error recovery guidance.
create_crossfilter and similar tools accept mini-DSL strings (e.g., 'scatter,x,y;hist,x;box,cat,y' for views) without documenting parsing rules, valid syntax, or error behavior. If LLM constructs invalid syntax, recovery path is unclear.
Numeric parameters lack range constraints. n_points in generate_large_dataset, width/height in plot tools, and page_size equivalents have no min/max guidance. LLMs can pass absurd values (10B points, 1px width).
Descriptions for discovery/suggestion tools (analyze_data, suggest_visualizations, list_datasets) could better explain WHEN to call them vs similar tools. Should include dependency hints like 'Call list_datasets first to find dataset names' or 'Use suggest_visualizations to pick plot types before create_plot'.
No error handling guidance for any tool. What does an invalid dataset_name return? What if code execution times out? What if a plot fails to render? LLMs need actionable error messages and recovery suggestions.
all
Define DSL syntax for create_crossfilter views parameter. Example: 'Each plot spec is type,x,y separated by semicolons. Valid types: scatter, hist, box, line, bar. Example: scatter,x,y;hist,x;box,species,y. Invalid syntax will return a parsing error.'
Add error classification to every tool. Example: 'If dataset_name is not found: retryable=false, suggest calling list_datasets() to see available names. If plot rendering fails: retryable=true, try again or simplify the plot.'
For tools that generate files (create_dashboard, auto_eda), document output formats and sizes. Example: 'Returns PNG (typically 50-200KB), interactive HTML (typically 500KB-2MB), and structured metadata (JSON). File paths/URIs available in response.'
Add idempotence guarantees where applicable. Example: 'transform_data always creates a new dataset without modifying the input. Can be called multiple times safely. Use unique output_name to track versions.'
For execute_code, add examples of common patterns. Example: 'For linked selections: import holoviews as hv; from holoviews.selection import link_selections; result = link_selections(scatter + hist). For custom aggregations: result = df.groupby(…).agg(…).hvplot.bar()'.