Skip to main content
Glama

Jev locate in file

jev_locate_in_file
Read-only

Locate the line range in one large file that serves a stated goal, so you can inspect only the relevant section instead of reading the entire file.

Instructions

Find which line range of ONE big file (over 19 KB) serves a goal, instead of reading it whole; known string or symbol -> your text search tool. Use for: a file too big to read whole (over 19 KB) when you know what you need from it ("where are retries scheduled", "the part that parses flags") and finding a range can focus the next inspection. Not for: an exact string or symbol → your text search tool. Files under 19 KB → read them directly. Several files → jev_ask_files or jev_find_files.

How Jev sees it: the file cut into declarations or sections, all glanced at once. Neighboring sections can share an answer (a getter and its setter), splitting the mass into unsure even when both are right: that still points at the right neighborhood. It reads what is written, not what a function does at run time.

path: one repo-relative file. goal: what you need from the file, as a sentence.

Result: the range as path:start-end with its label and probability, the runners-up, and a read: list naming the range to open. A leading probability at or above 0.7 is a verdict: read that range. Otherwise the line is unsure (two sections share the mass): read both ranges — usually neighbors, not the next section of the file. A none (no section fits) means the goal is probably not in this file: search elsewhere. Missing required answers or controls remain unjudged, without an invented probability. Typed diagnostics name parsing/window limits and native actions; primary and control provenance remain distinct. Marks are defined once in the reading guide.

The decision to call is discretionary: Use Jev for a bounded semantic judgment when its answer could change an open decision or focus the next inspection, and the relevant evidence is available. Use decisive reading, search or authorized execution directly when it settles the question. Exact lookup, counting and runtime causality belong to native tools. A Jev call is not a prerequisite for a conclusion, a review or task completion; no explanation is needed for choosing native tools.

After an unavailable, refused or out-of-scope result, continue natively within the existing permissions; do not widen sharing or confinement to obtain a judgment. For uncertainty or missing evidence, inspect or obtain the decisive piece, or leave the conclusion open. Revisit Jev only when new evidence, a material context change or a new useful question makes the judgment useful; rewording unchanged evidence is not a reason to retry. There is no retry quota for genuinely changed evidence, and no certification is needed once decisive evidence settles the question. A reached cap or an unjudged result is not evidence of safety or zero affected tests.

Input Schema

NameRequiredDescriptionDefault
goalYes
pathYes
rootNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.4.0

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already declare readOnly/openWorld/non-idempotent/non-destructive, but the description adds substantial context beyond them: how the file is segmented, neighbor-section ambiguity ('shared mass'), the 0.7 probability verdict, what `none`/unjudged results mean, and typed diagnostics. This is rich disclosure of non-obvious behavior.

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

Conciseness2/5

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

The opening 'Use for'/'Not for' block is well front-loaded, but the description balloons into long generic policy paragraphs about retry quotas, certification, and permissions that don't help invoke this specific tool. Much of that text does not earn its place and dilutes the actionable signal.

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?

Even though an output schema exists, the description helpfully explains result semantics (verdict threshold, runners-up, `read:` list), and it covers usage and ambiguity handling thoroughly. Only the undocumented `root` parameter and the verbosity keep it from a 5.

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%, so the description must carry parameter meaning, and it does for the two required params: path is 'one repo-relative file' and goal is 'what you need from the file, as a sentence'. The optional 'root' parameter is left completely undescribed, a clear but minor gap.

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 and resource with scope: 'Find which line range of ONE big file (over 19 KB) serves a goal'. It also explicitly distinguishes itself from text search, jev_ask_files, and jev_find_files, so an agent can tell it apart from siblings without opening a 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?

Provides explicit 'Use for' and 'Not for' routing: big file + known goal → here; exact string/symbol → text search; files under 19 KB → read directly; several files → jev_ask_files/jev_find_files. The alternatives and thresholds (19 KB) make the when-to-use decision unambiguous.

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