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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=false, so the description's closing line about repeat calls largely restates what is already structured. What it genuinely adds is the optimistic-concurrency contract: passing expected_stage_id makes the call fail if the card moved since read. It does not explain the destructiveHint=true annotation, i.e. what is lost or overwritten when fields are changed, which is the biggest remaining gap.

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 tight sentences with the affected fields front-loaded, then the two behavioral guarantees. No filler or marketing language. The field list is a dense enumeration but it is the highest-value content, so it earns its space.

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, nested-object mutation with no output schema and zero schema description coverage, the description leaves too much unstated: partial-update semantics, what the win/loss and sales_motion fields do, and what the response returns. An agent could still call it, but only by guessing at over half the body properties.

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 nested body carries roughly eighteen properties, but the description names only about eight of them. It does add real meaning the schema cannot convey for expected_stage_id (stale-read guard). Undocumented in both schema and description: win_reason, loss_reason and their subreasons/notes, sales_motion, follow_up_date, nurture_review_date, stage_effective_date, and whether omitted fields are left untouched.

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 specific verb (changes) and resource (a company card), and enumerates the mutable aspects: stage, pin, notes, owner, deal value, currency, expected close date, automation pause. This clearly separates it from pure readers like getPipeline or listCompanyDeals, though it never names the closest mutating siblings (updateDeal, moveDeal, pinContact) to sharpen 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 implied rather than stated: you use it when you need to alter a company card. The one genuine guideline is the concurrency rule tied to expected_stage_id, which tells the agent when to pass it and what failure means. There is no guidance on when to prefer updateDeal or moveDeal instead, and no mention of prerequisites such as permissions.

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