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

Annotations only cover the readOnly/destructive profile, and the description carries the rest itself: credentials pass through the model and persist in plain text in the session transcript, the connection is tested before saving so unreachable databases are not persisted, refusal messages name a cause, and permission is limited to owners/admins/editors. The only shortfall is that the SSH host-key refusal flow is described at length while nothing is said about other failure modes such as duplicate names or credential rotation.

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?

Front-loaded with purpose, then exclusions, then the failure/test-before-save behaviour, then SSH, then the return value and permissions — a sensible order. It is a dense single block of roughly 250 words with the SSH edge case consuming nearly a third of it; readable but the wall-of-text format costs it a point.

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?

No output schema exists, so the description supplies the return contract itself ('the new connection's _id, the connectionId other tools take'). Combined with the mutation side effects, prerequisite tools, permission scope and error semantics, an agent has everything needed to invoke this correctly on the first try.

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 already 100%, so a 3 would be the floor, but the description goes well beyond it: it documents the nested creds fields for bastion access (sshHost, sshPort with its default of 22, sshUsername, sshKeyId, sshHostKey), redefines what `host` means when a bastion is used (and that Oracle takes an IP address there), and explicitly neutralises projectId as not needed. That is real semantic value the schema does not supply.

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?

States a specific verb and resource ('Create a data connection to a database'), enumerates the supported datasources, and immediately distinguishes itself from the two nearest siblings: OAuth sources (BigQuery, Google Sheets) that need a browser sign-in, and fastero_create_file_connection for uploaded CSV/Excel files. An agent can route correctly without opening any schema.

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?

Explicit when-to-use with the caveat that the web app is the preferred route because credentials land in the transcript, explicit when-not (OAuth sources, file uploads), and an explicit prerequisite chain for SSH (sshKeyId from fastero_create_ssh_key, host-key fingerprint verification). Exclusions and alternatives are both named.

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