Skip to main content
Glama
nikolai-vysotskyi

trace-mcp

by nikolai-vysotskyi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

get_outline

Read-onlyIdempotent

Need to understand a file before editing? Retrieve its symbol outline with signatures only, using fewer tokens than a full read.

Instructions

Get all symbols for a file (signatures only, no bodies) — cheaper than Read for understanding a file before editing. Follow up with get_symbol to read one symbol's source. nested: true expands large top-level symbols (default ≥100 LOC) into inner declarations, each carrying parentId + depth (max 3). Read-only. Returns JSON: { path, language, symbols: [{ symbolId, name, kind, signature, lineStart, lineEnd, parentId?, depth? }] }. Supports output_format: "toon".

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pathYesRelative file path
nestedNoWalk the body of each top-level symbol past min_loc_for_nesting and emit inner declarations as extra rows carrying `parentId` + `depth`. Default false.
detail_levelNoOutput verbosity. "minimal" saves ~40-60% tokens (drops scores, fqn, signatures, summaries). Use to pick a candidate before get_symbol. Default: "default".
output_formatNo"json" (default) or "toon" (lossless, 30-60% fewer tokens). "markdown" is unsupported here and behaves as json.
min_loc_for_nestingNoMinimum (line_end - line_start) for a top-level symbol to be expanded when nested=true. Default 100.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv3.31.0
    • changedInput schema / properties / detail_level / description
      Previous value: -"Output verbosity. \"minimal\" returns ~40-60% fewer tokens (drops scores, fqn, signatures, summaries — keeps name/file/line). Use when you only need to pick a candidate before drilling in with get_symbol. Default: \"default\"."New value: +"Output verbosity. \"minimal\" saves ~40-60% tokens (drops scores, fqn, signatures, summaries). Use to pick a candidate before get_symbol. Default: \"default\"."
  2. Changed3 schema fields changedv3.3.0
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • changedInput schema / properties / nested / description
      Previous value: -"When true, walks the body of each top-level symbol whose LOC exceeds min_loc_for_nesting and emits inner function-like declarations as additional rows carrying `parentId` + `depth`. Default false — fully backward compatible."New value: +"Walk the body of each top-level symbol past min_loc_for_nesting and emit inner declarations as extra rows carrying `parentId` + `depth`. Default false."
    • changedInput schema / properties / output_format / description
      Previous value: -"Output format. \"json\" (default) returns JSON; \"toon\" returns Token-Oriented Object Notation — 30-60% fewer tokens, lossless. \"markdown\" is unsupported here and behaves as json."New value: +"\"json\" (default) or \"toon\" (lossless, 30-60% fewer tokens). \"markdown\" is unsupported here and behaves as json."
  3. Added
  4. Removedv1.38.0
  5. Changed2 schema fields changedv1.35.1
    • removedInput schema / additionalProperties
      Removed value: -false
    • addedInput schema / properties / detail_level
      Added value: +{
+  "description": "Output verbosity. \"minimal\" returns ~40-60% fewer tokens (drops scores, fqn, signatures, summaries — keeps name/file/line). Use when you only need to pick a candidate before drilling in with get_symbol. Default: \"default\".",
+  "enum": [
+    "minimal",
+    "default",
+    "full"
+  ],
+  "type": "string"
+}
  6. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds behavioral value beyond annotations: the nesting expansion semantics (parentId + depth, max 3, default ≥100 LOC), the 'Read-only' confirmation, and the explicit return JSON shape. No contradiction with 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?

Purpose is front-loaded in the first sentence. The description is dense but every clause earns its place: cost comparison, follow-up workflow, nesting behavior, return format, and toon support. Slightly long but structured well with a clear return-shape example that helps an agent parse the output.

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 read-only outline tool with 5 parameters and 2 enums, the description covers the core purpose, cost benefit, follow-up routing, nesting semantics, return structure, and output formats. Minor gaps: no mention of error behavior (e.g., file-not-found or unsupported language), but for a non-destructive tool with strong annotation coverage this is reasonably complete.

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%, so the baseline is 3 and the schema carries the parameter documentation. The description adds some marginal value — clarifying the toon output format support, nesting depth cap, and default LOC threshold — but these mostly restate or lightly extend what the schema already covers. Does not fully compensate beyond the baseline.

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 ('Get all symbols for a file') with a precise scope qualifier ('signatures only, no bodies'), and distinguishes itself from the sibling get_symbol by naming the follow-up workflow. An agent can immediately tell what this does and how it differs from its sibling.

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?

Explicitly positions the tool: 'cheaper than Read for understanding a file before editing' tells when to prefer it, and 'Follow up with get_symbol to read one symbol's source' defines the recommended workflow. The detail_level schema description also guides when to use 'minimal' ('Use to pick a candidate before get_symbol'). Clear usage context with no ambiguity.

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

Deploy Server

Other Tools