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

Annotations already say readOnlyHint=false and destructiveHint=false. The description adds real behavioral context beyond that: link-type items in SPRO trees trigger an activity, and the correct column is found via sap_read_tree. It doesn't say what happens after the click (popup, screen change), which keeps it from 5.

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?

Three short sentences: action first, execution scenario second, discovery pointer third. No filler and the key constraint is front-loaded.

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 needn't be described, and annotations cover the safety profile. The remaining gap is parameter meaning for tree_id/node_key and the post-click side effects, which are partially mitigated by the pointer to sap_read_tree.

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%, so the description must carry the load. It does explain item_name semantics (execute icon column, typically '2') and that valid columns are discoverable via sap_read_tree, but tree_id and node_key formats/origins are never explained, leaving two of three parameters undocumented.

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+resource: clicking a hyperlink item inside a tree node. It sits clearly apart from siblings like sap_select_tree_node or sap_expand_tree_node, though it doesn't explicitly contrast with sap_double_click_tree_item, which is the nearest neighbor.

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 usage scenario (SPRO/customizing trees, click the execute icon column) and names the prerequisite discovery step via sap_read_tree. It lacks an explicit 'do not use when...' clause, so it falls short of 5.

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 this is not read-only and not destructive, which is consistent with a UI state change. The description adds no behavioral context beyond the one-line purpose: it does not say whether the node must be visible or expanded, what happens if it is already collapsed, or what side effects occur.

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 a single front-loaded sentence with no wasted words. Its brevity is appropriate structurally, even though it is under-informative in other dimensions.

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 and the tool is a simple UI action, so the description need not explain return values. However, with two undocumented required parameters and no behavioral detail beyond the basic action, the definition is only minimally complete for reliable invocation.

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 0%, so the description must compensate, but it provides no explanation of tree_id or node_key. The parameter names are somewhat self-explanatory, but there is no guidance on acceptable values, how to obtain them, or formatting.

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 names a specific verb and resource: 'Collapse a folder node in a tree control,' and gives SPRO/customizing as a concrete example. It is clearly distinguishable from expand_tree_node by the word 'collapse,' though it does not explicitly mention that sibling or other tree-related alternatives.

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 no guidance on when to use this tool versus alternatives such as sap_expand_tree_node, sap_select_tree_node, or sap_read_tree. The use case is implied by 'collapse a folder node,' but there are no conditions, prerequisites, or exclusions.

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?

Goes well beyond the annotations by disclosing the credential resolution model (.env keys), the security rationale (passwords never appear in tool calls), and the override precedence with its exception for password. It does not state what happens on failed authentication or whether a new session/GUI instance is launched, which is the main remaining behavioral gap; output schema covers the return shape.

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?

Four short sentences, front-loaded with the action and the credential model, then routing. Minor line-break fragmentation in the first sentence but no filler content.

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 connect tool with an output schema and safety annotations already declared, the description covers credentials, override precedence, and sibling routing, which is what an agent needs to invoke it. Missing only failure-mode and session-lifecycle detail.

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 0%, so the description must compensate — and it largely does, mapping user/client/language to their .env counterparts and explaining that passed values override env defaults except password. It leaves the expected format of system_description (exact Logon Pad entry string) and of client/language codes implicit.

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 and resource — connecting to an SAP system identified by its Logon Pad entry name — and explicitly contrasts itself with the sibling sap_connect_existing. An agent can distinguish it from other connection tools without opening the schema.

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 an explicit when-not condition with the alternative named: 'If SAP is already open and logged in, use sap_connect_existing instead.' It also sets the precondition that a system name from SAP Logon Pad is required.

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?

Goes well beyond the read-only annotations by describing attached session types, index defaults, scripting-disabled restrictions, error behavior for ambiguous or missing named systems, and how the session is selected via dialog or index. These are material behavioral details an agent would not know from annotations alone.

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 core action and condition, then adds only relevant operational details. It is somewhat long, but the length is justified by the nontrivial selection and confirmation behavior.

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 a zero-description schema, an output schema, and read-only annotations, the description supplies all the operational context needed to invoke the tool correctly, including selection precedence, error conditions, and response field `chosen_by`.

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?

Despite 0% schema description coverage, the description explains all three parameters: the `system` format and its effect, the meaning of `connection_index` and `session_index`, and that indexes are ignored when `system` selects a session. This compensates fully for the absent 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?

States a specific verb and resource: connecting to an already open SAP session, with the condition that SAP is already logged in. It clearly distinguishes this from a fresh connection and names `sap_list_connections` as the source of indexes.

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?

Explains exactly when to use it, notes that `connection_index=0` and `session_index=0` target the first open session, and gives the `system` parameter as an alternative selector. It also covers exclusions such as connections with `scripting_disabled=true` and describes the attach confirmation behavior.

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?

Beyond the destructive annotation, the description explains exactly what is destroyed versus preserved: sessions opened by sap_connect are closed, while attached sessions and their /o windows are detached but left open. This is valuable behavioral detail that prevents accidental loss of user work.

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 front-loaded with the action in the first sentence, followed by a concise ownership rule. Every sentence adds useful scope information without repetition.

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 that there are no inputs, annotations declare destructive behavior, and an output schema exists, the description is complete enough to call the tool correctly. It supplies the critical session-ownership semantics that annotations alone cannot convey.

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?

The tool has zero parameters, so there are no parameter semantics to explain. The baseline for a parameterless tool applies, and the description correctly avoids unnecessary parameter discussion.

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 states a specific verb and resource: disconnect from the current SAP session and release the binding. It is clearly distinct from sibling connection tools such as sap_connect and sap_connect_existing.

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 makes clear which sessions are affected and which are not, implicitly guiding when this tool should be used. It does not name an explicit alternative, but there is only one disconnect operation among the siblings and the ownership rule provides strong context.

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=false and destructiveHint=false, so safety is partly covered. The description adds useful behavior context by noting the click typically opens detail views or drills down, and that it works on both ALV and TableControl. It does not say whether the double-click can mutate data, spawn a popup requiring sap_handle_popup, or change the screen context.

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?

Four short sentences, front-loaded with the action and effect, then the parameter semantics, then platform scope. Little waste; the only near-redundancy is restating 'column is the column name', which is quickly redeemed by naming the source tools.

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 need not be described. However, for a drill-down action tool the description omits the obvious follow-up consequences (popups, new screens) and never explains table_id, which is required and undocumented in both schema and description.

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 0%, so the description must carry parameter meaning, and it does explain the two non-obvious ones: 'row is zero-based' and 'column is the column name' sourced from sap_read_table or sap_get_column_info. The third parameter, table_id, is never explained (how to obtain it, format), leaving a real hole given the zero coverage.

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 concrete verb+resource pair ('double-click a cell in a table/grid') and adds the likely effect ('opens details or drills down'). This is clearly distinguishable from the tree-oriented siblings (sap_double_click_tree_node, sap_double_click_tree_item) and from sap_select_table_row, though it never names an alternative explicitly.

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 parenthetical ('often opens details or drills down') implies why you would reach for this tool, and it points to sap_read_table / sap_get_column_info as the source of valid column names. There is no explicit when-to-use versus sap_select_table_row or sap_press_button, and no guidance on what to do after the drill-down occurs.

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=false and destructiveHint=false, so the description must carry most of the behavioral burden. It doesn't disclose what a double-click triggers (new screen, transaction, popup), whether the action is idempotent, or that the target tree must already be rendered. Given this is a non-read-only UI interaction, the absence of side-effect information is a real gap.

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?

Three short lines, action stated first, parameter clarification second, discovery hint last. Nothing is redundant or padded.

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 needn't be explained, and the item_name semantics are covered. Still missing for a 3-required-param, zero-coverage tree interaction: definition of tree_id/node_key and their sourcing, plus what the double-click results in. Adequate but with clear gaps.

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 0%, so the three parameters are documented nowhere but the description. It explains the least obvious one well (item_name is a column name, with examples, and points to sap_read_tree for discovery), but tree_id and node_key are left entirely undefined — including how to obtain node_key.

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 gives a specific verb plus resource: 'Double-click a specific item (column cell) in a tree node row,' and the parenthetical clarifies that 'item' means a column cell rather than a node. This implicitly separates it from sap_double_click_tree_node, though the sibling is never named. Minor gap: it doesn't say what a double-click on an item achieves (drilldown, navigation, edit).

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?

It provides a prerequisite step, 'Use sap_read_tree to discover column names for the tree,' which is genuinely useful routing. However, it doesn't state when to choose this over sap_double_click_tree_node, sap_click_tree_link, or sap_select_tree_node, leaving the agent to infer the distinction from the name alone.

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 non-destructive and non-read-only, and the description adds real behavioral context beyond them: the action often only reveals details or documentation, meaning a 'successful' double-click may not perform the intended activity. It does not discuss focus changes, expansion side effects, or timing, so it stops short of full transparency.

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 primary action is stated first, followed by the caveat and the pointer to the alternative tool; every sentence carries information. The parenthetical and the SPRO paragraph could be slightly tightened but nothing is redundant.

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 needn't be explained, and the behavioral caveat is covered. The remaining gap is substantial for a two-required-parameter tool with zero schema documentation: an agent still cannot tell what a valid tree_id or node_key looks like.

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 0% – neither tree_id nor node_key is documented in the schema – and the description supplies nothing about them, such as where tree_id comes from (sap_read_tree / get_screen_elements) or whether node_key is a path, index, or internal key. The only parameter-like detail mentioned (column '2') belongs to a different tool.

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 gives a specific verb and resource ('Double-click a node in a tree control') and states the likely outcome (opens details or drills down). It partially distinguishes itself from siblings by naming sap_click_tree_link, but does not differentiate from the very similar sap_double_click_tree_item in the sibling list.

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?

It gives a concrete when-not case: in SPRO/customizing trees a double-click may open hypertext documentation instead of executing, so the agent should use sap_click_tree_link on the execute column instead. That is actionable routing guidance, though no other alternatives or preconditions (e.g. node must be visible/expanded) are mentioned.

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?

Adds substantial context beyond annotations: it navigates only to the initial screen, advises verifying the landed screen from the response, documents the SCWM /n/ prefix quirk, and warns that a bare /n discards unsaved data. That last point is in mild tension with destructiveHint=false, but only conditionally, so it reads as helpful disclosure rather than contradiction. Error behavior for blocked transactions is not described.

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-loaded with the core action, then layered warnings in short paragraphs. Every sentence carries operational value; the multi-line layout is slightly scannable rather than prose-tight, but nothing is filler.

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 need not be explained, and the description correctly points the agent at the screen info in the response. The main residual gap is what happens on a blocked/denied transaction and how that surfaces to the caller.

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 tcode parameter, so the description must carry full semantics — and it does: it names example tcodes (MM03, VA01, SM30) and the /n and /n/SCWM/MON formatting variants. This meaningfully exceeds the bare 'string' 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?

States a specific verb and resource ('Execute (start/run) an SAP transaction code') and immediately disambiguates with concrete examples (MM03, VA01, SM30). It also clarifies the scope boundary — it navigates to the initial screen only, rather than performing the transaction's business logic.

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 explicit pre-call guidance: 'Use sap_get_session_info to see the current transaction before navigating away,' and warns about blocklist/allowlist constraints. It does not, however, distinguish this from siblings like sap_get_transaction_guide or explain when transaction navigation is preferable to direct screen-element interaction.

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 mark this as non-read-only but non-destructive, and the description usefully explains the actual effect: children become visible and require a follow-up read to inspect. It does not mention whether expanding an already-expanded node is a no-op or errors, nor whether it scrolls/loads lazily, but the core state change is disclosed.

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?

Two short sentences with the action stated first and the follow-up second; no filler and nothing redundant with the schema.

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 need not be described, and the follow-up guidance covers the agent's next step. However, for a tool whose two required parameters are entirely undocumented in the schema, the description should have clarified tree_id and node_key formats, which it does not.

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 0% for both required parameters, so the description must carry the burden and largely does not. Saying 'a folder node' usefully implies node_key must reference an expandable/folder node rather than a leaf, but tree_id is never explained at all, leaving half the parameters undocumented anywhere.

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?

Specific verb (expand) plus resource (folder node in a tree control) plus the effect (reveal its children). It is clearly distinguishable from siblings like sap_collapse_tree_node, sap_select_tree_node, and sap_get_tree_node_children without opening any schema.

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 second sentence gives explicit follow-up guidance: after expanding, call sap_get_tree_node_children or sap_read_tree to see the children, which tells the agent the correct tool sequence. It does not explicitly state when not to use it (e.g., already-expanded nodes, or use sap_collapse_tree_node to reverse), but the context is clear.

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 this is a read-only, non-destructive lookup, so the safety profile is covered. The description adds the useful path-format example and says the result is a node key, but it does not explain invalid-path behavior, lookup failure, or other operational details.

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 two short sentences, front-loaded with the purpose and followed by a directly useful example. There is no wasted text.

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?

The output schema and read-only annotations cover return shape and safety. However, the description omits the meaning and source of 'tree_id' and does not route the agent among similar tree-navigation tools, so it is not fully complete.

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 0%, so the description must compensate. It explains the 'path' parameter well through the '2\1\2' example, but it says nothing about the required 'tree_id' parameter, leaving half the inputs undocumented.

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 and resource: find a tree node key by its path. It is clear what the tool does, but it does not explicitly distinguish itself from nearby siblings such as sap_search_tree_nodes or sap_get_tree_node_children.

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 no explicit guidance on when to use this tool instead of alternatives like sap_search_tree_nodes, sap_read_tree, or sap_get_tree_node_children. Usage is only implied by the phrase 'by its path'.

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 and destructiveHint=false, so the description need only add context beyond that, which it does: it names the returned fields (IDs, texts, types) and a real structural limitation (fails on GuiTableControl grids). It does not cover error behavior or what happens with an invalid/unknown grid_id, so it falls short of a 5.

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?

Three short sentences, no filler, with the purpose, return shape, and constraint ordered front to back. Every sentence adds 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?

An output schema exists so return values need not be spelled out, and the description still sketches them briefly. The grid-type constraint is valuable, but the one required input's origin is left unexplained, which is the only real completeness gap.

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 0% and the single parameter grid_id is never mentioned in the description – not where to obtain it, not whether it is a session-local handle or a screen identifier. With the schema carrying no semantics at all, the description should compensate and does not.

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 and resource ('Get all toolbar buttons from an ALV grid') and immediately bounds the scope with a component-type constraint (GuiGridView only, not GuiTableControl). An agent can distinguish it from sap_press_alv_toolbar_button and other table tools without reading the schema.

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 an explicit workflow: discover actions here first, then press them with sap_press_alv_toolbar_button. It also states the exclusion condition ('Only works on GuiGridView (ALV), not GuiTableControl'), which tells the agent when this tool will fail.

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 and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: the semantic meaning of the 'state' field (why a cell was rejected) and the hard limitation on GuiTableControl, which is behavioral and not derivable from schema or 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?

Front-loaded with purpose in the first sentence, then the field inventory, then the limitation last. The long parenthetical enumerations (cell_type, state) are dense but each item is an informative value domain rather than filler.

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?

A read-only tool with an output schema, so the return-value inventory is largely redundant and the description does not need to explain results. What it omits — parameter addressing conventions and how to obtain a valid grid_id — is the part an agent actually needs before calling.

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 0% for all three required parameters, so the description carries the full burden — yet it says nothing about grid_id format, whether row is zero- or one-based, or whether column is a name, index, or key. Only the return fields are described, leaving invocation details entirely to inference.

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?

Specific verb+resource ('Get detailed cell metadata from an ALV grid') with an enumerated payload and an explicit scope boundary ('Does NOT work on GuiTableControl'). An agent can distinguish it from sap_read_table, sap_get_column_info, and the GuiTableControl tools without opening any schema.

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 a clear when-not condition (GuiTableControl unsupported), which is the single most likely misselection here. However, it never names the alternative for that case (e.g. sap_get_table_control_row_info) nor contrasts with siblings like sap_get_column_info or sap_get_current_cell.

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 and destructiveHint=false, so the safety profile is covered. The description's remaining content is mostly return-value enumeration, which the existing output schema already provides, and it says nothing about prerequisites (active session, grid must be present on screen) or failure behavior for a bad grid_id.

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-loaded with the core action, then a compact per-type breakdown, then the alternative — a sensible order with no filler. The return-field enumeration is slightly redundant against the output schema, costing a point on economy.

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 an output schema and read-only annotations present, the description only needs to cover invocation context — and the one genuine gap is grid_id provenance and the requirement that a grid/table control be on the current screen. For a one-parameter introspection tool that gap is narrow but real.

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%, so the description must carry the burden for grid_id, and it never explains what a grid_id is or how to obtain one (e.g. from sap_get_screen_elements). The reference to 'ALV grid or table control' gives partial inference, which keeps this at minimum-viable rather than failing.

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 and resource ('Get detailed column info') and enumerates exactly what comes back for each of the two supported container types (ALV grid vs. table control). It also names the lighter sibling, so an agent can distinguish it from sap_read_table and sap_get_cell_info without opening a schema.

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?

Explicitly offers the alternative: 'For a lighter alternative, use sap_read_table with columns_only=true' — that is a real routing decision the agent can act on. It stops short of stating preconditions or when-not-to-use (e.g. no grid on the current screen), so it is clear context rather than a full when/when-not rule.

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 and destructiveHint=false, so the safety profile is clear. The description adds that results are key-value pairs, which is useful context, but it does not describe errors, permissions, or behavior for invalid combobox IDs.

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?

Two short sentences, front-loaded with the core action and followed by a useful note on return shape. There is no redundant or filler text.

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?

The tool is simple, read-only, and has an output schema, so the description does not need to explain return values in detail. However, the missing parameter explanation and lack of guidance on where to get combobox_id leave a meaningful gap for an agent invoking it in SAP automation.

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 0%, and the description never explains the required combobox_id parameter—what format it expects, where to obtain it, or whether it refers to a screen element ID. The single obvious parameter name helps, but the description does not compensate for the missing schema documentation.

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 states a specific verb and resource: 'List all entries in a combobox/dropdown.' This clearly distinguishes a read/discovery operation from the sibling selection tool, but it does not explicitly name or differentiate against sap_select_combobox_entry.

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 phrase 'so you know which values are valid' implies this should be used before selecting a combobox entry, but there is no explicit when-to-use guidance, no named alternative, and no prerequisites or exclusions.

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 and destructiveHint=false, so safety is covered. The description adds the useful nuance that this reports focus state rather than generic cell data, but says nothing about behavior before focus exists or what happens with an invalid table_id.

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?

A single front-loaded sentence with no filler. It is appropriately sized, though the brevity contributes to the missing parameter and usage detail.

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 need not be explained. However, for a tool with an undocumented required parameter in a dense sibling family, the description leaves the identifier semantics and alternative-selection guidance unresolved.

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% — table_id is entirely undocumented. The description does not clarify what table_id refers to (ALV grid vs table control identifier), how to obtain it, or whether it is required to match an existing focused element, so it fails to compensate for the schema gap.

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 gives a specific verb and resource ('get the currently focused cell position') and scopes it to ALV grids or table controls. It is clear what it does, but it doesn't distinguish itself from near-siblings like sap_get_cell_info or sap_get_table_control_row_info.

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?

There is no statement of when to use this versus sap_get_cell_info, sap_set_current_cell, or sap_get_table_control_row_info. The only context is the implied 'currently focused' framing, leaving the agent to infer selection criteria.

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 this a safe read (readOnlyHint=true, destructiveHint=false), and the description adds substantial behavior beyond them: it returns {popup_exists: false} when no popup is present, classifies the popup and suggests a safe next action, and documents that empty collections are omitted from the response. The texts-vs-list body distinction is real behavioral detail an agent could not infer from annotations alone.

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?

Purpose is front-loaded in the first clause, followed by return semantics and then the field-presence rules; each block earns its place. The second paragraph is dense and slightly long for a zero-parameter read tool, but it carries genuinely non-obvious information (list body never in texts, selected flag on radio/checkbox).

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 an output schema present the description need not enumerate return values, yet it covers the tricky cases an agent would otherwise get wrong: popup body as list vs. texts, omitted empty collections, and the pointer to sap_read_list. Nothing needed to call or interpret this tool correctly is missing.

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?

There are zero parameters, so the baseline of 4 applies; nothing about invocation arguments needs explaining. The description correctly spends its space on return-shape semantics instead of inventing parameter discussion.

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 specific verb+resource: 'Check if a popup/modal dialog is open (wnd[1], wnd[2], etc.)', which is unambiguous about what the tool does and the SAP context it targets. It does not explicitly name the closest sibling, sap_handle_popup, to say how it differs (inspect vs. act), so the agent must infer that boundary.

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?

Usage is only implied through the phrase 'so you know how to respond' and the note to read list-style popups with sap_read_list. There is no explicit when-to-use/when-not statement, and the relationship to sap_handle_popup (the obvious alternative for actually dismissing a popup) is never addressed.

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?

Beyond the readOnlyHint and destructiveHint=false annotations, the description explains how radio buttons, checkboxes, dropdowns, table controls, classic lists, and docking containers are represented in the response. It also warns that expand_tables=true can produce large output, which is useful behavioral context not available from annotations alone.

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 sized for a complex SAP tool with five undocumented parameters and several special screen structures. It is front-loaded with the core purpose and then organized by parameter and exception, with every paragraph adding decision-relevant 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?

Given the output schema, read-only annotations, and zero schema description coverage, the description provides enough context to call the tool correctly. It covers parameter tuning, response-shape caveats, and the key alternatives for tables, lists, and docking containers.

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 0%, so the description carries the full burden and does so effectively. It explains max_depth defaults and tuning, provides a type_filter example, clarifies container_id usage with concrete paths, and notes that expand_tables and changeable_only affect response size or inclusion.

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 specific verb and resource: 'Discover all elements on the current SAP screen.' It immediately distinguishes the tool's role by noting it is for finding field IDs and by naming related sibling alternatives such as sap_read_table and sap_read_list for different screen structures.

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 usage guidance: use type_filter and changeable_only to reduce response size, use max_depth=1 for an overview versus 3+ for deep nesting, and pass container_id='wnd[0]/mbar' for the menu bar. It also explicitly redirects table and list reading to sap_read_table and sap_read_list.

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?

Beyond the read-only annotations, the description explains that it reads from session.ActiveWindow, reflects what the user sees, and identifies the focused window via active_window. It also discloses conditional fields such as message_has_long_text, message_as_popup, subscreens, and cursor behavior, which are important behavioral details an agent would not infer from annotations alone.

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 first sentence is front-loaded and the paragraphs are organized by topic: active-window source, action-tool equivalence, conditional fields, and subscreen/cursor nuance. A few sentences, such as the title explanation, are slightly redundant, but the overall structure is efficient for the complexity of SAP screen state.

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 output schema and read-only annotations, the description provides ample context about what the tool reflects, how focus is represented, and which fields appear conditionally. Nothing material is missing for an agent to call this 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?

The tool has zero parameters, so there is no parameter semantics to clarify; the baseline for zero-parameter tools is 4. The description instead spends its space on returned screen-state semantics, which is appropriate.

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 states a specific read operation and enumerates the exact screen fields returned (transaction, program, screen number, title, status bar message). It also distinguishes itself from action tools that return the same screen info and from sap_get_popup_window, which provides full popup content.

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?

It clearly frames this as the way to inspect current screen state and explicitly routes the agent to sap_get_popup_window for full popup content. It also notes that every action tool returns the same screen info, which helps an agent decide when a standalone call is needed, though it does not spell out a strict when/when-not rule.

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 cover the read-only safety profile, and the description adds genuinely useful behavioral context beyond them: the scripting_read_only flag's semantics and the consequence that write tools refuse when it is true. It does not state what happens if no connection exists, which is a remaining behavioral gap.

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 purpose is front-loaded in the first sentence and the second sentence explains a non-obvious flag that would otherwise confuse a caller. The phrasing 'Also the SAP GUI release...' is slightly disfluent, but every element earns its 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?

For a zero-parameter read with an output schema and read-only annotations, this covers what an agent needs: what it returns and the critical scripting_read_only gate on write tools. Return-value details are correctly delegated to the output schema.

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?

Zero parameters, so the baseline is 4 per the rubric. The description additionally names the data points returned, adding light value over an empty schema, though the output schema already carries the return contract.

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 and resource ('Get information about the current SAP session') and enumerates the returned facets (system, client, user, transaction, screen), which implicitly distinguishes it from sap_get_screen_info. It stops short of explicitly naming the sibling it differs from, so an agent must infer the boundary.

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?

Usage is only implied: 'current SAP session' suggests an already-established connection, and the scripting_read_only note hints at a pre-flight check before write operations. There is no explicit when-to-use/when-not guidance or reference to sap_connect / sap_connect_existing for the not-yet-connected case.

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 and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context beyond that: the GuiTableControl-vs-ALV scope boundary and the default all-visible-rows behavior when the optional parameter is absent.

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?

Three short sentences, front-loaded with the return payload, then the default, then the exclusion. No filler at all.

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 need no explanation, and the description covers scope, defaults, and the main exclusion. The only real gap is the source/format expectation for table_id.

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 0%, so the description must carry all parameter meaning. It explains the rows parameter's default behavior well, but says nothing about what table_id refers to or how to obtain it, leaving the required parameter undocumented in every field.

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 and resource ("Get row metadata") and names the exact fields returned (selectable, selected) on a GuiTableControl. It also carves out ALV grids, which separates it from the ALV-oriented siblings, though it doesn't distinguish itself explicitly from adjacent readers like sap_get_cell_info or sap_get_column_info.

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?

"If rows is omitted, queries all visible rows" gives clear invocation context, and "Does NOT work on ALV grids" is an explicit exclusion. It stops short of naming the alternative tool to use for ALV grids, so the routing guidance is incomplete.

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 and destructiveHint=false, so the safety profile is covered. The description adds useful scoping detail (which toolbar indices are read and that it's the standard toolbar rather than ALV), but it repeats return fields that the output schema already documents and says nothing about behavior when no toolbar exists or about pagination/size limits.

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?

Three short sentences, front-loaded with the operation and the toolbar indices, followed by the return fields and the ALV exclusion. No filler; only the return-field sentence is arguably redundant given the output schema.

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?

The tool is simple (one optional param, read-only, output schema present), and the description covers scope, target structures, and the ALV boundary. The one gap is the unexplained window_id parameter, which is the only thing absent from an otherwise sufficient definition.

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?

There is one parameter, window_id, and schema description coverage is 0% – the description never mentions it, explain its 'wnd[0]' default, or how it relates to the tbar[0]/tbar[1] indices it describes. With low coverage the description is expected to compensate and it does not.

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 and resource ('List all buttons on the system toolbar... and app toolbar') and concretely identifies the structures involved (tbar[0], tbar[1]). It also explicitly demarcates itself from the nearest sibling, sap_get_alv_toolbar, so an agent can distinguish the two without opening either schema.

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 an explicit negative routing rule: 'This is for standard SAP toolbars, NOT ALV (use sap_get_alv_toolbar for ALV).' That names the alternative and the condition that selects it, leaving nothing for the agent to infer about which of the two toolbar tools applies.

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 and destructiveHint=false, and the description is consistent with that ('read-first guide'). It adds genuine context beyond the annotations: the guide is generic (not session-bound) and it spells out what each guide covers — tree navigation, ALV results, docked dialog-structure tree, saving, and the customizing request prompt. What it does not disclose is behavior for an unsupported transaction name.

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 purpose sentence is front-loaded, followed by a scannable per-transaction breakdown and an alias list, which is the right order for a lookup tool. There is minor redundancy — SM34 is described inside the SM30 bullet and then repeated in the alias list — but nothing wasteful enough to penalize heavily.

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 need no explanation, and the supported-transaction list makes the core call unambiguous. The gap is the undocumented 'task' parameter: an agent cannot tell whether it scopes or filters the guide, which is a real omission for a two-parameter tool.

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%, so the description must carry parameter meaning. It does well for the required 'transaction' parameter, enumerating valid values and accepted aliases (SCWM/MON, warehouse monitor, SM34, view cluster). But the second parameter, 'task', is never mentioned anywhere, leaving its purpose and format entirely unexplained.

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 and resource ('Return a generic, read-first guide for a supported SAP transaction') and immediately bounds the scope with an enumerated list of supported transactions. It does not explicitly distinguish itself from a sibling like sap_get_workflow_guide or position itself relative to sap_execute_transaction, so it stops 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?

'Read-first guide' implies the tool should be consulted before driving a transaction, which is a usable but implicit usage signal. There is no explicit when/when-not guidance, no mention of what to do for an unsupported transaction, and no named alternative for the case where the agent wants to actually run the transaction.

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?

Explains the non-obvious side effect behind readOnlyHint=false: expand=true mutates the tree state and therefore requires write permission. That is real disclosure beyond the annotations. It does not mention error behavior for invalid node_key, which keeps it from a 5.

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?

Three short sentences, front-loaded with the core action and the performance/sibling comparison before the parameter notes. Nothing is wasted.

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 an output schema present, return values need no explanation; the description covers the remaining decision-relevant facts — root handling, the write-permission requirement for expansion, and the read_tree alternative.

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%, so the description carries the burden and does it for two of three params: empty/omitted node_key means root level, and expand has a state-changing meaning. tree_id is only self-evident from context, so it is not fully covered.

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 and resource ("Get direct children of a tree node") and immediately differentiates itself from the sibling read_tree. An agent can pick between this and read_tree/expand_tree_node without opening any schema.

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?

Explicitly recommends itself for step-by-step navigation of deep trees like SPRO and positions read_tree as the slower alternative. It stops short of an explicit "use read_tree when you need the whole tree" exclusion, but the selection context is clear.

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 and destructiveHint=false, so the safety profile is covered. The description adds that the output is guidance rather than an action, but says nothing about connection prerequisites or whether the guide is static vs. screen-dependent — context that matters in this automation toolset.

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?

One framing sentence followed by a scannable bullet list where each entry pairs the workflow name with its target semantics. No filler, and the purpose is front-loaded before the enumeration.

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-value documentation is unnecessary, and enum-to-parameter mapping is fully covered. What's left thin is the usage/routing context relative to the many sibling guide and execution tools.

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 0%, so the description has to carry the load, and it does: each enum value is named, and `target`'s meaning is spelled out per workflow (field ID, table element ID, activity name). Only minor gap is that valid `target` formats/naming conventions aren't illustrated.

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 and resource: 'Return step-by-step guidance for a common SAP workflow', then enumerates the three supported workflows. The agent knows exactly what comes back, though it isn't explicitly contrasted with the similarly-purposed sibling sap_get_transaction_guide.

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 bullet list implies these are workflows you'd invoke before performing them, but there is no explicit when-to-use statement, no when-not, and no routing guidance versus sap_get_transaction_guide. The agent must infer that this is a preparatory, documentation-lookup call.

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 say readOnlyHint=false and destructiveHint=false; the description adds substantially more: save-related presses require user confirmation, unreadable popups (question_readable: false) force read-only behavior and never fall back to Enter, and accepted presses report confirmed_by_user: true. These are real behavioral traits beyond the annotations, though the precise destruction risk of each button type is not fully spelled out.

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 lead sentence and the 'Use when' clause are front-loaded, and the bulleted action list scans well. The safety paragraph is dense and useful but long; a few clauses (e.g. the F11 cross-reference) could be tightened without losing meaning.

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, and the description still summarizes the return payload (popup contents, classification, requested action, post-action screen/popup state) which is legitimately helpful context. For a two-parameter, safety-sensitive tool, the guidance on confirmation, unreadable popups, and outcomes is complete.

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%, so the description carries the full burden and does: every enum value of action is defined with concrete semantics (read/confirm/cancel/press/auto), and button_text is explained as 'press a specific button by its text or tooltip'. Without this text the two parameters would be largely opaque.

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 and resource ('Read and optionally act on the current popup/modal dialog') and explains it combines popup inspection and response in one call, which distinguishes it from siblings like sap_get_popup_window and sap_press_button. The enumeration of actions makes the scope 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?

Gives an explicit trigger ('Use when active_window shows wnd[1] or higher') and per-action guidance on when to pick each mode. It also states a clear prohibition ('never No, which on a save prompt drops the changes') and defines the auto fallback condition, which is when-to-use guidance at its most actionable.

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?

Consistent with readOnlyHint=true / destructiveHint=false, and it adds real context beyond annotations: what `host` values appear, and that a connection with no sessions plus `scripting_disabled: true` means sapgui/user_scripting is off so no session can be read — a diagnostic failure mode an agent would otherwise misread as an empty result. It does not mention ordering, limits, or what happens if no SAP GUI is running.

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-loaded with the one-line purpose, then two short paragraphs of scope and interpretation. The parenthetical `("(2)" in "DEV(2)")` is a useful concrete anchor rather than filler, though the paragraph on session fields is slightly dense.

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 params, an output schema, and read-only annotations, the description supplies everything needed to call and interpret the tool, including the scripting-disabled caveat. The only missing piece is a next-step pointer (which sibling to call after listing).

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?

Zero parameters, so the baseline is 4; the description still pre-explains the `host` discriminator values and the per-session fields, which primes interpretation of the result rather than the call.

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?

Specific verb+resource: "List all open SAP connections and sessions", with the scope widened explicitly to SAP Logon and Business Client / embedded SAP GUI sessions via the `host` values. It does not name a sibling (e.g. sap_connect, sap_get_session_info) to sharpen the boundary, so it stops 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?

Usage is only implied: an agent infers this is the discovery/enumeration step before selecting a session, and that `scripting_disabled: true` signals a troubleshooting condition. There is no explicit when-to-use/when-not or pointer to the alternative tools (sap_connect_existing, sap_get_session_info).

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=false and destructiveHint=false, so the safety profile is supplied. The description adds the editable-cell constraint, which is real behavioral value, but says nothing about what happens on a non-editable cell, whether the change is committed to the backend, or whether a save/confirmation step follows.

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?

Three short sentences, front-loaded with the action and followed by the precondition and the verification tool. No filler and nothing repeated from the schema or annotations.

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 need not be explained, and safety is covered by annotations. However, with 0% parameter documentation and no statement about post-write behavior (commit, save prompt, error on read-only cell), the definition leaves gaps an agent would likely hit on a first call.

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 0%, so the description carries the full burden for four required parameters and provides none of it. It does not say what grid_id refers to, whether row is zero- or one-based, whether column is a name or identifier, or what `value` must contain to be accepted.

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 and resource: modify a cell value in an ALV grid or table control. The mention of the two container types distinguishes it from field-level siblings like sap_set_field and sap_set_textedit, though those siblings are never named explicitly.

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 clear precondition ('Only works on editable cells') and routes the agent to sap_get_cell_info as a verification step before calling. It stops short of contrasting with sap_set_field or sap_set_batch_fields for bulk edits, so the routing is partial rather than exhaustive.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds genuinely new behavior: menu-type buttons open a menu and the response carries menu_items with text and function_code. That is real response-shape information beyond the annotations. It stops short of saying what a normal push does to the screen or whether popups/dialogs can result.

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?

Two short sentences, purpose first, procedural detail second; every clause carries information and nothing is padded.

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 an output schema present, return values need no explanation, and the menu_items behavior plus the discovery workflow cover the main risks. The unresolved grid_id semantics is the one real hole for a 2-parameter tool.

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 0% for both parameters, so the description must compensate. It does explain where button_id comes from (sap_get_alv_toolbar), but grid_id is never mentioned or explained, leaving one of two parameters undocumented in both places.

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 concrete verb+resource scoped to ALV grids, with examples (sort, filter, export) that make the target obvious. The ALV qualifier separates it from the generic sap_press_button, though it never names that sibling directly.

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 an explicit prerequisite workflow: use sap_get_alv_toolbar to obtain button IDs. Also handles the branch case — Menu/ButtonAndMenu buttons open a menu and the follow-up is sap_select_alv_context_menu_item — so the agent knows what to do next. Missing only an explicit exclusion (e.g., non-ALV buttons belong to another tool).

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?

Beyond the annotations, the description discloses that the tool returns screen info, detects navigation or popups, may save data, and asks the user for confirmation in certain popup cases. This is strong behavioral context, though the confirmation sentence is convoluted and references a confirmed_by_user field not present in the schema.

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 front-loaded first sentence is clear, but later paragraphs are dense and the popup confirmation sentence is hard to parse. Some details, such as the long-text flow, are useful, but the overall structure could be tighter.

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 an output schema present, the description needn't explain return values in detail. It covers prerequisites, side effects, confirmation behavior, and follow-up actions, though the confirmed_by_user reference and lack of ALV differentiation leave minor gaps.

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 0%, so the description must explain the single button_id parameter. It does provide discovery guidance and an example value ('wnd[0]/sbar'), but it also mentions confirmed_by_user, which is not in the input schema and may mislead about available 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 states a specific verb and resource: press a pushbutton or toolbar button on the current SAP screen. It distinguishes itself from discovery tools but does not explicitly differentiate from the similar sibling sap_press_alv_toolbar_button or state when to use sap_handle_popup instead.

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?

It gives explicit prerequisite workflows: use sap_get_toolbar_buttons or sap_get_screen_elements to find button IDs, and use sap_read_list for long-text popups. However, it does not clearly say when not to use this tool versus the ALV toolbar press or popup handler.

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=false and destructiveHint=false, so the description's disclosure that the click triggers a sort is real added context — the agent knows UI state changes. The GuiTableControl limitation is a useful behavioral constraint; what's missing is error/failure behavior or what happens on a non-sortable column.

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?

Two short sentences, zero waste, with the primary action and its effect front-loaded before the limitation. Nothing could be cut without losing 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?

An output schema exists, so return values need not be explained, and the purpose/limitation are covered. The remaining gap is parameter format detail, which is the one thing an agent still needs before calling.

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 0%: neither grid_id nor column is documented in the schema, and the description adds no format guidance (e.g., is 'column' a header text, field name, or index?). With both parameters required and undocumented, the agent must guess the identifier convention.

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 concrete verb and resource ('Click a column header in an ALV grid') and adds the effect '(triggers sort)', so the agent knows exactly what happens. It differentiates from table-control siblings by excluding GuiTableControl, though it does not name a specific alternative 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 negative guidance ('Does NOT work on GuiTableControl') is a genuine exclusion, and sorting is implied as the use case. However, it never names the sibling tool to use instead for GuiTableControl, leaving the agent to infer the alternative from a 55-tool list.

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 and destructiveHint=false, so the closing 'Read-only: nothing is written or saved' largely restates structured data. What the description does add is useful beyond the annotations: the card is composed of screenshot + session/transaction info + status bar + pending fields, so the agent knows what the user will see. It says nothing about cost/latency of capturing a screenshot or behavior when include_screenshot is false.

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?

Four tight sentences with the core purpose front-loaded and no filler; the conditional call guidance follows the content list in a logical order. Only the trailing 'Read-only: nothing is written or saved' is slightly redundant with the annotations.

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 correctly describes the rendered output (a preview card with named sections), which is the right call. However, for a 3-parameter tool with zero schema coverage, two parameters remain unexplained and there is no indication of what a preview actually returns as a tool result versus what the user sees.

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 0%, so the description must carry all parameter meaning, but it only explains one of three: pending_fields is described as 'the values the agent is about to write,' which is genuinely helpful. The 'note' and 'include_screenshot' parameters get no explanation in either the schema or the description, leaving their purpose and effect entirely inferential.

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 gives a specific verb ('render a preview card') and enumerates the exact contents (screenshot, session/transaction info, status bar, pending_fields), which cleanly separates it from the raw sap_screenshot and sap_get_screen_info siblings. It never names those siblings explicitly, so differentiation is implied rather than stated.

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?

'Call before significant writes (batch fills, F11 save) or whenever the user asks to see what's about to happen' supplies concrete triggers, including the specific sibling workflow sap_set_batch_fields. It stops short of stating when NOT to call it or naming an alternative preview/screenshot tool for other cases.

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 and destructiveHint=false, so the safety profile is given. The description goes further by disclosing the type-dependent semantics of the returned value (dropdown returns entry text, radio/checkbox return labels with a selected flag), which is real behavioral context an agent cannot get from annotations. Error behavior for a missing or invalid field_id is not covered.

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-loaded with the action, then the return shape, then the special-cased control types, then the discovery hint. Every sentence carries distinct information and nothing is repeated from the schema or annotations.

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 annotations, an output schema, and a single required parameter, the description covers what an agent needs: what it reads, what comes back for each control type, and how to obtain IDs. The only gap is failure behavior when the field does not exist or is not readable.

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 0% and the single field_id parameter has no documented format in the schema. The description partially compensates by telling the agent where valid field IDs come from (sap_get_screen_elements) but never indicates what an ID looks like or whether it is a screen-element path versus a plain name.

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+resource pair, 'Read the value of a field on the current SAP screen', which is immediately distinguishable from write-side siblings like sap_set_field or sap_modify_cell. It also enumerates what comes back (value, type, changeable status, labels), so an agent knows exactly what it is asking for.

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?

Explicitly directs the agent to sap_get_screen_elements when field IDs are unknown, which is the one real precondition for calling it. It does not, however, exclude other read siblings such as sap_read_textedit, sap_read_table, or sap_get_cell_info, so an agent facing a non-field control still has to reason it out.

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 a safe read operation, but the description adds substantial behavior: lists have no table object and are reported under 'lists' by sap_get_screen_elements, colors carry semantic meaning, scroll indicates pagination with a concrete next-page pattern, and with_ids enables focus before F2/double-click. These are traits not derivable from annotations alone.

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 definition, then the usage context, then a tight bullet list of behaviors. Every sentence carries necessary information, and the fallback condition is clearly placed at the end.

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 an output schema exists, the description need not explain return fields, yet it still adds useful semantics about colors, scroll, and is_list. For a read-only tool with four optional parameters, nothing critical is missing except the minor max_lines detail.

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 0%, so the description must compensate. It explains with_ids (adds line label ID for focus), scroll_to (position+page_size for next page), and window_id ('wnd[1]' for F4 popups). However, max_lines is never mentioned, leaving one of four parameters undocumented anywhere.

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 and resource ('Read a classic ABAP list ... as lines of text') and immediately distinguishes it from ALV grids, table objects, and screens without lists. An agent can identify the operation and its output form without opening the schema.

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?

Explicitly names when to use it (plain WRITE list, program SAPMSSY0 screen 120, F4 hit lists in wnd[1]) and when not to (is_list=false -> use sap_read_table). Alternatives and selection conditions are stated rather than implied.

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 and destructiveHint=false, so the description need not restate safety. It adds meaningful behavior beyond annotations: IE-only readability for HTMLViewer text/URL and the fact that Edge returns an explanatory note.

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?

Three compact sentences, front-loading the core purpose and following with the key limitation and prerequisite. No wasted text.

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 an output schema present and annotations covering safety, the description supplies the needed calling context: what GuiShell content means, the browser-control limitation, and how to obtain shell_id. Little is missing for a one-parameter read tool.

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 compensate. It usefully says to obtain shell IDs via sap_get_screen_elements, but does not describe the ID format or what a valid value looks like.

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 and resource: reading content from a GuiShell subtype such as HTMLViewer. It is clearly narrower than sibling read tools like sap_read_field or sap_read_textedit, though it does not explicitly contrast them.

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 clear prerequisite by instructing the agent to use sap_get_screen_elements first to find shell element IDs. It also explains the Edge-control limitation, but does not name alternatives for that unsupported case.

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 establish a safe read (readOnlyHint=true), yet the description still discloses non-obvious behavior beyond them: automatic table-type detection, that start_row=0 causes an actual UI scroll as a side effect, that TableControl reads are capped at visible rows, that scrolls may be clamped or fail (start_row_note), and that SM30 pads total_rows with empty lines. These are operational gotchas an agent could not infer from the 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?

Front-loaded with what the tool does and what it returns, then parameter guidance, then edge cases — a sensible order with no filler sentences. It is dense and longer than typical, and some of the latter material retreads return-field names that the output schema already documents, but each paragraph still carries actionable guidance.

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 five-parameter tool with zero schema descriptions and a rich output schema, this covers identification, projections, pagination, and truncation/empty-row edge cases thoroughly. The remaining gaps are max_rows semantics and its interplay with the visible-row limit, which an agent would still have to guess at.

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 0%, so the description must carry the load, and it does a strong job for three of five parameters: columns_only (metadata-only plus cell_type/cell_id template), columns (CSV projection), and start_row (pagination, zero-based, scroll semantics, null default behavior). table_id is left unstated and max_rows is never mentioned at all, including how it interacts with the visible-row cap, so it doesn't fully compensate.

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 concrete verb and resource ('read rows from a table on the current screen') and immediately disambiguates the two supported table types (ALV grid vs TableControl/SM30). It distinguishes itself from sibling readers like sap_read_field, sap_read_list, and sap_get_column_info by naming what it returns (row data plus table_type), so an agent can pick it without opening schemas.

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?

Explicit conditional routing: columns_only=true for schema discovery, columns (CSV) for projections, start_row for pagination, and named downstream tools per table type (sap_get_alv_toolbar for ALV, sap_scroll_table_control for TableControl). It also spells out the pagination loop condition (start_row=next_start_row while has_more) and the fallback behavior when start_row is omitted.

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 and destructiveHint=false, so the description only needs to add operational context. It does so usefully by stating what comes back (full text plus line count) and that max_lines=0 means all lines — a non-obvious behavior. Minor gap: no note on truncation semantics or the exact shape of the line count.

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?

Three short sentences, front-loaded with the purpose and followed by return behavior and the one parameter caveat. No filler, though the awkward line breaks in the source slightly hurt scannability.

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 an output schema present, return values need not be described, yet the description still summarizes them helpfully. For a simple read-only 2-parameter tool the only real omission is how to obtain textedit_id, which keeps it from a 5.

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 0%, so the description must carry parameter meaning. It fully explains max_lines (0 = all lines, caps output), but says nothing about textedit_id beyond the name — how to find it and what format it takes is left to inference.

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 states a concrete verb (Read) and a specific resource (a multiline text editor / GuiTextedit), and the parenthetical examples of content types (long texts, notes, comments, document text) make the target element unambiguous. It does not explicitly contrast with the nearby sap_read_field, but the 'multiline text editor' framing is specific enough to separate the two in practice.

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?

It gives guidance on the max_lines parameter (cap output for large editors, 0 = all lines) but never says when to prefer this over sap_read_field or how to obtain a valid textedit_id (e.g., via sap_get_screen_elements). Usage is implied rather than stated.

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 establish readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context beyond annotations: it returns node hierarchy with texts and column values, explains total_nodes and truncated=true semantics, and clarifies available_nodes versus max_nodes. It does not cover error conditions or screen-state prerequisites, so it is strong but not exhaustive.

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: purpose first, then alternatives for large-tree and search scenarios, then truncation semantics. Every sentence earns its place with no filler.

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 read-only annotations and an existing output schema, the description covers enough for correct invocation: purpose, alternative tools, and truncation behavior. The main remaining gap is that tree_id is never explained, which matters because schema coverage is 0%, but overall the definition is nearly complete.

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 0%, so the description must compensate for both parameters. It meaningfully explains max_nodes through the truncated/available_nodes explanation, but tree_id is not described at all. Partial compensation for a two-parameter schema merits a 3.

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 gives a specific verb and resource: 'Read data from a tree control' and names concrete control types (TableTreeControl, ColumnTreeControl). It explicitly distinguishes itself from sibling tools sap_get_tree_node_children and sap_search_tree_nodes by their use cases, so an agent can route correctly without opening other schemas.

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?

It states clear when-to-use guidance: use this tool for reading tree data, use sap_get_tree_node_children for large trees (e.g., SPRO with 1000+ nodes) for step-by-step navigation, and use sap_search_tree_nodes to find specific nodes by text. This provides explicit alternatives and the conditions that select them.

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 readOnly/destructive=false, and the description adds substantial non-obvious behavior: save_path must end in .png, the directory must already exist, existing files are never overwritten, the file keeps full SAP GUI resolution while the inline image is capped at 1920px, and the response reports the absolute path and pixel size. That is far beyond the annotation surface.

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?

Three short, front-loaded paragraphs: what it does, when to use it, then how to persist the result. Every sentence adds information or a constraint; nothing is redundant.

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?

No output schema exists, yet the description still describes the response payload (inline image, absolute path, pixel size, failure-free file behavior). For a two-optional-parameter read tool with annotations, an agent has everything needed to call it 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?

Schema description coverage is 0%, so the description carries the full burden and does: it documents save_path's format constraint (.png), directory precondition, no-overwrite behavior, and that it triggers path/pixel-size reporting, plus inline=False for file-only use. The only small gap is that the defaults (inline=true, save_path="") and the pure inline-only return case are implied rather than stated.

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 concrete verb and resource ('Take a screenshot of the current SAP window') and immediately frames it relative to the structured read siblings (sap_get_screen_elements, sap_read_field, sap_read_table). No ambiguity about what the tool returns.

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?

Explicit when-to-use rule: fallback when structured tools return empty or confusing results, with a named scenario (Web Dynpro screens with non-standard element trees). It also states the specific condition for the save_path versus inline-only path, so the agent can choose its call shape without guessing.

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 say readOnlyHint=false and destructiveHint=false, so the description carries the interesting behavioral burden and does it well: the scroll may land on a different row than requested, and the response surfaces requested_position plus a note when that happens. It also warns that cell IDs are relative to the visible window. What it does not state is whether scrolling has side effects on selection/current cell or whether it can fail for locked tables.

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?

Four short lines, front-loaded with the action and its scope, then the exclusion, then the preferred alternative, then the response caveat. Every sentence carries distinct, non-redundant 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?

An output schema exists, so return values need not be enumerated, yet the description still flags the one return detail an agent could misread (position vs requested_position). Combined with the ALV exclusion and the read_table routing, an agent has everything needed to call this correctly or avoid it.

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 0% and both parameters are required, so the description must compensate. It clarifies position's semantics partially (the effective top row, the divergence from the requested value) but never states the indexing base (0- vs 1-based) or valid range, and table_id is left entirely unexplained beyond its name.

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 and resource ("Scroll a GuiTableControl to a specific row position") and immediately scopes it against the sibling family that looks similar but behaves differently (ALV grids). An agent can distinguish it from sap_read_table and the ALV tools without opening either schema.

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 an explicit exclusion (does NOT work on ALV grids, with the reason: they scroll internally) and an explicit alternative with the condition that selects it ("For reading data at a specific offset, prefer sap_read_table with start_row — it handles scrolling automatically"). Both when-not and better-option are named.

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?

Goes well beyond the readOnly annotations: discloses case-insensitive substring matching, the critical scope limitation that only expanded/loaded nodes are searched, and the meaning of total_matches and stopped_early. This is behavior an agent cannot infer from the schema and directly prevents false-negative conclusions.

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-loaded with the action and return shape, then the limitation called out in bold so it cannot be skimmed past. The final paragraph on total_matches/stopped_early partly duplicates the output schema and could be trimmed, but every sentence remains useful.

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 4-parameter read-only search tool with an output schema, this covers the preconditions (nodes must be expanded), the matching semantics, and the truncation signal — everything needed to call it and to interpret a miss 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?

With 0% schema description coverage the description must carry the load, and it does explain search_text, column (search a specific column instead of node text), and max_results via the stopped_early note. It stops short of stating accepted column identifier format (header text vs. technical name) and leaves tree_id undocumented, so not a full 5.

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 and resource ("Search for tree nodes by text") plus the return shape ("matches with full ancestor paths"). The phrase "by text" implicitly contrasts with the path-based sibling sap_find_tree_node_by_path and with sap_read_tree, so an agent can route without opening schemas.

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 positive use case (deep trees where the same label appears in multiple branches), an explicit failure mode (collapsed subtrees aren't searched), and the exact remediation path — call sap_get_tree_node_children with expand=true then retry. It also names the column-scoped alternative inline.

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 declare non-destructive but readOnlyHint=false, and the description confirms the UI-state nature of the operation only implicitly. The failure mode on GuiTableControl is a genuinely useful disclosure beyond annotations, but nothing is said about whether prior selection is cleared, whether the grid needs focus, or where a valid grid_id comes from.

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?

Two sentences, zero filler, with the core action front-loaded and the constraint immediately after. Nothing to trim.

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 need no explanation, and the ALV-vs-table-control boundary is covered. The remaining gap is the sole required parameter's provenance, which is essential for a correct call on a tool with 0% schema coverage.

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 0%, so the description carries the full burden for grid_id — yet it never explains what a grid_id is, how to obtain it (e.g., from screen elements or table info), or its format. The single parameter is entirely undocumented in both places.

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 and resource ('Select all rows in an ALV grid') and immediately distinguishes itself from table-control siblings by excluding GuiTableControl. An agent can tell this apart from sap_select_multiple_rows or sap_select_all_table_control_columns without opening either schema.

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 negative constraint ('Does NOT work on GuiTableControl') gives a clear when-not-to-use rule, which is more than most siblings offer. It stops short of naming the alternative tool the agent should use instead on a GuiTableControl, leaving one inference step.

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=false and destructiveHint=false, so the mutation-safety profile is covered. The description adds the meaningful behavioral constraint that ALV grids are unsupported, but says nothing about what happens to existing selections when toggling, or whether the call requires a specific screen state.

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?

Two short sentences, zero filler, with the action stated first and the critical exclusion second. Nothing to trim.

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 need not be described, and the tool is only two parameters deep. Still, for a state-changing table tool the description omits how `table_id` is identified and what the resulting selection state looks like, leaving gaps an agent would hit on first invocation.

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 0%, so the description must carry parameter meaning and largely doesn't. "Select or deselect" loosely maps to the `select` boolean, but `table_id` is never explained — no hint on its format or how to obtain it from sap_get_screen_info or similar.

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 pair (select/deselect) and a precise resource (all columns in a GuiTableControl), and explicitly excludes ALV grids, which is the main confusion axis among the many table/ALV siblings. An agent can tell this apart from sap_get_alv_toolbar and the row-selection tools without opening the schema.

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?

"Does NOT work on ALV grids" is an explicit when-not condition, which is valuable given the many ALV siblings in the list. However, no alternative is named for the ALV case (e.g., which tool to use instead), and no preconditions for the table control are given.

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?

With readOnlyHint=false and destructiveHint=false already covering the safety profile, the description adds real behavioral context: the atomic open-and-select mode, and the fact that `auto` uses a space-based heuristic to guess id vs text, which materially affects outcomes. It does not describe what happens when a menu item is not found or when no menu is open, leaving failure behavior undisclosed.

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-loaded with the core action and the prerequisite workflow, then the parameter guidance in scannable bullets. Slightly over-long — the two `menu_item_id` examples plus the reiteration that human-readable text works could be tightened without losing meaning.

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-value details are not owed here, and the tool's main complexity (which identifier form to use, two-step vs atomic) is well covered. The remaining gap is the undocumented required `grid_id` and the absence of any error/fallback guidance for a failed selection.

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%, so the description carries the full burden and largely does: it enumerates the three accepted forms of `menu_item_id` with concrete examples, spells out each `select_by` enum value, and explains the role of the optional `toolbar_button_id`. The exception is `grid_id`, a required parameter that is never defined anywhere.

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 and resource ("Select an item from an opened ALV context menu") and immediately positions itself relative to the sibling that produces the menu, sap_press_alv_toolbar_button. An agent can distinguish this from sap_press_alv_toolbar_button and sap_select_menu without opening either schema.

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 explicit when-to-use context (menu must already be open), names the prerequisite tool, and offers a recommended alternative path (pass toolbar_button_id to open and select atomically). It even points to where to discover valid menu items when the menu is not yet open.

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 declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered structurally. The description adds that the action applies to the 'current SAP screen', implying session/screen-state dependency, but says nothing about whether toggling fires server-side events, whether state persists, or what happens if the ID doesn't exist on screen.

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?

Three short sentences, front-loaded with the core action, then the deselect trick, then ID discovery. No filler and no repetition of structured fields.

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 needn't be described, and both parameters are given meaning. What's missing is a brief note on the screen-state precondition (checkbox must exist on the active screen) and error behavior for a bad ID, which matters for an interactive UI-automation tool.

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 0%, so the description carries the full burden and does so well: it explains the semantics of 'selected' (false = uncheck, implying default true = check) and tells how to obtain a valid 'checkbox_id' with the exact type filter. That is materially beyond what the bare schema provides.

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 and resource ('select or deselect a checkbox') scoped to 'the current SAP screen', which is unambiguous. It doesn't explicitly distinguish itself from the close sibling sap_select_radio_button, which keeps it from 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 concrete operational guidance: use selected=false to uncheck, and discover checkbox IDs via sap_get_screen_elements with type_filter='GuiCheckBox'. It names the prerequisite tool and the exact filter, but offers no when-not-to-use condition or mention of the radio-button alternative.

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 disclose that this is a non-read-only, non-destructive action, and the description adds useful behavior context: both key and display text are accepted, and F4 does not open dropdowns. It does not explain what happens on an invalid key/value, whether selection triggers downstream events, or whether the operation commits immediately.

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 core action is front-loaded in the first sentence, followed by concise clarifications. The F4 note is slightly cryptic but contextually useful; overall there is little waste.

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 only two parameters and an output schema available, the description covers the critical input semantics and the prerequisite discovery step. What remains missing — error behavior and post-selection side effects — is secondary given the output schema and annotations.

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 0%, so the description must compensate. It does explain that key_or_value accepts either the technical key or visible display text, which adds real meaning beyond the schema, but combobox_id is left undocumented.

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 and resource — selecting an entry in a combobox/dropdown — and clarifies the two accepted identifier forms. It also names the sibling to consult first and the sibling that can do the same job, so the agent can distinguish it from adjacent 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?

Explicitly instructs the agent to call sap_get_combobox_entries first and notes that sap_set_field selects entries the same way, which gives a clear alternative path. It lacks an explicit 'when not to use' rule, but the prerequisite guidance is strong.

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 annotations already indicate this is not read-only and not destructive. The description adds useful behavioral context by saying it returns screen info after selection so the agent can detect navigation.

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 short and front-loaded: purpose, example, discovery guidance, and return behavior. Every sentence adds useful information without waste.

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 simple one-parameter navigation tool with existing annotations and an output schema, the description covers the key operational needs: what to select, how to form the selector, how to discover valid paths, and what to expect afterward.

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 0% and the single menu_id parameter has no schema description. The description compensates well by giving a concrete path example ('wnd[0]/mbar/menu[1]/menu[0]') and pointing to a discovery tool for the structure.

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 states a specific verb and resource: selecting a menu item from the menu bar or submenu. It is clearly distinguishable from sibling tools that press buttons, select tabs, or manipulate table/tree elements.

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?

It gives practical usage context by providing an example menu path and directing the agent to use sap_get_screen_elements on 'wnd[0]/mbar' to discover menu structure. It does not explicitly say when not to use this tool or name alternatives, so it stops short of a 5.

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 declare readOnlyHint=false and destructiveHint=false, so the agent knows this mutates UI selection state non-destructively. The description adds nothing beyond that: it doesn't say whether the new indices replace or extend the current selection, what happens with out-of-range indices, or whether the grid must already be focused/visible.

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?

Two short sentences, the action and target are front-loaded, and the second sentence gives the concrete argument shape. Nothing extraneous.

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 need not be described. But for a 2-required-parameter UI mutation tool, the definition leaves table_id semantics, selection-replacement behavior, and index-base ambiguity unresolved — enough gaps that an agent could call it wrongly.

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 0%, so the description must compensate. It does explain 'rows' as a list of row indices with an example ([0, 2, 5]), hinting at 0-based indexing, but it says nothing about 'table_id' — what identifier format is expected or how to obtain it (sap_get_screen_info / sap_read_table).

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+resource ('Select multiple rows') and scopes it to an ALV grid or table control, which distinguishes it from generic table reading tools. However it never explicitly contrasts with the close siblings sap_select_table_row (single row) and sap_select_all_rows, so the agent must infer the boundary itself.

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 phrase 'multiple rows at once' implies the batch use case, but no explicit when-to-use/when-not or alternative routing (e.g., use sap_select_all_rows for everything, sap_select_table_row for one) is given. Usage is inferable but not stated.

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 disclose that this is a non-read-only but non-destructive operation. The description adds that it acts on the current SAP screen and requires an ID discovered through another tool, but it does not explain whether selection triggers screen events, requires an active session, or changes navigation state.

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?

Two short sentences, front-loaded with the action and followed by the discovery instruction. No unnecessary repetition or filler.

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 simple one-parameter UI mutation with an output schema and annotations, the description covers purpose and ID discovery adequately. It could mention session requirements or post-selection behavior, but nothing critical is missing for correct invocation.

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 0%, so the description must carry parameter meaning. It does this well by naming the exact source of valid radio_id values via sap_get_screen_elements with type_filter='GuiRadioButton', though it does not specify the exact string format.

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 states a specific verb and resource: selecting a radio button on the current SAP screen. It is clear enough to distinguish from adjacent controls such as checkboxes, though it does not explicitly contrast itself with sibling tools like sap_select_checkbox or sap_press_button.

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?

It gives a concrete prerequisite workflow: use sap_get_screen_elements with type_filter='GuiRadioButton' to discover valid radio button IDs. It does not explicitly state exclusions or when to choose this over sap_select_checkbox, but the usage context is clear.

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 annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by saying the selection returns screen info and changes tab content, making it clear that UI state changes occur.

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 three short sentences: purpose first, behavioral effect second, parameter format third. Every sentence adds useful information with no filler.

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 simple one-parameter UI action with an output schema and annotations, the description covers purpose, effect, and ID shape well. It stops short of explaining where to obtain tab IDs or that a connected session is required.

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 0%, so the description must carry the parameter burden, and it does provide a concrete tab ID format example. It does not explain how to discover valid tab IDs, but the example is substantially more useful than the bare 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 states a specific verb and resource: select a tab in a tab strip control. This clearly distinguishes it from sibling actions such as sap_press_button, sap_select_menu, sap_select_checkbox, and sap_select_radio_button by naming the exact control type.

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?

Usage is implied by the control-specific purpose: use this when interacting with a tab strip. However, the description does not explicitly state when to use it versus alternatives, nor does it mention prerequisites such as an active session.

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 declare readOnlyHint=false and destructiveHint=false, which is already informative. The description adds genuine behavioral detail beyond them: zero-based indexing, absolute indexing on ALV, and the side effect that TableControl scrolls the row into view. It omits whether selection replaces any prior selection and whether a failure/not-found condition is reported.

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?

Four short sentences, front-loaded with the core action, then the ALV/TableControl nuance. No filler; the only mild redundancy is naming both 'table' and 'grid'.

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 need no explanation, and the tool is structurally simple with only two parameters. Still, the unidentified `table_id` and the lack of any note on selection semantics or error behaviour leave a gap an agent would hit on first call.

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%, so the description carries the full burden. It explains the `row` parameter well (zero-based, absolute for ALV, auto-scrolled for TableControl) but never says what `table_id` is or where to obtain it, leaving a required identifier undocumented in both schema and description.

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 and resource ('Select a row in a table/grid') and clarifies both supported surface types (ALV grid vs. table control). It doesn't explicitly mark the boundary against neighbours like sap_select_multiple_rows, sap_set_current_cell, or sap_select_all_rows, so twins remain distinguishable only by inference.

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?

Usage is implied by the resource ('select a row'), and the ALV/TableControl split hints at when each behaviour applies. However, there is no explicit 'use this instead of X when...' guidance and no statement of prerequisites (e.g., that the table must already be read/visible before selecting).

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=false and destructiveHint=false; the description adds the key non-obvious trait that selection highlights rather than opens the node, which is exactly the ambiguity for a tree 'select'. It does not mention side effects like scrolling the node into view or whether prior selection is cleared, so it falls short of full disclosure.

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?

Three short sentences, front-loaded with the core action, and every sentence carries distinct information (what it does, what it does not do, when to use an alternative). No filler.

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 need no explanation, and the tool is a simple two-parameter operation whose core ambiguity (highlight vs open) is resolved. The remaining gap is how to source tree_id and node_key, which the description leaves entirely to the caller.

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 0% — neither tree_id nor node_key carries any schema documentation — and the description adds nothing about their format or origin. It never points the agent to sap_read_tree or sap_find_tree_node_by_path to obtain a valid tree_id/node_key, so the caller must guess how to source both required 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?

Specific verb (select) plus resource (node in a tree control), with an immediate behavioral qualifier ('highlights the node without opening it') that distinguishes it from the expand/collapse/double-click tree siblings. It also names the sibling to use for a different tree flavor, so an agent can disambiguate without opening schemas.

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?

Explicit routing advice is given for one important case: SPRO-style trees should use sap_click_tree_link on the execute icon column instead. It does not address when to choose this over sap_double_click_tree_node, sap_expand_tree_node, or sap_find_tree_node_by_path, but the primary selection trap is covered.

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=false and destructiveHint=false; the description goes well beyond by disclosing that inactive keys are rejected with an error plus available_keys, that F11/Save triggers an elicitation confirmation and sets confirmed_by_user, and that a declined save returns status 'cancelled'. This is exactly the mutation-side behavioral context an agent needs.

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 verb and API name, then layers key meanings, failure behavior, and the save-confirmation caveat in short scannable paragraphs. No sentence is filler; the F11/Save note is the only repeated theme and it carries distinct informational content.

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-field enumeration isn't required, yet the description still surfaces the operationally important ones (error, available_keys, confirmed_by_user, status 'cancelled'). For a one-parameter, non-destructive mutation tool this is complete.

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 0%, so the single parameter relies entirely on the enum. The description compensates fully by glossing the semantically opaque entries (F4 = search/value help, F8 = Execute, F11 = Save, F12 = Cancel/Escape) and covering the Shift/Ctrl variants the enum merely lists.

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 and resource ('Press a keyboard key / function key in the SAP window') and names the underlying API (sendVKey). The key-vs-button distinction separates it cleanly from the sibling sap_press_button, so an agent can route correctly without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.