Connect a paste-a-key account

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

Annotations declare mutation semantics (destructiveHint=true, idempotentHint=true, openWorldHint=true) but say nothing about validation, credential safety, or special-case flows. The description adds all three: the key is validated live with the provider before anything is saved, the reply is read back from the saved connection, Hermoso never echoes a submitted key, pasting in chat leaves the key in conversation history, and Apple Ads without key material first generates a key pair and returns a public key plus a setupToken. That is substantial behavior beyond the annotation set, with no contradiction.

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?

It is long, but the length is driven by 13 providers with non-overlapping field sets and by genuine special cases (Apple Ads key generation, OAuth fallback), so nearly every clause earns its place. The purpose is front-loaded before the provider list and the credential-handling policy. The dense single-paragraph layout and mid-sentence ALL-CAPS instruction cost it a point on structure.

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?

With no output schema, the description still tells the agent what comes back ('the reply is read back from the saved connection') and what the Apple Ads special case returns (public key + setupToken). Combined with the provider/field inventory, live-validation behavior, and the OAuth fallback, nothing an agent needs to call this correctly is missing.

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 schema only says fields are 'that provider's own field names and values' and defers explicitly to the description, so the description is the sole source of per-provider parameter meaning. It enumerates each provider's exact field names with '*' marking required ones (e.g. stripe {apiKey*}, mixpanel {username*, secret*, projectId*, region, workspaceId}), which is far more than the 100%-covered top-level schema provides.

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+resource with scope: 'Connect an account that links with a KEY rather than a sign-in screen, from here, with no browser', then enumerates the exact 13 supported providers. It explicitly carves itself away from the OAuth path ('An account that connects through the provider's own sign-in screen (OAuth) cannot be connected here'), so an agent can distinguish it from sibling connector tools like list_connectors, set_connector_accounts, and leave_connector 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?

Gives explicit when-to-use and when-not-to-use guidance: use this for key-based providers, and if the provider is OAuth-only, 'this answers with the link to hand the user instead'. It even prescribes agent behavior for the credential-handling decision ('OFFER BOTH WAYS AND LET THE USER CHOOSE') and contrasts the two paste locations, which is the real routing decision the agent must make.

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