sap_read_shell_content

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

Annotations already declare this is a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower, and the description adds genuine behavioral context: content is only readable with the IE browser control, and the Edge control path (SAP GUI 7.70+ default) returns an explanatory `note` instead. This platform-dependent behavior is valuable disclosure beyond structured fields.

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?

Front-loads the purpose, then the platform caveat, then the prerequisite — a logical order. Three sentences with no filler, though the middle sentence is dense with parenthetical asides.

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?

An output schema exists (so return values like `note` need not be explained), and annotations cover the safety profile. The description adds the platform limitation and the ID-source prerequisite, making it largely complete for a one-parameter read tool, with only the ID format left implicit.

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 0% for the single `shell_id` parameter, so the description must carry the load. It partially compensates by pointing to sap_get_screen_elements as the source of valid IDs, but never describes the ID format or type, leaving a real gap for the only parameter.

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 (content from a GuiShell subtype such as HTMLViewer), which distinguishes it from sibling read tools like sap_read_field, sap_read_textedit, and sap_read_tree that target other UI element types. It does not explicitly name a competing sibling, so it falls just short of a 5.

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?

Gives a concrete prerequisite workflow: 'Use sap_get_screen_elements first to find shell element IDs,' and explains the runtime condition under which content is actually readable (IE control vs Edge control). It omits explicit when-not/alternative guidance for reading shell content versus other read tools, so it is clear context rather than a full routing rule.

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