sap_read_table_data

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the ABAP operator set (EQ NE GE LE GT LT LIKE IN), single-quote value rule, date format YYYYMMDD, leading zero treatment for vendor/material keys, and gives a full example. This goes well beyond the bare schema. It would be improved by explicitly stating this is a read-only, no side-effect operation, but 'Query rows' implies a safe read.

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 tight, focused paragraph. It front-loads the purpose in one short line, then layers in contextual guidance (when to use sibling tools), syntax rules, format tips, and an example. Every sentence contributes to practical use and there is no fluff or repetition of schema 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?

The description offers enough context for a 3-parameter tool with no output schema: the where-clause syntax, data formats, key leading zeros, and the example make it usable. It does not explicitly describe the return shape or output, but the intent of 'query rows' and the max_rows parameter cover the main expectations. Since output schema is absent, describing observed row keys or response structure would push it to 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?

Though schema coverage is 100%, the description adds crucial meaning for the where_clause parameter: allowed operators, quoted values, date formats, leading-zero semantics, and an example. The schema's where_clause description only says 'ABAP-style WHERE condition (see tool description)' and defers to the tool description, so the description absolutely compensates and is essential. It also adds context for table_name with numeric key conventions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear, specific verb and resource: 'Query rows from an SAP table with optional WHERE filtering.' It clearly identifies what the tool does and is easily distinguished from siblings like sap_search_tables (finding tables) and sap_read_table_structure (reading table metadata). The mention of using those tools when unsure of table/field names reinforces this differentiation.

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 an explicit prerequisite: 'Use sap_search_tables / sap_read_table_structure first if unsure of the table or field names.' It names the alternative tools and tells the agent when to consult them, which is strong usage guidance. However, it doesn't enumerate when NOT to use this tool, such as when reading code or dumps, so it is not a full exclusion list.

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