Skip to main content
Glama

write_project_files

Create or edit a project's complete source tree, including nerdit.toml, in one all-or-nothing batch so services and configuration deploy from a single workspace.

Instructions

Write a project's source tree (its nerdit.toml included), then apply_project.

    Exactly ``write_app_files`` on the workspace named after the project:
    same all-or-nothing batch, same text-only rule, same caps, and
    ``list_app_files`` / ``read_app_file`` read it back under the project
    name. One tree holds EVERY service; a service built from a subfolder
    says so with ``build_settings.subdir``. The root ``nerdit.toml`` is the
    declaration::

        [project]
        name = "asso"

        [services.web]
        port = 3000

        [services.api]
        port = 8000
        build_settings = { subdir = "apps/api" }

        [vars]
        required = ["API_KEY"]

    ``[services.<name>]`` takes the ``[deploy]`` keys except ``name``: the
    service ``web`` is served under the project name (``asso``), any other
    under ``<service>--<project>`` (``api--asso``), and that label is the
    name every other tool takes. ``[ai.*]`` / ``[db.*]`` bindings stay
    top-level tables shared by every service; a declaration cannot create
    a database (``create_database`` first, then bind it). WARNING: file
    contents you pass here transit this agent's transcript in plaintext;
    never write secrets into project files.
    

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": {
      "project": "<project>",
      "files": "<files>"
    },
    "name": "write_project_files"
  }
}

Input Schema

NameRequiredDescriptionDefault
filesYesWorkspace-relative path -> that file's full UTF-8 text; a write replaces the file whole. Paths are relative with no ``..``; ``.git``, ``node_modules``, ``__pycache__``, ``.venv`` and ``*.pyc`` are refused, and ``.env`` / ``.env.*`` by name. Text only (NUL or non-UTF-8 is refused). Caps: 256 KiB per file, 10 MiB and 500 files per workspace.
deleteNoWorkspace-relative paths to remove, applied with the writes in the same all-or-nothing batch. Omit (null) to delete nothing; a path that does not exist is a no-op; a path may not be in both ``files`` and ``delete``.
projectYesProject name: the ONE source tree of the project, a workspace of the same name. A new name creates the workspace; an existing one is edited in place. It must equal ``[project].name`` in the tree's ``nerdit.toml``.
idempotency_keyNoCaller-chosen key: a retry with the same key replays the first result instead of acting twice. Omit and a fresh key is minted per call, so each call acts.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.9.2
    • changedInput schema / properties / files / description
      Previous value: -"Workspace-relative path -> that file's full UTF-8 text; a write replaces the file whole. Paths are relative with no ``..``; ``.git``, ``node_modules``, ``__pycache__``, ``.venv``, ``data/`` and ``*.pyc`` are refused, and ``.env`` / ``.env.*`` by name. Text only (NUL or non-UTF-8 is refused). Caps: 256 KiB per file, 10 MiB and 500 files per workspace."New value: +"Workspace-relative path -> that file's full UTF-8 text; a write replaces the file whole. Paths are relative with no ``..``; ``.git``, ``node_modules``, ``__pycache__``, ``.venv`` and ``*.pyc`` are refused, and ``.env`` / ``.env.*`` by name. Text only (NUL or non-UTF-8 is refused). Caps: 256 KiB per file, 10 MiB and 500 files per workspace."
  2. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

With no annotations, the description carries the behavior burden and discloses important traits: all-or-nothing batches, text-only content, caps, service naming rules, and a plaintext-secrets warning. It relies on the schema for exact caps and idempotency/delete semantics, and does not describe return values or auth requirements.

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?

The purpose is front-loaded, and the TOML example and service-naming rules are structured and relevant for a complex write operation. The description is long and repeats some constraints already covered in the schema, but most sentences earn their place.

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?

For a mutation tool with no annotations and no output schema, the description is fairly complete: it covers the write/apply lifecycle, file content format, all-or-nothing behavior, and a security warning. It still leaves return values, auth requirements, and some exact failure semantics unstated.

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 meaningful context beyond the schema by explaining the required nerdit.toml declaration, service naming, subdirectory builds, and database binding prerequisites. It does not add much for the delete or idempotency_key parameters, which remain schema-only.

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 states a specific verb and resource: writing a project's source tree, including nerdit.toml. It clearly distinguishes this from siblings by saying it is exactly write_app_files on the project-named workspace and that apply_project is the subsequent step.

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?

It gives clear context for when to use it: writing a project's source tree before calling apply_project. It names the closely related write_app_files alternative and the read-back tools, but it does not spell out explicit exclusions or when to choose create_project versus this tool.

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