scaffold_service

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

With no annotations, the description carries the burden well: it discloses the write target (projectRoot), the overwrite default of false (no pisa), and the fail-closed behavior when mandatory params are absent. It stops short of describing the response/return shape or idempotency on re-runs, which is a meaningful gap for a mutation 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 output scope is front-loaded before the mandatory-parameter rules, and every clause maps to actionable behavior. The file enumeration is dense but earns its place by telling the agent what the tool creates; two long sentences is reasonably tight for the amount of behavior conveyed.

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 6-param mutation tool with no annotations and no output schema, the description covers scope, write location, overwrite semantics, and the hard prerequisite on three parameters. The main remaining gap is what the agent should expect back (created file list, refusal message format) after 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it names the three mandatory, never-defaulted parameters and states the consequence of omission, which is not fully spelled out for prefijoApi/prefijoError in the schema. Other params (overwrite, conexion) are left to the already-rich 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?

States a specific verb and resource (generate the base of a new hexagonal NestJS service) and enumerates exactly what gets written (shared layer, config/enforcement files, main.ts, app.module.ts) and where (projectRoot). This is clearly distinguishable from siblings like add_use_case, generate_from_spec, or install_agentic_kit.

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?

Implies a greenfield/new-service context and explicitly flags that prefijoApi, prefijoError and motor are always asked to the user and never defaulted, with the tool refusing to generate if any is missing. It does not, however, explicitly contrast itself with generate_from_spec or add_use_case, which would be the natural alternatives an agent might confuse it with.

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