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 already declare readOnlyHint=true and idempotentHint=true, and the description adds context: it uses dual-parse diff, does not connect to SAP, and reports specific metrics. No contradictions; the description reinforces the safe, stateless 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?

Approximately 150 words, front-loaded with purpose, then details, exclusions, and an example. Every sentence adds value; no redundancy or fluff.

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 (6 params, nested objects) and existence of output schema, the description sufficiently covers inputs, output expectations, limitations, and usage context. It mentions error handling (parser errors always surface).

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 beyond schema by explaining how the tool works (dual-parse diff, content-matching to avoid noise) and what the output includes, though it does not elaborate on individual parameter syntax 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 clearly states it compares BEFORE and AFTER ABAP source, reporting lint findings, cloud-blocker/score/A-D grade movement, and structural changes. It distinguishes from siblings like check_cloud_readiness and git diff, with a specific verb and resource.

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 when to use ('reviewing a refactor, modernization step, AI-generated rewrite') and what not to use it for ('not a textual diff tool', 'cannot judge functional equivalence'). Provides an example call, giving clear 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. The description adds that the tool does not perform analysis and is limited to abaplint rules, providing clear behavioral context beyond 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?

Concise and well-structured: purpose first, then usage context, then limitations, then example. Every sentence adds value with no redundancy.

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 single-parameter schema, annotations, and presence of output schema, the description is fully complete. It covers all necessary information for an AI agent to decide when and how to invoke 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% with a clear description of the 'rule' parameter. The description adds an example usage (explain_abap_rule({ "rule": "exit_or_check" })), which adds practical value 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 clearly states it explains an abaplint rule in depth, listing specific elements (title, description, rationale, examples). It distinguishes itself from sibling tools like lint_abap and check_cloud_readiness by focusing on justification, not analysis.

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: 'when a lint_abap or check_cloud_readiness finding needs justification'. Also specifies what is out of scope: 'does not run analysis and only knows abaplint rules; SAP ATC check documentation is out of scope'.

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 indicate idempotent and read-only (safe transformation). Description adds that it does not change logic and fails cleanly, but could mention return format or error specifics. 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?

Three sentences with no wasted words. Front-loaded with purpose, immediately followed by when to use and a concrete 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 simple tool with full annotations and output schema, description covers purpose, usage, exclusions, and failure mode fully. No gaps identified.

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 both parameters with descriptions (100% coverage). Description adds context that filename can be inferred when omitted and includes a usage example, slightly augmenting 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?

Clearly states it pretty-prints ABAP source, normalizing keyword casing and indentation using abaplint's formatter. Distinguishes as offline equivalent of ADT/SE80 Pretty Printer, separate from sibling tools like lint_abap or explain_abap_rule.

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 tells when to use (inconsistent casing/indentation before review or commit), what it does not do (does not reformat CDS or behavior definitions, does not change logic), and failure behavior (fails cleanly on unparseable source).

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, idempotentHint, and destructiveHint is false. The description adds valuable behavioral context beyond annotations: it is a 'cheap first call,' does not return method bodies or analyze quality, and yields empty outlines for CDS/behavior-definition files. The mermaid option is also explained.

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 concise—about 6 sentences—and front-loaded with the main purpose. Every sentence adds value: purpose, usage guidance, limitations, parameter explanation, and an example. It could be slightly shorter, but it is well-structured and clear.

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 are present, the description is complete enough for this moderately complex tool. It covers what is returned (structural outline of classes, interfaces, FORM), limitations (no method bodies, CDS yields empty), and the optional mermaid output. No critical gaps remain.

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 little extra meaning beyond the schema: it repeats the mermaid option purpose and provides an example call, which is helpful but not significant. No deeper parameter semantics are introduced.

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 tool returns a structural outline of ABAP sources—listing classes, methods, visibility, interfaces, inheritance, and FORM routines—and explicitly differentiates from siblings by noting it does not return method bodies or analyze code quality. It also specifies that CDS/behavior-definition files yield an empty outline, leaving no 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?

The description provides explicit when-to-use guidance: 'Use this when navigating a large class or legacy program to decide which part to read or edit next; it is the cheap first call.' It also excludes alternatives: 'use lint_abap for' code quality analysis, and mentions CDS files produce empty outlines, helping the agent decide correctly.

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 indicate read-only and idempotent. The description adds critical behavior: runs entirely offline, doesn't connect to SAP systems, doesn't run ATC, and explains how presets affect semantic checks. No contradictions.

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 moderately long but well-organized. It opens with the core function and output, then usage conditions, limitations, parameter details, alternative tool, and an example. Each section is informative without redundancy, justifying its length.

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 (5 parameters, 3 enums, nested objects, output schema exists), the description covers all essential aspects: offline usage, preset behaviors, focus tags, rule overrides, file limits, and language version. It also mentions output structure. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'focus' tag as a themed review, 'preset' options in detail, and 'rules' as overrides. It also includes an example call, enhancing understanding 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 clearly states the tool's purpose: running abaplint static analysis on ABAP, CDS, or behavior-definition sources and returning structured findings. It specifies output fields and distinguishes from sibling check_cloud_readiness.

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 (after writing/modifying ABAP code for offline feedback) and when not to (for system-level checks like ATC or object existence). It provides guidance on presets and mentions an alternative tool for cloud readiness.

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 provide readOnlyHint, openWorldHint, and idempotentHint. The description reinforces this by stating 'it is a read-only catalog' and adds context that it does not run analysis or change configuration, which is helpful but not critical given 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?

Two sentences plus an example code block. Every sentence adds value: purpose, usage guidelines, and a concrete example. No unnecessary words.

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 simplicity, presence of an output schema, and complete annotations, the description covers all necessary aspects: purpose, filtering options, example, and what the tool does not do, making it 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 coverage is 100%, so the baseline is 3. The description adds an example usage with query parameter and explains the filtering concept, providing practical context beyond the schema descriptions.

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 'List the abaplint rules this server can check' which clearly states verb and resource. It specifies optional filters and return fields, distinguishing it from siblings like lint_abap (which runs analysis) and explain_abap_rule (which explains a specific rule).

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 'Use this when deciding which rules to enable or override in lint_abap, or to discover what a Clean-ABAP-style check exists for.' and clarifies 'It does not run any analysis and does not change configuration,' providing clear when-to-use and when-not-to-use 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?

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?

The annotation readOnlyHint=true contradicts the described behavior of generating code artifacts, which is a side effect. While the description adds some behavioral detail (validations, templating), the contradiction undermines trust. Score 1 due to 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 concise yet comprehensive, using front-loaded purpose, bullet-like listing of artifacts, and clear limitations. Every sentence adds value without redundancy.

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 7 parameters and an output schema, the description fully covers usage context: what is generated, when to use, limitations, validation steps, and an example. It leaves no critical gaps for an agent to understand invocation.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds minimal extra meaning beyond the schema, such as the example and clarifying generated artifact names. 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 the tool generates a complete RAP managed business-object stack for one root entity, listing specific artifacts (CDS view, behavior definition, handler class, etc.). It distinguishes from sibling tools like lint_abap or format_abap, which are not about code generation.

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 starting a new RAP business object' and provides exclusions: does not create table or service binding, single-entity BOs only. Includes an example call and mentions validation steps.

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