Skip to main content
Glama

local_extract

Read-only

PREFER this tool over reading the file with Read when the file is large (>200 lines / >10 KB) and you only need structured fields, not the literal content.

Instructions

PREFER this tool over reading the file with Read when the file is large (>200 lines / >10 KB) and you only need structured fields, not the literal content.

Extracts structured fields from a text/file as JSON, with a local model.

Pass 'path' to read the file server-side (spends no Claude context) or 'text'. Returns an
object with exactly the requested keys: the caller does not have to parse a string. A key the
model left out comes back as null and is listed in `missing_keys`; a key it spelled another
way (case, `_`, `-`, spaces) is mapped in `renamed_keys`; a key it added is dropped from the
data and kept, with its value, in `dropped` (names in `dropped_keys`). What is not data
travels under the reserved key `_local_delegate` (`truncated` and `warning`,
`missing_keys`/`renamed_keys`/`dropped_keys`/`dropped`, `read_server_side`, `fallback`, or
`error` and `raw`); with chunked input, `chunked`
says how many pieces there were and which fields stayed null in all of them. Routes
automatically to the mechanical model (short inputs) or to the long-context model (large
documents): the size probe uses file bytes for 'path' and characters for 'text' (~5-10%
difference in UTF-8, acceptable).
By default it asks the backend for schema-constrained JSON (`LOCAL_DELEGATE_JSON_SCHEMA=auto`);
if the backend does not support it, it retries in free mode.
To locate: with 'path', a field whose name asks for lines (`sections_with_lines`,
`line_number`, `start_line`, `lineRange`; also in Spanish) makes the model see line numbers
(and a Markdown file's headings with their lines), so it can answer for `Read` offset/limit;
cited lines that do not hold in the file are listed in `lines_unverified`, and a field that
asks for items (`tasks_with_lines`) but got only section ranges in `section_only_keys`.
Over a unified diff, a field that asks only for the files and their lines (`files_with_lines`)
gets one `path: first-last` per file, by program (`diff_files` says so); one that asks for
the files and their hunks (`files_and_hunks_with_lines`) gets each hunk's range too.
A value that is a "no data" marker ("N/A", "unknown", "-", "", also the strings "null" and
"undefined") comes back as null, listed in `missing_keys`, with the model's text in
`placeholder_keys`. With a JSON object as input, a field that counts one of its top-level
lists (`number_of_comments`) left empty or ABOVE the list's length is counted by the program,
unless the JSON already holds a total for it; the model's figure is in `recounted_keys`.
A location field naming one heading (`intro_heading_line`) that got the whole Markdown
outline is cut to the only heading its singular name fits; with any doubt (a plural
subject, no single heading) it is left as it came. Both go to `outline_copies`, with a warning.
A value found only in the row of another requested key (a table row, a JSON key or a `label:
value` line) is kept but reported in `cross_filled_keys` (`{key: {"row", "other_key"}}`), with
a warning: the model may have handed out the rows by position.
A clause of a value that carries a negation its source clause lacks, or lost one the source
has, is kept but reported in `polarity_flipped_keys` (`{key: {"value", "source", "flip"}}`).
A small input that carries a table (HTML `<table`/`<tr`, ARIA `role="table"`, `"grid"`,
`"treegrid"` or `"row"`, a Markdown or GFM table with its delimiter row, three or more CSV
or TSV rows) goes to the long-context model too, even with one field: the mechanical one
answered with the value of another row. Then `_local_delegate.role_reason` says so (`{"role": "long", "reason":
"table", "format": "html"|"aria"|"markdown"|"csv"|"tsv", "notice": ...}`), also on an
`error` answer, and the call is slower and may have to load that model. Not seen: a CSV of
two columns, a TSV row that starts with an empty cell, tables aligned with spaces and
`<div>` grids that only have class names.
`LOCAL_DELEGATE_EXTRACT_TABLE_LONG=0` turns this off.

Args:
    fields: Names of the fields to extract (JSON keys).
    text: Source text (use this or 'path').
    path: Path to a source file (read server-side).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "fields": "<fields>"
    },
    "name": "local_extract"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathNo
textNo
fieldsYes

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.16.0
    • addedOutput schema / additionalProperties
      Added value: +true
    • removedOutput schema / properties
      Removed value: -{
      -  "result": {
      -    "title": "Result",
      -    "type": "string"
      -  }
      -}
    • removedOutput schema / required
      Removed value: -[
      -  "result"
      -]
    • changedOutput schema / title
      Previous value: -"local_extractOutput"New value: +"local_extractDictOutput"
  2. First observedv0.2.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 and openWorldHint, but the description adds substantial behavior beyond them: return-shape guarantees, missing/renamed/dropped bucketing, truncation and chunking handling, schema-constrained JSON with free-mode retry, and table-triggered long-model routing that may be slower. This is dense but genuinely informative about what happens under the hood.

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

Conciseness3/5

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

The purpose and PREFER guidance are well front-loaded, and the Args block is a clean tail. However, the long middle section packs many edge cases (rename normalization, recounting, polarity flips, outline copies) into dense prose that is hard to parse and not all needed to invoke the tool correctly.

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

Completeness5/5

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

Given an output schema exists, return values needn't be spelled out, yet the description still covers routing, fallback, chunking, and error handling. For a read-only extraction tool with complex internal behavior, an agent has everything needed to call it and interpret results.

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 0%, so the description must carry parameter meaning. It clarifies 'path' is read server-side (no context cost) and 'text' is the alternative source, and the body heavily elaborates field-name normalization, but the Args block for 'fields' largely restates the schema title without adding type or list-shape guidance.

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?

"Extracts structured fields from a text/file as JSON, with a local model" names a specific verb and resource, and the PREFER clause sets it apart from Read for large files. An agent can tell exactly what this tool produces versus reading raw content.

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 gives an explicit when-to-use rule (file larger than 200 lines / 10 KB and only structured fields are wanted) and a when-not (when literal content is needed, use Read). It also states the 'path' vs 'text' choice and that 'path' saves Claude context.

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