update_customer

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

With no annotations, the description carries the full burden. It usefully discloses that Id+SyncToken are mandatory (implying optimistic-concurrency semantics), that sparse enables partial updates, and that responses always mask PrimaryTaxIdentifier — real behavior not derivable from the opaque schema. It omits what happens on a stale SyncToken, which fields are immutable, permission requirements, and whether the call is destructive to unspecified fields.

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 dense sentences, front-loaded with the action, then the required-identifier constraint, then field/return caveats. No filler, though the parenthetical tax-field list is somewhat crammed and could be split for scanability.

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 annotations, no output schema, and a nested opaque params object, the description covers the critical entry conditions (Id, SyncToken, sparse) and the masking return behavior. It still leaves the agent guessing about the updatable field surface, error/conflict behavior, and side effects on fields not supplied without sparse.

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?

The input schema is essentially empty (customer typed as {} at 0% description coverage), so the description does the heavy lifting: it names Id and SyncToken as required, explains the sparse flag, and maps two tax fields to their business meaning, deferring full field semantics to create_customer. Coverage is still partial — most customer fields (display name, addresses, contacts) are undocumented anywhere — so it adds substantial but incomplete meaning.

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 and resource ('Update an existing customer in QuickBooks Online'), which cleanly separates it from create_customer and delete_customer. It doesn't explicitly name the sibling alternatives, but 'existing' plus the mutation verb makes the scope 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?

Provides operational prerequisites (Id and SyncToken required, sparse: true for partial updates) that effectively define when the call is valid, but gives no explicit guidance on choosing between this and other routes such as create_customer for new records or get_customer for read-only work. Usage is implied rather than stated.

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