Snowflake Discover Schema Lineage

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. Beyond that the description says only 'Composite recipe,' without disclosing the cost/round-trip implications of a fan-out call, any row or result limits, or pagination behavior – meaningful context for a tool that internally enumerates many objects.

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?

One front-loaded sentence with no padding, and the key scope ('all tables and views in a schema along with their column definitions') comes first. The 'Composite recipe:' prefix is jargon but does signal aggregation, so it earns marginal keep.

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 need not be described. However, with two required-nothing parameters at 0% schema coverage, no usage routing against a dozen closely related siblings, and a name/description mismatch on 'lineage,' the definition leaves too much for the agent to resolve on its own.

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% for both parameters, so the description must compensate and does not. It says 'in a schema' (vaguely implying schema_name) but never mentions the database parameter or what happens when either is omitted (both default to null, suggesting current-context fallback, which is left unexplained).

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 concrete compound action – enumerating tables/views in a schema plus their column definitions – but the tool name promises 'schema lineage,' which this description never delivers and which is actually served by siblings snowflake_get_object_lineage and snowflake_get_column_lineage. It also does not distinguish itself from snowflake_list_tables, snowflake_list_views, or snowflake_describe_schema, which appear to cover the same ground individually.

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 when-to-use guidance: no indication that this composite should replace several individual list/describe calls, no prerequisites (e.g., which database/schema must be active), and no exclusions. 'Composite recipe' hints at aggregation but leaves the agent to infer when to pick it over the sibling list_* and describe_* tools.

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