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

Annotations already establish read-only, idempotent, closed-world behavior, and the description adds substantial semantics on top: what needs_reconnect means versus a per-connection needsReconnect flag, the caveat that externalAnalytics only lists SQL views and is not proof metrics can be fetched, and what connectFailureMessage, isAlwaysAvailable, and isSettingsManaged represent. It also preempts a likely agent error by denying that the tool connects accounts or alters permissions.

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 purpose and status semantics are front-loaded and earn their space, but the middle section degenerates into a flat run of field notes (connectFailureMessage, isAlwaysAvailable, isSettingsManaged) with no structural separation from the workflow guidance. Every sentence carries content, yet the ordering would be easier to scan if return-field semantics were grouped 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?

There is no output schema, so the description must carry return-value meaning itself, and it does so thoroughly for every field and status value an agent would encounter. Nothing material is missing for calling this two-parameter read tool correctly.

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 100% schema coverage the baseline is 3, and the description earns above that by enumerating supported analytics integration keys (triple-whale, contentsquare, intelligems, meta-marketing-api, google-analytics, google-search-console, shopify, converge), which tells the agent what values integrationKey actually accepts beyond the schema's "figma" or "shopify" examples.

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 first sentence names a specific verb and resource with scope ("Check one integration's connection status in the selected Replo project") and immediately enumerates the three possible outcomes. It also explicitly separates itself from the sibling connect_replo_account by stating "This tool does not connect an account or change permissions."

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 concrete when-to-use conditions: before querying external metrics, when a provider's tools are absent from the catalog, and after the user connects an account ("when they say they're done, call this again"). It also states what to do with connectUrl in the user-facing flow, which is actionable routing guidance rather than a restatement of the name.

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