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

With annotations only indicating non-read-only and non-destructive, the description carries the full burden of behavioral disclosure and does so comprehensively. It explains that the tool returns a one-time link, explicitly states the connection string is never sent through chat, and outlines the mssql-specific requirement that URLs must not include embedded credentials. This goes well beyond the annotations and provides essential operational context.

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 moderately long but every sentence carries important information. It begins with the core action, then explains the non-obvious workflow (link, form, not via chat), and culminates in a high-risk mssql caveat. While slightly verbose, it is well-structured and front-loads the primary purpose, with no redundant phrases.

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 complexity (three dialects, a non-standard workflow, and a high-risk mssql edge case), the description covers all necessary aspects: what it returns, how to use it, what to do with the response fields, and a critical pitfall. Since an output schema exists, the description does not need to enumerate return values, but it still highlights key response elements, making it fully adequate for an agent to invoke correctly.

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 input schema already documents both `name` and `dialect` with descriptions, achieving 100% schema coverage. The description adds value by tying the dialect to specific behavioral implications (e.g., mssql's Azure SQL handling) and indirectly explaining how the name parameter is used (as a short connection identifier). This exceeds the baseline for fully covered schemas.

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 clearly states the tool's purpose: to obtain a secure one-time link for registering a new database connection, and explicitly lists supported dialects (postgres, mysql, mssql). It also distinguishes itself from typical connection tools by emphasizing that it does NOT take a connection string as input, clarifying its unique role among siblings like test_connection or list_connections.

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 concrete usage guidance: open the returned link, paste the connection string into a secure web form, and surface `connection_string_format` and `auth_note` to the user. It also warns against constructing a particular mssql URL format. However, it does not explicitly contrast with alternative tools or state conditions for when to prefer this tool over others, so the intended use case is clear but not fully differentiated.

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