SAPDiagnose

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

Even though annotations only provide readOnlyHint=false and destructiveHint=false (which the description correctly aligns with by flagging write-scoped actions like trace_start, trace_cancel, set_sql_trace_state), the description goes well beyond. It discloses critical side effects such as trace_start arming 'a profiler trace for the NEXT matching execution', the ST05 trace control needing SAP_ALLOW_WRITES, the read-only nature of cds_testcases/object_state/cds_sql, and odata_perf/authorization_trace needing allowDataPreview. It also discloses defaults (next HTTP request, SQL on, auto-expiry 24h) and dependencies like SAP_BASIS 8.16+ for cds_testcases. This adds genuine behavioral context beyond 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 long but appropriately so for a 21-action tool, and it's front-loaded with a clear mission statement and bullet-style action list. It ends with a workflow summary and pointer to a docs page. Each action line is terse and packs multiple facts. It's not minimal, but every line carries distinct information for a genuinely complex interface. Minor deduct for density making it harder to scan for a specific action, though the logical grouping (diagnostics, traces, system info, CDS, auth) helps.

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 35 parameters, 21 enum actions, and no output schema to describe returns, the description is remarkably complete. It covers read/write scope, prerequisites (SAP_BASIS version, allowDataPreview, SAP_ALLOW_WRITES), defaults, dependencies between actions (quickfix→apply_quickfix, trace_start→traces), and unit-test coverage behavior. It even explains the coverage fallback when unavailable and the divergence flags for object_state. It's not a full 5 because a few actions (e.g., sql_trace_directory, atc_variants detail) get only one-line coverage, but for this complexity it's strong.

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 coverage is 100%, so the baseline is 3. The description adds value by mapping parameters to their relevant actions (e.g., 'proposalUserContent... pass proposalUserContent through exactly', 'sourceUri... use this for class includes such as /includes/definitions', trace_start's processType/objectType/match semantics, and traceUser defaulting to connected user). Key parameters like proposalUserContent's exact-pass-through requirement and the odata_perf host-relative path constraint are clarified beyond the schema. Some nuance is inherited from the schema, but the description earns the extra point by clarifying multi-action parameter semantics and edge cases.

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 clear umbrella statement ('Run diagnostics on ABAP objects and analyze runtime errors') followed by an exhaustive action-by-action breakdown covering all 21 enum values. Each action has a specific verb+object pairing (syntax-check, run ABAP Unit tests, quick-fix proposals), and the read/write scope is flagged per action, cleanly distinguishing it from siblings like SAPRead, SAPManage, and SAPWrite (mentioned at the end). This is exemplary purpose clarity for a complex multi-action tool.

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 repeatedly states when to use specific actions and marks read-only versus write scope (e.g., 'pre-write dry-run, nothing written', 'write scope', 'read-only'). It even provides a quickfix workflow: 'syntax/ATC → quickfix → apply_quickfix → write via SAPWrite', which flags when NOT to use this tool (final writes go to SAPWrite). It doesn't systematically contrast with each sibling, but for a 21-action tool this is strong practical guidance.

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