Skip to main content
Glama

Scaffold Project

scaffold_project
Destructive

Creates a well-formed project structure in one call by generating convention directories, an item registry, an assembly manifest, and project.json for clean loading and assembly merging.

Instructions

Lay out a well-formed project in one call (issue #143 / D1) — promote the MULTI_AGENT.md §3/§7 directory convention to a primitive. Creates the convention directories (components/, .dp_lib/), an item registry (items.json, #140), a seed assembly manifest from the supplied components/instances, and the project.json container that ties them together. The result loads clean and merge_assembly consumes it unchanged once its components resolve.

base_dir: the project root directory (created if absent). name: the project id (naming-convention checked). components/instances/shared_parameters: the assembly manifest content. master: optional component id to record as the master/skeleton single-source-of- truth slot (the lean interface-geometry skeleton children mate against). items: optional {item_id: {files?, metadata?}} to seed the item registry with.

Returns the layout {project_file, manifest, registry, components_dir, lib_dir, lockfile, master, dirs}.

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": {
      "base_dir": "<base_dir>",
      "name": "<name>"
    },
    "name": "scaffold_project"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYes
itemsNo
masterNo
base_dirYes
instancesNo
workspaceNoRun this call in this named workspace
componentsNo
shared_parametersNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.5.7
    • addedInput schema / properties / workspace
      Added value: +{
      +  "default": "",
      +  "description": "Run this call in this named workspace",
      +  "title": "Workspace",
      +  "type": "string"
      +}
  2. First observed

TDQS

A3.5/5.0
Behavior3/5

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

Annotations declare destructiveHint=true and readOnlyHint=false, so the agent knows this mutates disk state; the description confirms it by saying base_dir is 'created if absent' and lists the returned layout keys. However, it never says what happens if the directory or project.json already exists — overwrite, merge, or fail — which is exactly the behavior a destructiveHint=true tool should disclose.

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

Conciseness3/5

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

The lead sentence states purpose up front, but the definition is padded with unhelpful references (issue #143 / D1, MULTI_AGENT.md §3/§7) and awkward line wrapping that buries the parameter glossary. Roughly a third of the text does not help an agent invoke the tool correctly.

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 an 8-parameter creation tool with no output schema, the description covers what gets created, how parameters map to artifacts, and explicitly enumerates the return layout {project_file, manifest, registry, components_dir, lib_dir, lockfile, master, dirs}. The missing piece is failure/overwrite semantics for an idempotency-sensitive scaffolding call.

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 description coverage is only 13% (just 'workspace'), so the description carries the burden and does document nearly every parameter: base_dir, name (naming-convention checked), components/instances/shared_parameters, master, and the items shape '{item_id: {files?, metadata?}}'. It stops short of describing the expected internal structure of components/instances/shared_parameters ('the assembly manifest content' is left vague), so a 4 rather than 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource ('lay out a well-formed project', creates convention directories, items.json registry, assembly manifest, project.json) and links its output to the sibling merge_assembly. The internal jargon (issue #143 / D1, MULTI_AGENT.md §3/§7, '.dp_lib/') adds noise but the created artifacts are enumerable, so an agent can tell what it produces.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies the usage context — bootstrap a project layout so that the result 'loads clean and merge_assembly consumes it unchanged' — but never states when to prefer this over siblings like items_new, make_assembly, or project_validate, nor what precondition must hold (e.g. project must not already exist). Usage is inferable rather than specified.

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