Dynamic Tables List Dynamic Tables

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds useful row-level context (quoted_name and when quoted_qualified_name is populated), but says nothing about result volume, pagination, or ordering — the practical concerns for an openWorld list call.

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 the core list operation and the fields returned. The second sentence is a bit dense around quoting, but it is relevant to consuming the output and contains no filler.

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 values needn't be explained, yet the description still spends its second sentence on output naming while leaving all three input parameters — including the undocumented `pattern` filter — unexplained. For a list tool whose main use is scoped discovery, the filtering story is missing.

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 `pattern` parameter is undocumented in both schema and description, so the agent cannot know it is a name-matching filter. The database/schema_name schema descriptions discuss name quoting rather than the filtering semantics, and the description does not clarify them either, leaving gaps at 67% coverage.

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?

States a specific verb and resource ("List dynamic tables") plus the attributes exposed on each row (lag targets, refresh mode, last refresh status). An agent can tell it is a listing tool distinct from dynamic_tables_describe_dynamic_table, though it does not name that sibling explicitly.

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?

There is no guidance on when to choose this over dynamic_tables_describe_dynamic_table or the other dynamic_tables list variants (list_iceberg_tables, list_external_volumes). Nothing says whether results are account-wide or scoped, or that filters are optional.

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