aminghadersohi opened a new pull request, #45084: URL: https://github.com/apache/superset/pull/45084
### SUMMARY Builds on https://github.com/apache/superset/pull/45081 and should merge after it: this branch merges that PR's branch to reuse its native tool inventory test and `native_tool_inventory.json`. Once #45081 lands, the diff here reduces to the changes below. **1. Opt-in compact native `tools/list` (default off).** New `MCP_NATIVE_TOOL_LIST_CONFIG = {"compact": False, "max_description_length": 300}`. It only applies when tool search is disabled (native mode). With `compact=True`, a FastMCP transform bounds each listed description using the rule tool search already applies to its results. That rule is pulled into one shared helper, `_bounded_description`, which the search serializers now call too, so there is no second implementation. The rule keeps whole paragraphs, then whole sentences, never a partial heading, `IMPORTANT` block or list, and deducts the request-parameter instructions (kept untruncated in the schema) from the budget. Only the listing changes. Names, input/output schemas (nullable unions, constraints, `$defs`) and annotations are served unchanged. `get_tool`/`tools/call` resolve the registered tool, so Pydantic validation and execution do not depend on the setting. FastMCP's `$ref` inlining is kept, because keeping `$re f`s would be larger. No default changes. **2. Editorial trims of redundant guidance**, applied in both modes: - `generate_chart`: the per-chart-type required-field list, the table/pie/SQL-metric examples and the validation-pipeline notes are removed. `get_chart_type_schema` already serves each type's fields, required fields and examples, and the description now points to it first. The discriminator rules, the natural-language → `chart_type` lookup and one XY example stay. - `update_chart`: duplicate examples and the "Use when" list are folded; it points to `get_chart_type_schema` for config. - `list_charts` / `list_dashboards` / `list_datasets`: filter-model docstrings that restated the `col`/`opr`/`value` field descriptions are removed, the shared `filters` description is shortened, deployment-internal wording is dropped from `deleted_state`, and a developer note moves from the `ListDatasetsRequest` docstring into a code comment. - `manage_dashboard_markdown` / `manage_native_filters`: placement and scope text that the tool docstring already covers is shortened on the spec models. No execution behaviour changes. The existing description-constraint audits (`test_tool_description_constraints.py`) pass unchanged. **Sizes** (compact UTF-8 JSON of the `tools/list` entries, 79 tools; chart_type enum excluded as in the inventory; tokens ≈ bytes / 4.6): | Listing | text-only | structured output | | --- | --- | --- | | Before (#45081) | 218,156 B (~47.4k tok) | 524,788 B | | Default, after trims | 210,375 B (~45.7k tok, −3.6%) | 516,296 B | | Compact (`compact=True`, 300) | 158,166 B (~34.4k tok, −27.5%) | 464,087 B | Largest text-only per-tool reductions in the default listing: `generate_chart` −3,731 B, `update_chart` −824, `manage_dashboard_markdown` −777, `list_datasets` −507, `list_charts`/`list_dashboards` −433 each, `manage_native_filters` −224, and the other list tools −71 each. The inventory now records `compact_description_chars` per tool and `compact_catalog_bytes` totals, and enforces both with the existing growth budget. ### BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF N/A ### TESTING INSTRUCTIONS ```bash pytest tests/unit_tests/mcp_service/test_native_tool_surface.py \ tests/unit_tests/mcp_service/test_mcp_server.py \ tests/unit_tests/mcp_service/test_tool_description_constraints.py # regenerate the inventory after an intentional change SUPERSET_MCP_UPDATE_TOOL_INVENTORY=1 pytest tests/unit_tests/mcp_service/test_native_tool_surface.py ``` New tests in `test_native_tool_surface.py`: - `test_compact_listing_is_off_by_default`: the default config, an empty config, and a zero budget all leave the listing alone. - `test_compact_listing_only_bounds_descriptions` (both output modes): every wire field except `description` is identical to the default listing. Each description equals `_bounded_description(...)` of the full text and is a prefix of it. - `test_compact_schemas_keep_nullability_constraints_and_definitions`: input and output schemas are identical, and the counts of nullable `anyOf`, `enum`, `minimum`/`maximum`, `maxLength`, `$defs`/`$ref`, etc. match. - `test_compact_listing_keeps_full_definitions_for_calls`: `get_tool` returns the full description and parameters for every tool. - `test_compact_listing_validates_calls_identically`: constraint violations, wrong types and missing required fields give identical validation errors, and nullable fields accept `null`. - `test_compact_listing_keeps_chart_guidance_reachable`: the compact chart tools reference `get_chart_type_schema`, which returns required fields and examples for every core chart type. In `test_mcp_server.py`, `run_server` passes `MCP_NATIVE_TOOL_LIST_CONFIG` through only in native mode. ### ADDITIONAL INFORMATION - [ ] Has associated issue: - [ ] Required feature flags: - [ ] Changes UI - [ ] Includes DB Migration (follow approval process in [SIP-59](https://github.com/apache/superset/issues/13351)) - [ ] Migration is atomic, supports rollback & is backwards-compatible - [ ] Confirm DB migration upgrade and downgrade tested - [ ] Runtime estimates and downtime expectations provided - [x] Introduces new feature or API - [ ] Removes existing feature or API -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
