Problem
src/uxarray_mcp/tools/frontdoor.py exposes essentially the whole library through one function. On current main:
- 38 parameters on
run_analysis
- 32 operations named in a 1210-character docstring
get_capabilities adds a further 2923-character description
Serialized, the two tools come to about 9,100 characters of tool specification sent on every request. For comparison, a plain file-inspector plus Python-interpreter pair is about 619 characters — a 15x difference. That overhead is a consequence of this design choice, not of MCP.
Why it matters beyond size
A tool this general cannot say anything specific about a particular call. It cannot express that calculate_zonal_mean needs face-centered data while calculate_area needs no data at all, because it has one signature for all 32 operations. Most of the 38 parameters are irrelevant to any given call — center_lon and outer_radius mean nothing to calculate_area — so a model must infer applicability from prose.
This also appears to drive #83: because the tool cannot describe the specific call, it compensates by attaching a catalog of everything else it could do.
Measurements
In a controlled comparison across four model deployments and six analysis tasks, the named-operation front door cost about 3.2k and 3.8k more median tokens than model-written Python on two tasks that both interfaces solved perfectly (20/20 either way). That is pure overhead on decisions that were easy to begin with.
The honest counterweight: on a remapping task the named operation was clearly worth it, taking correct runs from 10/20 to 20/20 and cutting median tokens for three of four deployments. The problem is not having named operations. It is having one name for everything.
Suggested direction
Split the front door into a small number of tools whose schemas can be specific, grouped by what they consume: mesh-only operations (calculate_area, inspect_mesh), single-field operations (calculate_zonal_mean, gradient), two-field operations (curl, divergence, bias), and subsetting/export. Each gets only the parameters it can use.
If the single entry point must stay for compatibility, consider generating per-operation schemas and advertising only the subset applicable to the dataset in play.
Worth measuring after any change: serialized schema size, and whether first-turn prompt tokens fall from the currently observed median of ~2,000.
Problem
src/uxarray_mcp/tools/frontdoor.pyexposes essentially the whole library through one function. On currentmain:run_analysisget_capabilitiesadds a further 2923-character descriptionSerialized, the two tools come to about 9,100 characters of tool specification sent on every request. For comparison, a plain file-inspector plus Python-interpreter pair is about 619 characters — a 15x difference. That overhead is a consequence of this design choice, not of MCP.
Why it matters beyond size
A tool this general cannot say anything specific about a particular call. It cannot express that
calculate_zonal_meanneeds face-centered data whilecalculate_areaneeds no data at all, because it has one signature for all 32 operations. Most of the 38 parameters are irrelevant to any given call —center_lonandouter_radiusmean nothing tocalculate_area— so a model must infer applicability from prose.This also appears to drive #83: because the tool cannot describe the specific call, it compensates by attaching a catalog of everything else it could do.
Measurements
In a controlled comparison across four model deployments and six analysis tasks, the named-operation front door cost about 3.2k and 3.8k more median tokens than model-written Python on two tasks that both interfaces solved perfectly (20/20 either way). That is pure overhead on decisions that were easy to begin with.
The honest counterweight: on a remapping task the named operation was clearly worth it, taking correct runs from 10/20 to 20/20 and cutting median tokens for three of four deployments. The problem is not having named operations. It is having one name for everything.
Suggested direction
Split the front door into a small number of tools whose schemas can be specific, grouped by what they consume: mesh-only operations (
calculate_area,inspect_mesh), single-field operations (calculate_zonal_mean,gradient), two-field operations (curl,divergence,bias), and subsetting/export. Each gets only the parameters it can use.If the single entry point must stay for compatibility, consider generating per-operation schemas and advertising only the subset applicable to the dataset in play.
Worth measuring after any change: serialized schema size, and whether first-turn prompt tokens fall from the currently observed median of ~2,000.