abap_journal

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

Beyond the destructiveHint annotation, the description discloses critical behavioral details: undo refuses on drift, delete-gate, or enhancement objects, and force overwrites other server changes with an explicit 'Read the object first' warning. This is exactly the extra safety context an agent needs for a destructive operation.

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 uses a compact mode-by-mode breakdown. Every clause adds information, and the pointer to a recovery reference is appropriately brief.

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 seven parameters, no output schema, and only destructiveHint as an annotation, the description carries a large burden—and it succeeds. It explains all three modes, entry requirements, undo safety constraints, the force overwrite risk, and where to find more details. Nothing essential 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?

The input schema already covers all parameters with descriptions, so the baseline is 3. The description adds cross-parameter semantics, especially the meaning of mode values, the relationship between entry/object, and the force behavior. That added context lifts it 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?

The description opens with a specific verb and resource: 'History and undo for writes abapsmith made.' It then enumerates three distinct modes (list, show, undo) with concrete purposes, making it clear what the tool does and how it differs from the broader abap_* sibling tools.

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

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

The description gives clear usage context for each mode: list for recent writes, show for a before-image, undo for reverting. It also warns about conditions where undo refuses to run. It does not explicitly name sibling tools as alternatives, so it loses a point, but the mode-based guidance is strong enough for an agent to decide when to invoke it.

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