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

Annotations already declare idempotentHint=true, destructiveHint=true, and openWorldHint=false, so the closing sentence about repeat calls largely repeats structured data. The genuinely additive part is 'Changes only Leadpoet's record, not any CRM', which tells the agent there is no external side effect, but the destructive aspect (what happens to the old company attribution) and any permission requirements go unexplained.

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?

Three short sentences with the core action front-loaded and no filler. The final idempotency sentence is somewhat redundant with the annotations, which keeps it from being maximally efficient.

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 nested-body mutation with zero schema descriptions and no output schema, the description covers the conceptual model (internal-only, idempotent) but leaves the caller without guidance on parameter identity or what a confirmed attribution does to prior state. Adequate but with clear gaps.

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% and the description never mentions dealId or company_card_id, their UUID formats, or that the company identifier lives in a nested body object. The words 'deal' and 'company' loosely map to the two parameters but add no meaning beyond the property names.

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?

States a concrete verb and resource: it moves a deal to a different pipeline company and confirms the attribution. That is clearly distinct from a mere rename, though it never names moveDeal or updateDeal as the siblings it differs from, so an agent must infer the boundary.

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?

Usage is only implied: 'marks that attribution confirmed' hints this is the confirm-assignment variant versus a plain move or field edit, but there is no explicit when-to-use, when-not, or named alternative among moveDeal, moveDeals, and updateDeal.

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