scaffold_project

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

With no annotations, the description carries the full burden. "Write a project skeleton" implies filesystem mutation, but it never says whether files are created at 'destination', what happens if the target already exists, or that 'overwrite' exists to allow clobbering — a notable omission for an unannotated write 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?

A single front-loaded sentence with the verb first and zero filler; the only mild cost is that the parenthetical scaffolding contents are dense and slightly compete with the actionable part.

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?

A write tool with no annotations, no output schema, and 0% schema description coverage needs the description to cover side effects, overwrite semantics, and destination meaning. It supplies only the kind enumeration, so an agent cannot safely predict what will land on disk before calling.

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% across 4 parameters. The description glosses only 'kind' (and partially at that), leaving 'destination' (directory? path prefix?), 'name' (project name vs folder name vs default value), and 'overwrite' (what it overwrites, and that default false means failure or merge) entirely unexplained.

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?

"Write a project skeleton" names a specific verb and resource, and the three enumerated kinds ('platform', 'adapter', 'pipeline') make the scope concrete. It is clearly distinguishable from the dataset/catalog siblings, though the parenthetical build descriptions read as content lists rather than a purpose statement.

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 on when to choose scaffold_project over, say, convert_dataset or catalog_index, and no stated preconditions (empty destination, existing project present, permissions). The only selection help is implicit in the 'kind' glosses.

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