Skip to main content
Glama

explain

Read-onlyIdempotent

Extract a function, class, or variable body with called functions and dependencies by symbol name, or get a structural file overview from a path without reading the whole file.

Instructions

Extract a specific function/class body with its dependencies, without reading the entire file. Provide symbol name to get its code + called functions. Provide file path for a structural overview.

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": "explain"
  }
}

Input Schema

NameRequiredDescriptionDefault
fileNoFile to explain (overview mode if no symbol given).
rootNoAbsolute project root. Omit only where this session started; required elsewhere and on every subagent call.
depthNoHow many levels of called functions to include. Default: 1. Use 0 for just the symbol.
formatNosource: body and location only, no callers/tests/dependencies. Default full.
symbolNoFunction, class, or variable name to explain.
symbolsNoBatch independent symbols in one call, instead of repeated reads. Use instead of symbol/file.
max_tokensNoBatch response byte/4 budget; default 4000. Whole omitted bodies are reported.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.6.0
    • changedInput schema / properties / root / description
      Previous value: -"Absolute project root. Required with linked worktrees; subagents must pass their own worktree root on every call."New value: +"Absolute project root. Omit only where this session started; required elsewhere and on every subagent call."
  2. First observedv1.4.0

TDQS

A3.6/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add behavioral context. It does so by framing the tool as a token-efficient partial read ('without reading the entire file') and by describing what the result contains (body plus called functions, or a structural overview), which goes beyond the annotations.

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?

Three short sentences, front-loaded with the core capability and the efficiency rationale, with no filler. The parallel 'Provide X to get Y' phrasing is easy to scan, though the repeated structure costs a few words.

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

Completeness3/5

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

With seven parameters and no output schema, the description should carry more weight. It explains the two primary modes and roughly what comes back, but omits the batch symbols path (explicitly encouraged by the schema to avoid repeated reads) and the root requirement, leaving meaningful gaps for a multi-parameter tool.

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 description coverage is 100%, so every parameter is already documented, and the description mostly restates the schema's symbol/file mode split. It adds a little meaning by clarifying that the symbol mode returns 'code + called functions', but says nothing about depth, format, max_tokens, or the batch symbols parameter.

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?

States a specific verb and resource: 'Extract a specific function/class body with its dependencies.' The phrase 'without reading the entire file' implicitly distinguishes it from a full file read (artifact_read) and hints at a structural alternative (skeleton), but no sibling is named explicitly.

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

Usage Guidelines3/5

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

Gives clear mode-selection guidance for two parameters: symbol for code plus called functions, file for a structural overview. It never says when to prefer this over siblings like skeleton, exact_references, or search, and it omits the batch (symbols) path entirely, leaving the agent to infer it from the schema.

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