ads_leaves

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 genuine behavioral context beyond that – leaves carry byte offsets, and with values=true the values come from a single whole-symbol read – but says nothing about limits, truncation from max_leaves, or ordering.

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 compact sentences, front-loaded with the core action and followed by a concrete example. The example and the with_values note both earn their place; only the trailing ellipsis-style formatting is slightly loose.

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 shape need not be described. Still, for a read-only enumeration tool with 0% schema coverage, the missing explanation of max_leaves and the absence of any when-to-use routing against sibling read tools leave the definition short of fully self-sufficient.

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 must carry parameter meaning. It partly does: it shows the accepted 'name' syntax and explains the effect of with_values=true. However, max_leaves (default 5000) is never mentioned, so one of three parameters is entirely undocumented.

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 uses a specific verb ('Enumerate') and resource ('every scalar leaf under a symbol'), and gives concrete examples of the symbol syntax ('MAIN', 'MAIN.arrSteps' → arrSteps[1].nId) that pin down exactly what is returned. It is clear what the tool does, though it never explicitly distinguishes itself from leaf-reading siblings like ads_read or ads_symbol_info.

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?

Usage is implied rather than stated: the syntax examples and the byte-offset detail hint at when leaf enumeration is appropriate, but there is no explicit 'use this when you need X instead of ads_read/ads_symbol_info'. An agent must infer the alternative from the description alone.

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