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

With no annotations, the description carries the full burden and does so thoroughly: secure-by-default with @SkipAuthorization() escape hatch, fail-closed semantics (403 on denial or unreachable authorizer), registration order after SecurityModule so rate limiting runs first, the files it patches, and idempotency.

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?

Dense but front-loaded with 'OPT-IN.' and the mandatory-ask rule, which are the highest-stakes facts. Every clause carries information (fail-closed, module ordering, patched files), though the single long sentence-per-idea style is harder to scan than it could be.

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 side-effectful scaffolding tool with no annotations and no output schema, the description covers what changes, what is created, security behavior, ordering constraints, and idempotency—everything an agent needs to call it correctly and warn the user.

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 all three parameters are already documented in the schema. The description adds context about file patching and overwrite/idempotent behavior but does not explain the individual parameters beyond what the schema provides, making the baseline 3 appropriate.

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 ('Agrega la autorización del borde HTTP al servicio') and enumerates the concrete artifacts created (IAuthorizationVerifier port, default adapter, GLOBAL Guard). This is clearly distinguishable from siblings like scaffold_service or add_use_case.

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?

Explicit when-to-use context: OPT-IN, agent must ask the user, never decide alone or silently omit, created once per service, idempotent. It does not name alternative tools for related security concerns, which keeps it below a 5, but the usage conditions are unusually clear.

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

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

No annotations, so the description carries the full burden and mostly succeeds: it discloses write location and casing rules, that later cases MERGE into existing domain modules, that refactor mode leaves app.module alone, and that class-name reconciliation is manual under infraStyle=project. It says nothing about what the tool returns or reports after generation, and overwrite semantics live only in 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.

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

A single dense paragraph mixing purpose, mode rules, adapter rules, merge behavior, and manual reconciliation, with ALL-CAPS fragments instead of headings or bullets. Every fact is relevant, but nothing is grouped, and several clauses (http adapter needs no DB, default adapterType) duplicate schema text the agent already sees.

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 24-parameter generator with no annotations and no output schema, the description covers the critical decision points and side effects an agent needs before calling: mode semantics, adapter variants, merge behavior, and infra reconciliation caveats. Missing pieces are the return payload and whether inspect_project should run first.

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 description coverage is 100%, so the baseline is 3. The description only re-states a handful of parameters (adapterType modes, nombreSp, apiExterna, infraStyle/infraRoot, motor/conexion defaults) and adds little beyond those schema texts, notably the merge effect of adding a case to an existing domain.

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?

First sentence gives a specific verb and artifact list (hexagonal vertical slice with port, service, adapter, controller, DTOs, entities, error catalogs, modules) written to src/<dominio>/. The scope is unmistakable. It never contrasts itself with generate_from_spec or scaffold_service, so an agent must infer which generator to pick when both could apply.

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?

Rich conditional guidance: greenfield vs refactor (refactor never touches app.module), adapterType selection with prerequisites (sp requires nombreSp, http requires apiExterna/rutaApi and no DB), infraStyle=project with infraRoot for existing projects, and multi-case merge semantics. It stops short of stating when to prefer this over the sibling generate_from_spec, which is the one routing decision left implicit.

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

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

With no annotations, the description carries the burden well: it discloses that files are written under specific paths, that output is idempotent and deterministic, that the Postman collection is merged without touching other folders, and that it must read source rather than recall. It omits failure modes (e.g. what happens with no controllers) and any return value.

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 mandatory outputs are front-loaded, which is good, but the body is a dense run-on with nested parentheticals and file paths that make it hard to scan. Sentences are long and mix purpose, policy and artifacts together; restructuring into bullets would earn the space better.

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 multi-file generator with no annotations and no output schema, the description covers what gets produced, where, the default module scope, and idempotency. What's missing is edge-case behavior (no controllers found, existing conflicting docs) and confirmation of what the tool returns to the caller.

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 description coverage is 100%, so the schema already documents modules, postman, projectRoot and architecture. The description mostly restates that same policy (postman opt-in, architecture always on), adding little new meaning beyond the schema text. Baseline 3 is appropriate.

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 concrete verb and resource ('Genera la documentacion de la API') plus its defining constraint: it reads the real code (controllers, DTOs, error catalogs) rather than memory. It also enumerates the exact outputs (per-module contract, Mermaid sequence diagram, docs/api/README.md, ARCHITECTURE.md), which separates it cleanly from siblings like verify_standards or generate_from_spec.

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?

Gives explicit interaction policy: the agent MUST ask the user before enabling postman, while the architecture doc is generated unconditionally ('siempre, no se pregunta'). It also names the siblings that invoke it implicitly ('add_use_case y record_architecture la refrescan solos'), clarifying it need not be called manually after those. No explicit when-not-to-use case, though.

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

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

With no annotations, the description carries the burden well: it discloses that dryRun is the default (safe), that false writes to disk, that it reuses add_use_case, and that it honors get_rules. It doesn't cover failure behavior on invalid specs, permissions, or idempotency, which keeps it off a 5.

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?

Front-loaded with the purpose, then dryRun semantics, then the dependencies on add_use_case and get_rules. Fairly tight, though the dryRun explanation partly duplicates the schema's own description.

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?

With no output schema, the description usefully says what dryRun=true returns (the plan: use cases, methods, files) so the agent knows the shape of the response. Missing only failure-mode and mode-selection detail for a five-parameter file-writing tool.

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 schema already documents all five parameters including the mode enum and overwrite semantics. The description reinforces dryRun and specPath at a conceptual level but adds no syntax beyond the schema and never mentions the mode parameter's greenfield/refactor distinction.

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 ("Genera un módulo hexagonal a partir de un middleware.spec.yaml") plus the scope (domain-agnostic, N methods per inbound/outbound port). It also differentiates from siblings by noting it reuses add_use_case and respects get_rules, so an agent can distinguish it without opening a schema.

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?

Explains the two operational modes clearly: dryRun=true validates and returns a plan without disk writes, dryRun=false generates the slice per use case. However, it doesn't state when to prefer this over scaffold_service or add_use_case directly, nor when-not to use it.

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

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

No annotations are provided, so the description carries the full burden; "Devuelve" implies a pure read with no side effects, but this is never stated outright. The consistency guarantee (shared with MCP prompts and the spec-builder-middleware agent, no desynchronized copies) is genuinely useful context beyond the name, yet nothing is said about the response form or whether the procedure text depends on workspace state.

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?

Two sentences, front-loaded with what is returned and the flow variants before the design rationale. Both sentences earn their place, though the second is more architectural justification than invocation guidance and could be tightened.

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 single-parameter read tool with full schema coverage and no output schema, the description covers what is returned (step-by-step procedure keyed by flow) and why it is authoritative. The only gap is the shape of the returned procedure, which the agent must discover by calling it.

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 description coverage is 100% and the enum values are already documented in the schema, including what greenfield vs refactor mean. The description's parenthetical listing of the three values essentially repeats the schema, adding no syntax, default, or selection advice beyond it, so the baseline 3 applies.

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 ("Devuelve el procedimiento paso a paso de un flujo") and enumerates the three supported flow values, so the agent knows exactly what it retrieves. It also asserts it is the sole source of the procedure, which implicitly separates it from template/rule lookups, but it never names or contrasts with a specific sibling such as get_template or get_rules.

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?

The claim that this is the "ÚNICA fuente del procedimiento" implies the agent should call it rather than rely on prompt copies or the installed agent, which is useful routing context. However there is no explicit when-to-use/when-not statement and no mention of prerequisites or ordering relative to scaffold_service or inspect_project.

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

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

With no annotations, the description carries the burden and does well: it declares read-only/advisory status, that it does not substitute for base rules or the verifier, and the graceful empty-result behavior ('si no hay nada util, lo dice y no pasa nada'). It does not explain scope/permanence of the stored memory (how it is accumulated or whether results are cached), leaving a small gap.

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?

Front-loaded with what is returned, then the read-only/advisory constraint, then the call ordering. Slightly dense with parenthetical enumerations, but every sentence contributes distinct guidance.

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?

No output schema exists, and the description compensates by naming the three categories of returned content and the empty case. Combined with the sequencing guidance, an agent has enough to call it correctly; only memory-scope details are missing.

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?

Single parameter with 100% schema description coverage, so the baseline is 4. The description adds no extra meaning about projectRoot beyond the schema, which is acceptable at this coverage level.

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: returns what the MCP remembers about THIS repo from prior uses, enumerated as conventions, one-off user decisions, and recurring verifier errors. It explicitly distinguishes itself from the sibling get_rules and from the verifier, so an agent can route correctly without opening the schema.

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?

Gives explicit sequencing ('Llamala justo despues de get_rules') and states the intended downstream action (use the data to PROPOSE defaults that the user confirms). It also names the alternative, get_rules, and clarifies that this tool does not replace or relax it.

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

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

No annotations exist, so the description carries the burden; it does disclose that the payload is domain-agnostic (module/entity supplied by the user) and includes distilled repo snippets, which is useful for interpreting the result. It says nothing about failure behavior (e.g. missing rules.yaml), caching, or whether the content is static — relevant for a file-backed fetch.

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?

Front-loaded with the verb and the artifact name, then a dense but purposeful enumeration of covered topics and a clear imperative. The content list is long but each item maps to a real rules domain; slightly verbose in Spanish prose but no filler.

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?

With no output schema, no annotations and no params, the description does the necessary work: it describes what comes back and when to call it. The only gap is operational behavior (what happens if the rules file is unavailable), which matters for an agent planning a scaffold or refactor.

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?

Zero parameters, so baseline 4 applies; the description correctly reinforces this by stating the tool is domain-agnostic and that module/entity are supplied by the user rather than as arguments.

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+resource ('Devuelve el cerebro de calidad del área (rules.yaml)') and enumerates its contents precisely: hexagonal architecture, naming, ports, DTOs, data access, error catalog, security. An agent can distinguish it from get_template or get_learnings by the contents, though no sibling is named explicitly.

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?

Gives an explicit trigger: read it BEFORE generating a new service or refactoring an existing one, which positions it relative to scaffold_service. It lacks any when-not guidance or named alternative, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the behavioral burden. It usefully discloses that the return is the raw template content scoped to the dataset, but it does not describe missing-path behavior, permissions, or any other operating context.

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 sentence with no waste, front-loading the action and the key selector. Nothing needs to be trimmed.

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 simple one-parameter getter with a fully documented schema and no output schema, the description gives enough to understand the operation and return form ('contenido crudo'). It could still mention failure behavior or path expectations, but the core is covered.

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 description coverage is 100%, and the sole parameter is already documented with an example. The description only restates that lookup is by relative path, adding no extra format or constraints beyond the 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?

The description states a specific verb ('Devuelve') and resource ('contenido crudo de una plantilla del dataset') and makes clear the lookup is by relative path. This naturally separates it from list_templates, but it does not explicitly name or contrast against any sibling.

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?

Usage is implied: an agent should call this when it already has a relative template path and wants the raw contents. The description does not explicitly say when to use this versus list_templates or what to do if the path is unknown.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the project is only READ, and that the sole write is a one-time agent-kit installation (.kiro/agents, agentic/templates, AGENTS.md), disabled via MIDD_NESTJS_AUTO_KIT=off, with a user-facing notice about which agent to select. This is unusually complete side-effect disclosure; only return-format/pagination-like details are absent.

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 purpose is front-loaded, but the body is a single sprawling run-on sentence that crams detection targets, reuse rules, and the agent-kit write exception into one block. It is informative but would benefit from splitting the discovery scope from the side-effect disclosure.

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 complex discovery tool with a fully documented single param and no output schema, the description explains what it returns (rules to respect) and covers the one surprising behavior (kit install on first use). An agent has enough to call it correctly, though the return shape is only loosely sketched.

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?

There is a single parameter (projectRoot) with 100% schema description coverage, so the schema already documents it fully. The description adds no syntax or constraint detail beyond what the schema provides, making the baseline 3 appropriate.

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?

The description names a specific verb+resource (project discovery of the target NestJS repo) and enumerates concrete artifacts it detects: folder/case conventions, TypeORM connection shape, transversal infrastructure, present modules. It also distinguishes itself from the generation siblings by framing itself as producing rules to respect 'antes de generar nada'.

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?

It scopes usage to 'Flujo 2 refactor' and states the output is rules to apply before generating anything, implying it runs ahead of scaffold_service/generate_from_spec. It does not explicitly name those alternatives or state when-not-to-use, so it falls short of a 5.

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

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

With no annotations, the description carries full burden and does well: it discloses idempotency (re-running updates to the MCP version), non-destructive default behavior (files not installed by this MCP are respected unless overwrite=true), and marker-scoped editing of AGENTS.md so the rest of the file is untouched. It omits any mention of permissions or what the call reports back.

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?

Information is front-loaded: what gets installed first, then the idempotency/overwrite contract, then the usage trigger. It is dense but nearly every clause carries distinct operational detail; only the file enumeration is slightly long.

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 3-parameter mutation tool with no output schema, the description covers target files, safety behavior, and the select-the-orchestrator detail that matters when calling it. Missing only return/report information and permission expectations.

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 description coverage is 100%, so the schema already documents all three parameters including the models defaults and the overwrite semantics. The description reinforces the overwrite rule consistently with the schema but adds no extra syntax or constraint detail beyond it, making the baseline of 3 appropriate.

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 (installs/updates) plus an enumerated resource list (middleware agents, spec template, AGENTS.md section), leaving no ambiguity about what gets written. It does not explicitly name a sibling to distinguish against, but the scope (repo bootstrap) is clearly different from scaffolding-oriented siblings.

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?

The closing sentence gives a clear trigger: use it when the user wants the repo ready to create services with the MCP. It also implies a precondition via 'repo consumidor'. No explicit when-not or named alternative (e.g., scaffold_service) is given.

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

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

No annotations are provided, so the description carries the full behavioral burden. "Lista" implies a read operation, but the description does not state read-only status, permissions, pagination, return format, or any other operational context.

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 description is a single front-loaded sentence with no wasted words. The parenthetical example list is compact, though it is incomplete relative to the schema enum.

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 simple one-parameter list tool, the description is minimally adequate. However, with no annotations or output schema, it could better explain return behavior, and its subset examples omit two schema enum values including the default all.

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 description coverage is 100%, so the schema already defines the subdir parameter and its enum values. The description mentions three subsets parenthetically but does not add meaning beyond the schema, and omits the authorization and all enum values.

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?

The description uses a specific verb ("Lista") and resource ("plantillas") and scopes it to the dataset. It implicitly distinguishes itself from get_template by focusing on listing rather than fetching a single template, but it does not name any sibling explicitly.

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?

There is no explicit guidance on when to use this tool versus alternatives such as get_template. The listing intent is implied, but no conditions, prerequisites, or exclusions are stated.

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

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

With no annotations at all, the description carries the full burden and does disclose key mutation semantics: it writes two file types, merges one entry per module 'sin tocar las de otros', and uses an envelope with mcpVersion/generatedAt. It omits what happens on re-registration of the same module (overwrite vs. append), required filesystem permissions, and error behavior.

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?

Three sentences, front-loaded with the write targets and followed by inputs and the memory rationale; little waste. The final sentence about being 'la memoria por repo del MCP' is useful routing context rather than filler.

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-parameter mutation tool with no output schema, it covers artifacts written, data sources read, and cross-session usage well. The remaining gap is the return value / confirmation shape, which an agent would need to verify the write succeeded.

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 schema already documents all six parameters including compliance ('Salida de verify_standards') and buildStatus. The description mostly restates those fields rather than adding syntax or format guidance, and it never mentions writeAuditFile, which lets the caller opt out of the audit file it describes as always written.

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 (registra) plus the exact resources touched: docs/architecture-inventory.json and docs/audits/<module>-<fecha>.md. It also names the source artifact it consumes (middleware.spec.yaml, verify_standards output), so an agent can distinguish it from pure documentation generators like generate_api_docs or verify_standards.

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?

Gives clear context for use: call it after generating/refactoring a module, feeding it compliance, build status and decisions; and read the inventory at the start of a future session to avoid re-registering modules. It lacks an explicit exclusion versus the sibling record_decision, which overlaps conceptually with the 'decisions' parameter.

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

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

No annotations, so the description carries the full burden. It usefully discloses the effect (persist across sessions) and the write target, but it does not say whether an existing decision is overwritten, what permissions are needed, or what the response looks like; it also conflicts with the schema's claim that the value is written to AGENTS.md rather than docs/mcp-learnings.json.

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?

Compact and front-loaded: what is recorded comes first, followed by constraints and the write target. No filler, though the closing file reference adds a contradiction rather than clarity.

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?

With no annotations and no output schema, the description must cover behavior on its own. It covers purpose, trigger discipline, and persistence, but leaves overwrite/merge semantics and the full decision set unaddressed and introduces a destination inconsistency an agent cannot resolve.

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 description coverage is 100%, so the baseline is 3. The description only restates part of the 'decision' enum (authorization) and the value set, omitting 'postman', and its stated output location contradicts the schema's per-parameter notes.

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?

Specific verb+resource: records an explicit user decision that applies repo-wide so it isn't asked again next session, and names the storage file. The scope is clear, though it only enumerates 'authorization' while the schema also allows 'postman', leaving the full purpose slightly under-stated.

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?

Gives an explicit when-to-use (a decision already made that must persist) and a firm when-not ('solo con una respuesta clara del usuario; nunca por suposicion del agente'). It does not name alternatives such as record_architecture, so routing between the two record_* siblings is left to inference.

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

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.

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

With no annotations, the description carries the full burden, and it does disclose two useful traits: it returns a report and it fails when blocking errors are found. It does not disclose that the tool writes into the target project (copying verify-standards.mjs to scripts/ when installScript is true), nor whether the run is idempotent or what permissions the project root requires.

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?

Two tight sentences: the first front-loads what is verified with a concrete checklist, the second covers the return and failure behavior. Nothing is redundant or padded.

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 tool with no annotations and no output schema, the description should say more: the shape of the returned 'reporte' is undefined, and the side effect of writing a script into the project is only discoverable via the schema. The essential invocation contract is present, but behavioral completeness has clear gaps.

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 description coverage is 100%, so both projectRoot and installScript are already documented in the schema, and the description adds no parameter-level detail. Baseline 3 applies since the schema does the work and the description merely implies scope with 'proyecto destino'.

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 ('Ejecuta la verificación') plus the resource (estándares del proyecto) and enumerates the exact checks performed (naming, cabeceras de seguridad, @Version, .env.example, SP opt-in), which lets an agent distinguish it from siblings like get_rules or inspect_project. It stops short of naming a sibling explicitly, so it is clear but not fully differentiated.

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?

The phrase 'sobre el proyecto destino' implies this runs against an already-scaffolded target project, which gives some usage context. However, there is no explicit statement of when to call it versus get_rules or inspect_project, and no preconditions (e.g., that the project must already exist) are spelled out.

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