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

The readOnlyHint annotation already declares this is a safe read operation, so the bar is somewhat lowered. The description does add value beyond the annotation: it discloses token efficiency ('7-30x fewer tokens'), compression behavior ('returns compressed dependency contracts, not full source'), and filtering behavior (SAP standard objects filtered out). However, it does not describe the return response shape or what happens when KTD is unavailable, and the guardrail error behavior is only mentioned in the schema action text, not the top description. It's adequate but not rich.

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 dense and front-loaded with the critical scoping sentence first. The 'Decision rule' section uses bullet-free line breaks for scannability. It's reasonably complete but does get long, with some redundancy between the top description and the action field descriptions in the schema (e.g., the impact description appears in both places nearly verbatim). A tighter version could trim the duplicated impact enumeration while keeping the sibling-tool comparisons.

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 is genuinely complex — 12 parameters, 4 actions with action-specific parameter meanings (depth means different things per action, maxResults has different defaults per action) — the description is remarkably complete. It covers the decision matrix, cross-tool sequencing, token-cost tradeoffs, and specific per-action return semantics. It points to a docs page (docs_page SAPContext) for full detail. There's no output schema, so the description carries the burden of explaining what's returned, which it does well for each action bucket.

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 each parameter's schema already has a detailed description. The tool description adds meaningful context on top: it explains the interplay between parameters (e.g., includeIndirect for transitive usages), and provides '7-30x fewer tokens' as motivation for depth/deps defaults. It documents the conditional requirements (type required unless impact/usages, group required for FUNC) that the schema alone doesn't fully convey semantically. This clearly exceeds the base-3 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 has a very specific verb+resource: 'Primary tool for understanding ABAP/CDS objects before specs, reviews, explanations, or changes.' It clearly distinguishes from the sibling SAPRead by saying 'use instead of SAPRead when the user asks what an object does' and explicitly says to use SAPRead after for exact source/method bodies/grep/drafts. The action enumeration (impact/deps/usages/structure) maps clear verbs to concrete behaviors, further differentiating it from siblings like SAPNavigate and SAPQuery.

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?

Provides an explicit decision rule mapping user question phrasing to the correct action: 'What breaks if I change <CDS>?' → impact, 'What does <object> do?' → deps, 'Find all callers' → usages. It names the alternative (SAPRead) and the exact sequencing ('Use SAPRead after SAPContext'). It also states exclusions — non-DDLS input returns a guardrail error for impact, and prefers impact over text-scanning SAPQuery. This is exemplary when/why/when-not guidance.

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

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.

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

The description adds significant context beyond annotations: it discloses which sub-actions are local vs. remote (calling SAP), that the 'set' for formatter settings is 'blocked read-only', and that lint_and_fix auto-fixes issues and returns fixed source. Annotations provide readOnlyHint=false and destructiveHint=false, but the description adds richer behavioral detail about the mixed local/remote execution model and the blocked set 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 compact and front-loads the core purpose in the first sentence before enumerating actions. The bullet list is scannable. Slight length from the detail on actions and their parameters, but each sentence earns its place and covers genuinely useful information.

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?

With no output schema, the description carries the burden of explaining what each action returns, which it does (fixed source for lint_and_fix, rules+config for list_rules). It covers the required parameter (action), the six actions thoroughly, and relevant tool boundaries. Minor gap: it doesn't specify the return shape of the lint/format actions beyond lint_and_fix, but the overall coverage is 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 which actions require which parameters (e.g., 'source needed for format', 'not needed for list_rules/get_formatter_settings', style/indentation are 'for set_formatter_settings'). This goes beyond the bare schema descriptions and clarifies parameter-to-action relationships.

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 'Run local abaplint rules on ABAP/CDS source' with a specific verb (run), resource (ABAP/CDS source), and explicit action categories for each sub-command. It distinguishes itself from siblings by explicitly noting 'For ATC/syntax/unit tests use SAPDiagnose'.

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 explains both when to use each action (lint, lint_and_fix, list_rules, format, formatter settings) and what each does. It explicitly calls out that lint/lint_and_fix/list_rules run locally while format and formatter settings call SAP, and names the alternative tool SAPDiagnose for ATC/syntax/unit tests. This is exceptional guidance.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=true. The description confirms this by listing mutating actions (create_package, delete_package, FLP write, set_api_state) and notes that mutating actions require 'writable safety config and write scope in authenticated mode.' This adds context beyond annotations without contradiction.

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 somewhat verbose but well-structured with a clear high-level statement followed by bullet points for actions. Every sentence adds value, though it could be slightly more concise.

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?

For a complex tool with 23 parameters, nested objects, and no output schema, the description covers major actions, prerequisites, and return format (features + systemType). It explains 'available: false' as a guard for dependent operations. However, it lacks full output schema details.

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 baseline is 3. The description adds value by explaining defaults for apiState and contract, and context for object types. It does not detail every parameter but provides meaningful guidance for key parameters.

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 'Probe and report SAP system capabilities' and enumerates specific actions (features, probe, cache_stats, package lifecycle, FLP management, set_api_state). It distinguishes from sibling tools like SAPRead and SAPSearch by focusing on management and probe actions.

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 explicitly advises using the features action before operations depending on optional features. It also outlines when to use each action (e.g., package lifecycle for DEVC, FLP actions for tiles, set_api_state for API contracts). However, it does not provide explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds behavioral detail: references uses a scope-based Where-Used API, objectType filters by ADT slash type with bare-prefix behavior, and hierarchy returns superclass+interfaces+subclasses. However it doesn't disclose edge cases like authentication requirements, error conditions, or what happens when neither uri nor type+name is provided.

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 reasonably tight, front-loaded with the four actions, and each sentence adds value. The CDS recommendation sentence is slightly long but necessary for sibling differentiation. No wasted prose.

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?

For a 9-parameter navigation tool with no output schema, the description covers the main behavioral surface: what each action does, the scope-based references approach, filtering behavior, and a strong sibling alternative. Some gaps remain (e.g., what definition/completion return, line/column handling), but the core guidance is present and actionable.

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 baseline is 3. The description adds value by explaining the bare-prefix matching behavior for objectType ('A bare prefix matches every subtype'), the maxResults default/cap semantics, and the type+name-as-uri-alternative pattern for references. These go beyond the literal schema texts.

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 navigates code with four specific actions: definitions, references, completion, and class hierarchy. It distinguishes itself from siblings by mentioning SAPContext for CDS views specifically, giving some differentiation though not for all sibling tools (SAPSearch, SAPLint etc.).

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 explicit when-to-use guidance, notably recommending SAPContext(action='impact') as an alternative for CDS (DDLS) where-used queries — a clear when-not-here, use-this-instead directive. It also explains when to pass type+name instead of uri for references, which is actionable usage guidance.

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

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

The description discloses many behavioral traits beyond the readOnlyHint annotation, such as caching behavior with force_refresh, token-efficient grep, and how version parameter works with drafts. It also explains limitations like on-prem only types and truncated packages. No contradictions 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 very long (600+ words) and dense with details. While it is well-structured and front-loads the purpose, it could be more concise. However, for the complexity of the tool, the length is justified.

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 complexity (23 parameters, many object types, no output schema), the description is remarkably complete. It covers all major behaviors, parameter combinations, and edge cases (e.g., deprecated aliases).

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?

With 100% schema coverage, baseline is 3. The description adds meaning by explaining interactions between parameters (e.g., method vs include for CLAS, grep vs method) and providing usage examples, which goes beyond the schema 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: 'Read SAP ABAP objects — exact raw source, a method body, grep output, inactive drafts, revision history, or metadata.' It uses specific verbs and resources, and distinguishes from sibling tools like SAPContext by recommending it for intent-level context.

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 explicit guidance on when to use this tool versus alternatives, e.g., 'prefer SAPContext first (intent-level context before raw source).' It also advises on token-saving strategies for CLAS (method="*" or grep) and explains on-prem only types.

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

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

Annotations only declare readOnlyHint=true, so the description carries the transparency burden. It discloses the db source requires 'sql scope and SAP_ALLOW_FREE_SQL=true', explains the 'splitBrain' array behavior when sources disagree, notes BOR objects appear as SOBJ, and covers how uri/objectType feed other tools. This is strong behavioral disclosure beyond the read-only hint.

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 front-loaded with the core purpose, then organized into numbered modes with a tips section. It's dense but every sentence adds value — no wasted words. Slightly long but appropriately so for a multi-mode tool with nuanced behaviors.

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?

For a tool with 7 parameters, no output schema, and readOnly-only annotations, the description covers the purpose, all modes, parameter semantics, cross-tool integration (uri feeds SAPNavigate, objectType feeds SAPRead/SAPWrite/SAPActivate), and edge cases (orphan/ghost rows, splitBrain). Nothing critical is unexplained for an agent to select and invoke correctly.

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?

Though schema coverage is 100%, the description adds substantial meaning: it clarifies searchType 'object' is default and tadir_lookup does exact cross-package lookup, explains query applies comma/whitespace-separated names for tadir_lookup, details the source enum values (adt uses info-system endpoint, db uses SQL against TADIR), and explains objectTypes for multiple type filters. Each parameter's behavior is enriched beyond the schema.

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 'Search for ABAP objects, exact object-directory entries, or source code' and enumerates two distinct modes (object search default, tadir_lookup). It distinguishes itself from siblings by explicitly stating searches object NAMES only and directing field-name searches to SAPRead/SAPQuery, clearly differentiating from associated 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 provides explicit when-to-use guidance: prefer tadir_lookup over 'long SAPQuery TADIR IN-lists', and directs users away for field-name searches ('for field names use SAPRead... or SAPQuery on DD03L'). It also explains when source='db' is advantageous (surfaces orphan/ghost rows) versus the adt default.

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

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

The description fully discloses behavioral traits beyond annotations. It details destructive actions (delete, release, remove_object) with sub-options (recursive, removeLockedObjects), explains create's inference of transport type, and notes read-only actions (history, layers, targets). No contradiction with annotations (destructiveHint=true).

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 efficient and front-loaded, immediately stating the tool's purpose and actions. While long, every sentence adds value. Could be slightly more structured (e.g., bulletized actions), but it remains clear and concise for the complexity.

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 (16 parameters, 11 actions, no output schema), the description is complete. It covers actions, parameters, prerequisites (e.g., for target), side effects (e.g., delete with removeLockedObjects), and error conditions. It also mentions response characteristics for key actions (e.g., 'The response reports the resolved transport target' for create).

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%, but the description adds significant context beyond the schema. For example, it explains the 'target' parameter's forms and restrictions, and notes that the 'action' parameter's description includes behavioral details for each value. Baseline 3; extra context justifies a 4.

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 as managing CTS transport requests (SE09/SE10). It lists 11 specific actions, each with a distinct verb and resource. The sibling tools (SAPRead, SAPSearch, etc.) are different in scope, making this tool well-differentiated.

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 explicit guidance for each action, including when to use each (e.g., 'list: show transports (defaults to current user, modifiable only)') and context like using summary=true for cheaper list operations. It does not explicitly state when not to use this tool, but the distinct sibling tools make it clear. Minor omission: no direct comparison to alternatives.

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