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

With annotations already declaring readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false, the description adds substantial context beyond those hints: the key is checked live before saving, the reply is read back from the saved connection, keys are never repeated back, chat-pasted keys remain in conversation history, and Apple Ads may generate a signing key pair with a setupToken. These details materially inform agent behavior and do not contradict the annotations.

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 definition is long but justified by 12 providers, per-provider field requirements, security guidance, OAuth fallback behavior, and the Apple Ads special case. It is front-loaded with purpose and then structured into provider list, security note, OAuth exclusion, special case, and field mapping, with no filler sentences.

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?

The description covers provider IDs, required fields, live validation, security handling, and special cases thoroughly. Because there is no output schema, it should ideally specify what a successful connection returns—it only says the reply is read back from the saved connection, which is vague about the actual return shape or error format.

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?

Although schema coverage is 100%, the schema's `fields` property only points to the description for provider-specific field names. The description supplies the actual per-provider field lists with required markers (e.g., `stripe {apiKey*}`, `bluesky {identifier*, appPassword*, pds}`), which is essential invocation detail not available in the schema alone.

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 opens with a specific verb and resource: 'Connect an account that links with a KEY rather than a sign-in screen.' It immediately distinguishes this tool from OAuth-based connections and names the supported providers, so an agent can tell what this tool does without opening the 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?

It states the core usage condition—key-based providers only—and explicitly excludes OAuth providers: 'An account that connects through the provider's own sign-in screen (OAuth) cannot be connected here.' It also directs the agent to offer both key-entry paths (chat vs. app link) and explains the security tradeoff, giving clear when-to-use and how-to-present guidance.

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