Skip to main content
Glama
JSungMin

vs-token-safer

by JSungMin
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

read_symbol

Extract a single function or class declaration from a file by name, returning only its source span instead of the entire file. Use signatureOnly to get just the declaration head, reducing token usage.

Instructions

USE INSTEAD OF Read on a file when you only need ONE function/class — returns just that named declaration's source (its span), not the whole file (the read twin of replace_symbol_body). signatureOnly = head only; body capped by VTS_SYMBOL_MAX_LINES.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
lineNo0-based line; disambiguate same-named (optional).
pathNoFile holding the symbol (else resolved via the index).
symbolYesDeclaration name to read.
backendNo
projectPathNo
signatureOnlyNoReturn just the declaration head.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.1.5
  2. Removedv1.1.2
  3. Changed5 schema fields changedv0.37.3
    • removedInput schema / properties / backend / description
      Removed value: -"Backend override; auto-detected."
    • changedInput schema / properties / path / description
      Previous value: -"File holding the symbol (pins the outline; else resolved via the index)."New value: +"File holding the symbol (else resolved via the index)."
    • removedInput schema / properties / projectPath / description
      Removed value: -"Project root (cwd)."
    • changedInput schema / properties / signatureOnly / description
      Previous value: -"Return just the declaration head (signature), not the full body."New value: +"Return just the declaration head."
    • changedInput schema / properties / symbol / description
      Previous value: -"Declaration name to read (function/class/method/…)."New value: +"Declaration name to read."
  4. Changed1 schema field changedv0.35.0
    • changedInput schema / properties / line / description
      Previous value: -"0-based line to disambiguate same-named symbols (optional)."New value: +"0-based line; disambiguate same-named (optional)."
  5. Addedv0.29.2

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations, the description carries the behavioral burden. It discloses that the result is just the named declaration's span, that signatureOnly returns the head only, and that the body is capped by VTS_SYMBOL_MAX_LINES. This is meaningful behavioral context beyond the tool name.

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 a single efficient sentence with the most important usage instruction front-loaded. Every clause adds value: when to use it, what it returns, how it differs from Read, the signatureOnly behavior, and the line cap.

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 simple read tool with no output schema, the description adequately explains the return value (named declaration source/span) and key behavior. However, it does not clarify the optional backend and projectPath parameters or error behavior, which are minor completeness gaps.

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 67%, and the description adds meaning only to signatureOnly ('head only'). The schema already explains line, path, and symbol, but backend and projectPath remain undocumented in both schema and description, leaving a gap in parameter understanding.

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 uses a specific verb and resource: 'read' a named symbol and return its source span, not the whole file. It also distinguishes itself from Read and positions itself as the read twin of replace_symbol_body, making its purpose unmistakable.

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 use this tool instead of Read: when only one function/class is needed. It also names the sibling twin replace_symbol_body, giving an agent clear routing guidance without needing to inspect other tool definitions.

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