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

Goes well beyond the annotations: it discloses that the saved connection is replaced (so future articles publish to the new CMS), that credentials are never returned, and that the operation is a two-step confirm flow where the first call returns a summary plus confirmToken. The destructiveHint annotation only flags risk generically; the description explains the exact effect and the confirmation protocol.

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?

A single dense paragraph, but it is front-loaded with purpose and every sentence carries operational weight (platform credential matrix, replace semantics, credential handling, confirm flow, follow-up call). Only the 'exactly like the Settings page' clause is mild filler.

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 19-parameter mutation tool with no output schema, the description covers the essentials: platform-specific inputs, destructive replacement behavior, the two-step confirmation, and the next tool to call. It does not describe what the first-call summary contains or how to recover from a failed credential test, which are the only remaining gaps.

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?

With 19 params at 58% schema coverage, the description does real work by mapping credential sets to platforms (WordPress username+app password, Webflow token+collection id, Shopify store name+token or client id/secret+optional blog id, Wix site id+API key, Framer project URL+API key, Duda site name+optional user/password). This lets an agent select the right subset, though the mapping is prose rather than named parameters, so the agent must still infer exact field names.

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 (tests/saves CMS credentials) and enumerates the six supported platforms, which cleanly separates it from the other connect_* siblings (connect_bing, connect_dutchie). An agent immediately knows this is the CMS-connection tool rather than a search or status tool.

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 clear usage context: call it to connect or re-test a CMS, and explicitly name get_platform_options as the required follow-up when a blog/collection/member must be chosen. It does not, however, state when NOT to use it (e.g. vs. the platform-specific connect_bing/connect_dutchie tools), leaving that to inference.

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