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

With safety already covered by annotations (readOnlyHint, idempotentHint, openWorldHint=false), the description adds substantial behavior: it is static and parser-level, connects to no SAP system, runs no ATC, and its 'ready' verdict means no detected language-level blockers rather than certification. It also explains the grade is blocker density, not SAP's Clean Core Level A-D.

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

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

Purpose is front-loaded, then mechanism, outputs, triggers, limits, grade caveat and example follow in a logical order. It is dense and long with heavy nested clauses, so it is slightly oversized, but nearly every sentence carries actionable information.

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

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

For a static analysis tool with an output schema already defining return values, the description covers purpose, scope, limitations, grading semantics and routing to the authoritative check. 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 schema carries most parameter meaning. The description adds the two-pass framing that gives context to baselineVersion (v758 baseline vs Cloud) and to edition-based snapshot selection, reinforcing rather than merely repeating schema text.

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?

It gives a specific verb+resource (assess ABAP source distance from ABAP Cloud Clean Core tier 1) and even explains the mechanism (parse twice at baseline and Cloud, diff). It clearly demarcates itself from the sibling check_released_api by stating its released-API scan is separate from the language-level blocker count and not exhaustive dependency discovery.

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 states explicit triggers ('is this code cloud-ready / Clean Core compliant', before porting classic ABAP, for a graded tech-debt assessment of an abapGit export) and explicit non-uses (static/parser-level, no SAP connection, no ATC, not a certification). It also names the authoritative alternative (a target system's own ATC released-API check with specific variants), so the agent knows when to defer.

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/openWorld=false/idempotent, and the description adds substantial context beyond them: strictly offline, no SAP connection, no activation, no ATC, cannot see DDIC tables or pool classes, and the important caveat that unknown constructs are reported as info, never errors, because the grammar is corpus-derived.

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

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

Front-loads the purpose before usage, limits, siblings and example, and every clause carries information. It is dense and long for a single block of prose, but not padded with filler.

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

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

With an output schema present, return values need not be described; the description covers scope, offline limits, cross-file prerequisites, release gating, sibling routing and an example, which is complete for a self-contained static checker.

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 earns more by explaining the semantics of passing base BDEF and .ddls.asddls files (this is what activates the cross-file half of the rules) and what abapRelease gating does, with a worked example call.

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

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

States a specific verb (check) and resource (RAP behavior definitions .bdef.asbdef and CDS service definitions .srvd.srvdsrv), plus the defect classes it looks for. It explicitly distinguishes itself from abaplint and from sibling tools, so an agent can route to it without opening the schema.

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

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

Gives an explicit trigger ('when you have written or generated a BDEF/SRVD ... before it reaches ADT') and names the alternatives with their selection condition (lint_abap for classes, scaffold_rap_bo for new BOs, explain_abap_release for release history). It also states the required companion files (base BDEF, .ddls.asddls) that enable cross-file rules.

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

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

Annotations already cover safety (readOnly, idempotent, closed-world), yet the description adds substantial behavioral context beyond them: no SAP system connection, no ATC execution, tied to a specific bundled snapshot (edition s4hc, 2026-09-10), and the crucial caveat that 'absent from the list' means 'not-released as of the snapshot' rather than proof. That is exactly the kind of limitation an agent must know before trusting the result.

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

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

Front-loaded with purpose, classification states, then caveats and example, so nothing critical is buried. It is dense and long, and the tail listing of ATC variant names (ABAP_CLEAN_CORE_DEVELOPMENT / ABAP_CLEAN_CORE_READINESS) is more detail than an agent strictly needs, but nearly every sentence 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?

An output schema exists, so return-value explanation is unnecessary, and the description still supplies the classification vocabulary, successor-hint behavior, snapshot/edition scoping, and a call example. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so both the edition enum and the objects/name/type structure are already documented in the schema, including the per-edition difference caveat. The description reinforces edition semantics and supplies a worked example, but adds little meaning the schema does not already carry; baseline 3 applies.

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

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

Specific verb (look up/report) plus concrete resource (ABAP repository objects in SAP's Cloudification list) with the exact three-state classification spelled out. It explicitly distinguishes itself from the sibling check_cloud_readiness, so an agent can route without opening either schema.

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

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

States the triggering need ('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') and names the complementary alternative check_cloud_readiness plus its limitation. It also names the authoritative fallback (target system ATC check) and the conditions under which this lookup is insufficient.

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 readOnly/idempotent/closed-world, and the description goes well beyond them: it discloses that the tool does not connect to any SAP system, does not read release notes live, is a curated snapshot dated 2026-09-10, is not a complete changelog, and that the target system's notes remain authoritative. It also describes per-row fields and the meaning of the 'confirmed'/'reported' confidence flag, which the annotations cannot convey.

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

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

Purpose, when-to-use, caveats, alternatives and an example are all front-loaded in a logical order, and the example call is a useful close. It is delivered as one dense paragraph, which makes the caveats and sibling pointers slightly harder to scan than bulleted structure would be.

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

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

For a 5-parameter, zero-required lookup with an output schema, the description supplies everything an agent needs: scope, filter semantics, freshness/curation limits, confidence semantics, sibling routing and a concrete invocation. Return values are covered by the output schema yet are still summarized, leaving no material gap.

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 genuine intent beyond the schema: it explains that sinceRelease should be set to the customer's current level to see what an upgrade buys, and it explains why pre-2502 rows exist (to prevent mislabeling established features as novelties). The worked example further clarifies parameter interaction.

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 concrete verb ('Look up what changed') and enumerates the exact resource scope (ABAP Cloud, CDS, ABAP SQL, RAP, EML, ABAP Unit, ATC, tooling across named release trains). It explicitly carves out its niche against siblings by pointing to check_released_api and search_sap_knowledge for adjacent questions, so an agent can distinguish it without opening the schema.

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

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

It gives explicit when-to-use ('when you are about to write or review ABAP and need to know whether a feature exists in the target release'), concrete trigger scenarios (draft persistence, BUFFER ON, RAP change documents, side effects, feature-control attributes), and named alternatives with their selecting conditions (check_released_api for released-API state, search_sap_knowledge for Clean Core/ATC vocabulary).

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, idempotentHint and openWorldHint=false, so safety is covered by structured data. The description adds real value beyond that by disclosing the non-obvious post-condition that the markdown is only returned and must be pasted by the caller, and that it encodes the tool contract rather than project-specific conventions.

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

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

A single dense paragraph, but it is front-loaded with the artifact it produces and every clause afterwards carries distinct information (contents, when to use, exclusions, example). Slightly overlong, but no sentence is pure filler.

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

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

With an output schema present the description needn't explain return values, and it still covers what is produced, the usage triggers, the boundaries, and an example invocation. For a zero-required-parameter generator, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema documents each parameter's meaning, setting a baseline of 3. The description goes slightly further by giving a concrete example call ({ target: "Cloud", pairedWith: ["sap-adt-mcp"], runEnabled: true }) that shows how the settings combine, though edition and packagePrefix are not illustrated.

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

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

States a specific verb (Generate) and a specific artifact (the ABAP section of AGENTS.md / CLAUDE.md), then enumerates its contents. No sibling in the list produces rules documentation, so the agent can distinguish it immediately from list_abap_rules / 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?

Gives explicit trigger conditions ('when you set up a new ABAP repo for agentic development' or want team rules referencing abap-mcp tools) plus clear exclusions: it does not write the file, does not read the workspace, and is not a substitute for project conventions. 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 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?

Beyond the readOnly/idempotent annotations, the description discloses key limits: it only sees the passed text, textual edges cannot see dynamic calls, an absent edge is not proof of independence, and system where-used/ATC remain authoritative. This is exactly the behavioral context an agent needs.

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

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

Front-loaded with purpose, node/edge semantics, then caveats and a worked example. It is dense and long but each clause adds real information; the trailing JSON example is somewhat verbose but illustrative.

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

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

With an output schema present, return values need no explanation, and the description covers scope, semantics, limitations, edition sensitivity, and alternatives. Complete for this complexity.

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

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

Schema coverage is 100%, so the schema already documents files, edition, mermaid, and abapVersion thoroughly. The description adds only the conceptual framing (provided objects, optional Mermaid output) and an example, which is a baseline 3 when the schema does the heavy lifting.

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

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

Names a specific verb and resource (build a dependency graph over provided ABAP sources) and precisely defines both node and edge semantics, including edge tiers. This clearly distinguishes it from siblings like check_cloud_readiness or plan_cloud_migration.

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

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

Gives explicit use cases (deciding what to migrate first, impact of a rework, finding non-released tables), names the companion tool plan_cloud_migration, and states what it is NOT (a system where-used list). 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?

Goes well beyond the readOnly/idempotent/closed-world annotations: it discloses offline execution, no SAP system connection, no ATC, inability to resolve referenced objects, the semantic-check gap of the default preset, and the automatic RAP-check merge for .bdef/.srvd files with an opt-out. These are non-obvious behavioral traits an agent needs.

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

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

Purpose and return shape are front-loaded, and most sentences carry unique information. However, it is a dense single-block wall of text mixing purpose, constraints, presets, focus, overrides, and RAP handling, which could be better partitioned for scanning.

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

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

An output schema exists, so return structure needn't be re-explained, yet the description still summarizes findings. For a six-parameter tool with nested file objects it covers triggers, alternatives, preset trade-offs, the RAP merge edge case, and an example call, leaving no material gap.

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

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

Schema coverage is 100%, so the schema already documents all six parameters, setting a baseline of 3. The description adds real meaning on top: why preset "style" is the default, that focus is ignored under "syntax-only", how rule overrides layer onto presets and focus, and why rapCheck defaults true.

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

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

States a specific verb+resource (run abaplint static analysis over ABAP/CDS/behavior-definition sources) and what it returns (rule key, message, severity, file/line/column, offending line, docs URL). It explicitly distinguishes itself from siblings by naming check_cloud_readiness and check_rap_behavior and clarifying it is not ATC.

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

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

Gives an explicit trigger ("when you have written or modified ABAP code and want style and correctness feedback before it goes anywhere near a system") and routes alternatives ("For an ABAP-Cloud migration verdict use check_cloud_readiness instead"; "call check_rap_behavior for the full structured RAP report"). It also explains when each preset applies.

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?

Annotations already cover readOnly/idempotent/no-open-world, but the description adds substantial context beyond them: it is a 'deterministic re-arrangement', it 'does not modify any code', 'does not estimate person-days', and it inherits static/parser-level/snapshot-dated limitations with ATC remaining authoritative. This tells the agent exactly what to trust and what not to expect.

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

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

A single dense paragraph that is front-loaded with the core purpose and phase ordering before the usage cues and example. It is long, but nearly every clause carries distinct information (phase sequence, effort bands, limitations), with little pure padding.

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 planning tool with an output schema, the description fully frames the return structure (per-object work items with S/M/L bands, recipes, sample locations; phases with goals and exit criteria) and closes the loop on scope and limitations. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents files, edition, and baselineVersion, making 3 the baseline. The description adds meaning by tying baselineVersion to the 'repair-the-baseline' phase ('broken code is not migration work') and reinforcing the snapshot-dated released-API framing behind edition, so it earns a small lift above baseline.

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

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

States a specific verb+resource ('Turn ABAP sources into an ordered, phased ABAP Cloud migration backlog') and immediately distinguishes itself from the sibling it builds on: it 'runs the same dual-parse analysis as check_cloud_readiness, then arranges every blocker into per-object work items.' An agent can tell this apart from the readiness and lint tools without opening any schema.

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

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

Gives explicit triggers ('plan the migration', 'what do we tackle first', wants a work breakdown / task backlog instead of raw findings) and names the alternative ('the natural next call after check_cloud_readiness says rework is needed'). It also states when-not by contrasting with 'raw findings' from the analysis 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?

Goes well beyond the annotations: discloses that round-tripping through abaplint only proves the ABAP parses and not exact API-surface fidelity, that the constructor seam enables cl_abap_testdouble, and that manual ISLM/cockpit steps are returned in setupSteps because the tool has no SAP system, credentials, or network. No contradiction with readOnlyHint/idempotentHint/openWorldHint.

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 single dense paragraph front-loads the core action and the SDK disambiguation before the seven-shape enumeration. It is long, but nearly every clause carries substantive, non-redundant information; the length is the main cost against a 5.

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

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

For a generator with an output schema, the description covers scope, safety boundary, validation method, testing seam, and manual prerequisites, leaving nothing an agent needs in order to call it correctly unstated.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning for the interaction enum by explaining what each of the seven shapes actually calls (EXECUTE_FOR_STRING, the tool-call DO-loop, IF_AIC_ADT_COMPLETION_API, etc.) and notes that 'functions' is ignored for other interactions.

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

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

States a specific verb+resource: 'Generate one validated global ABAP class that calls the SAP Generative AI Hub through the ABAP AI SDK ... ISLM.' It explicitly disambiguates from a third-party SDK with a similar name and clearly differentiates from sibling scaffolders like scaffold_rap_bo and scaffold_abap_unit.

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

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

Gives explicit when-to-use ('adding a Generative-AI-Hub call to ABAP Cloud code ... instead of guessing') and when-not (no LLM call, no deploy/activate, no comm-arrangement or INTS/INTM creation). It does not route to a sibling alternative, so it stops just short of a full 5.

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

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

Annotations already declare 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?

Adds substantial context beyond the annotations: round-trip validation of classes and CDS views through abaplint at ABAP-Cloud level, while behavior/service definitions are canonical templates rather than deeply parsed, and ADT activation is the real final check. It also discloses the scoping limit (single-entity only) and the deferral of the service binding, which the readOnlyHint/idempotentHint annotations cannot convey.

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

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

Front-loaded with the artifact list and the trigger condition, and the limitations and example follow in logical order. It is dense and lengthy, but every sentence (validation scope, deferred artifacts, single-entity restriction) 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 7-parameter code-generation tool with an output schema already covering return values, the description supplies the trigger, the artifact inventory, validation guarantees, explicit non-goals, and a concrete example. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a full worked example invocation that shows how entityName, sqlTable, keyField, fields, and draft combine in practice — meaningful semantics beyond the schema's field-by-field text.

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

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

States a precise verb (Generate) and resource (complete canonical RAP managed business-object stack for one root entity), then enumerates the exact artifacts produced. An agent can distinguish it from scaffold_abap_ai_sdk, scaffold_abap_unit, or check_rap_behavior without opening any schema.

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

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

Explicitly names the triggering scenario ('starting a new RAP business object in ABAP Cloud or S/4HANA') and sets boundaries — it does not create the table or service binding, and only handles single-entity BOs, with parent-child compositions left to the caller. It does not name a competing sibling tool by name, which is the only gap.

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 openWorldHint=false, but the description goes well beyond them: it states it does not connect to any SAP system, does not run ATC, fetches nothing live, is a curated snapshot dated 2026-09-10, and that the target system and SAP docs remain authoritative. It also discloses the return shape (sources, confidence flag, full card). This is exactly the extra behavioral context annotations cannot carry.

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

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

Front-loaded with purpose, then usage, then exclusions, then an example call — the ordering is good and every sentence does work. The long parenthetical enumerations of card names and ATC artifacts are dense and a little bulky, which costs it a point, but they serve the routing job.

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

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

For a multi-area search tool with three params, full schema coverage, an output schema and rich annotations, the description covers scope, freshness, authority limits, exclusions and alternatives. Nothing needed to select or invoke it correctly is missing.

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

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

Schema description coverage is 100%, so area, limit and query are already fully documented in the schema, including the enum values and the 1-25 bound. The description adds no parameter-specific syntax or defaults beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource (search a dated, cited SAP knowledge bundle) and enumerates the three covered areas in enough detail that an agent knows the answer surface without opening the schema. It also explicitly distinguishes itself from factual-authority siblings by framing the tool as a curated snapshot rather than a live system.

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

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

Gives an explicit usage trigger ('when a question is about SAP facts rather than about a piece of source text'), concrete example questions, and explicit negative routing to four alternatives: explain_abap_release, check_released_api, lint_abap, and check_cloud_readiness. Both the when and the when-not are stated.

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