Skip to main content
Glama
Sign In
basis1: Excel engine for AI agents (formulas, recalculation, audit)

basis1: Excel engine for AI agents (formulas, recalculation, audit)

Official
by basis1tech
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Create session

create_session

Open an Excel workbook in a session for reading, editing, recalculating, and exporting by path, base64, URL, Library file, or blank start.

Instructions

Open a workbook in a session that the other workbook tools then use by session_id: the starting point for reading, editing, recalculating and exporting a model. Pass at most one of path, base64 (raw .xlsx bytes) or url, or none for a blank workbook (the only kind add_sheet can extend). The workbook is recalculated on load, including formulas written by other tools without cached values, so opening a file you edited elsewhere is how you read back what its formulas compute (get_outputs, get_formula_range); change inputs with set_inputs. Returns {session_id, document_id, library_file_id, sheets: [{index, name}], defined_names, calc}. For a one-off recalculation of a file, use recalc_workbook instead; to try a formula without a file, use evaluate_formula. The workbook is uploaded to the Basis API and held there for the session. Pass library_file_id instead to open a file from your Library. Each API key can hold 5 open sessions, and a session closes on its own after 30 minutes without a call. A sixth create_session fails with max_sessions and lists the open sessions; close one first. save_to_library keeps the workbook beyond the session.

Input Schema

NameRequiredDescriptionDefault
urlNoPublic https URL to fetch the .xlsx file from (private and local addresses are refused)
calcNoIterative-calculation settings for circular models
pathNoLocal filesystem path to an .xlsx file
base64NoBase64-encoded .xlsx file bytes
document_idNoDisplay label for this session
library_file_idNoID of a Library file to open (library_file_id from save_to_library or an earlier session)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.3.2
    • changedInput schema / properties / library_file_id / description
      Previous value: -"Library file ID to load"New value: +"ID of a Library file to open (library_file_id from save_to_library or an earlier session)"
    • changedInput schema / properties / url / description
      Previous value: -"URL to fetch the .xlsx file from"New value: +"Public https URL to fetch the .xlsx file from (private and local addresses are refused)"
  2. First observedv0.3.1

TDQS

A4.8/5.0
Behavior5/5

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

With annotations only declaring readOnlyHint=false, openWorldHint=true and idempotentHint=false, the description adds substantial operational context: the workbook is uploaded to the Basis API and held server-side, recalculated on load including uncached formulas, capped at 5 open sessions per key, auto-closed after 30 idle minutes, and the sixth call fails with max_sessions. It even names the recovery path (close one first) and the durability escape hatch (save_to_library).

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

Conciseness4/5

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

Dense but front-loaded: the core purpose is in sentence one, return shape in the middle, and limits/alternatives at the end. Every clause carries operational meaning, though the paragraph is long enough that an agent must parse several distinct rules packed together.

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?

For a 6-parameter tool with a nested calc object and no output schema, the description covers input selection rules, return shape, load-time recalculation behavior, resource limits, and session lifetime. Nothing an agent needs in order to call it correctly is 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; the description earns above that by stating the mutual-exclusivity rule ('at most one of path, base64 or url, or none'), which the schema cannot express, and by noting that library_file_id is an alternative open path. It stops short of explaining the calc object's iterative settings, leaving that to the schema.

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 concrete verb and resource ('Open a workbook in a session') and immediately explains the downstream role of the returned session_id ('the starting point for reading, editing, recalculating and exporting'). It explicitly distinguishes itself from recalc_workbook and evaluate_formula, so an agent can route without opening 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 (

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