fix(tools): rewrite the semantic layer description around what it can do

[josep-reyero]

Supersedes #108, which was branched as fix/regional-dimension-names before the scope grew well past that. Includes both commits.

The problem

query_lfx_semantic_layer's description was 3,662 characters. Descriptions are cut at 2,048 before the model ever sees them, so 44% was invisible — the entity-prefix rule, the country/region routing tip and the tlf membership caveat all sat past the cut.

The visible half told the model that memberships were an exception without ever saying what to do instead. That is why regional questions kept landing on query_lfx_lens.

What the tool actually does

Rewriting it meant first establishing what is on offer. Probing the live Semantic Layer showed the old framing understated it in two ways that mattered:

• Not "pre-aggregated metrics". MetricFlow compiles SQL per request. Nothing is stored.
• Not only numbers. Grouping by a name dimension returns a ranked list of named organizations or people — which is exactly the shape of the stakeholder question this work exists to answer. An earlier draft framed the tool as "numbers, not records" and would have routed that question away from the tool built for it.

Also confirmed against the live API: cross-domain metrics combine in one query (joined on shared entities, no join syntax written by the caller), every metric carries metric_time at five grains, and 33 metrics ship built-in filters (current_* is active-only, total_contributors excludes bots) that a caller must not re-apply.

What changed

Description now names the six covered domains, states that country/region questions always belong here, and describes ranking, trending, multi-dimension breakdown and cross-domain combination. 2,021 bytes.

Syntax moved onto the parameter it governs — where carries the MetricFlow forms, group_by the entity__field rule and grain suffixes, metrics the outer-join semantics. Each jsonschema description is a separate field with its own budget, and the model reads it at the moment it fills that field. That redistribution is what made room; the description had been rationing characters against a limit the parameters do not share.

describe → help, since it is now a fallback for a failed query rather than a prerequisite. The old name still dispatches so a cached schema does not break.

Verification

Run end to end against the live stack, not by compiling SQL alone. Both motivating questions return real data:

Region	Membership revenue	Contributing orgs	Contributors
North America	$110,423,700	30,358	41,782
Europe	$24,451,350	28,330	30,079

Ranked named lists work (top contributing orgs in Asia Pacific: FOSSASIA, National University of Singapore, SK Group, Canva).

Running it caught a bug the SQL check could not. The ranked-list example filtered lf_region on 'Asia' — which compiles fine and matches nothing. The value is 'Asia Pacific'. compileSql validates dimension names, never values. Fixed, and the region values are now enumerated in the example.

Tests

Budget is guarded in bytes, not characters — em-dashes cost three bytes each and the description ran ~30 bytes over its character count. Coverage extends to every parameter and to query_lfx_lens, which has far less headroom and is the likelier of the two to drift past the cut unnoticed.

TestSemanticLayerDescription also asserts the absence of pre-aggregated and returns numbers, not records, so neither framing comes back.

Depends on

Two lines lean on linuxfoundation/lfx-lens#27 (ranked suggestions on an unknown metric name). If that does not merge, those claims must be cut.

🤖 Generated with Claude Code

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

_{Tip: disable this comment in your organization's Code Review settings.}

[Copilot]

Pull request overview

Reworks semantic-layer guidance to fit schema limits and improve query routing.

Changes:

• Rewrites tool and parameter descriptions.
• Renames describe to help, retaining compatibility.
• Adds schema-budget and guidance tests.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
internal/tools/lens.go	Updates semantic-layer guidance and help handling.
internal/tools/lens_test.go	Adds budget and schema regression coverage.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

internal/tools/lens.go:398

• This alias does not preserve compatibility for the cached schema that existed before this PR. That schema only knows query_lfx_semantic_layer, so an old action=describe request is sent to handleQuerySemanticLayer, never to this new explore handler, and fails the new required metrics schema/validation. The same applies to old list_metrics and get_dimensions calls. Preserve legacy action dispatch on the old tool name (or explicitly treat the split as breaking) rather than claiming the cached schema remains usable.

	// "describe" is the pre-rename name for help, kept so a caller working
	// from a cached schema does not get an Unknown action error.
	case "help", "describe":
		return handleLensHelp(args.Target)

cmd/lfx-mcp-server/main.go:804

• The new tool cannot actually be enabled by its advertised configuration name: with LFXMCP_TOOLS=explore_lfx_semantic_layer, this condition is false and neither semantic-layer tool is registered. Conversely, selecting only query_lfx_semantic_layer exposes both tools. This breaks the established per-tool -tools/LFXMCP_TOOLS behavior used by every registration above. Please either register the explore and query tools independently, or explicitly treat either configured name as enabling the pair.

	if enabledTools["query_lfx_semantic_layer"] && canRead && isStaff {
		tools.RegisterSemanticLayer(server)

[josep-reyero]

Closing for now — the scope has outgrown this PR. Live testing surfaced two further problems (unknown filter literals silently returning zero rows, and no way to discover dimension values), so the work is being consolidated into a single change that covers description truncation, caller guidance, and the new discovery capability. A replacement PR will follow from a fresh branch.