Skip to main content
Glama
semlayer MCP server

semlayer MCP server

load_layer

Idempotent

Loads a specified semantic layer by ref, connection, or file path and replaces the current session layer, returning updated status so queries use the intended warehouse context.

Instructions

Load one of the layers status listed under layers.

    ref: the `ref` from that list, the connection it is for, or a path to
    a layer file. Returns the new status. Use it when several layers are
    on this machine and the user has said which warehouse they mean --
    and after it, tell them which one you loaded. It replaces the layer
    this session answers from and leaves every file as it was; a ref that
    cannot be loaded comes back as status with an `error`, which still
    lists `layers`.
    

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "ref": "<ref>"
    },
    "name": "load_layer"
  }
}

Input Schema

NameRequiredDescriptionDefault
refYesA `ref` from `status.layers`, the connection the layer was built for, or a path to a layer file.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.1
    • addedInput schema / properties / ref / description
      Added value: +"A `ref` from `status.layers`, the connection the layer was built for, or a path to a layer file."
  2. First observedv0.1.0

TDQS

A4.1/5.0
Behavior5/5

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

Beyond the annotations (readOnly=false, destructive=false, idempotent=true), the description discloses the exact scope of mutation: it "replaces the layer this session answers from and leaves every file as it was," which reconciles a write operation with destructive=false. It also explains error behavior (unloadable ref returns status with an `error` that still lists `layers`), which the agent would otherwise have to guess.

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

Conciseness4/5

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

Purpose and constraint are front-loaded, and each sentence carries useful information (what changes, what is preserved, what errors look like). There is minor redundancy with the schema's parameter description and a slightly meandering clause about telling the user which layer was loaded.

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

Completeness4/5

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

For a one-parameter tool with an output schema and full annotation coverage, the description covers the key unknowns: mutation scope, file safety, and error semantics. Return values are largely delegated to the output schema, which is acceptable given it exists.

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

Parameters3/5

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

Schema coverage is 100% and the single `ref` parameter is fully documented in the schema, largely duplicating the description's text about refs, connections, and file paths. The description adds only slight framing ("from that list"), so the baseline 3 is appropriate.

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

Purpose4/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 ("Load one of the layers `status` listed under `layers`") and states the scope precisely, distinguishing it from the read-only `status` listing it depends on. It stops short of naming other siblings like `export_layer` or `save_layer` to contrast behavior, so a 4 rather than a 5.

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

Usage Guidelines4/5

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

"Use it when several layers are on this machine and the user has said which warehouse they mean" gives a concrete triggering condition and implicitly excludes ambiguity cases where the user hasn't specified. It adds a post-action instruction (tell the user which one was loaded), though it does not name explicit alternatives to use instead.

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