Format ABAP source

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.