Browse BAdI Definition

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which the description complements. It adds behavioral context beyond annotations: the output may fall back to raw when parsing yields nothing, and the tool is open-world (try spot name). 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 organized clearly: a one-sentence purpose, Args, Returns, Examples, then Notes. It is front-loaded with the core action and distinguishes from siblings early. Every sentence adds value—no repetition or filler—and the structure makes it easy 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?

The description fully equips an agent to call the tool correctly: it defines return shape (even without a formal output schema), provides examples, notes the raw fallback, and directs to sap_get_source for source code. Given the read-only metadata nature and 100% parameter schema coverage, nothing important 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 schema covers both parameters with descriptions and examples (100% coverage), giving a baseline of 3. The description adds realistic example values in the Examples section and clarifies that response_format defaults to markdown in the schema, but the description does not restate the parameter details. These real-world examples help an agent pick appropriate values, so a 4 is warranted.

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 ('read') and resource ('BAdI definition') and enumerates the contents (interface, active implementations). The examples clarify real use cases and the name distinguishes it from sap_get_source, which reads implementation source. The purpose is unambiguous and well-defined.

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 'This reads definition metadata only. Use sap_get_source to read the actual implementation class source,' naming the alternative and the condition. Also advises trying the spot name if the BAdI name isn't found. This is clear, actionable guidance on when to use and when not to use this tool.

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