SLayer

Overview Schema Source Related Servers Discussions Admin

recommend_root_model

Identifies the optimal source model for a set of columns and metrics, returning join-qualified paths for each item. Handles unreachable items by suggesting partial roots for multi-stage queries.

Instructions

Recommend the root model (query source_model) for a set of model.column / model.metric items, and give each item's join-qualified reference path from that root.

Introspects the join graph and picks the model from which every requested item is reachable (LEFT joins are directional; INNER joins traverse both ways), minimizing total join hops. The returned paths are ready to drop into a query whose source_model is the recommended root — e.g. a joined column comes back as customers.regions.name and a root-owned one as status; aggregation spellings (sum(revenue) / revenue:sum) are preserved.

When no single model reaches everything, root_model is null and coverage lists the best partial roots so you can split the request into a multi-stage query.

Call this once your item list is final, not as a schema browser — explore with search / inspect first.

Args: items: entity references (orders.revenue, customers.name, orders.revenue:sum / sum(orders.revenue), bare aov for a saved metric...). data_source: optional datasource scope; when omitted, names resolve via the datasource-priority list. All items must resolve to a single datasource. root_hint: optional intended root — a bare model name or <data_source>.<model> within the resolved datasource. Honored when it reaches every item (overriding the min-hops pick, so you can force a bridge model that owns none of the items); otherwise the auto-pick is used and a warning explains why. Resolved after the datasource is determined, so it cannot pick the datasource. format: "markdown" (default) or "json".

Input Schema

TableJSON Schema

Name	Required	Default
`items`	Yes
`format`	No	markdown
`root_hint`	No
`data_source`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.10.0Sep 3, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses directional LEFT joins, bidirectional INNER joins, min-hop optimization, root_hint override semantics, the warning when the hint is ignored, and the null-root/coverage fallback. This goes well beyond a basic 'recommends a root' summary.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then methodically covers behavior, edge cases, usage timing, and parameters. Every section earns its place; the Args section adds semantic value beyond the schema rather than repeating it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex join-graph tool with 0% schema parameter coverage, the description is complete: it covers when to use it, all parameter semantics, key edge cases, output examples, and interaction with sibling tools. The existing output schema handles detailed return-structure documentation, so nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate — and it does. items gets concrete spellings and examples, data_source gets scope and single-datasource constraints, root_hint gets override behavior and resolution order, and format gets its allowed values and default.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-and-resource statement: it recommends a root model for a set of items and returns join-qualified reference paths. It also distinguishes itself from schema-browsing siblings by explicitly saying it is not a schema browser and pointing to search/inspect for exploration.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to call the tool: once the item list is final, not during exploration. It also names alternatives (search/inspect) and explains the fallback behavior when no single root reaches every item, which helps an agent decide whether to split the request.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.