snowflake_describe_stream

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

With no annotations, the description carries the full burden. It discloses what information is returned (metadata, source table, stale status), which gives some behavioral context. However, it does not explicitly state that the operation is read-only (though 'describe' implies it), nor does it mention any side effects or permissions needed. It adds value beyond the schema but could be richer.

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 that front-loads the purpose. It has no fluff and earns its place. However, it is slightly terse; adding a note about the required parameter or typical usage would improve it without sacrificing conciseness.

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?

Since an output schema exists, the return format is covered elsewhere, so the description doesn't need to explain it. Yet the lack of usage guidance or parameter clarification leaves gaps. For a simple describe tool this is adequate, but it doesn't fully address the context in which an agent might pick this over siblings.

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 coverage is 0%, and the description does not explain any of the three parameters (database, schema_name, stream_name). While the parameter names are self-explanatory, the description fails to compensate for the lack of schema documentation, leaving the agent to infer that these are locators for the stream. No additional meaning is provided beyond the schema's bare property definitions.

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 'Describe stream metadata, source table, and stale status' clearly states a specific verb (describe) and resource (stream), and specifies the exact information returned (metadata, source table, stale status). It distinguishes from siblings like snowflake_list_streams (which lists) and snowflake_create_stream/drop_stream (which modify) by focusing on inspection.

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 description provides no explicit guidance on when to use this tool versus alternatives, such as snowflake_list_streams or snowflake_read_stream_changes. It does not mention prerequisites (e.g., needing the stream to exist), nor does it advise against use in certain contexts. The agent is left to infer that 'describe' implies inspection, but no explicit routing is given.

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