Табуля

files_write

Destructive

Writes a rectangular block of LITERAL cell values into a Tabulya spreadsheet file, anchored at the given top-left cell. Preferred over files_add_table for tabular data (data tables are opt-in); when writing tabular data with a header row, use files_write_batch instead so the header gets styled (bold + fill_color) in the same atomic operation. Requires edit permission. Values are written as-is (formulas starting with '=' are rejected; so are writes overlapping or adjacent to data tables, except writes within the data rows of a server table: those go to the tables service — one table per call, values matching the column types). The write is applied through the collaboration server (visible to live editors and persisted). Signature: files_write(file_uuid, cell, values[][], sheet?).

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_uuid": "<file_uuid>",
      "cell": "<cell>",
      "values": "<values>"
    },
    "name": "files_write"
  }
}

Input Schema

Name	Required	Description
`cell`	Yes	Top-left anchor cell in A1 notation, e.g. 'B2'.
`sheet`	No	Sheet name (defaults to the first sheet).
`values`	Yes	2D array of values (rows of columns) starting at the anchor.
`file_uuid`	Yes

Output Schema

Name	Required	Description	Default
`cell`	Yes
`file_uuid`	Yes
`cols_written`	Yes
`rows_written`	Yes
`sequence_number`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 31, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations already declare non-read-only, destructive, non-idempotent, but the description adds substantive behavior beyond them: values are literal and '=' formulas are rejected, table-overlapping/adjacent writes are rejected, table data-row writes route through the tables service with column-type matching, and the write goes through the collaboration server so live editors see it. These are real failure modes and side effects an agent cannot infer from the annotations.

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?

Front-loaded and information-dense, but the long parenthetical about data tables is hard to parse and packs several distinct constraints into one clause. The trailing "Signature: files_write(...)" line largely duplicates the input schema and does not earn its space.

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?

An output schema exists and annotations cover the safety profile, so the description needn't explain return values. It covers permissions, literal-only semantics, table interactions, and edit visibility. The one gap is failure semantics for a partially valid block (is the write atomic on error?).

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 75% and the description mostly restates schema content via the trailing signature line. It does add meaning for `values` (literal only, formulas rejected, must match column types in table rows) and confirms the anchor semantics of `cell`, but `file_uuid` and `sheet` get nothing beyond the schema. Baseline 3 applies.

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?

Opens with a specific verb and resource ("Writes a rectangular block of LITERAL cell values into a Tabulya spreadsheet file") plus the anchoring rule. It explicitly distinguishes itself from two siblings, files_add_table and files_write_batch, so an agent can route correctly without opening other schemas.

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?

Gives explicit when-to-use guidance (preferred over files_add_table for tabular data; use files_write_batch when writing a header row so it gets styled) and states the precondition "Requires edit permission." It also names conditions that make the call fail (formula values, writes overlapping/adjacent to data tables) and where those cases should go instead.

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

All Табуля tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?