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

The description discloses the READ-ONLY behavior explicitly, which is a useful behavioral trait. However, no annotations are provided, so the description carries the full burden. It doesn't disclose what happens with invalid paths, whether concurrent calls are safe, or performance characteristics of scanning a large codebase. The READ-ONLY disclosure is valuable but the behavioral picture is incomplete.

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 dense run-on sentence that packs a lot of information. It front-loads the primary purpose and lists deliverables. It could be broken into shorter sentences for readability, but every phrase contributes meaningful context and there's minimal wasted text.

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 that the tool takes a single well-documented path parameter and has only one input, the description covers the essential scope well. However, there is no output schema and the tool returns a complex structured inventory (OData datasources, sections, bound fields, value helps, actions, OData calls), so the description could specify more about the return format, data shape, or any assumptions. For a complex output-producing tool with no output schema, the description could do more.

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% and there is only one parameter (appPath) with a clear description ('Legacy UI5 app root path'). The description reiterates what the schema says about appPath being the root path containing webapp/. The description adds the scope of analysis (manifest, XML views, controllers, i18n) which gives the parameter context, but since there's only one well-documented parameter, 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?

The description clearly states the verb ('analyzes'), the resource (legacy freestyle UI5 app), the mode (READ-ONLY), and enumerates the specific inventory items returned (OData datasources, sections, tables, columns, bound fields, value helps, actions, OData calls). It distinguishes itself from siblings by focusing on analysis/inventory for migration, which is unique among the listed tools.

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 description explicitly states when to use it: 'Use it as the starting point to migrate to modern CAP/Fiori.' It also names complementary tools to use alongside (cap_project_context and conventions://cap knowledge), providing clear guidance on sequencing within the migration workflow and distinguishing its role from related 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?

With no annotations provided, the description carries the full burden of disclosure. It does well: it discloses that it loads db/data CSVs, that it requires @cap-js/sqlite, and critically that the throwaway database is deleted afterwards (side effect disclosure). It does not detail error/return behavior, but for a validation tool the key side effects are well covered.

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, zero waste. Every sentence earns its place: what it does, what it catches vs compile, and the prerequisite plus cleanup behavior. Front-loaded with the verb and purpose, then layers constraints and side effects efficiently.

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 validation tool with no output schema, this is quite complete. It explains the tool's role in the validation pipeline (third layer), its inputs, prerequisite, and cleanup behavior. It could mention the success/failure signaling (how the agent learns validation passed), but that may be obvious from deployment semantics.

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 the single projectPath parameter already documented as 'CAP project root path with @cap-js/sqlite available'. The description reinforces the requirement that @cap-js/sqlite must be present in the project but adds minimal additional meaning beyond the schema. Baseline 3 is appropriate given high schema coverage.

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 clearly states the verb (deploys), the resource (model to a throwaway sqlite database), and its specific role as a 'third CAP validation layer'. It explicitly distinguishes from the sibling `cds compile` tool by stating what it catches that compile cannot (CSV column mismatches, malformed data, duplicate keys). The title 'Test deploy' reinforces the primary action.

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 description implies this is a validation tool distinct from `cds compile` and the sibling `cap_validate`/'cap_lint', and it explicitly names a prerequisite (@cap-js/sqlite installed). However, it doesn't explicitly state when NOT to use it or name alternative tools as a fallback path, leaving some ambiguity around the validation layer ordering.

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?

The description states it runs `cds lint` via the @sap/cds eslint plugin and returns anti-patterns/best-practice warnings. It also discloses the prerequisite that @sap/cds must be installed. With no annotations provided, this covers the fundamental behavior but doesn't reveal details like execution time, output format, or failure modes when the plugin is missing.

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 compact sentences with no filler. Purpose, mechanism, value, and prerequisite are all packed efficiently. Front-loaded with the core purpose and position among validation layers.

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 tool with full schema coverage and no output schema, the description adequately explains the tool's purpose, mechanic, and value. It mentions what results to expect (warnings). Minor gaps: no description of what happens if @sap/cds is missing, and no guidance on severity levels of reported warnings.

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% and the single projectPath parameter is described as 'CAP project root path.' The description adds context that the tool operates on 'the project' but doesn't add beyond what the schema states. Given high coverage, 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?

The description gives a specific verb ('runs cds lint'), a clear resource (the project), and positions it as a 'second validation layer' that catches things cds compile does not. It's clear, though it doesn't explicitly contrast with sibling cap_validate or ui5_lint to sharpen differentiation.

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 clearly states when to use (after compile, as a second validation layer) and the prerequisite (@sap/cds installed). While it doesn't explicitly name alternatives or say 'use cap_validate for X instead,' the positional framing provides adequate 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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It clearly states the tool compiles the project to CSN (implying it reads/parses the codebase) and returns a 'digest', but does not disclose whether it modifies anything, performance for large projects, or failure behavior for invalid CAP projects. The read-only nature is implied by 'returns a digest' but not stated explicitly.

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, zero waste. The first sentence lists exactly what the digest contains, the second gives an imperative usage directive. Every word 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 tool with one well-documented parameter, an informative output-carrying description, and no output schema, this is adequately complete. It covers what the tool does, what it returns (content of digest), and when to call it. The only minor gap is not describing error/edge cases (e.g., empty project, invalid CSN), but for a context-gathering tool this is a reasonable level of detail.

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% for the single parameter (projectPath), and the schema already describes it as 'CAP project root path'. The description doesn't add additional meaning about the parameter beyond what the schema states, landing at the baseline 3 given full schema coverage.

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 ('Compiles the real project to CSN and returns a digest') and clearly states the resource ('existing model: services, entities, fields with types and keys, associations and compositions'). It distinguishes from siblings by framing itself as the pre-generation context-gathering tool, which complements rather than overlaps with generator tools like cap_scaffold_entity.

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 description explicitly states WHEN to use it ('Call it BEFORE generating code') and WHY ('so you reuse what exists instead of inventing fields or entities'). This creates a clear usage directive that no other sibling tool claims, giving the agent actionable guidance on sequencing.

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. It discloses the key behavioral trait that the tool only 'Returns the content' (i.e., it does not write files itself), which is critical for agents to avoid wrongly assuming side effects. It also transparently enumerates all generated artifacts, giving a clear expectation of output scope.

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 sentence that front-loads the tool's purpose and enumerates the output artifacts without waste. Every clause adds information: what is generated, the conventions applied, and the workflow follow-through. No filler or repetition of schema details.

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 generative tool with no output schema, the description adequately communicates what will be returned (content for four artifact types) and how to proceed. It could explain return format/structure further, but given schema coverage is complete and the description names the follow-up tools, it is reasonably complete for a scaffold generator.

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 thoroughly documents all 6 parameters. The description adds value by clarifying how fields map to generated output (inList -> UI.LineItem, managed -> cuid+aspects) and noting the fields array excludes the technical ID key, which reduces ambiguity beyond what the bare schema provides.

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 clearly states the verb 'Generates' with a specific resource ('complete scaffolding of a CAP entity') and enumerates precisely what is produced (CDS model, service projection, annotations.cds, mock CSV, i18n). It differentiates from siblings by naming downstream tools (cap_write_files, cap_validate), showing the tool is a generator, not a writer or validator.

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 description implies usage by noting the generated content should be written with cap_write_files and validated with cap_validate, effectively contextualizing the workflow. However, it doesn't explicitly state when NOT to use this tool or name alternatives like cap_analyze_legacy_ui5 or ui5_scaffold_section, leaving the exclusion boundary 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?

No annotations are provided, so the description carries the burden. It discloses that the tool runs cds compile and returns errors, and frames it as a non-mutating validation operation ('A clean compile means the scaffolding is valid'). It doesn't detail what happens to the project, whether cds compile has side effects, or what the error format looks like, but the read-only validation nature is reasonably clear.

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, tightly written, no filler. The opening 'The validation loop' sets framing, and the second sentence explains the concrete action. Every sentence serves a purpose, though slightly repetitive between the two opening 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 only one parameter (fully covered by schema), no output schema, and no annotations, the description is fairly complete for a simple validation tool. It explains purpose, outcome interpretation (clean compile = valid), and the fixing loop. Gaps: no mention of sibling cap_lint differentiation and no detail on error format. For a low-complexity tool with 1 well-documented param, this is adequate but not rich.

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 parameter projectPath is fully documented in the schema ('CAP project root path with @sap/cds available'). The description adds the behavioral nuance that the compile requires @sap/cds availability, which the schema already notes. The description doesn't add meaning beyond the schema, 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?

The description clearly states what the tool does: 'Runs cds compile on the project and returns the errors so the agent can fix them.' It identifies a specific verb (runs/validate), resource (CAP project/compile), and purpose (validation loop). It distinguishes from siblings like cap_scaffold_entity or cap_lint through the compile/validation purpose, though it doesn't explicitly name difference from cap_lint.

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 description implies usage in a validation loop during scaffolding work ('The validation loop. Runs cds compile... so the agent can fix them'). It says a clean compile means scaffolding is valid, giving context on when it's needed. However, it doesn't explicitly say when NOT to use it or name alternative validation tools like cap_lint, which could overlap.

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 provided, the description carries the full burden. It discloses that folders are created when missing and that multiple files can be written at once. However, it does not explain whether existing files get overwritten, whether there are any file-type restrictions, or what happens on partial failure (e.g., if one file write fails, are others rolled back?). The description is adequate but missing behavioral edge cases.

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 short, functional sentences with no filler. The first sentence states the core action and the second adds a meaningful behavioral detail. Every word 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 file-writing tool with 100% schema coverage and no output schema, the description covers the basics: what it does, where it writes, and folder creation. However, it lacks information about overwrite behavior and error handling for a write operation, which could be significant for a tool that modifies project state. It is functional but could be more 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 already fully describes both parameters (files: array of relPath/content objects relative to projectPath; projectPath: CAP project root). The description adds the folder-creation behavior but no additional parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate given full schema coverage.

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 ('Writes one or more files into the given CAP project') plus a useful detail about creating missing folders. It clearly distinguishes from siblings like cap_validate and cap_lint (which are analysis tools) and cap_scaffold_entity (which generates entities). However, it doesn't explicitly differentiate from other write-capable tools like ui5_scaffold_section.

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 description implies usage context (writing files into a CAP project) and indicates the projectPath expectation. There is no explicit when/when-not guidance or mention of alternatives. The sibling context makes the intended use reasonably clear, but there are no explicit exclusions or alternative recommendations.

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 discloses the dependency precondition (@ui5/linter installed, ui5.yaml present) which is genuinely useful. However, it does not describe the output format, whether it writes any files, whether it's a read-only analysis, or how it handles missing dependencies (error vs graceful degradation). For a read-oriented monitoring tool this is acceptable but not rich.

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, efficiently packed. It front-loads the core purpose, adds the differentiating capabilities, and closes with prerequisites. Every clause earns its place. Could arguably be trimmed slightly, but the 'Third UI5 validation layer' framing is valuable for sibling differentiation. 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?

For a single-parameter lint tool with no output schema, this description is reasonably complete. It names prerequisites (external dependency, yaml file), scopes its scope (UI5 2.x migration issues specifically), and notes what it does NOT cover (view validation). The main gap is describing the return format/results structure, but lint tools commonly return a report, so an agent can reasonably infer behavior. Solid for its complexity level.

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% and there's only one parameter (appPath). The description adds a small detail — that it's the 'UI5 app root path (where ui5.yaml lives)' — which slightly enriches the schema description by tying it to the yaml requirement. However, it's basically restating the schema's own wording. With single-param at full coverage, 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?

The description clearly states this is a linting tool ('runs SAP's official ui5lint') on the app, specifying exactly what it returns ('deprecations and anti-patterns'). It also distinguishes itself from sibling tools (cap_lint, ui5_validate_view) by framing itself as the 'Third UI5 validation layer' and explicitly noting it catches things 'that view validation does not catch' (obsolete APIs, deprecated libs, CSP). This provides strong differentiation from sibling lint/validation tools.

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 description gives explicit usage context: it's the third layer beyond view validation, targeting UI5 2.x migration readiness. It explicitly names prerequisites ('Requires @ui5/linter installed in the app and a ui5.yaml at the root'), which helps the agent decide when this tool is usable. The contrast with 'view validation' alternatives is clear enough to guide selection among libs.

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 of behavioral disclosure. It clearly states the tool is non-mutating (it 'returns the content' for review rather than writing files), and actually informs the generated code (SmartTable in table mode, SimpleForm in form mode). It names the write step as a separate tool, making the no-mutation behavior explicit. Some details like output format are implied but not stated.

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, zero waste. Every clause carries information: the pattern delivered, the mode variants, i18n handling, handler stubs, and the explicit return-then-write-then-validate workflow. Highly compressed without losing specificity.

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 scaffold generator with no output schema and no annotations, the description covers the key behaviors: what it generates, why its safety (non-mutating, returns for review) matters, and the required follow-up tools. It fully compensates for missing annotations on the mutation/safety front. The main shortfall is not explicitly describing the exact return format, though 'Returns the content' gives reasonable clarity.

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 documents all 6 parameters well. The description adds meaning by explaining the mode semantic ('table = SmartTable of an association; form = SimpleForm of fields' is from schema, described). The description itself adds mode-to-component mapping context beyond basic schema, but most parameter semantics are carried by the schema, 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?

The description states a specific verb ('Generates') with a precise resource ('an ObjectPage section for a freestyle UI5 app') and describes the concrete pattern delivered: fragment with uxap:ObjectPageSection, SmartTable or SimpleForm, dotted i18n keys, handler stubs, i18n lines. It clearly distinguishes from siblings like ui5_validate_view and cap_write_files by naming them explicitly as downstream steps.

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 description gives explicit workflow guidance: 'Returns the content so you review it, write it with cap_write_files and validate it with ui5_validate_view.' This clearly tells the agent when to use this tool (scaffold generation) and explicit next steps, implicitly distinguishing it from validation (ui5_validate_view) and writing (cap_write_files) tools in the sibling set.

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 burden. It discloses what the tool checks (XML well-formedness and event handler existence in controller) and that it returns failures. However, it doesn't describe side effects (read-only nature), what happens on malformed paths, or failure behavior detail. For a validation/read tool this is moderate transparency.

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 that states purpose, scope, and output value. It is efficient with no filler. Could arguably add sibling differentiation but is appropriately compact.

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 complexity (validation tool, 2 params, no output schema, no annotations), the description covers the core purpose and output but omits: whether controllerPath is truly optional, the exact return structure, and how it relates to ui5_lint. For a tool meant to drive an agent fix loop, slightly more detail on output format would help.

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 both parameters (xmlPath, controllerPath) are documented. The description clarifies that xmlPath must be a .view.xml or .fragment.xml and that controllerPath must implement the handlers, which adds context beyond raw schema text. But it doesn't mention that controllerPath appears optional (not in required list), leaving ambiguity.

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('validates') plus the resource ('UI5 view/fragment'), and clarifies the scope: checks XML well-formedness and all declared event handlers exist in the controller. It doesn't explicitly differentiate from siblings like ui5_lint, but the 'validation loop' terminology and event-handler focus distinguish it somewhat.

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 description implies 'run this to validate UI5 views and get failures to fix,' and notes it returns failures for the agent to fix. However, it doesn't explicitly state when to use this vs ui5_lint or cap_validate, nor any exclusions. The guidance is implied rather than explicit.

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