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

Adds real behavioral context beyond the annotations: earlier handles stop working, no company data or other connections are changed, and the returned _corply_context is what carries forward. This is consistent with destructiveHint=false. The idempotency and confirmation sentences are generic policy boilerplate whose enumerated cases (read, reversible save, plan refresh) do not map onto a connection-switch, so they add noise rather than clarity.

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 opening sentence is well front-loaded, but the bulk of the text is reusable boilerplate (Canonicality, Idempotency, Confirmation boundary) that is verbose, partly inapplicable, and repetitive of policy phrasing likely shared across many tools. It bloats the definition without earning each sentence.

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 state-mutating session tool with no output schema, the description does cover effect and context propagation, which is the critical part. But the broken prerequisite reference and vague, non-specific retry/confirmation language leave gaps an agent would have to resolve elsewhere.

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 coverage is only 50%, but the description compensates: it states companyId comes from whoami.companies and explains that _corply_context originates from this tool's own result, which the schema itself never says. That is meaningful semantics beyond the structured fields.

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?

Names a specific verb and resource (switch this connection to another company) and ties the target to whoami.companies, so an agent can tell it apart from list/read siblings like whoami or get_org. It stops short of fully distinguishing it from adoption-type tools such as adopt_existing_company, but the core action is unmistakable.

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 an implied trigger ("when the founder wants to work on it") and the downstream effect (later calls act in that company), which is enough to place the tool in a workflow. However, no alternatives are named and the prerequisite clause ("plus every prerequisite stated above") points at text that does not exist, weakening the guidance.

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