Skip to main content
Glama

investigate

Profiles warehouse tables and stores their current state as a baseline for later anomaly detection. Use it to establish drift checks before running watch.

Instructions

Profile tables and store them as the baseline for future anomaly checks.

Pass tables to limit to specific tables, or omit to profile the tables saved with scherlok connect --table, else everything visible. The first profile of a table establishes its baseline; no anomalies are reported here. Run watch later to detect drift. A table whose current state has a CRITICAL anomaly against its baseline keeps that baseline, with baseline_updated false: a broken state is not learned. Only a person makes it the new baseline, with scherlok accept. Fails while baselines are locked.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "investigate"
  }
}

Input Schema

NameRequiredDescriptionDefault
tablesNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations, the description carries the full load and does well: it discloses that no anomalies are reported, that only the first profile sets a baseline, that a table in CRITICAL state keeps its old baseline with `baseline_updated` false, and that the call fails while baselines are locked. It never states plainly that this is a state-mutating operation with potentially long profiling runtime, which is the remaining gap.

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?

Front-loaded with the action and its purpose, and every subsequent sentence adds a distinct rule (fallback order, baseline establishment, CRITICAL exception, lock failure). Density is high because CLI command names and quoted field names are interleaved with prose, which makes it slower to scan than it needs to be.

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?

An output schema exists, so return values need not be explained, and the description still references the meaningful `baseline_updated` outcome. For a one-parameter tool it covers scope, side effects, and failure modes well; only the cost/duration of profiling and the mutating nature are left implicit.

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

Parameters4/5

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

Schema coverage is 0% and the single `tables` parameter has no description, so the description must compensate — and it does, spelling out the three-level fallback when the parameter is supplied versus omitted. It does not say whether table names must be fully qualified or how unknown names are handled.

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?

States a specific verb+resource: "Profile tables and store them as the baseline for future anomaly checks." It also explicitly separates itself from the sibling that detects drift later ("Run `watch` later to detect drift"), so an agent can distinguish it from watch/check without opening the schema.

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?

Gives explicit when-to-use and when-not-to-use: profiling here establishes a baseline and reports no anomalies, while `watch` is the tool for drift detection and `scherlok accept` is the only way to adopt a new baseline. The parameter fallback chain (explicit tables → connect-saved tables → everything visible) further disambiguates invocation.

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