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

Annotations only declare the mutation/safety profile (readOnly false, destructive false, idempotent false), so the description carries the semantic burden and delivers: stage does not alter outreach or company lifecycle, 'won' means recorded won rather than paid, and null means unknown. It does not mention what a revision conflict returns or any permission requirement, which are the remaining gaps for an upsert tool.

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?

Six short, dense sentences with the core purpose front-loaded and no filler; every clause carries a rule. The telegraphic style ('null value means unknown', 'Won means recorded won, not paid') is efficient but occasionally terse.

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 an 11-required-parameter mutation with no output schema, the description focuses on semantics but leaves substantial parameter and workflow information implicit. Most notably, with optimistic concurrency via expected_revision, an agent is not told what the call returns (e.g. the new revision to use next), which matters for chained saves.

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 only 8% (just workspaceId), and 11 of 12 parameters are required with no schema docs. The description compensates for some: amount_minor null = unknown, currency should be solicited, expected_revision 0 means create, probability_override is gated. It says nothing about title, company_id, the stage enum values, next_step, or the two date fields, so the gap is only partially closed.

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 first sentence names a specific verb pair (create or revise) and resource (a deal for an existing CRM company), and the 'existing CRM company' qualifier distinguishes it from save_company and the lead-oriented siblings. It is clear what the tool does, though it never names a sibling tool to contrast against.

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 concrete when-to-use rules: create with a new UUID and revision=0, otherwise use the current revision; ask for missing value/currency; only set probability_override when the user supplies an estimate. These are real decision rules with conditions attached, but there are no explicit exclusions or named alternatives for edge cases.

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