snowflake_describe_secret

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the operation is read-only (describes metadata) and explicitly notes it does not expose the secret value, which is a critical behavioral trait. It also mentions the type enumeration (GENERIC_STRING, OAUTH2), giving insight into the output. While it does not discuss privileges or error behavior, the description is notably transparent about its scope.

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, well-structured sentence that front-loads the main purpose and includes important constraints. Every word earns its place; no filler or redundancy. It efficiently conveys the core function and the critical exclusion of the secret value.

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?

For a simple describe operation, the description conveys its main purpose and what it returns. However, the lack of parameter explanation is a gap given 0% schema coverage. The presence of an output schema reduces the need to describe return values, but the optional database and schema parameters remain unaddressed, leaving some ambiguity in how to scope the describe call.

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 compensate, but it does not explain any of the parameters. The required secret_name is only implicitly understood from the resource name, while database and schema_name are entirely unexplained. Without schema descriptions or elaboration in the description, an agent may not know how to locate the secret or what these optional parameters signify.

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 clear verb (describe) and resource (secret), specifies the contents of the metadata (type, owner), and explicitly notes it avoids exposing the secret value. This distinguishes it from list_secrets or any value-returning operation, making its purpose unmistakable even among many sibling describe tools.

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 explicit guidance on when to use this tool versus alternatives, nor any mention of exclusions or sibling tools. The phrase 'without exposing secret value' implies that this is for metadata only, but it does not state when one should instead retrieve the value or use other secret-related tools. The context is only implied, not stated.

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