Skip to main content
Glama
nerdit-ai

Nerdit

Official
by nerdit-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

write_project_files

Write a project's source tree and nerdit.toml in one all-or-nothing batch, creating or editing the workspace, so you can declare services and then apply the project.

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.

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``, ``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.
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. First observedv0.1.0

TDQS

A4.5/5.0
Behavior5/5

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

With no annotations, the description carries full burden and does so thoroughly: it discloses the all-or-nothing batch, text-only rule, caps, the key warning that file contents transit the agent transcript in plaintext (secrets risk), and that the root nerdit.toml is the declaration. It also explains service naming rules and how bindings work, which are behavioral traits not captured by 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.

Conciseness4/5

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

Front-loads the core action and then provides a dense but well-organized block of details, including a concrete TOML example. It is longer than typical, but the length is justified by the complexity; some sentences (e.g., restating the write_app_files equivalence) could be trimmed without losing meaning.

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 complex, multi-parameter mutation tool with no annotations and no output schema, the description is nearly complete: it covers purpose, sequencing, file rules, TOML format, service naming, and a critical security warning. It does not cover expected return values or error semantics, but with no output schema declared, that is a minor gap.

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 a 4 by adding meaning beyond the schema: the files parameter must include the tree's nerdit.toml, and the project name must equal [project].name. It also explains the TOML structure and service naming conventions that govern the contents of those parameters.

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 specific verb and resource ('Write a project's source tree') and explicitly distinguishes itself from the sibling write_app_files ('Exactly write_app_files on the workspace named after the project'). The mention of nerdit.toml and apply_project makes the scope unmistakable.

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?

Gives clear sequencing guidance: write the tree, then apply_project; also notes that a declaration cannot create a database and that create_database must come first. It does not explicitly say when not to use this tool versus write_app_files, but the equivalence statement effectively routes the agent.

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