ARC-1

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by detailing what each action does (e.g., 'returns full dump detail including formatted text, error analysis, source code extract, and call stack'), which helps the agent understand outputs. However, it lacks information on permissions needed, execution time, rate limits, or whether actions are read-only vs. mutating (e.g., running unit tests might modify data). No contradiction with annotations exists.

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 with a clear purpose statement followed by bullet-point actions. Each bullet efficiently explains requirements and behaviors. However, the 'dumps' and 'traces' bullets are slightly verbose with nested explanations, and some redundancy exists (e.g., repeating 'Requires name + type'). Overall, it's front-loaded and most sentences earn their 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?

Given the tool's complexity (8 parameters, multiple actions) and lack of annotations/output schema, the description is adequate but has gaps. It covers actions and parameter usage well, but doesn't address error handling, response formats (beyond high-level details for dumps/traces), or side effects. For a diagnostic tool with no structured output, more guidance on interpreting results would improve completeness.

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 significant value by explaining parameter dependencies and semantics beyond the schema: it clarifies that 'name' and 'type' are required for syntax/unittest/atc, that 'id' omission triggers listing vs. detail modes for dumps/traces, and what 'analysis' enum values mean (e.g., 'hitlist = hot spots'). This compensates for the schema's generic descriptions.

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 tool's purpose: 'Run diagnostics on ABAP objects and analyze runtime errors.' It specifies the exact actions (syntax check, unit tests, ATC checks, dump analysis, trace analysis) and distinguishes this diagnostic tool from likely sibling tools like SAPLint (static analysis) or SAPRead (data retrieval). The verb+resource combination is specific and unambiguous.

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 clear context for when to use each action (e.g., 'Requires name + type' for syntax/unittest/atc, 'Without id: lists recent dumps... With id: returns full dump detail'). It implicitly distinguishes between list vs. detail modes for dumps/traces. However, it doesn't explicitly state when to choose this tool over siblings like SAPLint or SAPContext, nor does it mention prerequisites or exclusions.

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