Skip to content

Enhance AI/BI dashboard skill with comprehensive widget documentation#374

Open
QuentinAmbard wants to merge 28 commits intomainfrom
dashboard-improvements
Open

Enhance AI/BI dashboard skill with comprehensive widget documentation#374
QuentinAmbard wants to merge 28 commits intomainfrom
dashboard-improvements

Conversation

@QuentinAmbard
Copy link
Copy Markdown
Collaborator

@QuentinAmbard QuentinAmbard commented Mar 25, 2026 •
edited
Loading

Summary

Comprehensive improvements to the AI/BI dashboard skill documentation and tooling.

Documentation Improvements

  • Restructured skill files for better organization:

    • Split widget specs into basic (1-widget-specifications.md) and advanced (2-advanced-widget-specifications.md)
    • Renumbered filter docs to 3-filters.md, examples to 4-examples.md, troubleshooting to 5-troubleshooting.md
    • Condensed SKILL.md to focus on workflow and key guidelines

  • Enhanced widget specifications with clearer field expression patterns and version requirements

  • Added comprehensive date range filtering documentation with examples for relative date filters

  • Added TOP-N + "Other" bucketing guidance for handling high-cardinality dimensions in charts

  • Restored critical behavioral instructions:

    • CORRECT/WRONG examples for text widgets (separate title/subtitle)
    • Full counter Pattern 2 example with CRITICAL field name matching note
    • Version hints (e.g., "NOT 3!") for counter and table widgets
    • Full 10-item quality checklist
    • Standard dashboard structure y-position template
    • Cardinality guidance table with suggested limits

MCP Tool Improvements

  • Added genie_space_id parameter to create_or_update_dashboard for linking dashboards to Genie spaces
  • Added catalog and schema parameters to create_or_update_dashboard for setting defaults for unqualified table names
  • Removed async deploy_dashboard function for API consistency (sync-only now)

Test plan

  • Verify dashboard creation with new genie_space_id parameter
  • Verify dashboard creation with catalog/schema parameters
  • Review restructured documentation for clarity

🤖 Generated with Claude Code

calreynolds
calreynolds requested changes Mar 25, 2026
View reviewed changes
Copy link
Copy Markdown
Collaborator

@calreynolds calreynolds left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can we separate this from the previous PR? I see both in here -- this one should just be ai/bi dashboards I think

Quentin Ambard and others added 7 commits March 28, 2026 11:40
@claude
Enhance AI/BI dashboard skill with comprehensive widget specs
7e0a5c4 
Added missing documentation from production dashboard generation:

1-widget-specifications.md:
- Combo charts (bar + line on same widget) with version 1
- Counter number formatting (currency, percent, plain number)
- Widget name max length (60 characters)
- Color scale restrictions (no scheme/colorRamp/mappings)
- Quantitative color encoding for gradient effects
- Bar chart group vs stacked decision criteria with examples

2-filters.md:
- Date range picker complete example
- Multi-dataset filter binding (one query per dataset)
- Global filter performance note (auto WHERE clause)

SKILL.md:
- ORDER BY guidance for time series and rankings

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Add TOP-N + Other bucketing guidance for high-cardinality dimensions
86b76b2 
When a dimension has too many values (50+ stores, products, etc.),
charts become unreadable. Added guidance to:

- Check cardinality via get_table_details before charting
- Use TOP-N + "Other" SQL pattern to bucket low-value items
- Aggregate to higher abstraction level as alternative
- Use table widgets for high-cardinality data

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Remove async deploy_dashboard function for consistency
a4cf4a2 
The codebase doesn't use async anywhere else, so remove the unused
async version of deploy_dashboard and keep only the synchronous one.
- Remove asyncio import
- Remove async deploy_dashboard function (was using asyncio.to_thread)
- Rename deploy_dashboard_sync to deploy_dashboard
- Update exports in __init__.py

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Add genie_space_id parameter to dashboard creation
5cd7189 
Allow linking a Genie space to a dashboard by passing genie_space_id.
This enables the "Ask Genie" button on the dashboard UI.

The Genie space config is injected into the serialized_dashboard JSON
under uiSettings.genieSpace with isEnabled=true and enablementMode=ENABLED.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Add catalog and schema parameters to dashboard creation
f29bbff 
Allow setting default catalog and schema for dashboard datasets via
the dataset_catalog and dataset_schema API parameters. These defaults
apply to unqualified table names in SQL queries.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Add comprehensive date range filtering documentation
93a91b2 
- Document field-based filtering (automatic IN_RANGE on date fields)
- Document parameter-based filtering (:date_range.min/max in SQL)
- Show how to combine both approaches in one filter
- Add guidance on when NOT to apply date filtering (MRR, all-time totals)
- Update SKILL.md tools table with new genie_space_id, catalog, schema params

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Restructure AI/BI dashboard skill with improved organization
618b2d4 
- Split widget specs into basic (1-widget-specifications.md) and advanced
  (2-advanced-widget-specifications.md) files
- Add area chart, scatter plot, combo chart, and choropleth map documentation
- Rename files for consistent numbering (3-filters, 4-examples, 5-troubleshooting)
- Remove duplicate information across files (versions, naming rules, etc.)
- Add widget display formatting guidance (currency, percentage, displayName)
- Simplify SKILL.md quality checklist with link to version table
- Shorten verbose examples while preserving all critical information
- Clarify query naming convention for charts vs filters

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@QuentinAmbard QuentinAmbard force-pushed the dashboard-improvements branch from 5586f10 to 618b2d4 Compare March 28, 2026 10:42
Quentin Ambard and others added 12 commits March 28, 2026 19:40
Add back critical behavioral instructions for text widgets and filters
99b2307
Restore important behavioral instructions removed during restructure
5d25ecf 
- Counter: full Pattern 2 example with CRITICAL field name matching note
- Table: disaggregated:true guidance and bold emphasis
- Line/Bar: x,y,color encodings and disaggregated guidance
- Pie: 3-8 category limit for readability
Restore detailed guidance that was removed during restructure
09e71ae 
- 5-troubleshooting.md: Restore full troubleshooting content with version
  guidance, filter debugging, and detailed error explanations
- SKILL.md: Restore full 10-item quality checklist
- SKILL.md: Restore standard dashboard structure example
- SKILL.md: Restore cardinality guidance table (with softer 'suggested' language)
@claude
Optimize MCP tool docstrings for token efficiency
ead5a54 
- Reduce docstring verbosity across all 18 tool files (~89% reduction)
- Keep all functional information while being concise
- Add skill references to complex tools (dashboards, vector search, genie, jobs, pipelines, lakebase, unity catalog, serving, apps, agent bricks)
- Maintain human readability with bullet points and structure
- Preserve critical warnings (ASK USER FIRST, CONFIRM WITH USER)
- Keep return format hints for AI parsing

Net reduction: 1,843 lines across 18 files

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Add parameter context for ambiguous docstring params
f0032d1 
- agent_bricks.py: Add context for description, instructions, volume_path, examples
- genie.py: Add context for table_identifiers, description, sample_questions, serialized_space
- jobs.py: Add context for tasks, job_clusters, environments, schedule, git_source
- lakebase.py: Add context for source_branch, ttl_seconds, is_protected, autoscaling params,
  and sync source/target table names
- pipelines.py: Add context for root_path, workspace_file_paths, extra_settings, full_refresh

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Consolidate MCP tools from 77 to 44 (43% reduction)
e7b6053 
Tool consolidations:
- pipelines.py: 10→2 (manage_pipeline, manage_pipeline_run)
- volume_files.py: 6→1 (manage_volume_files)
- aibi_dashboards.py: 4→1 (manage_dashboard)
- vector_search.py: 8→4 (manage_vs_endpoint, manage_vs_index, query_vs_index, manage_vs_data)
- genie.py: 5→2 (manage_genie, ask_genie)
- serving.py: 3→1 (manage_serving_endpoint)
- apps.py: 3→1 (manage_app)
- file.py: 2→1 (manage_workspace_files)
- sql.py: 6→5 (manage_warehouse replaces list/get_best)
- lakebase.py: 8→4 (manage_lakebase_database, manage_lakebase_branch, manage_lakebase_sync, generate_lakebase_credential)

Key patterns:
- All consolidated tools use an action parameter
- Each action has required params documented in docstring
- Error messages specify which params are required
- Hot paths (query_vs_index, ask_genie) kept separate for clarity
- All skills updated with action tables and examples

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Merge mcp-tool-token-optimization into dashboard-improvements
6e86c0f 
Merged consolidated tool approach with dashboard-improvements params:
- Combined manage_dashboard actions with genie_space_id, catalog, schema params
- Updated SKILL.md to document consolidated tool with optional params

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Add integration test infrastructure and fix tool bugs
fb40af6 
Test infrastructure:
- Add comprehensive integration tests for all MCP tools
- Add test runner script with parallel execution support
- Add fixtures for workspace, catalog, and resource cleanup
- Add test resources (PDFs, SQL files, app configs)

Bug fixes in databricks-tools-core:
- Fix workspace file upload for directories
- Fix job notebook path handling
- Fix vector search index operations
- Fix apps API responses
- Fix dashboard widget handling
- Fix agent bricks manager listing

Bug fixes in MCP server tools:
- Add quota skip handling for apps test
- Fix genie space operations
- Fix lakebase database operations
- Fix compute cluster lifecycle handling
- Fix dashboard operations

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Change manage_dashboard to use file path instead of inline JSON
75830b8 
- Replace serialized_dashboard param with dashboard_file_path
- Tool reads JSON from local file for easier iterative development
- Update SKILL.md with new workflow documentation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Merge mcp-tool-token-optimization (with tests)
089aacb 
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Update dashboard tests for file-based approach
0db8152 
- Change simple_dashboard_json fixture to simple_dashboard_file
- Update all manage_dashboard calls to use dashboard_file_path
- Add tempfile imports and tmp_path usage for update test

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Fix deploy_app to correctly handle SDK Wait[AppDeployment] return type
a73db19 
The Databricks SDK's w.apps.deploy() returns a Wait[AppDeployment] object,
not an AppDeployment directly. The previous code passed the Wait object
to _deployment_to_dict(), which caused getattr() to return None for all
attributes since the Wait object doesn't have them.

This fix uses wait_obj.response to get the actual AppDeployment object
before converting it to a dictionary.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@QuentinAmbard
Copy link
Copy Markdown
Collaborator Author

QuentinAmbard commented Apr 1, 2026

Additional Fix: deploy_app SDK return type handling

Added commit a73db19 which fixes a bug in databricks_tools_core/apps/apps.py:

Problem

The deploy_app function was incorrectly handling the Databricks SDK's async operation pattern. The SDK's w.apps.deploy() returns a Wait[AppDeployment] object, not an AppDeployment directly. The previous code passed the Wait object to _deployment_to_dict(), which caused all attribute extractions via getattr() to return None.

Fix

Changed to use wait_obj.response to get the actual AppDeployment object before converting it to a dictionary.

-    deployment = w.apps.deploy(...)
-    return _deployment_to_dict(deployment)
+    # w.apps.deploy returns a Wait[AppDeployment], use .response to get the AppDeployment
+    wait_obj = w.apps.deploy(...)
+    return _deployment_to_dict(wait_obj.response)

Testing

  • Verified with integration test test_full_app_lifecycle - passed in ~5 minutes
  • The deployment details (deployment_id, source_code_path, state) are now correctly populated

@claude
Fix deploy_app to correctly handle SDK Wait[AppDeployment] return type
ad568e3 
The Databricks SDK's w.apps.deploy() returns a Wait[AppDeployment] object,
not an AppDeployment directly. The previous code passed the Wait object
to _deployment_to_dict(), which caused getattr() to return None for all
attributes since the Wait object doesn't have them.

This fix uses wait_obj.response to get the actual AppDeployment object
before converting it to a dictionary.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@QuentinAmbard
Copy link
Copy Markdown
Collaborator Author

QuentinAmbard commented Apr 1, 2026

once #394 is merged we'll rebased and only the dashboard update will remain

@QuentinAmbard QuentinAmbard mentioned this pull request Apr 1, 2026
Open
4 tasks
Quentin Ambard and others added 5 commits April 1, 2026 09:23
@claude
Clarify MCP tool usage in Genie skill documentation
7f37a3e 
- Add tools summary table at top of MCP Tools section
- Change code blocks from python syntax to plain text
- Add "# MCP Tool: <name>" comments to clarify these are tool calls, not Python code
- Move Supporting Tools table to main tools table

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Fix typo in aibi_dashboards.py docstring
fe7ea10 
Remove garbage characters from widget documentation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Fix genie tools to use SDK methods instead of manager
defaf89 
- Use w.genie.trash_space() in _delete_genie_resource
- Add _find_space_by_name() using SDK's list_spaces with pagination
- Use w.genie.update_space() and w.genie.create_space() for space management
- Use w.genie.get_space() with include_serialized_space in _get_genie_space
- Fix validation to allow space_id for updates without display_name

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Improve integration test reliability and timeout handling
3fb94b6 
- Add per-suite timeout in run_tests.py (10 min default, configurable)
- Improve apps test with better cleanup and assertions
- Add skip logic for quota-exceeded scenarios

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Improve Unity Catalog tool docstrings with comprehensive parameter do…
30617bf 
…cumentation

Add detailed parameter documentation to all 9 Unity Catalog MCP tools:
- manage_uc_objects: Document parameters by object_type (catalog/schema/volume/function)
- manage_uc_grants: Add privilege lists per securable type
- manage_uc_storage: Detail credential and external_location parameters
- manage_uc_connections: Document connection_type options and create_foreign_catalog
- manage_uc_tags: Detail set_tags/unset_tags/query parameters
- manage_uc_security_policies: Document row filter and column mask parameters
- manage_uc_monitors: Detail monitor creation and refresh parameters
- manage_uc_sharing: Document share/recipient/provider resource types
- manage_metric_views: Detail dimension/measure format and query parameters

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
Quentin Ambard and others added 3 commits April 1, 2026 09:41
@claude
Add CRITICAL validation steps to dashboard tool docstring
4cf4133 
Add clear instructions requiring users to:
0. Review the databricks-aibi-dashboards skill for widget JSON structure
1. Call get_table_stats_and_schema() for table schemas
2. Call execute_sql() to test EVERY query before use

This prevents widgets from showing errors due to untested queries.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Add design best practices section and use relative file paths
04f06d6 
- Add Design Best Practices section for default dashboard behaviors
- Change /tmp paths to ./ for less opinionated examples
- Update parent_path example to use {user_email} placeholder

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Merge mcp-tool-token-optimization into dashboard-improvements
92acf6f 
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@calreynolds calreynolds calreynolds requested changes

Requested changes must be addressed to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@QuentinAmbard @calreynolds