Layerz

Parse uploaded file

layerz_parse_file

Read-onlyIdempotent

Parses an uploaded Excel/CSV (file_id) deterministically and returns a token-optimized structure: sheet summaries (without sheet_name) or, for one sheet, the detected timeline, suggested_structure (layout, header row, columns), row labels and column headers with samples. A wide sheet is recognised by its period header: a run of at least three consecutive periods (bare years such as 2026, YYYY-MM, Jan 2026, Q1 2026, date cells) in any column, reported as detected_periods and period_range. A raw DATEV EXTF export and a French FEC (compact YYYYMMDD dates) are detected natively; on any columnar ledger a journal column of short codes is mapped as category_column, and its opening journal (AN, RAN, ANO, AD, or a journal labelled "à nouveau") is read as opening entries (opening_rows; prior-year rows moved into the first month) — remap or ignore that column to change it. structure_override re-parses with corrected columns when a ledger is misdetected (a Débit column taken as the value, an account-code column taken as the label) or when a wide sheet has fewer than three period columns (layout: "wide"). Without sheet_name, a model workbook (formulas under period headers) also returns workbook (how far the Excel engine recalculates it, its scenario selectors with their scenarios, its data tables) and guidance. The raw binary is not returned.

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": {
      "file_id": "<file_id>"
    },
    "name": "layerz_parse_file"
  }
}

Input Schema

Name	Required	Description
`file_id`	Yes	Upload id as returned by layerz_create_upload_url ('f_' + 16 hex chars).
`sheet_name`	No	Sheet of a multi-sheet workbook. Omitted: sheet summaries only.
`structure_override`	No	Override auto-detected columns for a long-format/ledger file (e.g. value_column chose "Débit" and dropped credit rows, or an account-code column won the label). Omitted fields stay auto-detected.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 3, 2026

addedInput schema / properties / structure_override / properties / category_column / description

Added value: +"Category or journal-code column. An opening journal in it (AN, RAN, ANO, AD, or a journal labelled \"à nouveau\") is read as opening entries; remap or ignore this column to change that."

Changed3 schema fields changedSep 30, 2026

changedInput schema / properties / file_id / description

Previous value: -"Upload identifier returned by layerz_create_upload_url (format: 'f_' + 16 hex chars)."New value: +"Upload id as returned by layerz_create_upload_url ('f_' + 16 hex chars)."

changedInput schema / properties / sheet_name / description

Previous value: -"Target sheet name for multi-sheet workbooks. Omit to get sheet summaries."New value: +"Sheet of a multi-sheet workbook. Omitted: sheet summaries only."

changedInput schema / properties / structure_override / properties / header_row_index / description

Previous value: -"0-based header row. Omitted: re-detected for the requested `layout` (a columnar override never inherits the wide-layout period-row guess); the row used is reported back (`file_structure` on layerz_import_branch, `suggested_structure` on layerz_parse_file)."New value: +"0-based header row. Omitted: re-detected for the requested `layout` (a columnar override is re-detected rather than inheriting the wide-layout period-row guess); the row used is reported back (`file_structure` on layerz_import_branch, `suggested_structure` on layerz_parse_file)."

Changed1 schema field changedSep 26, 2026

addedInput schema / properties / structure_override / properties / header_row_index / description

Added value: +"0-based header row. Omitted: re-detected for the requested `layout` (a columnar override never inherits the wide-layout period-row guess); the row used is reported back (`file_structure` on layerz_import_branch, `suggested_structure` on layerz_parse_file)."

First observedSep 17, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, and the description adds real behavior beyond them: determinism, that the raw binary is not returned, that a model workbook also returns `workbook` and `guidance`, and that the opening-journal mapping can be changed by remapping or ignoring the column. It does not disclose any operational limits (file size, timeout, cost on large workbooks), which is the remaining gap for a parsing tool.

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 lead sentence is correctly front-loaded with the verb and the return shape, but the body is a single dense block with deeply nested parentheses and em-dash asides that are hard to scan. Detail on period-header runs, opening-journal codes and prior-year row handling is useful but could be split or trimmed; several clauses do not earn their place in a first-read pass.

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?

With no output schema and a nested `structure_override` object, the description carries the full burden of explaining return values, and it does: sheet summaries, timeline, `suggested_structure`, `detected_periods`, `period_range`, `opening_rows`, `workbook`, `guidance`. Nothing an agent needs in order to call this correctly appears to be missing.

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 100%, so the baseline is 3, but the description adds meaning the schema does not: when to reach for `structure_override` at all, that omitted override fields stay auto-detected, and that a columnar override re-detects the header row rather than inheriting the wide-layout guess. The remaining detection heuristics (period runs, DATEV/FEC) describe the tool's inference rather than the parameters, so it does not reach a 5.

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 opens with a specific verb+resource ("Parses an uploaded Excel/CSV (`file_id`) deterministically") and immediately enumerates the returned structure, so an agent knows exactly what the tool produces. It also names the distinguishing scope versus layerz_import_branch by referencing `file_structure` on that sibling, so the two are not confusable.

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

Usage Guidelines4/5

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

Usage is clearly implied and conditioned: omitting `sheet_name` yields summaries, supplying it yields one sheet's timeline and `suggested_structure`, and `structure_override` is prescribed for specific misdetection cases (Débit taken as value, account-code taken as label, wide sheet with fewer than three period columns). What is missing is an explicit when-not or a direct statement of the alternative path (e.g. going straight to layerz_import_branch), so it stops short of full routing guidance.

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

All Layerz tools Inspect

Try in Browser

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?