infosys_declaration

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: ambiguous names are 'refused as ambiguous with the candidates', library= disambiguates, same_page_in and also_in are returned for cross-book cases, and member resolution follows the Help Viewer contents hierarchy. This is rich transparency for a read-only retrieval 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?

The description is front-loaded with the return-field list, but it is long and dense, with run-on sentences and parenthetical asides. The final sentence about the twincat-docs skill's docs_declaration resolving names by the same rule is likely extraneous for an agent invoking this tool, and the member-resolution explanation could be more structured.

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

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

Given the output schema exists, the description need not explain return values in full, but it still lists them helpfully. Annotations cover read-only safety. The description covers ambiguity handling, member syntax, and the purpose of the library parameter. It lacks guidance on finding a symbol name when unknown (e.g., using infosys_search_symbols) or on behavior when the symbol is not found, but it is otherwise complete for a two-parameter read-only lookup.

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

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

Schema coverage is 0%, so the description must compensate for undocumented parameters. It explains the library parameter's role in resolving ambiguity and shows that symbol can take a member form like '<FB>.<name>' (FB_WG_ComboFilter.Call). However, it does not describe the plain symbol format, case sensitivity, or other parameter details, so compensation is partial.

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

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

The description states a specific verb and resource: 'Declaration of a library symbol as data' and enumerates the returned fields (kind, inputs/outputs/in_out, struct members, enum values, return type, EXTENDS/IMPLEMENTS, methods, properties, ST declaration, page URL). It is clear what the tool does, but it does not explicitly contrast with sibling tools like infosys_get_page or infosys_search_symbols, so sibling differentiation is implied rather than stated.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides a clear trigger: 'The thing to call before writing code against an FB you have not used before.' It also explains how to handle ambiguous names via the library parameter. However, it does not name alternatives such as infosys_search_symbols for finding a symbol first, nor does it specify when not 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.