ads_types

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds some behavioral value by enumerating the data returned (offsets, sizes, bounds, enum literals, attributes), but says nothing about scope limits, connection requirements, or behavior when a type/pattern matches nothing.

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?

A single dense sentence, front-loaded with the resource and then the two operating modes. Nothing is padded, though the parenthetical detail list pushes it toward a run-on.

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?

An output schema exists, so return-value explanation is not required, and the read-only annotations cover safety. Still, with three undocumented parameters (limit, pattern, type_name all at 0% schema coverage), the description should say more about parameter meaning and defaulting to be fully actionable.

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 0%, so the description carries the burden. It effectively disambiguates type_name (single type) from pattern (matching list), but leaves 'limit' entirely unexplained and gives no syntax for pattern (glob vs. regex) or expected type-name format, so it only partially compensates.

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 names a specific resource ('Runtime datatype table') and two distinct operations (describe one type vs. list types matching a pattern), plus what a description contains (members with offsets/sizes, array bounds, enum literals, attributes). It is clear enough to distinguish from symbol/read siblings, though it never names an alternative such as ads_symbol_info or ads_list_symbols.

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 two modes ('describe one type' vs 'list types matching a pattern') imply which parameter to use, giving implicit usage guidance. There is no explicit when-to-use/when-not-to-use statement and no routing to a sibling tool, so an agent must infer the selection.

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