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

Annotations already declare the safety profile (readOnly=false, destructive=false), and the description adds beyond that: it explains why the tool is non-OAuth, that secrets are validated and never echoed back, and that existing config is replaced. One mild tension exists between 'store or replace' (upsert-flavored) and idempotentHint=false, but it is not a clear safety-profile 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?

Three compact sentences, with the core action front-loaded and the caller-routing caveat placed after it. No filler, though the second sentence is information-dense enough that it borders on packing two concerns together.

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 annotations and an output schema present, the description only needs to add what structured data cannot: it covers the secret-handling behavior, the non-OAuth rationale, and the replace semantics. What remains unstated (e.g., whether replacement invalidates existing connections) is a minor gap for a 3-parameter tool.

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 description coverage is 67% and the credentials/workspaceId fields already carry their own explanations, including the provider enum. The description only restates 'provider-nested credentials' without adding format, validation, or per-provider nuance, so the schema is doing the heavy lifting.

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 states a specific verb+resource ('Store or replace one provider integration') and immediately characterizes the input shape ('provider-nested credentials'), so an agent knows exactly what the tool does. It implicitly separates this from the OAuth-based connect flow, but does not clearly distinguish it from the sibling campaignstack_edit_workspace_integrations, leaving one ambiguity among the integration-family tools.

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 gives clear context for use (non-OAuth providers whose credentials are supplied directly) and a concrete when-not-to-use path ('connected apps should direct the user to the workspace's Settings tab'). It stops short of explicitly naming an alternative tool, so it is strong context rather than full routing guidance.

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