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

Annotations already declare readOnlyHint and idempotentHint, and the description largely restates this ('Read-Only', 'Sin efectos secundarios en disco'). It adds that the operation is NLP-based extraction, which is mildly informative, but discloses nothing about accuracy limits, handling of ambiguous or missing fields, or what happens when no power/performance value is found.

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?

Purpose is front-loaded in the first sentence, followed by clearly labelled 'Cuándo usar' and behavior sections. Slightly verbose in restating the read-only nature, but each section is short and earns its place.

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-input analysis tool with an output schema (so return format needn't be explained), the description covers purpose, trigger context, and safety profile. What is missing is guidance on fallback behavior when extraction fails or values are absent, which matters for an NLP extraction 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?

With a single parameter at 100% schema description coverage, the schema already documents the argument fully, including an example string. The description's added detail about extraction targets concerns outputs rather than the input parameter, so 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 specific verb (analiza/extrae) on a specific resource (descripción textual o ficha técnica de un equipo térmico) and enumerates exactly what is extracted (potencia nominal kW, SCOP/COP/SEER, vector energético). It also names the equipment types and the CE3X target, so it is clearly distinguishable from all listed siblings, none of which parse equipment datasheets.

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 'Cuándo usar' section gives concrete triggers: technical notes, photo-of-nameplate transcriptions, manufacturer catalogs, in order to parameterize thermal installations in CE3X. This is clear invocation context, though it names no exclusion or alternative sibling (e.g., when to use the BIM or PDF-plan analyzers instead).

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?

Annotations already declare readOnlyHint and idempotentHint, so safety is partly covered; the description adds concrete behavioral context: it does not modify the original IFC file and emits interactive progress to FastMCP. That is real value beyond the structured hints, though it stops short of noting failure modes (corrupt/unsupported IFC) or performance considerations.

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 core action and organized under clear headers (Cuándo usar, Comportamiento), which aids scanning. Slightly verbose in enumerating the IFC entity types, but every clause carries information useful for routing.

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?

Given a single-parameter tool with full schema coverage, an output schema (so return values need no prose), and annotations covering safety, the description supplies the remaining essentials: what it extracts, when to pick it, and its side-effect profile. Nothing needed to invoke it correctly is 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?

Schema description coverage is 100% and the single ifc_path parameter is fully documented there (absolute/relative path, .ifc/IFC2X3/IFC4). The description adds no format or path-handling detail beyond the schema, 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 (abre y analiza) plus resource (modelo BIM IFC), and enumerates exactly what it extracts (IfcSpace, IfcWall, IfcWindow/IfcDoor) and the downstream purpose (integración en CE3X). An agent can distinguish it from other siblings 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?

The 'Cuándo usar' block explicitly names the trigger condition (having the 3D BIM model from Revit, Archicad, Allplan, CYPE) and names the alternative for the opposite case ('analizar_plano_arquitectura_pdf' for 2D plans/PDF). When-to-use and when-to-use-something-else are both covered.

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?

Annotations already declare readOnlyHint and idempotentHint, but the description adds real context: vector parsing via PyMuPDF, explicit statement that the input PDF is not modified, and that interactive progress is emitted to FastMCP. It stops short of covering error/failure behavior for malformed or raster PDFs.

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 purpose, then labeled sections for usage and side effects, so an agent can skim. Slightly verbose with the header scaffolding, but every sentence carries information.

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 an output schema present, return values need not be explained, and the description covers purpose, alternatives, input expectations, and side effects. Nothing an agent needs to call this correctly is 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?

Only one parameter (pdf_path) at 100% schema description coverage, so the schema already documents it. The description adds no syntax or format detail beyond the schema. 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 (abre y analiza) and resource (plano arquitectónico en PDF vectorial), names the engine (PyMuPDF) and the concrete outputs (superficies útiles en m² y cuadros de carpintería). It clearly differentiates itself from the IFC sibling tool.

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 'Cuándo usar' block gives an explicit condition (planos de planta en PDF) and routes the agent to the alternative ('analizar_modelo_bim_ifc') for 3D IFC models. No inference required.

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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is partly covered. The description confirms no file modification (largely redundant with readOnlyHint) but adds genuinely new behavior: it emits interactive progress to FastMCP and produces a document-health report, which is not derivable from the annotations.

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 purpose sentence followed by clearly labeled usage and behavior sections, so an agent can scan it quickly. The header scaffolding is slightly heavier than needed for a single-parameter tool, but every sentence carries relevant content.

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?

An output schema exists, so the description need not explain return values, and it covers purpose, usage, and side effects. For a one-parameter read-only audit tool this is complete enough to invoke correctly.

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?

Only one parameter (ruta_carpeta) with 100% schema description coverage, so the schema fully documents it. The description does not add format, path-convention, or validation details beyond what the schema provides; 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 (audita) and resource (carpeta de visita), enumerates the inspected content types (croquis, notas, planos PDF, fotos, fichas) and names the concrete outcome (informe de salud documental). It is clearly distinguishable from the sibling certificar_desde_carpeta_visita, which it references by name.

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 'Cuándo usar' section tells the agent to invoke it before certificar_desde_carpeta_visita, and states the purpose of doing so (detecting mandatory omissions like facility photos, plans, cadastral reference). The condition that selects this tool over its closest sibling is spelled out.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds some operational context (it reads CE3X reference databases and registers no persistence), but the central 'read-only, no file modification' claim largely restates the annotation. With annotations carrying the safety burden, this is a modest add rather than rich new disclosure.

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 purpose sentence followed by clearly labeled 'Cuándo usar' and 'Comportamiento' sections. Efficient and well-organized, though the behavior block slightly overlaps the annotation 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 read-only calculation tool with full schema coverage, annotations, and an output schema, the description covers purpose, routing, and side effects adequately. Nothing an agent needs to invoke it correctly appears to be missing, though it says little about required environmental inputs beyond the parameters.

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 six parameters, including ACS/heating vectors and allowed tipología values. The description adds no syntax, ranges, or defaults beyond what the schema provides, so 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 specific outputs (demanda energética, consumo de energía primaria no renovable, emisiones de CO2, letras A-G) and the data source it leverages (CE3X Escala/Localidades.xml). An agent can immediately tell this is the pre-certification energy-rating calculator, distinct from the full-certificate generator named as a 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?

The 'Cuándo usar' section explicitly names the alternative tool 'generar_certificado_completo' and the condition that selects this one (quick pre-qualification before producing the definitive documentary package). Explicit when-to-use with a named alternative is exactly what a routing agent needs.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description largely restates that ('Operación analítica de solo lectura') while adding that no local files or records are altered. It adds the dependency on cold-water network temperature derived from the province, which is useful, but omits any error conditions, table-lookup limits, or fallback 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?

The header-based structure (purpose, cuándo usar, comportamiento) is front-loaded and easy to scan. It is slightly padded by restating the read-only nature already covered by annotations, but no sentence is wasted enough to hurt readability.

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 an output schema present, the description need not explain return values, and it covers purpose, invocation context, and side-effect profile adequately. The one residual gap is the relationship between the two occupancy parameters (personas vs dormitorios), which is left to the schema.

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 all four parameters are already documented. The description adds only indirect meaning by mentioning the cold-water network temperature (tied to 'provincia') and the 60 °C output target; it does not clarify when to supply numero_personas versus numero_dormitorios, so it stays at the baseline for high-coverage schemas.

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 precise verb and resource ('Calcula la demanda normativa obligatoria de ACS'), pins the output unit and condition (60 °C, litros/día), and names the governing standard (CTE DB-HE4). No sibling tool covers ACS demand, so the agent can identify it unambiguously from the name-plus-description alone.

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 'Cuándo usar' section gives a clear context: determining the regulatory daily ACS volume for sizing thermal production and solar coverage installations in CE3X. It does not name alternatives or exclusions, but no sibling overlaps this calculation, so explicit routing is largely unnecessary.

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?

Annotations already declare readOnlyHint and idempotentHint, and the description's 'operación analítica de solo lectura... no modifica archivos ni registros locales' largely restates them. It does not add non-obvious behavior (assumptions, default fallbacks, error cases) beyond the safety profile.

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-loads the purpose, then separates 'Cuándo usar' and 'Comportamiento' into labeled sections, which makes scanning easy. Minor redundancy: the read-only statement repeats the annotations and the terciario/comercial scope is restated.

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 an output schema present, return values need not be explained, and the description covers purpose, trigger and safety, which is sufficient for this four-parameter calculator. Only the parameter-to-normative-table mapping is left implicit.

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 every parameter is already documented in the input schema. The description adds domain framing but no parameter-level semantics (e.g., how tipo_actividad maps to occupancy/VEEI tables) beyond what the schema provides. 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 ('Estima') and a precisely scoped resource (parámetros normativos obligatorios de CE3X para terciario y locales comerciales), enumerating the concrete outputs (potencia de iluminación, VEEI, caudales RITE IDA, tasa de ocupación). No sibling tool computes normative tertiary parameters, and the scope boundary against residential use makes it distinguishable.

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 condition ('Invoque esta herramienta obligatoriamente cuando el edificio... sea de uso terciario o local comercial') and implicitly excludes non-tertiary cases. It stops short of naming an alternative tool for residential/in other cases, so it is a clear context without full routing.

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?

Annotations already declare readOnlyHint and idempotentHint, but the description adds useful context beyond them: it is a telematic query to the European Commission's PVGIS API, uses SARAH-2 satellite radiation, and maintains a local SQLite cache with a 90-day TTL. It does not cover rate limits or failure modes, but the behavioral picture is substantially richer.

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 well structured with front-loaded purpose followed by 'Cuándo usar' and 'Comportamiento' sections. It is efficient overall, though 'con precisión científica' is mildly promotional and the final 'Read-Only' repeats an annotation already visible elsewhere.

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?

Given full schema coverage, existing annotations, and an output schema, the description supplies enough context: what is calculated, when to use it, and the external API/caching behavior. It is nearly complete, though it could mention practical limits or error handling for an API-dependent 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 description coverage is 100%, so the schema already documents latitude, longitude, azimuth, peak power, and tilt with examples and defaults. The description adds no parameter-level meaning beyond what the schema provides, so the baseline of 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 specific verb (Calcula), resource (producción de energía solar fotovoltaica), output units (kWh/año y mensual), and method (API PVGIS / SARAH-2). This clearly distinguishes it from sibling tools like calcular_calificacion_energetica or proponer_medidas_mejora_rd390.

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 'Cuándo usar' section gives a clear context: evaluating solar PV integration for self-consumption as an improvement measure or CTE DB-HE5 justification. It does not name alternatives or explicit when-not-to-use cases, 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description repeats this ('solo lectura, sin efectos secundarios'). The normative citation adds context about the calculation basis, which is somewhat useful. However, there is no disclosure of assumptions like default zero for optional lengths, or that year drives the reference value selection—these behavioral nuances are left implicit.

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 core purpose and normative reference, then clearly sectioned into 'Cuándo usar' and 'Comportamiento.' Every sentence serves a function. Slightly redundant to restate read-only given annotations, but not verbose.

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?

An output schema exists, so no need to describe return values. The description covers purpose, usage, and read-only nature, sufficient to invoke correctly. Minor gap: doesn't warn that optional bridge lengths default to 0, which an agent might miss.

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 four parameters are already documented with descriptions and units. The description adds no parameter-level information beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (calcula) and resource (transmitancias térmicas lineales psi and pérdida térmica global por puentes térmicos), cites the exact normative reference (DA DB-HE/3 CTE). An agent can distinguish this from siblings like calcular_transmitancia_ventana_iso10077 which handles windows, not linear thermal bridges.

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 'Cuándo usar' section tells the agent to invoke this instead of estimated global values, and names the concrete elements it applies to (frentes de forjado, contornos de hueco, pilares en fachada). The alternative (valores globales estimados) is named, satisfying when-instead-of guidance.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the read-only nature is covered structurally. The 'Comportamiento' section largely restates this ('operación de solo lectura, no modifica archivos'), adding only the minor detail that no local records are affected. No additional behavioral traits (idempotency, determinism, rate limits) are disclosed beyond the annotations.

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 front-loaded with the core computation and organized into labeled sections ('Cuándo usar', 'Comportamiento'), so each block is easy to scan. There is mild redundancy in restating read-only status already in the annotations, keeping it just short of optimal.

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 an output schema present, the description need not explain return values, and annotations carry the safety profile. The purpose, scope, standard, and sibling routing are all covered, so an agent has everything needed to invoke the tool correctly.

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. The description adds value by tying the domain concepts (voladizos, retranqueos, aleros) directly to the shading computation, which maps the agent to the vuelo_voladizo_m, retranqueo_m and related parameters, giving slightly more than the schema alone.

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 (Calcula) and precise resource: factores reductores de sombra estacionales (verano/invierno) and factor solar modificado Fs para huecos acristalados. It names the exact scope (elementos de sombra propios: voladizos, retranqueos, aleros) and the governing standard (CTE DB-HE), making it easy to distinguish from the sibling tool.

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?

A dedicated 'Cuándo usar' section tells the agent exactly when to use this tool (protección solar propia de las ventanas) and names the explicit alternative for the contrasting case ('calcular_sombras_obstaculo_edificio_enfrente' for remote obstacles). Both the when and when-not conditions 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description's '(Read-Only). No escribe archivos ni altera estado' largely restates this rather than adding new traits. It does add useful context by naming the governing standard (Anejo E del CTE DB-HE) and the analytical/geometric nature of the operation, but does not disclose anything beyond annotation plus method reference.

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 core purpose, then structured into labeled 'Cuándo usar' and 'Comportamiento' blocks. Every sentence is informative and appropriately sized for a 4-parameter analytical tool.

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 an output schema present, the description needn't explain return values, and it covers purpose, routing to the sibling, and behavioral profile. Combined with full schema coverage and annotations, an agent has everything needed to select and invoke it correctly.

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 four parameters (units, orientation values, defaults). The description adds no parameter-level syntax or format detail beyond what the schema provides, 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?

Names a specific verb (calcula) and precise outputs: ángulo de elevación solar alfa y tabla de perfil de sombras de un obstáculo remoto. It explicitly scopes the tool to neighbor buildings/topography and distinguishes itself from the sibling calcular_sombras_hueco.

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?

Contains an explicit 'Cuándo usar' section stating the use case (sombras de construcciones vecinas o accidentes topográficos) and naming the alternative 'calcular_sombras_hueco' for opening-level elements (voladizos, retranqueos, aleros). Nothing 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description essentially restates this ('Operación analítica de solo lectura... No altera archivos ni estado local') rather than adding new behavioral context. It discloses no validation limits (e.g. the 0.05–0.60 fraccion_marco bounds), error behavior, or robustness notes beyond what the annotations cover.

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?

Structure is front-loaded and scannable with labeled sections (Cuándo usar, Comportamiento y efectos secundarios). The effects sentence largely duplicates the annotations, so it is slightly less than maximal economy, but overall it is tight.

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 pure calculation tool with a 6-parameter schema (4 required) and an output schema, the definition adequately conveys purpose, timing, and non-mutating nature; return values correctly need not be explained. It could add a note on valid input ranges or edge cases to be fully complete.

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 fully documents all six parameters (units, example values, defaults, range). The description adds conceptual framing of area weighting and the intercalario effect but no syntax or usage detail beyond the schema, 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 (calcular) and resource (transmitancia térmica total Uw de una ventana) and grounds it in a named standard (UNE-EN ISO 10077-1), plus the method (weighting glass/marco areas, intercalario effect). It is clearly distinguishable from siblings like calcular_puentes_termicos or calcular_sombras_hueco.

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 'Cuándo usar' section gives a concrete context: use it to obtain accurate glazing transmittance from frame/glass data before entering it into the CE3X thermal envelope. This is a clear usage context, but it names no explicit alternative tool or exclusion (e.g. when NOT to use it vs. other envelope calculators).

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?

Goes beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing the write behavior: it creates a 'CERTIFICADO' subfolder inside '05_ENTREGABLES' and emits interactive progress to FastMCP. Useful side-effect context, though it does not state overwrite/reversibility or auth requirements.

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-loads the core action in the first sentence, then organizes the remainder under 'Cuándo usar' and 'Comportamiento y efectos secundarios' headers. Efficient, though the opening sentence is dense and slightly redundant with the section headers.

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?

Even with an output schema present, the description usefully names the generated files, their destination folder, and the side effects, and it clarifies the required input state. It omits prerequisites such as CE3X connectivity checks, which is the only notable gap for a complex end-to-end 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 description coverage is 100%, so the schema already documents all five parameters. The description adds only high-level context (folder contains PDFs, Catastro data, field notes) and no per-parameter semantics beyond that. 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 specific verb (certifica), the resource (el inmueble), the source (carpeta de visita with planos PDF, Catastro, notas de campo) and the concrete outputs (.cex, .xml, .pdf in 05_ENTREGABLES). This clearly distinguishes it from siblings like organizar_carpeta_visita and auditar_carpeta_visita by framing it as the end-to-end certification run.

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 'Cuándo usar' section gives an explicit condition: use it when an organized visit folder is available to run the whole certification flow in one step. This implicitly positions organizar_carpeta_visita as the prerequisite, but no alternative tools or exclusions are named.

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?

Annotations only declare write (readOnlyHint=false, destructiveHint=false). The description adds real behavioral context: it is persistent, it writes to a local user profile file, and the data is auto-injected into .cex/.xml/.pdf outputs. It does not clarify overwrite-vs-merge semantics or auth/permission requirements, keeping it below 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?

Well front-loaded and organized into purpose, 'Cuándo usar', and 'Comportamiento' sections. Slightly redundant in repeating the persistent-write notion in both the opening and the side-effects block, but otherwise efficient.

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 an output schema present, the description need not explain return values, and annotations cover the safety profile. Purpose, timing, and side effects are all covered; only edge-case behavior (overwrite semantics, validation failures) is unaddressed.

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% across 13 parameters, so the schema already carries the semantic load. The description only restates the 5 required fields (nombre, NIF, titulación, colegio, número), adding nothing beyond what the schema documents; the baseline of 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 ('Configura y guarda') and a highly specific resource ('datos colegiales y profesionales del técnico certificador'), then enumerates the key fields. This is unmistakably distinct from the analysis/certificate-generation siblings, so an agent can identify it 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?

The 'Cuándo usar' block gives explicit triggering guidance: invoke once, or when professional data changes. It lacks an explicit 'when-not'/alternative statement, but no sibling competes for this function, so the practical ambiguity is low.

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?

Annotations already cover readOnlyHint and idempotentHint, so the description adds value with new context: it is an external telematic query with a persistent local SQLite cache (30-day TTL) and it does not alter local files or state. The cache TTL is genuinely useful because it warns the agent results may be up to a month old, though it says nothing about network failures or auth needs.

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-loads the purpose, then uses labeled sections for usage and side effects. Every sentence carries distinct information – no repetition of the schema or annotations, 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?

An output schema exists, so return values need not be described. The description covers purpose, when-to-use, ordering in the workflow, and behavioral side effects, which is complete for a single-parameter read-only query 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?

With a single parameter at 100% schema description coverage, the schema already documents the expected format (14 or 20 alphanumeric characters) with an example. The description adds no format or validation detail beyond that, so the baseline 3 is correct.

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 (consulta telemática a la Sede Electrónica del Catastro de España) and enumerates exactly what it returns (dirección oficial, municipio, provincia, año de construcción, superficie catastral). An agent can distinguish this from sibling tools like determinar_zona_climatica without opening any 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?

The 'Cuándo usar' section gives an explicit trigger (first step for any property in common Spanish territory) and a prerequisite condition (when the Referencia Catastral is available), plus the downstream purpose (auto-fill administrative data for the certificate). Nothing 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?

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds 'Operación analítica de solo lectura' and 'No altera archivos,' which mostly restates the read-only annotation rather than adding new behavioral context such as authorization needs or output characteristics.

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 front-loaded with purpose and organized into clear sections for usage and behavior. It is efficient overall, though the behavior section largely repeats the read-only annotation and could 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?

Given the output schema exists and annotations cover the safety profile, the description provides sufficient context for calling the tool: purpose, regulatory context, and read-only behavior. It does not need to explain return values, but could be slightly richer about what kinds of anomalies or outputs to expect.

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 all four parameters are already documented in the input schema. The description reinforces the energy types and 12-month period, but does not add syntax, format, or interaction details 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?

States a specific verb (compara), resource (consumo real de energía de facturas vs consumo teórico CE3X), and scope (últimos 12 meses, electricidad/gas natural/gasóleo). It implicitly distinguishes itself from sibling calculation tools like calcular_calificacion_energetica by focusing on validation and anomaly detection rather than producing the rating itself.

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?

Includes an explicit 'Cuándo usar' section tying invocation to the RD 390/2021 validation and invoice contrast procedure. It gives clear context but does not state when not to use it or name alternative sibling tools for related tasks.

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?

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds genuinely new context: it is analytical, requires no CE3X connection, and does not write to disk, which tells the agent it can be called standalone.

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 and then cleanly sectioned into usage and side effects; every sentence earns its place. The header labels add slight overhead but improve scanability for an agent.

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 simple three-parameter lookup with full schema coverage and an output schema that already documents the returned climate zone. The description covers purpose, timing, and side effects, so nothing needed to call it correctly is 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?

Schema description coverage is 100%, so the schema already documents provincia, municipio, and altitud_m. The description only restates that these three inputs drive the lookup, adding no syntax, format, or lookup-behavior detail beyond the schema. 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 (Determina), the exact resource (zona climática CTE DB-HE oficial), and gives concrete example outputs (C1, D3, A3, E1). It also pins the authority (Apéndice B del CTE), so an agent can distinguish it from the many other calculation siblings 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?

The 'Cuándo usar' block is explicit: invoke mandatorily before estimating transmittances or computing the energy rating, to fix winter/summer climate severity. Clear context, though no alternatives or when-not conditions are named.

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?

Annotations already declare readOnlyHint and idempotentHint, and the description reinforces this ('operación analítica... Read-Only. No altera archivos') and adds that it performs economic and normative evaluation producing a report. It does not contradict annotations and adds mild context, but repeats the read-only fact the annotation already carries.

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 purpose followed by clearly labeled 'Cuándo usar' and 'Comportamiento y efectos secundarios' sections. Every sentence earns its place with no redundancy or 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description covers purpose and usage adequately; only sibling differentiation and richer behavioral detail are missing, which are minor given the structured data available.

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 all six parameters (tipo_acs, paquete_mejora, zona_climatica, superficie_util, ano_construccion, tipo_calefaccion) are documented in the schema itself. The description adds no syntax or format detail beyond that, 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 (Genera) and concrete deliverables (informe técnico justificativo y dictamen oficial de cumplimiento) plus the regulatory scope (RD 853/2021, IRPF 40%/60%). This is far more specific than a tautology, though it does not explicitly contrast itself with similar siblings such as generar_certificado_completo.

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 'Cuándo usar' section gives an explicit trigger: justifying compliance with the 30% non-renewable primary energy reduction requirement to process public aid. However it names no alternatives or when-not conditions, so the agent gets context but no routing guidance against sibling tools.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description's 'Comportamiento' section largely restates this ('operación analítica de solo lectura... no altera archivos ni estado persistente'), adding little beyond the annotations. It omits output detail and any handling of edge cases such as years outside the tabulated regimes.

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 core purpose, then clearly delimited sections for when-to-use and side effects. The explicit 'Read-Only' restatement is slightly redundant given annotations, but structure and ordering are strong and the text is appropriately sized.

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 read-only analytical tool with an output schema and 100% schema coverage, the description supplies everything an agent needs: what is computed, the normative basis, when to prefer it, and which sibling to use instead. Return values need not be described since an output schema exists.

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%, with both parameters documented (zona_climatica with CTE DB-HE examples, ano_construccion with Catastro/writing examples). The description adds contextual meaning by linking ano_construccion to the historical regulatory bands, but duplicates rather than extends the schema's own documentation.

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 (estimar) and resource (transmitancias térmicas de fachadas, cubiertas, suelos y huecos) and even enumerates the regulatory regimes (NBE-CT-79, CTE-HE-2006/2013/2019) that define the output. This clearly distinguishes it from sibling tools like registrar_ensayo_flujometria_termica_in_situ and calcular_puentes_termicos.

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 'Cuándo usar' section gives the triggering condition (no in-situ flujometría testing and no known construction reports) and explicitly routes the agent to the alternative ('registrar_ensayo_flujometria_termica_in_situ') for real measurements. Nothing 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write nature is known. The description adds real value beyond that: it is an on-disk file generation operation, specifies the exact artifacts written, states they go to the specified output directory, and notes interactive progress is emitted to FastMCP. It stops short of mentioning overwrite/collision behavior when files already exist, which is the main remaining risk for a 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?

Front-loaded with the deliverables sentence, then labelled sections for usage and side effects, which makes it scannable. It is somewhat long and the 'Comportamiento' section partially restates what the write annotation already implies, keeping it just short of a 5.

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?

An output schema exists, so return values need not be described, and all parameters are covered by the schema. The description supplies the usage trigger and the disk-write side effects an agent needs. Only minor gaps remain (no note on overwriting existing output files or expected runtime), so it is near-complete rather than fully complete.

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%, with all 12 parameters documented including defaults and units (m², rango 1800-2050, formato de CP de 5 dígitos). The description adds no parameter-level meaning beyond what the schema already provides, so the baseline 3 for high coverage 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?

Names a specific verb (genera) plus the exact resource and enumerates the three official deliverables with their formats and versions (.cex para CE3X v3.2, XML v3.0 validado con xmlcheck.exe, PDF de 15 páginas con Typst/xml2cert.exe). This distinguishes it from siblings like certificar_desde_carpeta_visita or calcular_calificacion_energetica without needing to open any 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?

The 'Cuándo usar' section gives an explicit trigger: invoke as the final phase of certification after validating envelope, climate and installations data. That is clear context for invocation. It does not, however, name or exclude a concrete alternative sibling (e.g. certificar_desde_carpeta_visita), 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?

Annotations only say readOnlyHint=false / destructiveHint=false, so the description carries most of the load and does so well: it distinguishes the read-only action ('estadisticas') from the two mutating ones ('purgar_expiradas', 'vaciar_todo') and names the affected store. It stops short of warning that 'vaciar_todo' discards all cached entries (including unexpired ones) and forces slow re-fetching, and it sits in tension with destructiveHint=false.

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?

Well front-loaded and organized under labeled headings ('Cuándo usar', 'Comportamiento y efectos secundarios'), which makes it scannable. There is mild redundancy: the opening sentence and 'Operación de mantenimiento del sistema de caché local' restate the same idea, and the Read-Only note partly duplicates what the action list already conveys.

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 two-parameter maintenance tool with an output schema (so return values need no explanation) and full schema coverage, the description supplies everything needed: what is managed, the underlying store, TTLs, when to use it, and which actions mutate. Nothing an agent needs in order to invoke it correctly is 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?

Schema description coverage is 100%, so the schema already documents both parameters, their defaults and allowed values (baseline 3). The description adds meaning beyond the plain enumeration by assigning semantics to each 'accion' value (read-only vs. purge), though it says nothing about the 'categoria' selector, which is left entirely to 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?

States a specific verb+resource ('Gestiona el subsistema de caché persistente SQLite local') and pins down the concrete scope: the ~/.ce3x_mcp/cache.db file, Catastro entries (TTL 30 días) and PVGIS entries (TTL 90 días). No sibling tool touches cache management, so there is little risk of confusion, but the description never explicitly positions itself against alternatives, which keeps it just short of a 5.

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 explicit 'Cuándo usar' block gives two concrete triggers: inspecting occupied space / hit-miss rate, and invalidating old entries to force a fresh telematic reload. It gives clear context for use but names no exclusions or alternative tools (e.g. re-querying via consultar_catastro instead of purging), so no 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is known. The description adds meaningful context by clarifying that it is a write/organize operation that moves files within the indicated folder without deleting content. It does not discuss permissions, error handling, or rate limits.

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 front-loaded with what the tool does, then clearly sections 'Cuándo usar' and 'Comportamiento y efectos secundarios.' Every sentence is relevant and the structure aids quick scanning.

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?

Given the simple input schema, the presence of an output schema, and annotations, the description covers purpose, when to use it, and side effects. Nothing essential for an agent to invoke it correctly is 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?

There is only one parameter and schema description coverage is 100%, so the schema already documents ruta_carpeta fully. The description mentions 'carpeta indicada' but adds no syntax or format details beyond what the schema provides, making 3 the appropriate baseline.

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+resource: creates a standard 5-folder structure and automatically classifies existing files by extension and metadata. It even names the canonical folders, making the operation unambiguous and easy to distinguish from sibling tools like auditar_carpeta_visita.

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 explicitly says when to use the tool: at the start of the documentary workflow after downloading visit files, and before certification run auditar_carpeta_visita. It provides clear sequencing context but does not state when not to use it or name an alternative tool for the same task.

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?

Annotations already declare readOnlyHint and idempotentHint, so safety is covered structurally. The description adds useful context beyond that: it specifies analytical/financial computation, that no files on disk are modified, and that interactive progress is emitted to FastMCP. The 'Read-Only' phrasing partly restates the annotation, capping it below 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 purpose followed by clearly labeled sections ('Cuándo usar', 'Comportamiento y efectos secundarios'). Efficient overall, with only minor redundancy where 'Read-Only' overlaps the readOnlyHint annotation.

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 an output schema present, return values need not be explained, and the description correctly focuses on purpose, usage and side effects. It is complete enough for correct invocation, though it could specify the relationship to the downstream Anexo III workflow more concretely.

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 five parameters (superficie_util, ano_construccion, tipo_acs, zona_climatica, tipo_calefaccion) with defaults and ranges. The description mentions the computed outputs but adds no per-parameter meaning beyond the schema, matching the baseline 3.

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 and resource ('Genera automáticamente los 3 paquetes de medidas de mejora') and enumerates exactly what those packages are (SATE, Aerotermia, Solar FV). It also differentiates from the sibling tool 'emitir_dictamen_subvenciones_nextgen', 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?

The 'Cuándo usar' section explicitly instructs preceptive invocation for every existing-building energy certificate to complete Anexo III, and names the alternative tool for the NextGen subsidy audit case. Both the when-to-use and the disambiguating alternative 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?

Annotations already declare readOnlyHint and idempotentHint, and the description largely restates this ('Read-Only', 'no altera archivos ni estado persistente'). It does add value by naming the normative calculation basis (UNE-EN ISO 9972) and the derived quantities, but says nothing about edge cases such as validation of the 50 Pa measurement or handling of degenerate geometry.

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?

Well front-loaded with labeled sections (Cuándo usar, Comportamiento y efectos secundarios) and no filler sentences. Minor redundancy between 'Read-Only' and 'no altera archivos ni estado persistente', which say the same thing twice.

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 an output schema present, the description needn't explain return values, and it correctly covers purpose, trigger condition, and safe behavior. Complete enough for a 3-parameter read-only calculation tool, though it omits any note on input validity ranges or expected output units.

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 all three required numeric parameters are documented with units and exclusiveMinimum constraints. The description mentions the computed outputs but does not map them back to the inputs or add format guidance beyond the schema, so the schema does the heavy lifting.

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 (procesa/calcula) and resource (ensayo de estanqueidad al aire Blower Door bajo UNE-EN ISO 9972), and names the exact outputs produced: n50, q50 y tasa de infiltración para CE3X. This clearly distinguishes it from the sibling registrar_ensayo_flujometria_termica_in_situ, which is a different test.

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 'Cuándo usar' block gives an explicit trigger condition: use it after a Blower Door pressurization/depressurization test to replace CE3X's default infiltration rate with the measured value. It lacks any explicit exclusion or named alternative for when a test has not been run, but the context is 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?

Annotations already declare readOnlyHint and idempotentHint, and the description usefully reinforces that 'registrar' is an analytical normative calculation rather than a persistence write, plus states the output's purpose (official U for insertion into CE3X). It adds context beyond the annotations, though it does not discuss assumptions or limits of the calculation.

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 core purpose, then organized under clear 'Cuándo usar' and 'Comportamiento' headers. Slightly verbose but every section carries information; no filler sentences.

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 an output schema present, return values needn't be described, and annotations cover the safety profile. The description supplies purpose, precondition, and behavioral framing, leaving only minor gaps such as handling of invalid or short measurement windows.

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 five parameters, including units, defaults, and the 72 h ISO minimum. The description adds no parameter-level syntax or format detail beyond what the schema provides, so 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 (Registra/calcula) and resource (ensayo in situ de flujometría térmica con termoflujómetro y sondas), naming the governing standard ISO 9869-1 and the outputs U and R. It is clearly distinguishable from siblings like registrar_ensayo_estanqueidad_blower_door and estimar_envolvente_por_defecto.

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 'Cuándo usar' section gives an explicit precondition: direct in-situ measurements with a heat flow meter to certify a historic wall's real transmittance. It implicitly contrasts with the default-estimation path ('sin necesidad de estimarlo por defecto') but never names the sibling tool, so it stops short of full routing guidance.

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?

Annotations declare readOnlyHint=false and destructiveHint=false, and the description corroborates this while adding value: it labels the operation as a Write and discloses the concrete side effect of generating the Anexo IV acta and writing it to disk. It stops short of noting overwrite behavior, permissions, or what happens on repeated calls for the same certificate.

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-loads the purpose sentence and uses clear labeled sections ('Cuándo usar', 'Comportamiento y efectos secundarios'), which an agent can parse quickly. There is mild redundancy between 'obligatoria', 'preceptiva' and 'exigida' that could 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?

An output schema exists, so return values need not be described. Combined with 100% schema coverage, annotations indicating a non-destructive write, and the description's legal scope plus disk-write side effect, an agent has everything needed to call this correctly.

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%, with each of the three parameters documented in the schema itself (format YYYY-MM-DD, examples of pruebas and observaciones). The description adds no additional parameter-level meaning, 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 ('Registra formalmente la visita presencial') and grounds it in the legal instrument (Art. 8 RD 390/2021, Anexo IV). This clearly distinguishes it from the cluster of sibling tools that organize, audit, or certify from the visit folder, so an agent can select it 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?

The 'Cuándo usar' section gives an explicit trigger condition: invoke mandatorily for every certificate of an existing building to accredit the technician's on-site visit. It does not, however, name alternatives or state exclusions (e.g. new-build certificates, or whether a prior organizar_carpeta_visita step is required), so routing vs. siblings is left partly 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered; the description does restate 'solo lectura (Read-Only)', which is mildly redundant. It adds genuine value by specifying that it inspects the local filesystem 'sin alterar configuraciones ni registrar escrituras', clarifying the touch surface beyond the annotations.

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?

Well front-loaded and clearly sectioned ('Cuándo usar', 'Comportamiento y efectos secundarios'), with the purpose stated first. Slightly padded by the read-only restatement that duplicates the annotations, but overall efficient.

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?

An output schema exists, so return values need not be described, and annotations cover the safety/idempotency profile. Purpose, invocation timing, and side effects are all present, leaving nothing critical for an agent to call it correctly.

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% with a single parameter whose description already documents the autodetect default path. The tool description adds no syntax or format detail beyond the schema, 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?

Specific verb (verifica/testea) plus resource (instalación y conectividad con CE3X v3.2), and it enumerates the exact artifacts checked (ejecutables, motores climáticos, validador XML RelaxNG, escalas oficiales). Among siblings it is clearly the diagnostic/verification tool, distinguishable from transactional tools like generar_certificado_completo or gestionar_cache_ce3x.

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 gives an explicit when-to-use: 'durante el arranque inicial o en pruebas de diagnóstico del entorno'. This is clear context but it names no alternative tool and states no when-not conditions, 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.