Skip to content

Improve code execution and synthetic data generation skills#403

Open
QuentinAmbard wants to merge 33 commits intomainfrom
code-execution-improvements
Open

Improve code execution and synthetic data generation skills#403
QuentinAmbard wants to merge 33 commits intomainfrom
code-execution-improvements

Conversation

@QuentinAmbard
Copy link
Copy Markdown
Collaborator

@QuentinAmbard QuentinAmbard commented Apr 1, 2026 •
edited
Loading

Summary

  • Execution compute skill: Split into 3 clear execution modes (interactive REPL, serverless jobs, cluster execution) with consolidated guidance
  • Synthetic data gen skill: Emphasize business story, domain modeling, and realistic data generation patterns
  • Dashboard skill improvements: Enhanced widget definitions, filter documentation, and validation steps

Branch Relationships

                    mcp-tool-token-optimization
                        PR #394 [OPEN]
                        (BASE - 17 commits)
                             │
           ┌─────────────────┴─────────────────┐
           │                                   │
dashboard-improvements              code-execution-improvements
    PR #374 [OPEN]                      PR #403 [OPEN]
     (19 commits)                        (22 commits)
    +2 unique commits              +5 unique commits
                                   (includes dashboard changes)
                                   *** MOST COMPLETE ***

This branch (code-execution-improvements) is the MOST COMPLETE - it contains:

  • All 17 commits from mcp-tool-token-optimization
  • All 2 unique commits from dashboard-improvements (cherry-picked)
  • 3 additional unique commits for execution compute improvements

Merge Order

⚠️ Merge PRs in this order to avoid conflicts:

  1. First: PR Optimize MCP tool docstrings for token efficiency #394 (mcp-tool-token-optimization) - Base changes
  2. Second: PR Enhance AI/BI dashboard skill with comprehensive widget documentation #374 (dashboard-improvements) - Dashboard skill improvements
  3. Third: PR Improve code execution and synthetic data generation skills #403 (code-execution-improvements) - This PR, execution compute + synthetic data skills

Test plan

  • Verify skill files load correctly
  • Test dashboard creation with updated skill guidance
  • Test code execution modes documentation
  • Manual testing of synthetic data generation patterns

🤖 Generated with Claude Code

Quentin Ambard and others added 30 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>
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>
@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>
@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>
@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>
@claude
Improve code execution and synthetic data gen skills
5ef5b94 
Execution compute skill:
- Split into 3 clear execution modes: Databricks Connect (default), Serverless Job, Interactive Cluster
- Add decision matrix for choosing execution mode
- Add job_extra_params for custom dependencies in serverless jobs
- Create dedicated reference files for each mode

Synthetic data gen skill:
- Emphasize business story: problem → impact → analysis → solution
- Add guidance to propose compelling stories by default
- Consolidate reference files (6 → 2)
- Add critical rules for data coherence and Databricks value
- Clarify when to read reference files

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

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Add performance rules for synthetic data generation
dac32a5 
- Add Critical Rule #12: No Python loops or .collect()
- Add Performance Rules section with anti-pattern table
- Emphasize Spark parallelism over driver-side iteration

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

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Clarify parquet path is folder with table name
cfad30b 
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@calreynolds calreynolds self-requested a review April 1, 2026 14:52
Quentin Ambard and others added 2 commits April 2, 2026 09:39
@claude
Improve AI/BI dashboard skill documentation with comprehensive examples
85966e6 
- Replace basic NYC taxi examples with complete Sales Analytics dashboard
- Add critical widget version requirements table to SKILL.md
- Add data validation guidance to verify dashboards tell intended story
- Document key patterns: page types, KPI formatting, filter binding, layout grid

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

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Add skill reading requirement to dashboard MCP tool docstring
d799053 
Require agent to read 4-examples.md before creating dashboards, and if
unfamiliar, read full skill documentation first. Valid JSON is critical.

🤖 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 Awaiting requested review from calreynolds

At least 1 approving review is required 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.

1 participant

@QuentinAmbard