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

With no annotations, the description discloses the core action (activation including inactive parts) and the read-only restriction. However, it lacks details on side effects or error states.

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 concise sentences with no waste, front-loaded with the action and essential usage context.

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 single-parameter tool with no output schema, the description covers what it does, when to use, and a key restriction. It is adequate but does not explain return values or nuances of 'inactive parts'.

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 100% and the description does not add extra meaning to the objectUri parameter beyond what the schema already 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?

The description clearly states the action 'Activate an ABAP object' and distinguishes it from siblings by specifying usage after adt_write_source or manual editing.

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 states when to use ('after adt_write_source with activate=false, or to activate a manually edited object') and when not ('Blocked in read-only mode').

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?

No annotations are provided, so the description must fully disclose behavior. It mentions what is returned but does not specify read-only nature, error conditions, or side effects. This is adequate but not thorough.

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 concise sentence immediately stating the purpose, followed by a brief note on return values. No 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?

For a simple tool with one parameter and no output schema, the description covers the main purpose and returns. It could mention read-only nature or whether subpackages are included, but it is largely 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 100%, so the baseline is 3. The description adds only a simple example (e.g., ZMY_PKG) which does not significantly enhance the schema 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?

The description clearly states the verb (list), resource (objects in an ABAP package), and return values (object type, name, URI). It is specific and differentiates from sibling tools like adt_create_package.

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 implies usage (list objects in a package) but does not explicitly state when to use this tool vs alternatives like adt_get_object_structure or adt_search_objects. No when-not-to-use guidance is provided.

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?

Without annotations, the description effectively discloses key behaviors: type derivation, label length handling, package and activation defaults, and return values. It does not cover error scenarios or authentication, but the core behavioral traits are well explained.

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, dense paragraph that efficiently conveys purpose, behavior, and key parameter nuances. It is front-loaded with the core action and follows with relevant details. While not structured with bullet points, it remains concise and scannable.

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 complexity (10 parameters, no output schema, no annotations), the description covers purpose, behavioral details, label defaults, return values, and naming constraints. Missing are explicit error conditions and prerequisites (e.g., domain existence), but the overall completeness is high.

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 100% schema coverage, the baseline is 3. The description adds valuable context beyond schema descriptions, particularly the default label lengths and behavior when longer labels are supplied. This helps an agent understand parameter constraints without relying solely on the 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 clearly states the verb 'create', the resource 'DDIC data element (DTEL)', and key differentiators like referencing an existing domain and automatic type derivation. It distinguishes well from sibling tools like adt_create_domain by specifying the reliance on a pre-existing domain.

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 implies usage when needing a data element based on a domain, mentioning the package default ($TMP) and naming convention. It lacks an explicit statement of when not to use or direct comparison to alternatives, but the context is sufficiently clear for an agent.

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 no annotations, the description carries the full burden and discloses key behaviors: creation in a package (default $TMP), optional activation, naming constraints, and return of object URI and activation status. It does not cover auth or rate limits, but for a creation tool this is sufficient.

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 sentences front-loading the main action, concise with no filler. Every sentence provides essential information (purpose, parameters, constraints, return values).

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 tool with 8 parameters and no output schema, the description covers creation, defaults, naming, activation, and return values. It does not explain error handling or side effects, but is adequate for selecting and using the 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 100%, so baseline is 3. The description adds context like 'default $TMP' and 'local/no transport' and clarifies activation is optional, but largely rephrases schema descriptions. It adds moderate value beyond the 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 clearly states it creates a DDIC domain with specific technical attributes (type, length, decimals) and mentions the naming constraint (Z*/Y* prefix). This distinguishes it from sibling tools like adt_create_dataelement or adt_create_table.

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 explains what the tool does but does not explicitly indicate when to use it versus alternatives or provide exclusion criteria. The context is implied through the object name (domain), but no direct guidance on selecting this tool over siblings like adt_create_dataelement or adt_create_table.

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 no annotations provided, the description carries full burden for behavioral disclosure. It states that the tool creates a function group, optionally activates it, and returns the group URI and activation status. However, it does not disclose side effects (e.g., overwriting existing groups), permissions needed, or what happens if the name already exists.

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 sentences, each providing essential information: main action, prerequisite, naming constraint, and output. No unnecessary words. It is front-loaded with the core purpose.

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 5 parameters, no output schema, and no annotations, the description covers most key aspects: action, naming, default package, activation, output. It could be more explicit about the transport behavior (e.g., 'if omitted and package is $TMP, no transport; otherwise you'll be asked'), but the schema already provides this 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 coverage is 100%, so baseline is 3. The description adds value by clarifying the default behavior for package ($TMP, local/no transport) and indicating output (URI and activation status). It reinforces the naming constraint already in the 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 clearly states 'Create a function group (FUGR) in a package' and mentions activation. It distinguishes from sibling tools by specifying that function modules must live inside a function group, establishing this as a prerequisite for other operations.

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 provides usage context by noting the naming convention (Z*/Y* prefix) and the default package ($TMP, local/no transport). It advises that this tool should be used before creating function modules. However, it does not explicitly state when not to use this tool or mention alternatives.

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 no annotations, the description carries full burden. It discloses that the tool writes source, optionally activates, auto-normalizes source, and returns URI, activation status, and normalized source. It mentions transport handling. Lacks details on error handling or side effects.

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, front-loaded with purpose and precondition. Every sentence adds essential information without fluff. Highly efficient.

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?

Despite no output schema, the description covers purpose, precondition, source format, return info (URI, activation status, normalized source), and transport handling. It lacks detailed error scenarios but is mostly complete for a create 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 100%, baseline 3. The description adds value by clarifying the auto-normalization of source and the two accepted forms (classic with/without local interface), and that activation defaults to true. This enhances understanding beyond 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?

The description clearly states that the tool creates a function module inside an existing function group, writes its source, and optionally activates it. It distinguishes from sibling tools like adt_create_function_group by explicitly requiring the function group to already exist.

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 explicitly says the function group must exist and should be created with adt_create_function_group. It also specifies that the name must match a Z*/Y* prefix. It does not explicitly state when not to use this tool, 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?

No annotations, but description discloses that the object is created without source, returns URI, and names must match prefix. It does not mention authorization needs, rate limits, or side effects like transport request creation.

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, front-loaded with verb and resource. Every sentence adds essential information with no redundancy.

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?

Covers creation intent, follow-up step, naming rules, and default package. Lacks details on transport handling or error scenarios, but sufficient for a shell creation tool with a clear output.

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?

Adds value beyond schema by stating default package ($TMP), required name prefix (Z*/Y*), and return URI. Schema coverage is 80%, but the description enriches the meaning of 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?

Description clearly states the action (create an ABAP object shell), the resource (object in a package), the outcome (returns URI), and adds a constraint (name prefix whitelist). It distinguishes from siblings like adt_write_source and other create 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 says to follow up with adt_write_source, indicating a two-step workflow. Lacks explicit when-not-to-use or alternative tools, but the purpose is clear enough to guide selection.

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?

No annotations provided, so description carries full burden. It discloses nesting inheritance, automatic derivation of software component/transport layer, option to override, and return value (URI + resolved attributes). No mention of destructive behavior or auth, but appropriate for a create tool.

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?

Approximately 5 sentences, well-structured with main action first, then constraints, then parameter clarifications. Slightly dense but not overly verbose; a minor simplification could improve conciseness.

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 no output schema, description explains return value. All 7 parameters are covered with context. Sibling tools are diverse (ABAP development), and this description clearly differentiates the package creation step. Complete for agent use.

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 100% (baseline 3). Description adds meaning beyond schema: clarifies superPackage must be real, softwareComponent/transportLayer inheritance, and naming prefix requirement. This adds value for agent understanding.

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 clearly states the tool creates a development package (DEVC/K) with specific verb 'Create' and resource 'development package'. It distinguishes from siblings by referencing the 'package/transport decision flow' and specifying it's the 'create package' branch.

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 guidance on when to use: when a write tool returns a package clarification. Provides constraints: parent must be real (not $TMP), naming prefix Z*/Y*, and clarifies inheritance and override conditions.

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 no annotations, the description carries full disclosure burden. It transparently discloses auto-prepend of MANDT, default technical attributes (delivery class, enhancement category), field foreign key support, and naming constraints. Minor omissions around error handling and side effects are acceptable for a creation tool of this complexity.

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 coherent paragraph that front-loads the primary action and progressively adds details. Every sentence adds value, covering core functionality, defaults, exceptions (autoClient), constraints, and return values. No redundant or 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?

Given the tool's complexity (10 parameters, no output schema), the description is remarkably complete. It explains the creation process, field types, foreign keys, default behaviors, naming rules, optional activation, and return information (URI, field count, DDL source, activation status). Only minor details like error scenarios are omitted, which is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds significant value beyond the schema by explaining autoClient behavior ('Auto-prepend... disable via autoClient=false'), naming convention, and default technical attributes. This extra context compensates well for the schema's already complete 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?

The description states 'Create a DDIC transparent table (TABL) using ABAP Dictionary DDL' – a specific verb and resource, distinguishing it from siblings like adt_create_domain and adt_create_dataelement. It also clarifies key behaviors such as auto-prepending MANDT and naming constraints, leaving no ambiguity.

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 provides clear context on when to use the tool (creating transparent tables) and covers default behaviors (auto-client, package, activation), naming requirements (Z*/Y* prefix), and optional features. While it does not explicitly list when not to use or compare with siblings, the detail is sufficient for appropriate selection.

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?

Describes the process: reads source, applies replacements, lock->write->unlock->optional activate. Mentions blocked in read-only mode and whitelist. Lacks error handling details but is quite transparent.

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?

Efficient description: one sentence for purpose, one for key benefit, two for constraints and process. No wasted words.

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 annotations or output schema, the description covers purpose, usage, behavior, and parameters well. Missing error scenarios or return value, but overall adequate for an edit 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 100%, so baseline 3. Description adds context: explains oldString uniqueness requirement, deletion via empty newString, and sequential application. Provides meaningful usage guidance beyond 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?

Clear verb+resource: 'precise edit of an ABAP object'. Distinguishes from sibling adt_write_source by noting it is more efficient for few changes.

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 states when to use (instead of adt_write_source for few changes) and constraints (oldString must be unique, blocked in read-only mode, Z*/Y* prefix whitelist).

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?

No annotations provided, so description carries full burden. Describes what it returns (includes sourceUri, method/attribute outline with name+visibility) and that it's token-optimized, but does not explicitly state it is read-only or disclose any side effects, permissions, or rate limits. Adequate but not fully transparent.

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 well-structured sentences: purpose, return content, usage guidance, strategic positioning. No redundant words, each sentence adds value. Highly efficient.

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, but description compensates by detailing the return structure (includes sourceUri, method/attribute outline with name+visibility). Connects to sibling tools for next steps. Could specify more about the outline format, but overall complete for navigating large objects.

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?

Only one parameter (objectUri) with schema description 'Object URI from adt_search_objects'. Schema coverage is 100%, but description adds context by specifying the source of the URI, which helps the agent understand how to obtain it. Baseline 3 with added value.

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?

Description clearly states it gets the structure/outline of an ABAP object, listing specific components (methods, attributes, includes, metadata). It distinguishes from sibling tools like adt_read_source (full source) and adt_search_objects, making the purpose unmistakable.

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 advises using the include sourceUri with adt_read_source for reading includes and method names for edits. Positions itself as a token-optimized entry point for navigating large objects, implicitly telling when to use it (to avoid full source reads). Lacks explicit when-not-to-use conditions but provides clear 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?

With no annotations provided, the description carries the full burden. It states the tool is read-only and that values are decoded to human-readable form, which are key behavioral traits. It does not mention performance, timeouts, or error handling, but these are less critical for a simple read operation.

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 wasted words. The first sentence front-loads the primary purpose and read-only nature. Every sentence 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?

Given the tool's low complexity and full schema coverage, the description adequately covers behavior (read-only, decoding) and options (WHERE, limit). No output schema needed. Could mention that the entity is required, but that is in the 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?

The input schema covers 100% of parameters with descriptions. The description adds no new semantic information beyond summarizing the where clause and row limit, which are already clear from the schema. Baseline 3 applies.

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 clearly states 'Read rows from a DDIC table or CDS view (read-only)', specifying the verb (Read), resource (DDIC table or CDS view), and the read-only nature. This distinguishes it from sibling tools that handle activation, creation, or transport management.

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 implies usage for reading table data without side effects, but lacks explicit when-to-use or when-not-to-use guidance. It does not mention alternatives among siblings, though the read-only hint provides 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?

No annotations provided, so description carries full burden. It describes the operation as listing and returning data, implicitly safe, but does not explicitly state it is read-only or mention any constraints like authorization or rate limits. Adequate but could be more explicit.

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: first sentence states action and output, second provides usage context. No unnecessary words, front-loaded with key 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?

For a simple list operation with one parameter, the description adequately explains what the tool does, what it returns, and when to use it. No output schema, but return values are described. Slightly more detail on potential limitations (e.g., if large groups) could be added.

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?

Only one parameter (functionGroup) with 100% schema coverage already describing it as a function group name. The description reinforces that the parameter is the group to list, but adds minimal new meaning beyond the 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?

Description clearly states the tool lists function modules and includes in a function group, with specific verb 'list' and resource 'function modules'. It also mentions returning name, URI, and description, distinguishing it from siblings like adt_read_function_module.

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 states it is useful for discovering what a group offers before calling/reading a module, giving clear when-to-use context. However, it does not list alternatives or exclusions, which would improve guidance.

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?

No annotations are provided, so the description must convey behavioral traits. It only states the action without mentioning side effects, permissions, or read-only nature. Minimal behavioral 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?

The description is a single, clear sentence that efficiently conveys the core purpose and output categorization. No wasted words.

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 lack of output schema and annotations, the description provides reasonable context (split into categories) but lacks details on output format or what 'open transport requests' entails. Adequate for a simple 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 100% and the parameter 'user' has a description. The tool description adds that it lists transports 'owned by a user', which aligns with the schema but does not add significant new meaning. Baseline 3 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 clearly states it lists open transport requests owned by a user, with a specific split into workbench/customizing targets and modifiable/released status. This distinguishes it from siblings like adt_manage_transport which likely manages transports.

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 implies when to use (to list transports for a user) but does not explicitly state when not to use or provide alternatives among sibling tools. No comparative guidance.

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?

Discloses read-only mode blocking, but no annotations exist, so description carries burden. Does not explain side effects (e.g., release implications), but the actions are straightforward.

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?

Single sentence with no wasted words. Efficiently covers purpose and a key constraint.

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 and no description of return values. Lacks information on what each action returns (e.g., list returns transport numbers, create returns new request 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 coverage is 100%, so baseline 3 applies. Description adds no extra meaning beyond schema descriptions for each parameter.

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

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

The description clearly states the verb 'Transport request operations' and lists three specific actions (create, release, list), distinguishing it from sibling tools like adt_list_transports which only lists.

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?

No explicit guidance on when to use this tool versus alternatives. Only mentions 'Blocked in read-only mode' as a constraint, but no comparison with sibling tools or prerequisite 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?

No annotations exist, so the description must disclose behavior. It accurately describes the tool as a connectivity test that reports session/role info, implying no destructive side effects. However, it could mention potential errors or timeout behavior, but for a simple ping, this is adequate.

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 concise, front-loaded sentences with no unnecessary words. Every sentence adds value: the first defines the action, the second provides usage 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?

Given no parameters and no output schema, the description is sufficiently complete. It explains the tool's purpose and when to use it. Minor gap: it doesn't specify the format of the session/role info, but that's acceptable for a connectivity test.

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 input schema has zero parameters, so schema coverage is 100%. The description doesn't need to add parameter details. The baseline for zero parameters is 4, and the description meets that.

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 clearly states the tool's purpose: 'Test connectivity' and 'report session/role info'. This is a specific verb+resource combination that distinguishes it from sibling tools like adt_search_objects or adt_read_source, which are about SAP object operations.

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 guidance is provided: 'Call this first to verify the MCP server can reach SAP via ADT.' This tells the agent when to use it (as an initial check) and implies it's a prerequisite for other ADT operations.

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?

No annotations are provided, so the description carries full burden. It mentions read operation and return of source and parameters, but does not disclose error handling, prerequisites, permissions, or side effects. Basic transparency but lacks depth.

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 sentences long, front-loaded with the core purpose, and contains no unnecessary words. Every sentence 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?

Given the tool's relative simplicity (2 params, no output schema), the description covers the key outputs (source, parameters) and notes the write tool for editing. However, it does not detail the structure of the parameters array or error handling, which may be needed for agent reasoning.

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 100% (baseline 3). The description adds meaning for functionGroup by explaining it can be omitted for auto-resolution, which goes beyond the schema description. For functionModule, no extra semantic value is added.

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 clearly states it reads a function module, including full source and parsed parameter interface. It specifies SE37 context and distinguishes from generic read tools like adt_read_source.

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 provides guidance on the optional functionGroup parameter to skip lookup, but does not explicitly state when to use this tool versus alternatives like adt_read_source or adt_create_function_module. Usage context is implied but not formally framed.

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?

No annotations provided, so description bears full burden. It discloses truncation with a warning for large sources, the effect of attachContext (prepends compressed prologue of referenced DDIC objects), and that URIs can be two forms. No contradictions. Minor gaps: doesn't explicitly state whether it modifies anything or if authentication is required.

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?

Well-structured: starts with core purpose, then details. Each sentence adds value. Could trim 'token optimisation' redundancy, but otherwise efficient. Slightly verbose in the attachContext explanation.

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, but description implies return value (source code with optional prologue and truncation warning). Covers essential usage aspects. Could mention error handling or format of warning, but sufficient for a read-only tool with good parameter documentation.

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 100%, baseline 3. Description adds meaning: objectUri can be object URI or source/main URI; startLine and endLine are 1-based; attachContext saves agent from one lookup per referenced type (token optimisation). These go beyond schema definitions.

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?

Description clearly states it reads ABAP source of an object, accepts specific URI forms (object URI or /source/main URI), and lists features like line-range slicing and line-number prefixes. It distinguishes from siblings like adt_search_objects (which returns URIs) and adt_write_source (which writes).

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 explicit guidance: URI must come from adt_search_objects; recommends using line-range for large sources to avoid truncation; suggests setting attachContext=true for token optimization. Lacks explicit when-not-to-use but implies alternatives for different tasks (e.g., adt_read_function_module for function modules).

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?

No annotations are provided, so the description carries full behavioral burden. It states 'Read' (non-destructive) and language override, but does not detail side effects, behavior on missing language, or whether it reads active or all texts.

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 with no fluff: first sentence states what it reads, second sentence adds features and use cases. Every word 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?

Given no output schema, the description hints at return content (text symbols, etc.) but not structure. It covers input well but lacks output format details. Still fairly complete for a simple 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 100%, so parameters already have descriptions. The description adds value by explaining the language parameter as enabling 'language override to read translations', which supplements the 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 explicitly states it reads 'text elements (text pool)' and lists the types: text symbols, selection texts, heading texts. This clearly distinguishes it from siblings like adt_read_source (source code) or adt_write_textelements (writing).

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 mentions usefulness for i18n audits and before editing texts, providing clear context. However, it does not explicitly state when to avoid this tool or name alternatives beyond implication.

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 no annotations provided, the description carries the full burden. It discloses wildcard support and return fields, but does not mention pagination behavior, error handling, or authorization requirements. This is adequate for a search tool but could be more comprehensive.

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 sentences long, front-loading the action and supported wildcards, then specifying return values and usage guidance. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 3 parameters, no output schema, and no annotations, the description covers the primary function, return information, and ties to sibling tools. It lacks details on pagination or result ordering, but the maxResults parameter addresses the limit. Overall, it is sufficient for effective use.

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 100% with clear descriptions for all three parameters (query with example, maxResults with range, objectType as optional filter). The description adds only the context of wildcard support and URI usage, which is already implied by the schema examples. Thus the description adds minimal extra meaning beyond the 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 clearly states the tool searches ABAP repository objects by name pattern with wildcard support, and specifies the returned fields (name, type, package, URI). This distinguishes it from sibling tools like adt_browse_package or adt_read_source by focusing on search rather than browsing or reading.

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 explains when to use the tool (searching by name pattern) and provides guidance on next steps by mentioning to use the URI with adt_read_source or adt_get_object_structure. It does not explicitly exclude other use cases or mention alternatives, but the context is sufficient for an AI agent to decide.

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 no annotations, the description carries full burden and discloses key behaviors: it does not lock or write (non-destructive), and returns errors/warnings with line numbers. It lacks details on authorization requirements or rate limits but covers the most important aspects for safe invocation.

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 concise sentences, each adding essential information: the core action, the non-destructive nature, the return format, and usage guidance. No fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (two parameters, clear output), the description is fairly complete, covering purpose, behavior, and usage. It does not address edge cases like empty results or invalid URIs, but these are minor for a syntax check 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 100% with clear parameter descriptions. The description adds a minor clarification on objectUri format ('base, not /source/main'), but does not significantly enhance understanding beyond the schema. Baseline 3 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 clearly states the tool runs an ABAP syntax check, specifies the resource as 'provided source', and distinguishes itself by noting it does so 'without locking or writing'. It also explicitly contrasts with adt_write_source, providing clear differentiation among siblings.

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 explicitly advises to use the tool before adt_write_source for pre-validation, which is a clear usage guideline. It does not cover when not to use, but the context of many siblings makes this selective suggestion helpful.

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?

No annotations, so description carries full burden. Discloses the lock-write-unlock-activate process, auto-normalization, and read-only blocking. Does not detail transport handling or error states.

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?

Concise paragraph covering purpose, process, constraints, and sibling reference. No redundant sentences. Efficiently communicates key points.

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?

Covers core behavior but lacks mention of return values or output (no output schema). Adequate for an edit tool, but could be more complete for an AI agent expecting result confirmation.

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 100%, and description adds practical context: source format normalization, transport auto-creation, function group auto-resolve. Enhances understanding beyond 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?

Clearly states the purpose: edit an existing function module's source. Distinguishes from create tool (adt_create_function_module). Describes the process and constraints.

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 advises using adt_create_function_module for first-time create. Mentions read-only blocking. Lacks comparison to sibling adt_write_source but provides clear context for when to use this 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?

With no annotations, the description fully discloses the orchestration steps: optional conflict check, optional syntax check, lock, write with transport, mandatory unlock, and optional activate. It explicitly states that locks are never left dangling. This is comprehensive behavioral 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 description is very concise: four sentences that front-load the core purpose, then enumerate the workflow, emphasize safety, and list restrictions. Every sentence adds value without redundancy.

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 7 parameters and no output schema, the description covers the essential flow, safety guarantees, and constraints. It does not describe return values (e.g., success message or errors), but for a write tool with no output schema, this is acceptable. Slight omission of parameter formats or error handling prevents 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 coverage is 100%, so baseline is 3. The description adds value by explaining that 'expectedCurrentSource' serves as a concurrency guard and that 'description' is used only when auto-creating a transport. This clarifies parameter usage beyond the 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 clearly states this tool is for editing an ABAP object with a safe orchestration workflow. It distinguishes itself from siblings by outlining the multi-step process (conflict check, syntax check, lock, write, unlock, activate) and emphasizes 'AI-safe' behavior, which is unique among the listed sibling 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?

The description explicitly notes that the tool is blocked in read-only mode and requires object names to match a Z*/Y* whitelist, providing clear conditions for use. However, it does not explicitly compare to alternative tools like 'adt_edit_source' or 'adt_create_object', leaving some ambiguity about when to choose this over others.

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?

No annotations, so description carries full burden. Discloses replacement behavior, orchestration steps (lock, unlock always, activate), blocking in read-only mode, and prefix whitelist. Rich behavioral detail.

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?

Description is packed with information but efficiently structured. Could be slightly more concise, but every sentence serves a purpose and it 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?

Covers behavioral aspects, constraints, and process well. Lacks mention of error handling or return values, but given no output schema, completeness is good.

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 100% with detailed parameter descriptions. The description does not add meaning beyond the schema, so baseline 3 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?

Describes writing/replacing the text pool of an ABAP program with specific verb and resource. Clearly distinguishes from sibling tools like adt_read_textelements (read) and adt_write_source (source code).

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 context on the orchestration process and constraints (read-only mode, prefix whitelist) but does not explicitly state when to use this tool versus alternatives or when not to use it.

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