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

The annotation destructiveHint=true already signals mutation, but the description adds the key behavioral detail that only provided fields are modified, preventing assumptions of full replacement. Mentioning 'Twenty REST: PATCH' also provides HTTP method context. This goes beyond the annotation without contradicting it.

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?

The description is composed of two short, information-dense sentences. The action is front-loaded, and every phrase ('Update fields', 'existing opportunity', 'Only provided fields change', 'Twenty REST: PATCH') adds value without redundancy.

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?

Given full schema coverage and a clear partial-update statement, the description covers the essential behavior for a mutation tool. It does not describe return values or error handling, but no output schema exists and the schema handles parameter details. The core ambiguity (partial vs full update) is resolved, making it adequately complete.

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 100%, so all parameters are individually documented. The description adds no extra parameter-specific meaning beyond the global 'Only provided fields change' behavior, which is already a general update trait. Baseline 3 is appropriate given the schema's completeness.

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 clearly states the action with a specific verb and resource: 'Update fields on an existing opportunity.' It distinguishes from create/get/list siblings by the word 'update' and the reference to an existing record. The additional clause 'Only provided fields change' further clarifies the partial-update semantics.

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?

The description makes clear this tool is for updating an existing opportunity, not creating one, and the clause 'Only provided fields change' signals partial updates. It does not explicitly name alternatives like 'use create_opportunity to create a new record', but the context and wording imply the appropriate usage.

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