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

Annotations already declare destructive, idempotent, and openWorld, so the safety profile is covered. The description adds genuinely new behavior: an external HubSpot write that only applies to contacts Leadpoet created, plus the retry contract that the first result is replayed rather than the move repeated. It omits atomicity — whether a rejected movement fails the whole batch — which matters for a destructive 100-item call.

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 tight sentences, front-loaded with the operation and its cap, then exclusions, side effects, and retry semantics — no filler. Density is high but each clause carries distinct information.

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 destructive bulk mutation with nested optimistic-locking parameters and no output schema, the description covers limits, one exclusion, external side effects, and retry, which is substantial. It still leaves the two questions an agent most needs before calling: partial-failure semantics and what a stale expected_revision/expected_stage_id produces.

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 50%, and the undocumented half is the risky half: expected_revision and expected_stage_id are optimistic-locking fields the description never mentions, so the agent gets no hint about conflict behavior or why the expected values must be supplied. The idempotency explanation restates what the idempotencyKey schema description already says, so it adds no meaning beyond the schema.

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?

"Moves up to 100 contacts to one stage" gives a specific verb, resource, cardinality cap, and a single destination, which is precisely the axis that separates it from moveContact. An agent can tell the bulk form from the single-contact sibling without opening either schema.

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 names the alternative explicitly (moveContact) and gives the condition that forces it: qualified stages are rejected here and must be qualified one at a time. It does not state prerequisites such as required permissions or ownership of the contacts, and gives no guidance on choosing bulk vs. single when both are legal.

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