SAPContext

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.