bw_get_open_hub

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

The description clearly indicates that this is a read operation ('Read') and details the extensive output content. It discloses that only the definition is retrieved and includes specific behavior for FILE destination types. However, without any annotations, it does not explicitly state that no modifications are made or mention required permissions. It effectively conveys the scope and nature of the 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?

The description is a single, well-structured sentence that begins with the core purpose ('Read an Open Hub Destination...'). It efficiently lists the key aspects of the definition without unnecessary words. While it is somewhat dense, it remains clear and front-loads the essential information.

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

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

Given the absence of an output schema, the description thoroughly enumerates the return values, including destination type, source, DB table, InfoArea, package, status, output field list (with type/length, InfoObject binding, conversion routine, compounding, key flag), and file properties conditionally for FILE type. This provides complete contextual information for an agent to understand the output without needing additional 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 description coverage is 100%, with one parameter 'open_hub_name' described in the schema as 'Technical name of the Open Hub Destination (e.g. "OBJECT_NAME").' The tool description does not add further semantics about the parameter beyond what the schema already provides. The baseline of 3 is appropriate since the schema covers the parameter adequately.

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 begins with 'Read an Open Hub Destination (TLOGO DEST) definition', clearly stating the action (read) and the specific resource (Open Hub Destination). It lists detailed components such as destination type, source, DB table, InfoArea, package, status, output field list, InfoObject binding, conversion routine, compounding, key flag, and file properties for FILE type. This specificity distinguishes it from sibling get_* tools that target other BW objects (e.g., bw_get_adso, bw_get_infoobject).

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 does not explicitly state when to use this tool versus alternatives, nor does it provide any exclusion criteria or context for selection. It implicitly suggests use when reading an Open Hub Destination definition, but lacks explicit guidance such as 'Use this when you need the full OHD definition with field details'. No mention of when not to use or alternative tools is made.

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