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

The annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation is known. The description adds valuable context: it clarifies the sparse vs full update semantics (only sent fields change, Line array replaces all), the requirement to repeat Name for sparse updates, and the impossibility of deletion. It also warns about sensitive fields (SSN, birth dates) that must not be sent. This significantly exceeds the annotation baseline, though it doesn't describe response format or error handling, hence 4.

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 a single, dense paragraph that front-loads the verb and resource, and then packs in critical operational details without redundancy. Every sentence carries weight: the SyncToken requirement, the sparse update behavior, the Name repetition rule, and the deletion workaround. It's concise (around 150 words) but no word is wasted.

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 mutation tool with no output schema and relatively simple parameters (2), the description covers the key pitfalls and behaviors. It explains the semantics of sparse vs full updates, the irreversibility of deletion, and the need to fetch the current SyncToken. It doesn't describe the exact response shape or error scenarios, but given that the schema covers parameter types and the description covers usage pitfalls, it's nearly complete. The only minor gap is lack of explicit mention of response structure.

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 coverage is 100%, so the schema fully documents both parameters (entity and company). The description adds nuance about the entity object's behavior (sparse updates, Line replacement, sensitive field restrictions), which is helpful. However, it doesn't add meaning to the 'company' parameter beyond the schema's description. Since the schema already covers the basics, a baseline of 3 is appropriate, with the extra context justifying keeping it at 3 (not higher because no new parameter-specific details).

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 states the specific action ('Update an existing term') and the resource ('term in QuickBooks Online'), with the key requirement 'requires Id and SyncToken'. It clearly distinguishes this from create_term and delete operations on terms, and the context of sibling tools (update_term vs create_term vs delete_*) makes the purpose unambiguous.

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 provides explicit guidance on when to use this tool: 'fetch the Term first' to get SyncToken, and essential operational details like sparse update behavior, the need to repeat Name, and how to retire a term (since deletion isn't possible). It also warns against sending sensitive fields, which is crucial for correct usage. This is effectively a mini-user manual for proper invocation.

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