snowflake_discover_schema_lineage

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

With no annotations, the description must carry the behavioral disclosure burden. It only states what it returns but does not mention whether it is read-only, potential performance implications of a 'composite recipe', schema existence requirements, or how it handles missing database/schema parameters. The 'composite recipe' label hints at multiple steps but offers no further detail.

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 concise sentence, achieving clarity without verbosity. It front-loads the action ('Discover') and the composite nature is noted upfront. However, its brevity leaves out important usage and parameter details, so it is not perfect.

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 tool's composite nature and the existence of an output schema, the description provides a minimal understanding of what it returns. However, it lacks context on parameters, error conditions, and how the composite recipe operates. The name implies lineage but the description does not address that, leaving ambiguity about the output's scope. It is adequate but has clear gaps.

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% and the description does not explain the parameters at all. It mentions 'a schema' but does not map database and schema_name to the inputs, nor how the parameters interact. Without compensation for the missing schema descriptions, agents cannot infer parameter meaning from the tool description.

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 ('Discover') and resource ('all tables and views in a schema along with their column definitions'). It clearly differentiates from siblings like list_tables or describe_table by indicating a composite result that includes both table/view lists and column details. The name suggests lineage, but the description's explicit scope still gives a clear purpose.

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 use this tool versus alternatives. It does not mention that it replaces multiple calls (e.g., list_tables + describe_table) or when to prefer it over simpler tools. No exclusions or conditions are provided.

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