Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@AdvancedCalc Engine Can you analyze my expenses.xlsx and give me a summary of trends?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Excel workbooks are the de-facto tool for ad-hoc analysis — and the hardest to automate safely. AdvancedCalc Engine is an agentic workflow system built on secure MCP tooling: it inspects a workbook, plans a calculation, executes it through whitelisted MCP tools, writes results back safely, and validates the outcome — with a full audit trail and a backup before every modification.
The workflow is deterministic: a task is decomposed into an Architect →
Engineer → Validator pipeline by rule-based code in app/workflow/, with
no LLM in the loop. A hardened MCP server exposes fifteen whitelisted
tools that the workflow executes. Safety is the product: path confinement,
formula sanitization, mandatory backups, and audit logging are enforced in
code, not by convention.
This is an end-to-end example of a deterministic agentic engineering pipeline: structured plan/execute/verify orchestration, typed tool contracts, defense-in-depth security, and automated verification. The current implementation requires no LLM; a future phase could add LLM-driven planning without changing the tool surface or the validation gates.
Related MCP server: Excel MCP Server
Fifteen whitelisted MCP tools over stdio — read-only metadata, calculation and analytics tools plus two guarded mutation tools and the agentic workflow runner.
Multi-agent architecture — four OpenCode subagents with strict separation of concerns (plan / execute / verify / audit), formalized as a deterministic in-process workflow with per-run correlation ids.
Safe Excel mutation — a timestamped backup is created before every write; the workbook is reopened and validated afterwards.
Security-first design — paths are confined to data/input, formulas
and cell references are sanitized, arbitrary code execution is impossible.
Audit trail — every operation, success or failure, is recorded as a
JSONL event with no secrets or workbook contents; workflow runs share a
single workflow_id across all their events.
Typed contracts — Pydantic request/response models for every tool.
Agentic workflow runner — a natural-language task is parsed into an
execution plan, executed, and independently validated without an LLM;
the same pipeline is exercised end to end by advanced-calc demo and by
the agent evaluation harness.
754-test suite with 98% coverage, plus a live MCP smoke test.
CLI (advanced-calc) for serving, smoke-testing, auditing,
validating, running the agentic demo, and evaluating the ML layer
(ml-eval) — CI runs on Linux and Windows with a 90% coverage gate.
┌────────────────────────────────────────────────────────────────┐
│ OpenCode agent orchestration │
│ │
│ Architect ──plan──▶ Engineer ──modify──▶ Validator │
│ │ │ │ │
│ └──────────────────┴─── audit events ────┴──▶ Audit log │
│ │
│ Security Auditor (reviews, never modifies) │
└──────────────────────────────┬─────────────────────────────────┘
│ MCP (stdio)
┌──────────────────────────────▼─────────────────────────────────┐
│ MCP server (app/mcp_server.py) │
│ read_excel_metadata rolling_average percentage_change │
│ rolling_volatility write_formulas validate_workbook │
│ summary_statistics correlation_matrix anomaly_detection │
│ linear_forecast ml_forecast ml_anomaly_detection │
│ data_quality_report write_output │
│ run_analysis_workflow (Architect → Engineer → Validator) │
└──────────────────────────────┬─────────────────────────────────┘
│
┌──────────────────────────────▼─────────────────────────────────┐
│ Application layer (app/tools) │
│ Calculation engine Excel metadata Formula writer │
│ Workbook validator │
└──────────────────────────────┬─────────────────────────────────┘
│
┌──────────────────────────────▼─────────────────────────────────┐
│ Core layer (app/core) │
│ security.py backup.py audit.py config.py │
└─────────────────────────────────────────────────────────────────┘The layering is strict: mcp_server.py contains transport logic only.
Excel business logic lives in app/tools, and every cross-cutting concern
(security, backups, audit, configuration) lives in app/core. Agents
never touch the filesystem directly — they only call MCP tools.
Agent | Role | Can modify? |
Architect | Understands the request, inspects workbook structure, produces an execution plan | No |
Engineer | Executes the approved plan through the MCP tools, verifies modifications | Approved cells only |
Validator | Independently verifies results and reports PASS/FAIL | No |
Security Auditor | Reviews the application for vulnerabilities and unsafe tool usage | No |
The workflow is enforced by agent definitions in .opencode/agents/ and
formalized as deterministic code in app/workflow/ (no LLM required):
Architect (app/workflow/architect.py) analyzes the workbook via
read_excel_metadata, parses the task with task_parser.py, and
produces a numbered execution plan plus a validation spec. It never
modifies anything.
Engineer (app/workflow/engineer.py) executes only whitelisted
plan steps through the MCP tool handlers (write steps use write_output
with automatic backup), and records every outcome.
Validator (app/workflow/validator.py) independently recomputes the
result — raw openpyxl cell reads and pure-Python math, sharing no code
path with the calculation engine — and reports PASS or FAIL without
ever modifying the workbook.
The orchestrator (app/workflow/orchestrator.py) runs the whole
pipeline, generates a per-run UUID workflow_id, and threads it through
every audit event of the run.
Every step is recorded in the audit log; the Security Auditor reviews the tool surface and configuration for risk.
Planning failures (unsupported or ambiguous tasks) raise structured
ACE_* errors; execution or validation failures are returned as a FAIL
response with the validator's reason.
The pipeline is fully deterministic today — planning, execution, and
validation are plain Python with no LLM in the loop. A future phase could
replace the rule-based planner with LLM-driven reasoning while keeping the
same whitelisted tool surface, structured ACE_* errors, and independent
validation gates.
The repository's AGENTS.md codifies the core rules: analyze before
modifying, never blindly modify a workbook, always back up before
destructive operations, validate after modification, never ignore errors,
and never execute arbitrary user code.
The MCP server (python -m app.mcp_server) exposes fifteen tools:
Tool | Description | Mutates? |
| Read workbook structure: sheets, columns, sample rows | No |
| Rolling mean of a column (configurable window, default 14) | No |
| Period-over-period percentage change of a column | No |
| Rolling standard deviation of percentage change | No |
| Write Excel formulas into a sheet; backup is created first | Yes |
| Validate sheet existence and expected cells | No |
| Count, missingness, mean, median, std, min/max, quartiles | No |
| Pearson correlation matrix of numeric columns | No |
| z-score or IQR anomaly detection on a column | No |
| Linear trend fit (numpy) plus future period forecasts | No |
| Seeded ML forecast with temporal holdout evaluation against persistence/mean/linear baselines | No |
| Seeded isolation-forest anomaly detection with optional injected-anomaly precision/recall/F1 evaluation | No |
| Per-column type, completeness, uniqueness, numeric stats | No |
| Write computed rows into | Yes |
| Run a task through the Architect → Engineer → Validator pipeline | No* |
* The workflow itself never mutates the source workbook; a task that asks
to write results produces a new file under data/output.
ml_forecast fits a seeded bagged-ridge forecaster on causal lag and
rolling features, splits the series temporally (train prefix, holdout
suffix), reports RMSE / MAE / MAPE / R² for the model and the
persistence, mean and linear baselines on the same holdout, and
recursively forecasts future periods. The seed, test fraction, minimum
points and row cap come from the ACE_ML_* settings; when fewer than
two supervised training rows survive feature warm-up it falls back
deterministically to the same linear trend fit used by
linear_forecast.
ml_anomaly_detection grows a seeded isolation forest (subsampled,
random-threshold isolation trees driven entirely by
numpy.random.default_rng(seed)) and flags the most isolated
contamination share of a column's values, ties broken by position so
the result is fully reproducible. With evaluate=true it injects known
far-outlier anomalies on an in-memory copy of the series, reruns the
detection, and reports precision, recall and F1 against the injected
labels — the workbook is never touched. The seed, minimum points and
row cap come from the ACE_ML_* settings; insufficient data raises a
structured ACE_CALCULATION error.
All inputs are validated through Pydantic request models; all outputs are
serialized through typed response models with explicit JSON-safe
conversion (NumPy scalars, timestamps, and non-finite floats). Failures
are returned as structured MCP errors carrying an ACE_* taxonomy code
(ACE_VALIDATION, ACE_SECURITY, ACE_NOT_FOUND, ACE_CALCULATION)
instead of raw exception strings.
ml-eval)advanced-calc ml-eval runs the complete read-only ML evaluation of a
workbook column in one command and prints the metrics tables:
advanced-calc ml-eval
# options: --file, --sheet, --column, --periods, --window, --seed,
# --output, --no-artifactIt reuses the exact same deterministic pipelines as the ml_forecast
and ml_anomaly_detection MCP tools (app/ml/harness.py): the seeded
bagged-ridge forecaster is evaluated on a temporal holdout (train prefix
/ test suffix, never shuffled) and compared against the persistence,
mean and linear baselines evaluated on the same holdout targets; the
seeded isolation forest injects known far outliers on an in-memory copy
of the series and reports precision, recall and F1 against them. A
reproducible JSON artifact (no timestamps, everything derived from the
seed) is written to data/output/ml_evaluation.json unless
--no-artifact is given, and the run is recorded in the audit log as an
ml_eval event.
data/input/sales_data.xlsx (seed 42)The demo workbook holds 60 daily sales rows (2026-01-01 → 2026-03-01,
first 12 rows preserved from the original sample, rows 13–60 a rising
sales trend). With the default configuration (ACE_ML_RANDOM_SEED=42,
ACE_ML_TEST_FRACTION=0.3, lags 1–3, rolling window 7, 25 bagged ridge
estimators) the evaluation splits into 35 training / 17 holdout rows:
Model | RMSE | MAE | MAPE % | R² |
ML model (bagged ridge) | 600.144635 | 559.906208 | 1.099238 | 0.987647 |
persistence | 1118.822911 | 1105.882353 | 2.230778 | 0.957067 |
mean | 28648.482558 | 28135.014006 | 55.684029 | -27.149278 |
linear | 13495.661774 | 13159.096333 | 25.941149 | -5.246725 |
Anomaly evaluation (isolation forest, n_estimators=100,
max_samples=256, contamination=0.1, 5 injected outliers): precision
0.833333, recall 1.000000, F1 0.909091 (6 points flagged, 5
of which are the injected outliers).
The first 12 rows repeat a flat pattern, so the mean and linear
baselines are badly wrong on the trend — while the ML model's causal lag
and rolling features track it with a 1.1% average error, roughly half
the persistence baseline's error. Every number above is fully
reproducible: the harness is deterministic for a fixed seed, and the
artifact contains the complete report (data/output/ml_evaluation.json).
Phase 10.5 evaluated whether fitted estimators should be persisted to
data/models/. It is not implemented: both estimators are fully
deterministic for a given seed and are re-fit on demand (a stored model
could never differ from a fresh fit), the system is stateless with no
cross-request model reuse or serving path, and reproducibility is
already guaranteed by the seed plus the audit trail. Skipping
serialization removes the entire unsafe-deserialization surface
(pickle/joblib object graphs, user-supplied model artifacts) without
losing anything — see SECURITY.md for the full rationale.
Security is enforced in app/core/security.py and applies to every tool:
Path confinement — every workbook path is resolved and must stay
inside the configured input_dir. .. traversal, drive-relative paths,
cross-drive paths, and UNC paths outside the root are rejected
(Windows-specific cases handled explicitly).
Formula sanitization — formulas must start with =, are length- and
control-character-checked, and may not contain DDE markers (|),
external workbook references ([), or functions that exfiltrate data or
execute commands (HYPERLINK, WEBSERVICE, IMPORT*, EXEC,
POWERSHELL, CALL, REGISTER, …).
Cell reference validation — references must match Excel bounds
(columns up to XFD, rows up to 1048576).
Whitelisted surface — only the fifteen tools above are registered; arbitrary Python execution is never exposed to agents or users.
Limits — formula length (512 chars) and cells per write (500) are configurable caps.
The repository's Security Auditor agent and SECURITY.md document the
threat model and reporting process.
Backups (app/core/backup.py)
write_formulas never touches a workbook without first creating a
timestamped copy in data/backups.
If any validation step fails before the backup, the workbook is never modified; a rejected write leaves no trace.
Audit log (app/core/audit.py)
Every operation — reads, calculations, writes, backups, validations —
is written to logs/audit.jsonl as a JSON line with timestamp, agent,
operation, status, file, sheet, and details.
Workflow runs carry a workflow_id on every event they produce, so a
single analysis can be traced end to end.
Failures are recorded together with their error message, then re-raised.
The log never contains secrets, environment variables, workbook contents, or cell values.
Inspect the trail with the CLI:
advanced-calc audit
advanced-calc audit --workflow <workflow_id>
advanced-calc statsRequirements: Python 3.11+ and uv.
git clone https://github.com/surajpanwar/advanced-calc-engine.git
cd advanced-calc-engine
uv sync --devThis creates the virtual environment, installs the package in editable
mode, and exposes the advanced-calc CLI.
Optional: copy .env.example to .env and adjust paths if you do not
want the defaults (directories inside the project root).
Place a workbook in data/input/ (a sample sales_data.xlsx with 60
daily rows is included).
Run the live MCP smoke test — it starts the server exactly as OpenCode does, lists the fifteen tools, and reads the sample workbook:
advanced-calc smokeStart the MCP server over stdio (used by any MCP client):
advanced-calc serve
# or
python -m app.mcp_serverRun the agentic workflow demo — the Architect parses the task, the Engineer computes and writes the 5-day rolling volatility, and the Validator independently checks the result:
advanced-calc demoThe demo prints the workflow trace, the generated workflow_id, and the
path of the output workbook in data/output/. Follow the trail with:
advanced-calc audit --workflow <workflow_id>Validate a workbook from the CLI (relative paths resolve against
data/input/):
advanced-calc validate sales_data.xlsx Sheet1 A1 B1Inspect the audit trail:
advanced-calc audit --tail 10
advanced-calc statsRun the ML evaluation harness against the demo workbook and regenerate the reproducible metrics artifact:
advanced-calc ml-evalThe command prints the forecast metrics table (RMSE / MAE / MAPE / R²
for the ML model and the persistence, mean and linear baselines), the
anomaly detection metrics (precision / recall / F1 against injected
outliers), and writes data/output/ml_evaluation.json — see
ML Evaluation Harness for the
measured results and methodology.
Watch the full pipeline run end to end, then replay the audit trail for that exact run:
advanced-calc demo
advanced-calc audit --workflow <WORKFLOW_ID>advanced-calc demo runs a live task through the Architect → Engineer →
Validator pipeline and prints the trace — the plan, each executed step,
and an independent PASS result with the generated workflow_id and output
workbook:
advanced-calc audit --workflow <WORKFLOW_ID> replays every event of that
single run — planning, calculations, writes, backups, validation — linked
by one shared workflow_id:
What the demo proves:
Deterministic agent orchestration — the same task always produces the same Architect → Engineer → Validator sequence, executed in code with no LLM in the loop.
Workflow_id correlation — one id threads through every audit event, so an entire run is traceable end to end.
Validation before completion — the run reports success only after the Validator independently recomputes and confirms the result.
Output workbook generation — the task produces a real workbook in
data/output/, written through the guarded, backup-first tools.
Auditable execution — every step, success or failure, is recorded in
logs/audit.jsonl for replay and inspection.
The workflow is fully deterministic today; optional LLM-driven planning on top of the same whitelisted tool surface is future work.
opencode.json registers the local MCP server with OpenCode:
{
"$schema": "https://opencode.ai/config.json",
"default_agent": "plan",
"mcp": {
"advanced-calc-engine": {
"type": "local",
"command": [".venv/Scripts/python.exe", "-m", "app.mcp_server"],
"cwd": ".",
"enabled": true
}
}
}The configuration is portable — it contains no machine-specific
paths. The command and cwd are resolved relative to the directory
where OpenCode is launched (the project root), so the only prerequisite
is the project virtual environment:
uv sync --dev must have been run (creates .venv/).
The bootstrap check is simply:
.venv/Scripts/python.exe -m app.mcp_server # Windows
.venv/bin/python -m app.mcp_server # macOS / LinuxIf your environment differs (different venv location, no venv, or
macOS/Linux), update the command array accordingly — e.g.
[".venv/bin/python", "-m", "app.mcp_server"] on Unix. The fifteen MCP
tools are then available to OpenCode agents exactly as before.
Note:
advanced-calc serveis equivalent to launchingpython -m app.mcp_server; use whichever you prefer.
The suite exercises every layer, from pure functions to a live MCP handshake:
uv run pytest --cov=app --cov-report=term-missing --cov-fail-under=90Coverage areas:
Security: path traversal, drive/UNC edge cases, formula and cell reference sanitization, rejected writes leave no trace.
Calculations: window validation, missing columns, numeric accuracy.
Backups: collision handling, restore fidelity, no backup on failure.
Audit: SUCCESS/FAIL events, error messages, no cell values in logs, workflow_id propagation.
MCP handlers: request validation, JSON-safe serialization, audited failures.
End-to-end: the full agent workflow including audit-trail assertions.
Agent evaluation: ten deterministic golden cases (tests/agent_eval/)
with known expected values, plus validator-independence tests that
sabotage plans and workbooks to prove the Validator catches mistakes.
ML evaluation: harness shape, determinism, guard propagation and
fallback behaviour (tests/test_ml_harness.py), and CLI wiring,
artifact writing, error handling and audit propagation for
ml-eval (tests/test_cli.py).
GitHub Actions (.github/workflows/ci.yml) runs on every push to main
and every pull request on both ubuntu-latest and windows-latest:
uv sync --dev — installs the project and dev toolchain.
pytest with coverage — 90% coverage gate (--cov-fail-under=90).
ruff check . — lint (app code; tests are excluded by config).
mypy app — static type checking.
The Linux job additionally exercises the symlink-related path security tests that skip on Windows.
advanced-calc-engine/
├── app/
│ ├── cli.py # Typer CLI: serve, smoke, audit, stats, validate, demo, ml-eval
│ ├── mcp_server.py # MCP transport; registers the 15 tools
│ ├── core/
│ │ ├── security.py # Path/formula/cell-reference validation
│ │ ├── backup.py # Mandatory pre-mutation backups
│ │ ├── audit.py # JSONL audit trail (+ workflow_id context)
│ │ ├── errors.py # ACE_* structured MCP error taxonomy
│ │ └── config.py # ACE_-prefixed settings (pydantic-settings)
│ ├── models/ # Pydantic request/response contracts
│ ├── ml/ # Deterministic ML layer (evaluation,
│ │ │ # features, forecast, anomaly detection,
│ │ │ # evaluation harness)
│ ├── workflow/ # Agentic orchestration (Phase 9.3)
│ │ ├── orchestrator.py # run_analysis_workflow runner
│ │ ├── architect.py # Plan builder (read-only)
│ │ ├── engineer.py # Whitelisted executor
│ │ ├── validator.py # Independent recomputation (PASS/FAIL)
│ │ ├── task_parser.py # Deterministic natural-language parsing
│ │ └── models.py # Plan/validation-spec models
│ └── tools/
│ ├── calculation_engine.py # Rolling average, % change, volatility
│ ├── analytics.py # Summary stats, correlation, anomalies, forecast, quality
│ ├── excel_metadata.py # Workbook structure reader
│ ├── formula_writer.py # Safe formula writes (backup first)
│ ├── output_writer.py # Safe output writes into data/output
│ └── workbook_validator.py # Sheet/cell validation
├── data/
│ ├── input/ # Workbooks the tools may access
│ ├── output/ # Computed outputs + ml_evaluation.json (gitignored)
│ └── backups/ # Pre-mutation backups (gitignored)
├── logs/ # audit.jsonl (gitignored)
├── tests/ # 754 tests + MCP smoke test
│ └── agent_eval/ # Golden cases + validator independence
├── .opencode/agents/ # Architect, Engineer, Validator, Security Auditor
├── .github/workflows/ci.yml # Linux + Windows CI
├── AGENTS.md # Agent rules and project conventions
├── pyproject.toml # Metadata, pinned deps, entry point, tool config
└── main.py # Thin entry point delegating to the CLIPhase 9.2 — Product / ML surface: summary statistics, correlation,
anomaly detection (z-score / IQR), linear forecasting, data quality
reports, output writing, structured ACE_* errors, overwrite guard
and post-write verification. (Implemented)
Phase 9.3 — Agentic orchestration: deterministic Architect →
Engineer → Validator workflow, per-run workflow_id correlation
across audit events, golden-case agent evaluation harness, and the
demo CLI. (Implemented)
Phase 9.4 — MCP extensions: MCP resources and prompts; optionally an LLM-driven planner on top of the deterministic workflow. (Planned)
Phase 9.5–9.7 — Hardening & delivery: property-based and fuzz testing, structured logging and metrics, Docker packaging and release automation. (Planned)
Phase 10.1–10.2 — ML evaluation layer: pure metrics, baselines,
temporal splits, leak-free features, and the seeded ml_forecast
pipeline with holdout evaluation. (Implemented)
Phase 10.3 — ML anomaly detection: seeded isolation-forest
ml_anomaly_detection with injected-anomaly precision/recall/F1
evaluation. (Implemented)
Phase 10.5 — ML evaluation harness: the advanced-calc ml-eval
CLI running the combined forecast + anomaly evaluation with a
reproducible metrics artifact; the model-persistence decision
(not implemented — see ML Evaluation Harness).
(Implemented)
Phase 10.4 / 10.6 / Phase 11 — ML extensions: clustering, classification and further validator/workflow integration. (Planned)
Detect anomalies in a column using z-score (|z| > threshold) or IQR (1.5 * IQR bounds) methods. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| column | Yes | ||
| method | No | zscore | |
| file_path | Yes | ||
| threshold | No | ||
| sheet_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It does state 'Read-only' and gives the exact detection rules (|z| > threshold and 1.5 * IQR bounds), which is useful. However, it does not mention input requirements such as numeric columns, how missing values are handled, or whether results are returned as indices/rows/values, though the output schema may cover some of this.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The core action and algorithm details are front-loaded, and the read-only note is placed efficiently at the end. Every sentence contributes information worth having.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core algorithm and the read-only nature, and an output schema exists to define return values. However, it lacks guidance on when to choose this tool over ml_anomaly_detection, and it does not mention necessary input preconditions like numeric column data. Some contextual gaps remain that an agent would need to resolve elsewhere.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for missing parameter documentation. It adds meaning for 'column', 'method', and 'threshold' by explaining how they are used in the algorithms. However, 'file_path' and 'sheet_name' are only present in the schema titles and receive no descriptive treatment, and the allowed values for 'method' are not enumerated beyond the two names in the text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Detect anomalies' and names the resource ('a column') plus the two concrete methods (z-score and IQR), so the tool's function is clear. It does not explicitly distinguish itself from the sibling ml_anomaly_detection, but the statistical method detail makes the intended scope reasonably evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a statistical anomaly-detection use case and notes that the operation is read-only, but it gives no explicit guidance on when to use this tool instead of ml_anomaly_detection, summary_statistics, or data_quality_report. An agent would have to infer the appropriate context from the method names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute the Pearson correlation matrix of numeric columns in a workbook sheet. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| columns | No | ||
| file_path | Yes | ||
| sheet_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description declares read-only behavior ('Read-only'), which is the only annotation available, but no annotations are provided. It adds clarity about the tool's non-destructive nature beyond the schema. However, it does not disclose details about handling non-numeric columns or missing values, which could be important behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, concise and front-loaded with the core purpose. The read-only note is efficiently appended. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 3 parameters, it is a moderately complex tool. The description covers the main purpose and the key input (numeric columns), and the output schema exists, so return values are handled. Missing details on edge cases (e.g., non-numeric columns) but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description mentions 'numeric columns' which gives some meaning to the 'columns' parameter. However, it does not add detail for file_path or sheet_name beyond their schema titles. The description partially compensates for lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Compute'), resource (Pearson correlation matrix), and scope (numeric columns in a workbook sheet). It distinguishes itself from siblings like summary_statistics or rolling_average, though not explicitly naming alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for correlation analysis but does not explicitly state when to use this over other statistical tools. There is no mention of when not to use it or how it differs from alternatives like summary_statistics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Produce a data quality report for a workbook sheet: per-column type, completeness, uniqueness and numeric stats. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| columns | No | ||
| file_path | Yes | ||
| sheet_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It does state 'Read-only', which is valuable safety-relevant information, but it does not mention details such as performance expectations, required permissions, or behavior with empty or large datasets. It adds some transparency beyond the schema but is not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It states the action, the target, the output contents, and the safety profile efficiently. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple interface and an output schema, so the description covers the main purpose and read-only nature. However, it lacks usage guidance and does not clarify the optional columns parameter, leaving part of the call semantics underspecified. This is adequate for a basic invocation but incomplete for confident optional-parameter usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only mentions 'per-column' and does not explain the optional 'columns' parameter or how it affects the report. The names file_path and sheet_name are self-explanatory, but the semantics of the optional columns list (filtering vs inclusion) remain ambiguous. The description fails to add meaning beyond the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Produce') and clearly identifies the resource ('data quality report for a workbook sheet') plus the report contents ('per-column type, completeness, uniqueness and numeric stats'). It is clear and actionable, though it does not explicitly distinguish itself from sibling tools such as summary_statistics or read_excel_metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like summary_statistics, validate_workbook, or read_excel_metadata. The description implies a read-only exploratory use case but does not state conditions, exclusions, or preferred tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fit a linear trend to a column with numpy and forecast future periods. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| column | Yes | ||
| periods | No | ||
| file_path | Yes | ||
| sheet_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It states 'Read-only', which is useful, but it does not mention assumptions (e.g., column must be numeric), handling of missing values, or potential errors. It also does not clarify what the output contains beyond 'forecast future periods'. This is insufficient for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundancy or fluff, and the core action is front-loaded. It is concise and to the point. However, it might be slightly too terse given the missing parameter details, but as a concise statement it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters (3 required), no schema descriptions, no annotations, and an output schema that presumably describes returns. Despite this, the description fails to explain the file/sheet context, the meaning of 'periods', or any constraints. It is far from complete for an agent to correctly invoke the tool with the right arguments and expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning property names are the only clue. The description only vaguely references 'a column' and 'future periods', which maps to 'column' and 'periods', but it gives no explanation for 'file_path' or 'sheet_name', nor does it clarify the format or type of the 'column' parameter. The description does not compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Fit a linear trend') and resource ('a column'), and specifies the action ('forecast future periods'). It distinguishes itself from siblings like 'ml_forecast' by explicitly naming the linear approach. The 'Read-only' note adds an important trait. This is a clear, distinct purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'ml_forecast' or 'rolling_average'. It does not mention any exclusions or conditions under which a different tool would be preferable. The only implicit hint is 'linear', but no explicit comparison or selection criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detect anomalies in a column with a seeded machine-learning isolation forest: flags the most isolated points under a contamination rate. Optionally injects known anomalies on an in-memory copy and reports precision, recall and F1. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | ||
| column | Yes | ||
| evaluate | No | ||
| file_path | Yes | ||
| n_injected | No | ||
| sheet_name | Yes | ||
| max_samples | No | ||
| n_estimators | No | ||
| contamination | No | ||
| injection_amplitude | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description itself must disclose side effects; it states 'Read-only' and clarifies that known anomalies are injected only 'on an in-memory copy', so the agent can safely infer no persistent write occurs. It also surfaces the seeded nature and evaluation metrics, which are meaningful behavioral details beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with the primary behavior first, optional evaluation second, and a final 'Read-only' safety marker. Every sentence earns its place and there is no redundant restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core algorithm, evaluation option, and safety profile, and an output schema exists, so return values need not be described. However, with 10 parameters and no annotations, several parameters remain semantically opaque and there is no guidance on when to use this ML tool versus the plain anomaly_detection sibling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description explains only a subset of parameters: 'seeded' covers seed, 'contamination rate' covers contamination, and 'injects known anomalies... reports precision, recall and F1' covers evaluate/n_injected/injection_amplitude. Parameters like max_samples and n_estimators are left unexplained, so the description does not adequately compensate for the missing schema semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action, 'Detect anomalies in a column', and names the exact algorithm ('seeded machine-learning isolation forest') and criterion ('contamination rate'). It also distinguishes itself from the simpler sibling 'anomaly_detection' by adding seeding and optional evaluation behavior, so an agent can identify this as the ML variant without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies ML isolation-forest usage and an evaluation mode, but it never states when to choose this tool over the sibling 'anomaly_detection' or other alternatives. There is no when-not-to-use guidance or explicit exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fit a seeded machine-learning forecaster (bagged ridge on causal lag and rolling features), evaluate it on a temporal holdout against persistence/mean/linear baselines with RMSE/MAE/MAPE/R², and forecast future periods. Falls back to the deterministic linear forecast when supervised training is not viable. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| lags | No | ||
| seed | No | ||
| alpha | No | ||
| column | Yes | ||
| window | No | ||
| horizon | No | ||
| periods | No | ||
| file_path | Yes | ||
| sheet_name | Yes | ||
| n_estimators | No | ||
| test_fraction | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses 'Read-only' (a key behavioral trait), mentions the fallback behavior, and states that evaluation against baselines occurs. It does not cover potential side effects, data format requirements, or performance implications, but the core behavioral traits are addressed. Given the lack of annotations, this is a strong disclosure, though not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, and no extraneous content. The read-only note is at the end but still present. Every sentence earns its place; this is an example of efficient writing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (11 parameters, ML algorithm, evaluation), the description is too brief. It omits parameter semantics entirely and does not mention prerequisites like data format or time series requirements. The output schema covers return values, but the missing parameter explanations and lack of guidance on data preparation make it incomplete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it fails to explain any of the 11 parameters. The description mentions 'causal lag and rolling features' which hints at lags and window, but does not explicitly map them to parameter names or provide meaning for alpha, test_fraction, n_estimators, or other fields. An agent cannot infer parameter usage from the description, making this a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('fit... evaluate... forecast') on a time series resource, names the algorithm (bagged ridge on causal lag and rolling features), and differentiates from siblings by mentioning the fallback to linear forecasting. An agent can clearly distinguish this from linear_forecast and other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: this is for machine-learning-based forecasting with evaluation and a fallback to linear when training is not viable. However, it does not explicitly state when to prefer this over linear_forecast or other alternatives, only that it falls back to linear under certain conditions. No explicit exclusions are given, so it earns a 4 for clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the percentage change of a column in a workbook sheet.
| Name | Required | Description | Default |
|---|---|---|---|
| column | Yes | ||
| file_path | Yes | ||
| sheet_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'calculate' and does not reveal whether the tool is read-only, how missing values are handled, whether it adds a column, or what the output structure is. The output schema exists, but the description itself adds little behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler words. It is as concise as possible while conveying the core action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and 0% schema coverage, the description is too thin. It leaves unclear what 'percentage change' means operationally (e.g., over rows, between values), when to choose it over siblings, and what side effects or output to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only loosely maps to the parameters via 'column', 'sheet', and 'workbook'. It does not explain file_path format, sheet_name expectations, or how column is referenced, so it fails to compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Calculate') and resource ('column in a workbook sheet'), making the core purpose clear. It does not explicitly differentiate from sibling tools like summary_statistics or rolling_average, but the operation itself is distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as rolling_average or summary_statistics. There are no exclusions, prerequisites, or context signals about when percentage_change is the appropriate choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the structure of an Excel workbook: sheets, columns and sample rows. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explicitly states 'Read-only', which is a key non-mutation guarantee, and it specifies the limited data scope ('sample rows') rather than implying a full data read. It does not mention edge cases like missing files or permission requirements, but for a simple metadata reader the provided behavioral details are adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action and includes the most important outputs. Every phrase earns its place, and there is no redundant or promotional language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is functionally complete for a simple metadata reader: it states the input type, the operation, and the key outputs, and an output schema exists to carry return-value details. It does not explicitly mention supported file formats or handling of invalid paths, but these are minor gaps given the tool's simplicity and the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% parameter description coverage, so the description needed to compensate. It does not explicitly describe 'file_path', but the parameter name is self-explanatory and the description's reference to 'Excel workbook' implies the path target. This is minimally sufficient but not enriched beyond what an agent would assume.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read'), a clear resource ('Excel workbook'), and the exact scope of what is returned ('sheets, columns and sample rows'). This clearly distinguishes it from sibling analysis and writing tools, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Read-only' qualifier provides clear context that this tool is for inspection, not modification, and the mention of 'structure' implies it is for understanding the workbook layout before analysis. It does not explicitly name alternatives, but the sibling tool names (rolling_average, write_formulas, etc.) make the use case clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the rolling average of a column in a workbook sheet.
| Name | Required | Description | Default |
|---|---|---|---|
| column | Yes | ||
| window | No | ||
| file_path | Yes | ||
| sheet_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'calculate,' which implies a read operation, but it does not state whether the tool writes to the sheet, returns a value, or handles edge cases like missing data or invalid windows. This ambiguity is notable given sibling tools like write_formulas and write_output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff or redundant wording. It is concise and easy to parse, though it sacrifices important detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has four parameters, no annotations, and no parameter documentation, yet the description leaves out window semantics, output behavior, and selection guidance among several closely related sibling tools. While an output schema exists, the description alone is not enough for an agent to understand when and how to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It mentions 'column' and 'sheet' but does not explain the meaning of 'window,' the role of 'file_path,' or the default behavior. The parameter names are somewhat self-explanatory, but the description adds little semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('calculate') and the resource ('rolling average of a column in a workbook sheet'). It is specific enough to be understood, though it does not explicitly differentiate itself from the sibling rolling_volatility or summary_statistics tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as rolling_volatility or summary_statistics. No exclusions, prerequisites, or selection criteria are provided, so an agent must infer the appropriate context from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the rolling volatility (standard deviation of percentage change) of a column in a workbook sheet.
| Name | Required | Description | Default |
|---|---|---|---|
| column | Yes | ||
| window | No | ||
| file_path | Yes | ||
| sheet_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the calculation method (std dev of percentage change) but does not state whether the window is trailing/centered, how missing values are handled, whether the result is added as a new column or returned, or whether the operation modifies the workbook. These are material behavioral gaps for a calculation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the core purpose and formula. It is concise and readable, though it could add a brief usage note without becoming bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters, no annotations, and an output schema, but the description does not explain the return value, the window behavior, or data requirements. For a calculation tool with no annotation coverage, an agent needs more context to invoke it correctly and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains 'column' and 'window' implicitly via the formula, but it does not clarify the meaning of 'window' (e.g., number of periods), the expected format of file_path, or the role of sheet_name. The description adds only minimal meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Calculate') and resource ('rolling volatility ... of a column in a workbook sheet'), and the formula is clarified as standard deviation of percentage change. It is distinguishable from siblings like rolling_average and percentage_change, though it does not explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus rolling_average, percentage_change, or summary_statistics. The description implies a financial/time-series context but does not state prerequisites, such as needing a date column or sorted data, nor when an alternative would be preferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute the full Architect -> Engineer -> Validator workflow for a natural-language analysis task. Generates a workflow_id, plans the analysis, executes it through the other tools, writes results into data/output when the task asks for it, independently validates the outcome, and returns a structured report. Never modifies source data.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | ||
| file_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It does well: it discloses side effects (writes results into data/output when requested), safety behavior (never modifies source data), internal steps (generates workflow_id, plans, executes, validates), and return behavior (structured report).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly written sentences with no filler. The main action is front-loaded, followed by concrete behavioral details and a safety guarantee. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description need not detail the report format. It covers the workflow stages, side effects, validation behavior, and data-safety promise. The only notable completeness gap is the ambiguous meaning of file_path and the lack of explicit guidance on when to prefer this workflow over individual sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies 'task' as a natural-language analysis task, but 'file_path' is left completely unexplained in both the schema and the description. An agent cannot tell from the description whether file_path is an input path, output path, or something else.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Execute the full Architect -> Engineer -> Validator workflow') and clearly differentiates itself from granular sibling tools by presenting itself as the end-to-end orchestrator. The description makes it obvious this is not a single analysis utility but a workflow runner.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes clear context for use: it is for natural-language analysis tasks that should be planned, executed, validated, and reported as a full workflow. It does not explicitly state when-not-to-use or name alternatives, but the distinction from simpler siblings is strongly implied by the workflow framing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute summary statistics (count, missing, mean, median, standard deviation, min, max, quartiles) for a column in a workbook sheet. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| column | Yes | ||
| file_path | Yes | ||
| sheet_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses that the operation is read-only, which is a key behavioral trait. However, it does not mention edge cases like what happens if the column contains non-numeric data, or whether missing values are handled, or if there are any prerequisites like the sheet existing. For a simple read-only tool, the read-only disclosure is a positive, but more context on expected behavior would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It front-loads the purpose, lists the computed statistics, and adds the read-only qualifier. Every phrase earns its place, and the structure is clear and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description does not need to explain return values. The tool is simple with three self-explanatory parameters. The description covers the core action and safety (read-only), which is sufficient for an agent to invoke it correctly. Minor gaps like handling of non-numeric columns are not critical for a basic summary statistics tool and are not essential for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero description coverage, so the description must compensate. It mentions 'for a column in a workbook sheet,' which maps to the three parameters (file_path, sheet_name, column) and gives a sense of their roles. However, it does not explicitly explain that file_path is a path string, sheet_name is a sheet name, and column is a column identifier. The names are self-explanatory, but the description could be more explicit about the expected format or any constraints (e.g., column must be numeric). It provides minimal added value beyond the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool computes summary statistics for a column in a workbook sheet, and lists the specific statistics (count, missing, mean, median, standard deviation, min, max, quartiles). The verb 'Compute' and resource 'summary statistics for a column' are specific and distinct from siblings like rolling_average or correlation_matrix. The read-only note further distinguishes it as a non-mutating analysis tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or alternatives. It only says 'Read-only,' which is a safety hint but not usage guidance. Without comparisons to siblings like data_quality_report or rolling_average, the agent has to infer when this is the right choice based on the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a workbook sheet: existence of the sheet and of the expected cells. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| sheet_name | Yes | ||
| expected_cells | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly discloses that the tool is read-only, which is the key behavioral trait. It also clearly states what it checks (sheet existence and expected cell existence), giving the agent a concrete behavioral model. No annotations are present, so the description carries the burden; it does so reasonably well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. It front-loads the purpose and adds the read-only trait as a compact second sentence. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to explain return values. It covers the tool's purpose, core inputs, and its read-only nature, which is enough for an agent to invoke it. It falls short only by not placing the tool in the broader workflow context or clarifying the expected_cells format, but those are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has almost no descriptions (only titles/types), so the description must compensate. It adds meaning by explaining that sheet_name and expected_cells are checked for existence, but it does not define the expected cell format (e.g., 'A1', 'B2'). This leaves ambiguity about how to pass expected_cells.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Validate') and the resource ('a workbook sheet') and immediately defines the scope: existence of the sheet and of expected cells. This clearly distinguishes it from siblings like read_excel_metadata or data_quality_report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention, for example, that data_quality_report should be used for value-level checks or that read_excel_metadata is for metadata. The read-only hint suggests a pre-flight check, but this is not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write Excel formulas into a workbook sheet. A backup of the workbook is created before any change. Mutating operation.
| Name | Required | Description | Default |
|---|---|---|---|
| updates | Yes | ||
| file_path | Yes | ||
| sheet_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It does disclose two important traits: a backup is created before change and the operation is mutating. It does not, however, describe overwrite behavior, backup location/recovery, or what happens to existing formulas in targeted cells.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two sentences plus a short mutation tag. The primary action is front-loaded, the backup behavior is included, and there is no redundant fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with a nested parameter object, no annotations, and 0% schema descriptions, the description is incompleted. It omits how updates maps to cells and formulas, whether existing content is overwritten, backup details, and prerequisite conditions despite an output schema being present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds no parameter-level meaning. 'Updatates' is left ambiguous; the description does not clarify that keys likely represent cell references and values formula strings, nor does it explain file_path and sheet_name beyond their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Write') and resource ('Excel formulas into a workbook sheet'), making the tool's core action immediately clear. This also distinguishes it from sibling read-analysis tools like read_excel_metadata and from write_output, which is not specifically about formulas in a sheet.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for writing formulas into a workbook sheet and marks the operation as mutating, which clues the agent to avoid it for read-only needs. However, it does not explicitly state when to use this tool versus alternatives such as write_output or the analysis siblings, nor does it list exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write computed output rows into a workbook in the output directory. A backup is created before an existing file is overwritten. Mutating operation.
| Name | Required | Description | Default |
|---|---|---|---|
| rows | Yes | ||
| file_path | Yes | ||
| sheet_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It discloses the mutating nature ('Mutating operation') and backup creation before overwrite, which is valuable. However, it omits details like error handling, whether the workbook must already exist, or what happens to existing sheets. It covers the core mutation safety but not full behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero filler. The purpose is front-loaded, the backup behavior is stated second, and the mutating nature is called out. Every sentence adds value, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating operation with no annotations and a 0% schema coverage, the description is under-specified. It doesn't mention prerequisites (e.g., file existence, sheet creation), error scenarios, or the structure of the output. While an output schema exists, its content isn't visible, so the description should cover more. The short text leaves an agent guessing about expected inputs and edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% – the schema provides no descriptions for the three parameters. The description adds minimal meaning: 'output directory' hints at file_path, but rows and sheet_name are left unexplained. It doesn't compensate for the lack of parameter documentation, making it hard for an agent to know the expected format or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Write computed output rows into a workbook') and the resource (workbook in output directory). It distinguishes from siblings like write_formulas by specifying 'computed output rows', though it doesn't explicitly name alternatives. The purpose is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (writing output rows) but provides no explicit when-to-use or when-not-to-use guidance. It doesn't mention alternatives or conditions like 'use write_formulas for formulas instead'. The context is clear but lacks exclusions or routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.6.0anomaly_detectioncorrelation_matrixdata_quality_reportlinear_forecastml_anomaly_detectionml_forecastpercentage_changeread_excel_metadatarolling_averagerolling_volatilityrun_analysis_workflowsummary_statisticsvalidate_workbookwrite_formulaswrite_outputScored across 15 tools
Most tools target distinct operations, but pairs like anomaly_detection/ml_anomaly_detection and linear_forecast/ml_forecast could be confused at a glance. Detailed descriptions clarify the statistical vs. machine-learning distinction, and other tools have clear boundaries.
Names mix verb-first tools (read_excel_metadata, write_formulas, run_analysis_workflow) with descriptive noun phrases (rolling_average, percentage_change, correlation_matrix). The consistent snake_case and lowercase style keep them readable, but the lack of a uniform verb_noun pattern is a minor inconsistency.
15 tools is well-scoped for an advanced calculation engine. Each tool covers a distinct analysis, mutation, or validation capability without unnecessary bloat or obvious redundancy.
The server provides broad coverage: metadata reading, summary statistics, correlations, anomalies, forecasting, data quality, output writing, and a workflow orchestrator. Minor gaps like an explicit full-data read tool are not critical because analysis tools operate on columns directly.
Structured financial modeling for AI agents: build, version, audit models, export to Excel.
Formula-backed WorkPaper tools for workbook readback, input edits, and JSON persistence.
Open, inspect, filter, edit and convert xlsx and csv files from your AI chat. Processing is local.
Open, inspect, filter, edit and convert xlsx and csv files from your AI chat. Processing is local.
