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

Annotations cover the safety profile (not read-only, non-destructive, closed world), and the description adds substantial context beyond them: nothing already in the review queue is affected, nothing is written to the CRM, the change is forward-only, and HubSpot connections are rejected. That is exactly the kind of side-effect and eligibility disclosure annotations cannot express.

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?

Four dense sentences, each carrying a distinct payload (purpose, enum semantics, related read tool, effect constraints and refusal rule) with no filler. Slightly long, and the enum explanation is embedded mid-paragraph rather than front-loaded, but nothing is wasted.

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 two-parameter configuration setter with no output schema, the description supplies everything an agent needs: what is being configured, the meaning of both enum values, how to read the current setting, that the effect is prospective only, and the HubSpot exclusion. No material gap remains.

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 100%, so the baseline would be 3, but the description goes further by explaining what each enum value actually proposes: 'account_contact' creates a linked Account and Contact reviewed together, while 'lead' creates a Lead instead. That adds real semantic meaning the terse schema enum descriptions ('account_contact' or 'lead') do not.

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 a specific verb plus resource: setting what a job change proposes when a new employer is not an existing CRM account. It scopes the effect precisely ('what later departures propose') and routes the reader to the sibling that reads the current value, so it is distinguishable from the many other set_*/create_* 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 clearly frames the operative context (new employer absent from the Salesforce CRM) and names list_crm_connections as the way to inspect the existing setting, plus an explicit when-not: HubSpot connections are refused. It stops short of stating the user-facing intent verbatim ('use this when you want to change future proposals'), so it is clear context rather than a full when/when-not/alternative matrix.

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