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

With no annotations, the description carries the full burden and does so well: it discloses that op=set rejects ids the credential cannot reach, that ambiguity causes refusal rather than silent misrouting, that `_account` needs no reconnection or key setup, and that set/rename at org/group scope require that level's admin. Gaps remain — nothing about what op=list returns beyond field names, whether rename is reversible, or any rate limiting — and the `_org` parameter is never discussed.

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?

Every sentence carries real information, but the delivery is a dense wall of parentheticals, bolded asides, and an emoji warning, making it hard to scan for the one fact an agent needs at a given moment. The most critical rule (use `_account` for a single call) is buried mid-paragraph rather than front-loaded after the purpose statement. Structure could be tightened without losing content.

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 six-parameter, three-operation tool with no annotations, no output schema, and zero schema description coverage, the description supplies most of what an agent needs: operation semantics, the ephemeral-vs-persistent distinction, refusal behavior, and permission levels. The remaining holes — the undocumented `_org` parameter, unspecified `connector` value domain, and no hint at the shape of list output — are the only things keeping this from complete.

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 0%, so the description must compensate, and it does for most parameters: op values are each explained, identity_id is tied to op=list output, new_name is scoped to op=rename, and scope=org/group is given concrete meaning (one key per company of a group) plus an admin prerequisite. However, `_org` is completely unaddressed and the `connector` parameter's expected values (connector slugs? names?) are never characterized.

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 names the resource precisely — 'connected identities/accounts your credential can act as for a connector' — and enumerates the three operations (list, set, rename) with their argument shapes. It is clearly distinguishable from siblings like google_accounts or linkedin_unipile_account because it is about the identity registry itself, not the connector's data. It loses a point only because the tool performs three distinct jobs and no single crisp verb anchors the opening line.

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?

Explicit routing is provided: op=list to discover, op=set for a PERSISTENT default, and `_account=<id>` for an EPHEMERAL single-call pin, with a concrete example (slack_post_message(_account='client-x', …)). The description also states the edge cases that select behavior — a single posted account resolves alone, while several accounts with no default cause a call without `_account` to be REFUSED. It even warns that the bare `account` name belongs to other tools, heading off a predictable misuse.

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