Read Message Class

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds a concrete return shape with optional fields (description?, language?, selfExplanatory?) and an example of how to locate a message by id. It does not mention error behavior or pagination, but the core read-only nature is clear. No contradiction with annotations.

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

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

The description is compact and well-organized into summary, args, returns, and examples. It is under 150 words and every section adds value. The only minor repetition is the response_format name without a type, but the schema covers it.

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?

Though there is no output schema, the description provides a clear return shape and examples. It leaves open how the default 'markdown' response_format renders (the return shape is shown as json only) and does not address large message sets or not-found cases. Given the tool's simplicity and annotations, this is adequate but not 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 description coverage is 100% and both parameters are documented. The description adds example name values ('ZFI_MSGS', 'VR') and clarifies post-processing ('look for id='001''). It does not significantly expand on the response_format semantics, so a 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?

States it reads all messages in an ABAP message class (T100 content + metadata). The verb 'read' and resource 'ABAP message class' are specific and distinct from sibling tools like sap_get_text_elements. Examples clarify the exact object ('ZFI_MSGS').

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 shows example queries and how to map them to the 'name' parameter, which implies when to use it. However, it never explicitly contrasts this tool with alternatives or lists conditions where another sibling (e.g., sap_get_text_elements, sap_read_table) would be preferred. So usage guidance remains implicit.

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