arc-1 1.5.2 → 1.7.0

package/dist/handlers/tools.js

@@ -3,12 +3,16 @@ import { ATC_BATCH_MAX_OBJECTS, ATC_BATCH_NAME_MAX_LENGTH, ATC_BATCH_NAME_PATTER
 import { KTD_SHORT_TEXT_MAX_LENGTH } from '../adt/ddic-xml.js';
 import { TEXT_ELEMENT_PARTS } from '../adt/text-elements.js';
 import { MAX_GREP_PATTERN_LENGTH } from '../context/grep.js';
+import { API_RELEASE_FIELDS } from './api-release-fields.js';
 import * as DtelFields from './data-element-fields.js';
 import { SAPDIAGNOSE_ADDITIONAL_INPUTS } from './diagnose-fields.js';
+import { dumpFiltersJson } from './dump-filter-inputs.js';
 import * as FuncProcessing from './function-processing.js';
 import { getHyperfocusedToolDefinition } from './hyperfocused.js';
 import { CLASS_WRITE_INCLUDES } from './object-types.js';
+import { createQueryDefinition } from './query-tool.js';
 import { addLiveRelationsDefinition } from './relation-tool.js';
+import { TABLE_TYPE_BATCH_TOOL_PROPERTIES, TABLE_TYPE_DIMENSION_TOOL_PROPERTIES, TABLE_TYPE_TOOL_PROPERTIES, } from './table-type-fields.js';
 import { SAPWRITE_DESC_BTP, SAPWRITE_DESC_ONPREM } from './tool-descriptions.js';
 import { ATC_BATCH_TYPES_BTP, isGitToolVisible, SAPCONTEXT_TYPES_BTP, SAPCONTEXT_TYPES_ONPREM, SAPREAD_TYPES_BTP, SAPREAD_TYPES_ONPREM, SAPWRITE_TYPES_BTP, SAPWRITE_TYPES_ONPREM, } from './tool-registry.js';
 import { BATCH_CREATE_MAX_OBJECTS } from './write/batch-results.js';
@@ -41,12 +45,12 @@ const TOOL_ANNOTATIONS = {
 function isBtpMode(config) {
     return config.systemType === 'btp';
 }
-const SAPREAD_DESC_ONPREM = 'Read SAP ABAP source, metadata or syntax-check results. For purpose, explanations, specs, reviews or pre-change context, prefer SAPContext first. DDIC metadata: omit format (default text); structured is CLAS-only for ordinary reads. ' +
-    'Types: PROG, CLAS, INTF, FUNC, FUGR (expand_includes=true for all include sources), INCL, DDLS, DCLS, DDLX, BDEF, SRVD, SRVB, SKTD/KTD (KTD aliases SKTD), TABL (covers both transparent tables AND DDIC structures — no separate STRU type), TTYP, VIEW, DOMA, DTEL, TRAN, TABLE_CONTENTS (single-column filter), TABLE_QUERY (multi-column WHERE via the freestyle endpoint; gated by allowDataPreview; CDS views need SAP_BASIS 752+), DEVC, SOBJ (BOR — method param reads one method), SYSTEM, COMPONENTS, MSAG, TEXT_ELEMENTS, VARIANTS, BSP, BSP_DEPLOY, API_STATE (contract states C0-C4; objectType for non-class), INACTIVE_OBJECTS (no name; pending-activation list), AUTH, FEATURE_TOGGLE, ENHO, VERSIONS, VERSION_SOURCE. AUTH/FEATURE_TOGGLE/ENHO/VERSIONS/VERSION_SOURCE are on-prem only. ' +
-    'SYNTAX: read-only SAP check (objectType+name, optional source for unsaved text). CLAS: method="*" for signatures, method="NAME" for one body, or grep. Global class declaration/implementation: MAIN (omit include). definitions/implementations contain local helpers. ' +
-    'grep: case-insensitive regex; returns matching lines, context and line numbers, with owning class/method for CLAS.';
+const SAPREAD_DESC_ONPREM = 'Read SAP ABAP source, metadata and syntax results. ' +
+    'For source purpose, explanations, specs, reviews or pre-change context, prefer SAPContext first. DDIC metadata: omit format (default text); structured is CLAS-only for ordinary reads. ' +
+    'TABLE_QUERY: multi-column filters, data preview required; CDS needs SAP_BASIS 752+. TABLE_CONTENTS: single-column filter. INACTIVE_OBJECTS: no name. TABL/DTT: technical settings. ' +
+    'SYNTAX: read-only SAP check (objectType+name, optional source for unsaved text). CLAS: method="*" for signatures, method="NAME" for one body, or grep. Global class declaration/implementation: MAIN (omit include). definitions/implementations contain local helpers.';
 const SAPREAD_DESC_BTP = 'Read SAP ABAP source, metadata or syntax-check results (BTP ABAP Environment). For purpose, explanations, specs, reviews or pre-change context, prefer SAPContext first. DDIC metadata: omit format (default text); structured is CLAS-only for ordinary reads. ' +
-    'Types: CLAS, INTF, FUNC (released/custom only), FUGR (released/custom only), DDLS (primary data model on BTP), DCLS, DDLX, BDEF, SRVD, SRVB, SKTD/KTD (KTD aliases SKTD), TABL (custom tables AND structures — no separate STRU type), DOMA, DTEL, TABLE_CONTENTS (custom tables + released CDS only; standard tables blocked), TABLE_QUERY (multi-column WHERE on custom tables + released CDS; needs SAP_BASIS 752+), DEVC, SYSTEM, COMPONENTS, MSAG (custom only), BSP, BSP_DEPLOY, API_STATE (contract states C0-C4; objectType for non-class), INACTIVE_OBJECTS (no name; pending-activation list). PROG/INCL/VIEW/TRAN/TEXT_ELEMENTS/VARIANTS and VERSIONS/VERSION_SOURCE are not available on BTP (use CLAS with IF_OO_ADT_CLASSRUN for console apps, DDLS for data models). ' +
+    'Types: CLAS, INTF, FUNC (released/custom only), FUGR (released/custom only), DDLS (primary data model on BTP), DCLS, DDLX, BDEF, SRVD, SRVB, SKTD/KTD (KTD aliases SKTD), TABL (custom tables AND structures — no separate STRU type), TABL/DTT (technical settings), TTYP, DOMA, DTEL, TABLE_CONTENTS (custom tables + released CDS only; standard tables blocked), TABLE_QUERY (multi-column WHERE on custom tables + released CDS; needs SAP_BASIS 752+), DEVC, SYSTEM, COMPONENTS, MSAG (custom only), BSP, BSP_DEPLOY, API_STATE (contract states C0-C4; objectType for non-class), INACTIVE_OBJECTS (no name; pending-activation list), ENHO. PROG/INCL/VIEW/TRAN/TEXT_ELEMENTS/VARIANTS and VERSIONS/VERSION_SOURCE are not available on BTP (use CLAS with IF_OO_ADT_CLASSRUN for console apps, DDLS for data models). ' +
     'SYNTAX: read-only SAP check (objectType+name, optional source for unsaved text). CLAS: method="*" for signatures, method="NAME" for one body, or grep. Global class declaration/implementation: MAIN (omit include). definitions/implementations contain local helpers. ' +
     'grep: case-insensitive regex; returns matching lines, context and line numbers, with owning class/method for CLAS.';
 // ─── SAPContext Types ───────────────────────────────────────────────
@@ -70,15 +74,6 @@ const SAPCONTEXT_DESC_BTP = 'Primary tool for understanding ABAP/CDS objects bef
     'deps: target KTD when available + selected dependency contracts, derived from source (not SAP-native relationships or a complete inventory). Counts distinguish root candidates from recursive attempts. On BTP, CL_ABAP_*/IF_ABAP_* and custom Z/Y are included.\n' +
     'structure (TABL only): the DDIC include/append tree.\n\n' +
     'Full detail: docs_page SAPContext.';
-// ─── SAPQuery ───────────────────────────────────────────────────────
-const SAPQUERY_DIALECT_GUIDE = 'ADT freestyle ABAP SQL: one read-only SELECT. Use AS aliases, alias~field/alias~*, ASCENDING/DESCENDING, single-quoted literals (no @/:/? parameters), and maxRows (not TOP/LIMIT/OFFSET/FETCH). JOINs, GROUP BY, aggregates, UNION and subqueries work. CTEs, FULL JOIN, derived/window tables, INTERSECT/EXCEPT, comments, semicolons and schema prefixes do not. ARC-1 auto-chunks long literal IN-lists in plain projection SELECTs. ';
-const SAPQUERY_DESC_ONPREM = 'Query SAP tables with ABAP SQL; returns columns + rows. For reverse-engineering metadata: DD02L, DD03L, TADIR, TFDIR, SWOTLV. Unknown tables get suggestions. ' +
-    SAPQUERY_DIALECT_GUIDE +
-    'For CDS consumers, do not scan DDDDLSRC/ACMDCLSRC/DDLXSRC_SRC; use SAPContext(action="impact", type="DDLS").';
-const SAPQUERY_DESC_BTP = 'Query BTP ABAP Environment with ABAP SQL; returns columns + rows. ' +
-    SAPQUERY_DIALECT_GUIDE +
-    'BTP permits custom Z/Y tables and released CDS entities; standard tables are blocked. ' +
-    'Use released views such as I_LANGUAGE. Unknown tables get suggestions.';
 // ─── SAPSearch ──────────────────────────────────────────────────────
 const SAPSEARCH_DESC_ONPREM = 'Search for ABAP objects, exact object-directory entries, or source code. Modes:\n' +
     '1. Object search (default): name pattern with wildcards (*); returns type, name, package, description, ADT URI.\n' +
@@ -306,8 +301,10 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                     type: {
                         type: 'string',
                         enum: btp ? SAPREAD_TYPES_BTP : SAPREAD_TYPES_ONPREM,
-                        description: 'Object or metadata type. TABL includes DDIC structures; KTD aliases SKTD (Knowledge Transfer Documents). SYNTAX checks objectType+name. Server-driven objects use discovery-gated XML metadata and AFF JSON source (DTSC/DSFD/DTDC/DRTY use DDL text). DESD logical external schema; EVTB event binding; EVTO event object; CSNM CSN model; COTA communication target; DTSC static cache; DTDC dynamic cache; DSFD scalar function; UIAD launchpad descriptor; DRTY CDS type; APLO log object; SAJC/SAJT job catalog/template. Deprecated: MESSAGES→MSAG.' +
-                            (btp ? ' ENQU lock object as JSON.' : ' FTG2→FEATURE_TOGGLE. ENQU lock object as JSON.'),
+                        description: 'Repository or metadata type. TABL includes structures. KTD aliases SKTD; MESSAGES aliases MSAG. ' +
+                            (btp ? '' : 'FTG2 aliases FEATURE_TOGGLE. ') +
+                            'SYNTAX requires objectType+name. Server-driven: discovery-gated XML metadata, AFF JSON source; DTSC/DSFD/DTDC/DRTY use DDL text. ENQU: JSON. TABL/DTI: TABLE~INDEX, prefers pending JSON. ' +
+                            'DESD external schema; EVTB/EVTO event binding/object; CSNM CSN model; COTA communication target; DTSC/DTDC static/dynamic cache; DSFD scalar function; UIAD launchpad descriptor; DRTY CDS type; APLO log object; SAJC/SAJT job catalog/template.',
                     },
                     name: { type: 'string', description: 'Object name (e.g., ZTEST_PROGRAM, ZCL_ORDER, MARA)' },
                     action: {
@@ -325,17 +322,16 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                     },
                     fromLabel: {
                         type: 'string',
-                        description: 'action="diff" optional display label for the OLD side in the summary and patch header, e.g. "DNT-6-6: Validate discounts (DS7K900123)". Does not affect source resolution.',
+                        description: 'Diff OLD-side display label; does not change source resolution.',
                     },
                     toLabel: {
                         type: 'string',
-                        description: 'action="diff" optional display label for the NEW side in the summary and patch header, e.g. "active" or "inactive draft". Does not affect source resolution.',
+                        description: 'Diff NEW-side display label; does not change source resolution.',
                     },
                     include: {
                         type: 'string',
-                        description: 'CLAS: omit include or use main for the global declaration + implementation; definitions/implementations select local helper classes, macros/testclasses their own sections. Explicit include wins over method auto-routing. ' +
-                            'For DDLS: use include="elements" for the CDS field catalog (key fields, aliases, associations, expression types) instead of raw DDL. ' +
-                            'For VERSIONS (CLAS): include selects the class include history to query (main, definitions, implementations, macros, testclasses). BSP: case-sensitive path; name may also be APP/path.' +
+                        description: 'TABL: indexes. CLAS: omit include or use main for global class; definitions/implementations are local helpers; macros/testclasses as named. Explicit include wins over method routing. ' +
+                            'DDLS: elements returns field catalog (keys, aliases, associations, types). VERSIONS CLAS: selects include history. BSP: case-sensitive path; name also accepts APP/path.' +
                             // TEXT_ELEMENTS does not exist on BTP — keep the BTP surface byte-identical.
                             (btp ? '' : ' TEXT_ELEMENTS: symbols|selections|headings; omit for pool (CLAS: symbols).'),
                     },
@@ -352,18 +348,29 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                     grep: {
                         type: 'string',
                         maxLength: MAX_GREP_PATTERN_LENGTH,
-                        description: 'Regex pattern (case-insensitive) to search within the object source. Returns only matching lines with 1-based line numbers and ±3 context lines, instead of the full source — token-efficient. ' +
-                            'For CLAS, matches are annotated with the owning class/method; combine with include= to scope a section, but do NOT combine with method= (use grep to find, then method= to read). ' +
+                        description: 'Case-insensitive source regex: matching lines, 1-based numbers and ±3 context; invalid regex becomes literal. CLAS adds owning class/method; include scopes a section. Never combine with method. ' +
                             'Works for source-bearing types (CLAS, INTF, DDLS, DCLS, BDEF, SRVD, SRVB, SKTD/KTD, DDLX, TABL' +
                             (btp ? '' : ', PROG, FUNC, FUGR, INCL, VIEW') +
-                            '). Falls back to a literal search when the pattern is not valid regex.',
+                            ').',
+                    },
+                    lineStart: {
+                        type: 'integer',
+                        minimum: 1,
+                        description: 'First source line (1-based, inclusive); requires lineEnd. Text reads only: CLAS, INTF, DDLS, DCLS, BDEF, SRVD, DDLX, TABL' +
+                            (btp ? '' : ', PROG, FUNC, INCL') +
+                            '. Supports CLAS include; incompatible with grep, method, diff, structured/editable output and signature/element extraction.',
+                    },
+                    lineEnd: {
+                        type: 'integer',
+                        minimum: 1,
+                        description: 'Last source line (inclusive); requires lineStart. Clamped to the source end; a start beyond the source is an error.',
                     },
                     ...(btp
                         ? {}
                         : {
                             expand_includes: {
                                 type: 'boolean',
-                                description: 'For FUGR type only. When true, recursively expands the function group include tree — the main source plus all nested INCLUDEs (the FUNCTION...ENDFUNCTION bodies live in nested LZ<grp>U01/U02 includes, so a flat one-level walk misses them). Each block is prefixed with a "=== name ===" marker; depth/count-capped. Dynpros and GUI status are not included (ADT does not expose them over REST).',
+                                description: 'PROG/INCL/FUGR: add nested includes as "=== name ===" blocks; bounded, a closing note reports omissions. With grep: search all (FUGR: implied). No dynpros.',
                             },
                         }),
                     format: {
@@ -378,7 +385,7 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                     },
                     includeSignature: {
                         type: 'boolean',
-                        description: 'For FUNC type only. When true, response is JSON: {source, signature: {importing[], exporting[], changing[], tables[], exceptions[], raising[]}, processingType?, updateTaskKind?} — each parameter parsed into {kind, name, type, byValue?, default?, optional?}; processingType reports rfc/update/normal. Default false (returns plain source body).',
+                        description: 'FUNC: JSON {source,signature,processingType?,updateTaskKind?}. Signature and descriptions come from source. Default false: raw source.',
                     },
                     force_refresh: {
                         type: 'boolean',
@@ -417,8 +424,8 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                     where: {
                         type: 'array',
                         description: 'For TABLE_QUERY: structured WHERE conditions, ANDed together. Each item: {field, op, value?}. ' +
-                            'Ops: =, <>, <, <=, >, >=, LIKE, NOT LIKE, IN, NOT IN, IS NULL, IS NOT NULL; use <> because 758 rejects !=. ' +
-                            'For IN/NOT IN: use bare comma-separated values; do NOT quote them. ARC-1 quotes and escapes values, e.g. "261,262". No subqueries. ' +
+                            'Ops: =, <>, <, <=, >, >=, LIKE, NOT LIKE, IN, NOT IN, IS NULL, IS NOT NULL; STARTS_WITH: literal prefix. Use <>; 758 rejects !=. ' +
+                            'IN/NOT IN: bare comma-separated values, e.g. "261,262". ARC-1 quotes/escapes them; no subqueries. ' +
                             'Example: [{"field":"MATNR","op":"=","value":"300006888"},{"field":"BUDAT_MKPF","op":">=","value":"20250101"}].',
                         items: {
                             type: 'object',
@@ -468,9 +475,7 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                             'batch_create',
                             'scaffold_rap_handlers',
                             'generate_behavior_implementation',
-                            // Class text-symbol writes are on-prem only (BTP has no classic text elements) — keep out
-                            // of the BTP action enum so the zod↔json-schema parity check stays green.
-                            ...(btp ? [] : ['edit_text_symbols']),
+                            'edit_text_symbols',
                         ],
                         // This is where an LLM decides WHICH action to use, so every action gets a line —
                         // especially the destructive and refusing ones, whose behaviour is not guessable.
@@ -485,20 +490,20 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                             'delete_method is destructive — it discards the body, so to re-section a method use change_method_visibility, never delete+add. ' +
                             'scaffold_rap_handlers / generate_behavior_implementation: derive behavior-pool handlers from a BDEF (the latter is the equivalent of Eclipse\'s "Generate Behavior Implementation").' +
                             (btp
-                                ? ''
+                                ? ' edit_text_symbols: replace CLAS symbols (@MaxLength:NN\\nNNN=text; blank-line separated). Read first with SAPRead CLAS include=text_symbols; source="" clears the pool. Activates texts only.'
                                 : ' edit_text_symbols: replace a CLAS/PROG/FUGR textpool part; read first, retain other entries. source="" clears it.'),
                     },
                     type: {
                         type: 'string',
                         enum: btp ? SAPWRITE_TYPES_BTP : SAPWRITE_TYPES_ONPREM,
                         description: btp
-                            ? 'Object type (for create/update/delete/edit_method/edit_class_definition/add_method/edit_method_signature/delete_method/change_method_visibility). Supported on BTP: CLAS, INTF, DDLS, DCLS, DDLX, BDEF, SRVD, SRVB, SKTD or KTD (Knowledge Transfer Documents), TABL, TABL/DT, TABL/DS, DOMA, DTEL, MSAG. Class-section surgery actions require type=CLAS. UIAD: checks AFF JSON; create honors header.abapLanguageVersion. Manual cloudDevelopment items are editable; generated items may be read-only.'
+                            ? 'Object type. Class-section surgery actions require type=CLAS. UIAD: checks AFF JSON; create honors header.abapLanguageVersion. Manual cloudDevelopment items are editable; generated items may be read-only.'
                             : 'Object type (for create/update/delete/edit_method/edit_unit/add_unit/edit_class_definition/add_method/edit_method_signature/delete_method/change_method_visibility). Supported on-prem: PROG, CLAS, INTF, FUNC, FUGR, INCL, DDLS, DCLS, DDLX, BDEF, SRVD, SRVB, SKTD or KTD (Knowledge Transfer Documents), TABL, TABL/DT, TABL/DS, DOMA, DTEL, MSAG. Class-section surgery actions require CLAS. UIAD: validates AFF JSON and saves active; create honors header.abapLanguageVersion. Manual cloudDevelopment items are editable; generated items can be read-only.',
                     },
                     name: {
                         type: 'string',
                         description: btp
-                            ? 'Object name (for create/update/delete/edit_method/edit_class_definition/add_method/edit_method_signature/delete_method/change_method_visibility).'
+                            ? 'Object name.'
                             : 'Object name (for create/update/delete/edit_method/edit_unit/add_unit/edit_class_definition/add_method/edit_method_signature/delete_method/change_method_visibility).',
                     },
                     expectedSourceHash: {
@@ -517,7 +522,7 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                         description: 'CLAS-ONLY. Do NOT send unless type=CLAS AND action is update / edit_method / edit_class_definition. OMIT it entirely for every other type and for delete / batch_create / add_method / edit_method_signature / delete_method / change_method_visibility (those use /source/main). Targets a class-local include: definitions (CCDEF), implementations (CCIMP), macros, testclasses. edit_method auto-detects it from the method specifier (lhc_*/lcl_* → implementations, ltc_* → testclasses), so you rarely pass it; use include=testclasses to create a new local test class. Whole-include writes auto-create a missing include and produce an inactive draft (read with SAPRead version="inactive" before activation).',
                     },
                     ...(btp
-                        ? {}
+                        ? { textPart: { type: 'string', enum: ['symbols'] } }
                         : {
                             textPart: {
                                 type: 'string',
@@ -588,15 +593,8 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                     },
                     ...(btp ? {} : FuncProcessing.FUNCTION_PROCESSING_TOOL_PROPERTIES),
                     dataType: { type: 'string', description: 'DOMA/DTEL: ABAP data type (e.g., CHAR, NUMC, DEC)' },
-                    rowType: {
-                        type: 'string',
-                        description: 'TTYP create: the row type — a built-in ABAP type (STRING, I, …) or a DDIC structure/type name. Required for TTYP create.',
-                    },
-                    rowTypeKind: {
-                        type: 'string',
-                        enum: ['builtin', 'structure'],
-                        description: 'TTYP create: row-type mode (auto-detected from rowType if omitted).',
-                    },
+                    ...TABLE_TYPE_TOOL_PROPERTIES,
+                    ...TABLE_TYPE_DIMENSION_TOOL_PROPERTIES,
                     length: { type: 'number', description: 'DOMA/DTEL: data type length' },
                     decimals: { type: 'number', description: 'DOMA/DTEL: decimal places' },
                     outputLength: { type: 'number', description: 'DOMA: output length' },
@@ -648,19 +646,25 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                     },
                     parameters: {
                         type: 'array',
-                        description: 'FUNC: structured signature parameters. ARC-1 builds the IMPORTING/EXPORTING/CHANGING/TABLES/EXCEPTIONS/RAISING clause and splices it into the FM body. When omitted, the supplied source is PUT verbatim.',
+                        description: 'FUNC: replace the source signature with these parameters; preserve the body. Omit to PUT source verbatim.',
                         items: {
                             type: 'object',
                             properties: {
                                 kind: {
                                     type: 'string',
                                     enum: ['importing', 'exporting', 'changing', 'tables', 'exceptions', 'raising'],
-                                    description: 'Parameter kind. EXCEPTIONS/RAISING use only `name`; the others require `type`.',
+                                    description: 'EXCEPTIONS/RAISING need only name; other kinds need type.',
                                 },
                                 name: { type: 'string', description: 'Parameter / exception name (uppercased on emit).' },
+                                description: {
+                                    type: 'string',
+                                    minLength: 1,
+                                    maxLength: 60,
+                                    description: 'Importing/exporting/changing/tables short text: 1–60 printable characters in the original language; omit to preserve.',
+                                },
                                 type: {
                                     type: 'string',
-                                    description: 'ABAP type expression. Required for IMPORTING/EXPORTING/CHANGING/TABLES; ignored for EXCEPTIONS/RAISING. Examples: "STRING", "I", "BAPIRET2", "TYPE STANDARD TABLE OF X", "LIKE DOKHL-OBJECT". For TABLES, include the leading TYPE/LIKE keyword.',
+                                    description: 'ABAP type, e.g. STRING, I, BAPIRET2. TABLES includes TYPE/LIKE, e.g. TYPE STANDARD TABLE OF X or LIKE DOKHL-OBJECT. Ignored for exceptions/raising.',
                                 },
                                 byValue: {
                                     type: 'boolean',
@@ -668,7 +672,7 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                                 },
                                 default: {
                                     type: 'string',
-                                    description: 'Raw ABAP literal — IMPORTING/CHANGING only. Emitted verbatim. Example: "\'X\'", "0", "SPACE".',
+                                    description: 'Raw ABAP literal for IMPORTING/CHANGING, e.g. "\'X\'", "0", "SPACE".',
                                 },
                                 optional: { type: 'boolean', description: 'Emit `OPTIONAL` keyword.' },
                             },
@@ -713,7 +717,7 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                     },
                     refObjectDescription: {
                         type: 'string',
-                        description: 'SKTD/KTD create: parent description; required and nonempty for SMBC/TYP (BCMO).',
+                        description: 'SKTD/KTD create: optional parent description; blank values are omitted.',
                     },
                     shortTexts: {
                         type: 'array',
@@ -735,8 +739,8 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                             properties: {
                                 type: {
                                     type: 'string',
-                                    enum: btp ? SAPWRITE_TYPES_BTP : SAPWRITE_TYPES_ONPREM,
-                                    description: 'Object type (includes TABL for RAP stack bootstrapping)',
+                                    enum: (btp ? SAPWRITE_TYPES_BTP : SAPWRITE_TYPES_ONPREM).filter((type) => type !== 'TABL/DTT'),
+                                    description: 'Creatable object type; technical settings TABL/DTT are update-only',
                                 },
                                 name: { type: 'string', description: 'Object name' },
                                 source: { type: 'string', description: 'ABAP source code (optional — some objects have no source)' },
@@ -753,8 +757,8 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                                 // DDIC metadata fields (DOMA/DTEL/TTYP/MSAG/SRVB) mirror the top-level SAPWrite
                                 // params 1:1 — descriptions omitted here to keep the tools/list payload small (#520).
                                 dataType: { type: 'string' },
-                                rowType: { type: 'string' },
-                                rowTypeKind: { type: 'string', enum: ['builtin', 'structure'] },
+                                ...TABLE_TYPE_BATCH_TOOL_PROPERTIES,
+                                ...TABLE_TYPE_DIMENSION_TOOL_PROPERTIES,
                                 length: { type: 'number' },
                                 decimals: { type: 'number' },
                                 outputLength: { type: 'number' },
@@ -864,8 +868,8 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
     tools.push({
         name: 'SAPNavigate',
         description: btp
-            ? 'Navigate code (BTP ABAP Environment): definitions, references, completion, hierarchy. references: scope-based where-used with lines/snippets/package; objectType filters results (e.g. CLAS/OC); type+name replaces uri. Scope = released SAP + custom Z/Y. hierarchy queries SEOMETAREL: requires data/SQL opt-in + matching scope; otherwise inspect class MAIN with SAPRead. CDS (DDLS) impact: SAPContext(action="impact") classifies where-used into RAP buckets.'
-            : 'Navigate code: definitions, references, completion, hierarchy. references: scope-based where-used with lines/snippets/package; objectType filters results (e.g. CLAS/OC, PROG/P); type+name replaces uri. hierarchy queries SEOMETAREL for superclass/interfaces/direct subclasses: requires data/SQL opt-in + matching scope; otherwise inspect class MAIN with SAPRead. CDS (DDLS) impact: SAPContext(action="impact") classifies where-used into RAP buckets.',
+            ? 'Navigate code (BTP ABAP Environment): definitions, references, completion, hierarchy. references: where-used objects by default; detail=positions/snippets adds bounded native usages; objectType filters results (e.g. CLAS/OC); type+name replaces uri. Scope = released SAP + custom Z/Y. hierarchy queries SEOMETAREL: requires data/SQL opt-in + matching scope; otherwise inspect class MAIN with SAPRead. CDS (DDLS) impact: SAPContext(action="impact") classifies where-used into RAP buckets.'
+            : 'Navigate code: definitions, references, completion, hierarchy. references: where-used objects by default; detail=positions/snippets adds bounded native usages; objectType filters results (e.g. CLAS/OC, PROG/P); type+name replaces uri. hierarchy queries SEOMETAREL for superclass/interfaces/direct subclasses: requires data/SQL opt-in + matching scope; otherwise inspect class MAIN with SAPRead. CDS (DDLS) impact: SAPContext(action="impact") classifies where-used into RAP buckets.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -887,6 +891,18 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                     type: 'string',
                     description: 'references RESULT filter, not the root type: CLAS/OC, PROG/P, FUGR/FF. Omit for all consumer types. A bare prefix ("CLAS") matches every subtype.',
                 },
+                packages: {
+                    type: 'array',
+                    minItems: 1,
+                    maxItems: 20,
+                    items: { type: 'string', maxLength: 30 },
+                    description: 'references: exact package names (e.g. ["$TMP"]); no wildcards or implicit subpackages. Native scope when available, otherwise local filtering.',
+                },
+                detail: {
+                    type: 'string',
+                    enum: ['objects', 'positions', 'snippets'],
+                    description: 'references: objects (default), or expand at most 10 native nodes for positions/snippets. Method positions can be component-relative; inspect usageDetails limits.',
+                },
                 maxResults: {
                     type: 'number',
                     description: 'references: max entries (default 100, max 1000). "total" counts every match of the filter.',
@@ -900,24 +916,9 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
     });
     const navigation = tools.find((tool) => tool.name === 'SAPNavigate');
     addLiveRelationsDefinition(navigation, config, options.discoveryMap ?? resolvedFeatures?.discoveryMap);
-    // SAPQuery — only registered when free SQL is allowed
-    if (config.allowFreeSQL) {
-        tools.push({
-            name: 'SAPQuery',
-            description: btp ? SAPQUERY_DESC_BTP : SAPQUERY_DESC_ONPREM,
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    sql: { type: 'string', description: 'ABAP SQL SELECT statement' },
-                    maxRows: {
-                        type: 'number',
-                        description: 'Rows (default 100, max 10,000; byte limit may apply sooner).',
-                    },
-                },
-                required: ['sql'],
-            },
-        });
-    }
+    const query = createQueryDefinition(config, resolvedFeatures);
+    if (query)
+        tools.push(query);
     tools.push({
         name: 'SAPLint',
         description: 'Run local abaplint rules on ABAP/CDS source (auto-selects cloud or on-prem rules by system type). Actions:\n' +
@@ -958,26 +959,27 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
         },
     }, {
         name: 'SAPDiagnose',
-        description: 'ABAP diagnostics and runtime analysis. Actions:\n' +
-            '- "syntax": compatibility check; when available prefer SAPRead(type="SYNTAX", objectType, name, version?, source?).\n' +
+        description: 'ABAP diagnostics:\n' +
+            '- "syntax": check objects[] (CLAS/INTF/PROG/DDLS; version active/inactive). Single: prefer SAPRead SYNTAX.\n' +
             '- "unittest": harmless ABAP Unit for CLAS/PROG/FUGR or DEVC (exact; includeSubpackages recurses).\n' +
             '- "unittest_ci": harmless package tests with source reconciliation; empty/incomplete runs fail.\n' +
-            '- "atc": run ATC checks (name+type or objects [{type,name}], max 20; omit variant to bind the system default; unknown variant = error). "atc_variants": list variants + that default (variant = name filter; read-only).\n' +
+            '- "atc": ATC (name+type or objects [{type,name}], max 20). Omit variant for system default; unknown variant errors. "atc_variants": read variants/default, optional variant name filter.\n' +
             '- "atc_ci": package ATC CI; requires available API and verified selection.\n' +
-            '- "cds_testcases": SAP-suggested ABAP Unit test cases for a CDS entity (name; read-only; SAP_BASIS 8.16+).\n' +
-            '- "object_state": active/inactive ETags, hashes and divergence (name+type; CLAS: all includes). Server-driven types unsupported.\n' +
-            '- "quickfix": proposals at name+type+source+line (optional column/sourceUri).\n' +
-            '- "apply_quickfix": return proposal text deltas without writing; needs quickfix inputs + proposalUri/proposalUserContent.\n' +
-            '- "dumps": list/read ST22 short dumps (no id = list, newest first, user/from/to/maxResults; id = read; includeFullText, sections).\n' +
+            '- "cds_testcases": read suggested CDS Unit tests (name; SAP_BASIS 8.16+).\n' +
+            '- "object_state": active/inactive ETags/hashes/divergence (name+type; CLAS includes). No server-driven types.\n' +
+            '- "quickfix": proposals: name+type+source+line; optional column/sourceUri.\n' +
+            '- "apply_quickfix": text deltas, no save; quickfix inputs + proposalUri/proposalUserContent.\n' +
+            '- "dumps": ST22, newest: user/from/to/maxResults/filters; id=detail.\n' +
+            '- "feed_schema": optional dump filters; action only.\n' +
             '- "traces": list profiler traces; id+analysis analyzes one.\n' +
-            '- "trace_start": arm a profiler trace for the NEXT matching execution, then reproduce and read via "traces" (write scope; defaults: next HTTP request, SQL on).\n' +
-            '- "trace_requests": list armed trace requests. "trace_cancel": cancel one by id (write scope).\n' +
+            '- "trace_start": arm NEXT matching execution (write; defaults HTTP, SQL on); reproduce, then read "traces".\n' +
+            '- "trace_requests": list armed traces. "trace_cancel": cancel by id (write).\n' +
             '- "system_messages": list SM02 messages. "gateway_errors": list /IWFND/ERROR_LOG (on-prem; detailUrl or id+errorType for detail).\n' +
-            '- "odata_perf": diagnose why an OData call is slow (url = host-relative path); returns the sap-statistics timing split (DB/ABAP/framework/auth). Read-only; needs allowDataPreview.\n' +
-            '- "authorization_trace": read the on-prem STUSERTRACE auth trace (SUAUTHVALTRC); needs SAP_ALLOW_DATA_PREVIEW.\n' +
-            '- "cds_sql": show the native SQL a CDS view compiles to (name; read-only).\n' +
+            '- "odata_perf": read OData timing (url: host-relative; DB/ABAP/framework/auth); needs allowDataPreview.\n' +
+            '- "authorization_trace": read STUSERTRACE/SUAUTHVALTRC (on-prem; needs SAP_ALLOW_DATA_PREVIEW).\n' +
+            '- "cds_sql": read CDS native SQL (name).\n' +
             '- "sql_trace_state" / "set_sql_trace_state" (sqlOn; needs SAP_ALLOW_WRITES) / "sql_trace_directory": ST05 SQL-trace control.\n' +
-            'Quickfix workflow: syntax/ATC → quickfix → apply_quickfix → write via SAPWrite. Full action reference: docs_page SAPDiagnose.',
+            'Quickfix: syntax/ATC → quickfix → apply_quickfix → SAPWrite.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -992,6 +994,7 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                         'atc_variants',
                         'cds_testcases',
                         'dumps',
+                        'feed_schema',
                         'traces',
                         'trace_start',
                         'trace_requests',
@@ -1025,7 +1028,7 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                     type: 'array',
                     minItems: 1,
                     maxItems: ATC_BATCH_MAX_OBJECTS,
-                    description: 'ATC only, instead of name/type/url. One batch + at most one verification. Returns coverage; unreported objects stay incomplete. No packages.',
+                    description: 'ATC/syntax list instead of name/type/url. ATC may verify once. Missing reports stay incomplete. No packages.',
                     items: {
                         type: 'object',
                         required: ['type', 'name'],
@@ -1087,7 +1090,7 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                 },
                 id: {
                     type: 'string',
-                    description: 'Dump or trace ID (for dumps/traces actions); also the trace-request id to cancel (for trace_cancel). Omit to list, provide to get details.',
+                    description: 'dumps/traces: omit to list, supply for detail. trace_cancel: request ID.',
                 },
                 detailUrl: {
                     type: 'string',
@@ -1098,6 +1101,10 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                     description: 'gateway_errors: required with id instead of detailUrl, e.g. "Frontend Error".',
                 },
                 user: { type: 'string', description: 'SAP-user filter for dumps, feeds, or authorization_trace.' },
+                filters: {
+                    ...dumpFiltersJson,
+                    description: 'AND ≤8 incl. user: [{attribute:"runtimeError",operator:"equals",values:["MESSAGE_TYPE_X"]}].',
+                },
                 authObject: { type: 'string', description: 'Authorization object filter, e.g. S_TCODE.' },
                 from: {
                     type: 'string',
@@ -1314,16 +1321,7 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                     type: 'string',
                     description: 'ADT object type (e.g., CLAS/OC, DDLS/DF, PROG/P). Required for change_package. For set_api_state: object type of "name" when objectUri is omitted (e.g. CLAS, INTF, DDLS, TABL).',
                 },
-                apiState: {
-                    type: 'string',
-                    enum: ['RELEASED', 'NOT_RELEASED'],
-                    description: 'For set_api_state: target state of the object\'s API release contract — RELEASED (mark released for ABAP Cloud / Clean Core) or NOT_RELEASED (revoke). Default RELEASED. Visibility (ABAP Cloud / Key User Apps) follows the contract\'s defaults. Read the current state first with SAPRead(type="API_STATE").',
-                },
-                contract: {
-                    type: 'string',
-                    enum: ['C0', 'C1', 'C2', 'C3', 'C4'],
-                    description: 'For set_api_state: which release contract to set. Default C1 (Key-User/Cloud — the common clean-core contract). Object types support different contracts: e.g. service definitions (SRVD) only support C0, classic DDIC views only C3, behavior definitions and tables support C0+C1. If the object does not support the chosen contract, the error lists the ones it does.',
-                },
+                ...API_RELEASE_FIELDS,
                 objectName: {
                     type: 'string',
                     description: 'Object name to move (e.g., ZCL_MY_CLASS). Required for change_package.',
@@ -1391,7 +1389,7 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                         enum: sapTransportActions,
                         description: "list: show transports (defaults to current user, modifiable only). Pass summary=true for a headers-only overview that omits each transport's object lists (keeps an objectCount) — far cheaper when many transports are open. " +
                             'get: fetch transport details including tasks and objects. ' +
-                            'diff: what a transport CHANGED — per object, the revision written under it vs the one before, as diff hunks (get only lists names). LIMU entries roll up to their class; an open transport compares to the last released revision. Read baselineStatus first: prior-revision = solid; prior-revision-unverified = pair guessed, may be another change; no-prior-snapshot = created here; baseline-ambiguous = no baseline, so an all-additions block is NOT proof of creation; baseline-unavailable = the read FAILED, never call that unchanged. ' +
+                            'diff: source review. Released requests need attributed snapshots; open requests use active source, never drafts. baselineStatus: prior-revision=attributed pair; prior-revision-unverified=unattributed candidate; no-prior-snapshot=missing history, NOT creation; baseline-ambiguous=uncertain predecessor; baseline-unavailable=no comparison, NOT unchanged. Non-source gaps are explicit. Follow nextOffset; pages are not snapshots. ' +
                             'create: create a new transport request (description required). To target another system, pass target=<system | system.client | /group/> (the Transportziel / TR_TARGET, e.g. "/TRG/" or "C11"; the group and system.client forms require extended transport control to be active). Otherwise omit target and pass an optional package to let SAP infer the route (defaults to $TMP). The response reports the resolved transport target; an empty target means a LOCAL request (cannot be transported onward). ' +
                             'release: release a single transport or task. ' +
                             'delete: delete a transport (use recursive=true to delete tasks first; removeLockedObjects=true to strip locked objects that otherwise block deletion with "...contains locked objects"). ' +
@@ -1456,7 +1454,7 @@ export function getToolDefinitions(config, textSearchAvailable, resolvedFeatures
                     },
                     summary: {
                         type: 'boolean',
-                        description: 'For list only. DEFAULT true: headers-only — drops each transport\'s (and task\'s) object lists, keeping id/description/owner/status/target + objectCount; use action="get" for one in full. Pass false for full object lists (~5x larger).',
+                        description: 'diff: true omits hunks, retaining counts and evidence (same SAP reads). For list, DEFAULT true: headers-only — drops each transport\'s (and task\'s) object lists, keeping id/description/owner/status/target + objectCount; use action="get" for one in full. Pass false for full object lists (~5x larger).',
                     },
                     maxResults: {
                         type: 'number',