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

The description goes well beyond the readOnlyHint and idempotentHint annotations by detailing the analysis behavior: two parsing passes, diffing, separate reporting of pre-existing broken code, snapshot-dated released-API observations, and explicit limitations (static, parser-level, not exhaustive, no ATC, verdict not certification). This gives the agent an accurate mental model of what the tool does and does not do.

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 long single paragraph, but nearly every clause carries a distinct piece of information: purpose, method, output categories, use cases, limitations, and an example. It is dense rather than padded, though a shorter front-loaded summary could make it slightly easier to scan.

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 tool's moderate complexity, an output schema, and 100% parameter schema coverage, the description supplies the crucial non-schema context: what the verdict means, what is excluded, the example invocation, and the separating of baseline vs cloud findings. An agent has everything needed to invoke it correctly and interpret results.

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 input schema already defines files, source, filename, baselineVersion, its enum, default, and limits. The description adds useful context on how baselineVersion participates in the two-pass diff and gives an example call, but that is supplementary; the schema carries the parameter semantics.

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 opens with a specific verb and resource: 'Assess how far ABAP source is from ABAP Cloud', and immediately explains the two-pass parsing and diffing method. It distinguishes itself from siblings by describing its static parser-level nature and explicitly separating cloud blockers from broken code, so an agent can tell it apart from check_released_api or lint_abap.

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 provides explicit use triggers: 'when someone asks is this code cloud-ready / Clean Core compliant / S/4HANA-cloud safe, before porting classic ABAP into an ABAP Cloud environment, or for a graded tech-debt assessment of an abapGit export.' It also warns when not to trust it: not exhaustive dependency discovery, no SAP connection, no ATC, verdict is not certification. However, it never names sibling alternatives for those other cases, so the guidance stops short of fully explicit 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 indicate read-only and idempotent behavior, and the description adds meaningful context beyond that: the tool ships offline, uses a specific snapshot date (2026-08-24), does not connect to any SAP backend, and does not modify any system or source file. This gives the agent an accurate safety and freshness 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?

The description is dense but well organized: it front-loads the object types and result categories, then provides the offline/snapshot constraint, the use case, and the sibling distinction. Every sentence conveys a distinct, necessary fact with 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?

For a lookup tool with one input and a known set of output statuses, the description is complete: it covers accepted object types, result categories, CDS successor hints, data source/snapshot, offline behavior, non-mutating behavior, and the relationship to check_cloud_readiness. The output schema handles detailed return structure, so the description does not need to duplicate it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'objects' is already fully described in the input schema, including the 1–200 limit, bare string vs object forms, examples, and optional disambiguation types. The description adds no additional parameter-level syntax or format details, so the schema carries 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?

The description states a specific verb and resource: "Look up ABAP repository objects ... in SAP's published ABAP Cloudification list" and reports per-object status ('released', 'deprecated', 'not-released') plus a CDS successor hint. It also differentiates itself from the sibling check_cloud_readiness, so an agent can tell them apart.

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 a clear when-to-use: "when you need to know if your code may reference a given object in ABAP Cloud, or which released CDS view to use instead of a classic table." It also names the relevant alternative, check_cloud_readiness, and explains how this tool complements it, though it does not explicitly state when not to use the tool.

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 and idempotentHint, and the description adds meaningful behavioral context beyond that: it explains matching by content (moved-but-unchanged code is not noise), explicitly notes that it does not connect to any SAP system, and highlights a limitation ('behavior can change while every number improves'). This is valuable disclosure beyond the structured 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 well-structured and front-loaded: it starts with the main functionality, then usage guidance, then exclusions, ending with an illustrative example. Every sentence adds necessary information without repetition or fluff, and the length is justified by the tool's complexity.

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?

The description covers purpose, usage context, limitations, and provides an example. Since the tool has an output schema, the description does not need to detail return values. The mention of reuse of check_cloud_readiness logic and the explicit exclusions round out the context, making the description complete for an agent to select and use the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the input schema already documents all parameters with descriptions. The description adds an example call that illustrates the structure of 'before' and 'after' arrays, but it does not provide any additional parameter semantics that are not already in the schema. Therefore, a baseline score 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?

The description opens with a specific verb and resource: 'Compare a BEFORE and an AFTER version of ABAP source' and enumerates the exact kinds of results (lint findings, cloud-blocker/score/grade movement, structural changes). It explicitly differentiates itself from a textual diff tool ('use git diff to see the edits'), making it clear what this tool does and does not do.

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 provides explicit usage contexts: 'Use this when reviewing a refactor, a modernization step or an AI-generated rewrite' and gives exclusions: 'It is not a textual diff tool' and 'cannot judge functional equivalence.' It also mentions that it uses the same diff as check_cloud_readiness, linking to a sibling tool without confusion.

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 read-only and idempotent; description adds domain boundary (abaplint only) and states it does not run analysis. Useful context beyond annotations, though not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Three sentences, front-loaded with purpose, followed by usage and scope limitation, ending with a concrete example. Every sentence is informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter read-only tool with output schema, the description covers purpose, usage, and limitations sufficiently. No need to detail return values due to output 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 covers the single parameter with examples; description's example is redundant. No additional semantic meaning beyond schema, so 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?

States it explains one abaplint rule in depth, listing included elements (title, description, rationale, tags, docs URL, examples). Distinguishes from siblings by referencing lint_abap/check_cloud_readiness findings. Clear verb+resource+scope.

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?

Explicitly says 'Use this when a lint_abap or check_cloud_readiness finding needs justification' and notes it does not run analysis and excludes SAP ATC documentation. Provides clear when/when-not 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?

Even with readOnlyHint/idempotentHint annotations present, the description adds substantial behavioral context: fixes are applied in "verified batches" where each batch is re-parsed and any parse-breaking batch is discarded, so "the output is parser-guaranteed, never guessed". It discloses that unfixed findings surface in `remaining`, and that it "does not invent rewrites (only fixes abaplint defines)". The pure-function framing (source in → corrected code out) is consistent with readOnlyHint=true, so there is no contradiction.

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 long but every sentence earns its place: core action first, then the verification mechanism, the unfixed-findings contract, when to use, what it does not do with named alternatives, and a working example. There is no redundancy or filler; the structure flows logically from what → how → when → when-not → example.

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 an output schema exists, the description need not document return values, yet it still pre-announces the `remaining` field. It covers scope (files, up to 32 per call via schema), the correctness guarantee, exclusions, sibling routing, and an example — complete for a 4-parameter tool with nested objects and two enums. Nothing an agent needs 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 baseline is 3. The description adds value beyond the schema by giving a concrete invocation example ("fix_abap({ "files": [ { "source": ... } ] })") and by illustrating fix categories (keyword casing, MOVE → =) that help an agent anticipate what the `files`/`rules` parameters will produce. It does not elaborate on preset/abapVersion semantics, but the schema already documents those fully.

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 and resource — "Apply abaplint's own machine-applicable corrections to ABAP sources and return the corrected code" — and names the mechanism (deterministic, batched abaplint fixes). It explicitly distinguishes from siblings: "is not a formatter (format_abap pretty-prints without changing statements)" and points cloud-blocker work to plan_cloud_migration. An agent can tell exactly what this tool does and what it is not.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use guidance: "Use this when someone highlights code and wants it corrected to best practices / modern syntax instantly, as the mechanical first pass before any AI rewriting, or to modernize a file before review." It also gives when-not-to-use with named alternatives — cloud blockers needing re-architecture go to plan_cloud_migration, and formatting goes to format_abap. 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, so the safety profile is covered. The description adds useful context beyond that: it does not change any logic, fails cleanly on unparseable source, and is an offline equivalent of Pretty Printer in ADT/SE80. This extra behavioral detail goes 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 three sentences, each earning its place: purpose, usage guidance with exclusions, and a concrete example. It is front-loaded with the core purpose and contains no filler or redundant phrases.

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 moderately simple tool with an output schema and good annotations, the description is complete. It covers what the tool does, when to use it, what it deliberately does not do, failure behavior, and includes an example. The sibling tools are clearly distinguishable.

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?

The input schema already provides rich descriptions for both parameters (source and filename), including filename inference behavior. The description's example demonstrates the 'source' parameter but does not add new semantics for 'filename' beyond what the schema already states. With 100% schema coverage, 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?

The description clearly states the verb+resource: 'Pretty-print one ABAP source' with specific details about normalizing keyword casing and indentation. It also differentiates from siblings by noting it is the offline equivalent of ADT/SE80 Pretty Printer and explicitly excludes CDS views and behavior definitions.

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 usage guidance is provided: 'Use this when generated or hand-written ABAP has inconsistent casing/indentation and you want it normalized before review or commit.' It also lists exclusions (CDS views, behavior definitions, logic changes) and gives a concrete example, making the intended use very 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 adds critical behavioral context: it does not return method bodies, does not analyze code quality, and produces empty outlines for CDS/behavior files. It also explains the optional mermaid output. This goes well beyond the annotation bare minimum.

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 longer than a one-liner but each sentence earns its place: purpose, usage scenario, mermaid option, limitations, and an example. It's structured with a clear progression and no fluff, though it could arguably be trimmed slightly.

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?

The description fully covers the tool's scope, constraints (no method bodies, empty CDS), usage context, and provides an example. With an output schema present, no return-value detail is required. This is a complete package for an AI agent to decide when and how to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (both params have descriptions), so baseline is 3. The description adds value by providing a concrete usage example and explaining the mermaid flag's purpose ('for documentation visuals'). The example clarifies the expected input shape, which is helpful beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Return the structural outline') and enumerates exactly what it covers (classes with methods/visibility/attributes/interfaces/inheritance, interfaces, FORM routines). It distinguishes itself from siblings by contrasting with lint_abap, making it clear this is a structural navigation tool, not an analysis 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?

It directly states when to use it ('when navigating a large class or legacy program to decide which part to read or edit next') and positions it as a 'cheap first call.' It explicitly names the alternative for code quality (lint_abap) and calls out CDS/behavior-definition files as yielding empty outlines, so the agent knows when not to rely on it.

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

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

Annotations already provide read-only, closed-world, and idempotent hints. The description adds crucial limitations beyond that: it only sees the text passed, textual edges miss dynamic calls, and absence of an edge is not proof of independence. This gives a clear mental model without contradiction.

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 dense but well-structured: purpose, node/edge derivation, optional Mermaid output, usage, limitations, and example. Every sentence earns its place, though it is slightly long; still it is front-loaded with the most important intent.

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 safety and idempotency, the description covers all necessary usage context: what it analyzes, how edges are derived, when to use, limitations, and an example. Nothing an agent needs 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 covers all parameters with descriptions (100% coverage), and the description adds a concrete example invocation and clarifies filename inference rules (e.g., omitting filename infers type from source). This exceeds baseline but doesn't deeply elaborate each parameter beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Build a dependency graph') on a specific resource ('provided ABAP sources') and clearly frames it for migration sequencing and impact reading. It distinguishes itself from siblings by naming plan_cloud_migration as a companion and explicitly contrasting with a where-used list.

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?

Explicitly lists when to use (deciding migration order, rework impact, pulling non-released tables) and when not (it is not a where-used list, cannot see dynamic calls, absent edge is not proof of independence). Points to authoritative alternatives like system where-used and ATC.

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 read-only and idempotent, but the description adds significant context: fully offline, no ATC, cannot judge undefined objects unless provided, and preset behavior differences. It also explains focus tags and rule overrides. No contradiction with 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 dense but well-structured: purpose first, then when to use, limitations, preset semantics, focus/overrides, alternative, and an example. Every sentence conveys distinct information—no filler or repetition. The length is justified by the tool's complexity.

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 tool's 5 parameters, nested objects, enums, and output schema, the description covers all critical aspects: input types, limits (via schema), return value contents, preset meanings, and the boundary case (check_cloud_readiness). It even includes an example, making it self-contained for an agent.

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% (all five parameters have descriptions), but the description adds meaningful semantics beyond the schema: explains why the default preset skips whole-program checks, how focus packs work with rule overrides, how filename omission triggers type inference, and includes a concrete invocation example that maps 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?

The description starts with a specific verb and resource: 'Run abaplint static analysis over ABAP, CDS or behavior-definition sources' and clearly states the output (structured findings). It distinguishes from siblings by naming check_cloud_readiness as the alternative for migration verdicts, and the detail about offline operation further differentiates it from system-connected 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?

Explicit use case: 'Use this when you have written or modified ABAP code and want style and correctness feedback before it goes anywhere near a system.' It provides exclusions (does not connect to SAP system, does not run ATC) and presets with scenario guidance (style for isolated snippets, full when all dependencies provided). It names an alternative tool for a different intent.

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, but the description adds further transparency: it is a 'read-only catalog' that does not run analysis or alter configuration. It also describes the optional filtering behavior (free-text query or tag) and the example call. This goes beyond the annotations without contradicting them.

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 tightly packed: first the action, then when-to-use, then safety/exclusion, then an example. Every sentence earns its place, with no fluff or repetition of schema field names. It is front-loaded and concise for the level of detail provided.

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 tool has an output schema (though not shown), the description already mentions return fields. Both parameters are covered, usage guidance is explicit, and safety behavior is disclosed. For a read-only listing tool, this is fully complete—an agent can confidently 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 coverage is 100%, but the description enriches param understanding by explaining 'tag' as an abaplint tag with examples and 'query' as a case-insensitive substring matched against specific fields. It also provides a concrete invocation example, which is more than the schema alone. This meaningfully aids correct parameter usage.

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 opens with the specific verb+resource: 'List the abaplint rules this server can check'. It clearly distinguishes from siblings like lint_abap (which runs checks) and explain_abap_rule (which explains a single rule). It also enumerates the return fields (key, title, one-line description, tags, documentation URL), leaving no ambiguity about what the tool does.

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?

Explicitly states when to use: 'Use this when deciding which rules to enable or override in lint_abap, or to discover what a Clean-ABAP-style check exists for.' It also says what it does not do: 'It does not run any analysis and does not change configuration', which clarifies when not to use it (e.g., for actually running linting). Sibling tool lint_abap is named as the alternative.

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 goes well beyond the readOnlyHint and idempotentHint annotations by disclosing that the tool is a deterministic re-arrangement, does not modify any code, does not estimate effort in person-days, and inherits every readiness limitation such as static parser-level analysis and snapshot-dated released-API data. This gives an agent an accurate model of side effects and reliability without relying on annotations alone.

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 dense but every sentence earns its place: it front-loads the primary outcome, enumerates the phase ordering, gives concrete selection guidance, states limitations, and provides an example. For a tool with this much behavioral nuance, the length is justified and well-structured, not padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich annotations, full input schema coverage, and existing output schema, the description still adds essential context: the relationship to check_cloud_readiness, deterministic non-mutating behavior, inherited limitations, phase semantics, and an invocation example. An agent has everything needed to decide when to call it and what 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 the baseline is 3: the schema already fully documents files, filename inference, maxItems/minItems, and baselineVersion semantics. The description adds a concrete usage example and some context around phases, but it does not materially improve parameter understanding beyond what the schema already 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 opens with a specific verb and resource — 'Turn ABAP sources into an ordered, phased ABAP Cloud migration backlog' — and clearly distinguishes this tool from check_cloud_readiness by stating it arranges blockers into work items rather than returning raw findings. It names the exact deliverable (per-object work items, phases, exit criteria) so an agent can tell what this tool produces.

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 states when to use this tool: when someone asks 'plan the migration', 'what do we tackle first', or wants a work breakdown instead of raw findings, and frames it as 'the natural next call after check_cloud_readiness'. It also names the sibling alternative and clarifies what the tool does not do (estimate person-days, modify code), giving clear selection 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 readOnly and idempotent, and the description adds valuable behavioral detail beyond that: generated skeletons fail loudly via cl_abap_unit_assert=>fail('TODO …'), edge cases (abstract classes, parameterized constructors) get guidance, and the output is round-tripped through abaplint. This fully informs the agent of the tool's operational traits without contradicting 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 a single dense paragraph that front-loads the core purpose, then covers key behaviors, exclusions, and an example. Every sentence carries information—no filler or redundancy. For a tool with this complexity, the length is justified and well-structured.

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 tool's complexity (generating test harnesses with specific constraints) and the presence of an output schema, the description covers all necessary context: what it produces, how it handles edge cases, what it deliberately avoids, and how it validates output. An agent has everything needed to 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% (both parameters are described in the schema). The description adds a complete invocation example with the files parameter and clarifies the 100k chars limit (implied via schema's maxItems but reinforced). It doesn't repeat parameter definitions but adds usage context, which is appropriately helpful beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Generate the local ABAP Unit test-class include' for each global class. It clearly differentiates from siblings like scaffold_rap_bo (which targets RAP business objects) and lint/fix/format tools, so an agent can select it without ambiguity.

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 guidance: 'Use this when a class has no tests yet' and it positions the tool as the natural first step in TDD. It also states exclusions—does not invent assertions/test data, does not create test doubles, cannot run tests—and gives a concrete example invocation, leaving no doubt about when to use it.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true, and the description does not contradict them. The description adds useful behavioral context: round-trip validation via abaplint, that behavior/service definitions are canonical templates not deeply parsed, and ADT activation as the final check. This goes beyond the annotations to set expectations on quality and limitations.

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 long but densely informative—every sentence contributes: artifact list, usage, exclusions, validation, example. It is well-structured with a clear opening scope, conditional notes, and a concrete example. Not perfectly concise but appropriately detailed for a complex code-generation 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?

The tool generates many artifacts and has an output schema; the description covers generated artifacts, potential caveats (validation depth, binding/table not created), next steps, and an example. With 7 parameters and an output schema, this description is enough for an agent to select and invoke correctly, and to interpret the result.

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 has 100% parameter description coverage, so baseline is 3. The description adds value through a concrete example that illustrates parameter usage and relationships (entityName, sqlTable, keyField, fields, draft), and clarifies defaults (e.g., prefix Z, admin fields auto-added). This supplements the schema without redundancy.

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?

Description uses a specific verb ('Generate') and details the exact resource ('the complete, canonical RAP managed business-object stack for one root entity') with an explicit list of artifacts. It clearly distinguishes from sibling tools (lint/format/check) and states its scope in the first sentence.

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 usage guidance is provided: 'Use this when starting a new RAP business object in ABAP Cloud or S/4HANA' and contrasts with hand-writing. It also states exclusions ('does not create the table or the service binding', 'single-entity BOs: model compositions (parent-child) yourself'), giving clear when-to-use and when-not-to-use signals.

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