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

While annotations already mark destructiveHint=true, the description goes well beyond that: it explains sparse updates by default, that a Line array replaces all lines, that sparse:false clears omitted writable fields, that VendorRef must be repeated, and that sensitive fields must not be sent. This is strong behavioral disclosure and does not contradict the annotations.

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 main description is a single, front-loaded sentence stating the action, target, and prerequisite with no filler. Detailed behavioral nuances are delegated to the structured parameter schema, keeping the description appropriately concise.

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?

The combination of annotations and the rich entity description covers preconditions, sparse/full update behavior, destructive semantics, and prohibited fields. A minor gap is that the main description does not mention the expected response or explicitly direct users to create_bill for new bills, but this is not essential given the sibling context and open object schema.

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 the schema already documents both entity and company parameters. The tool description only restates that Id and SyncToken are required, which adds no meaning beyond the schema, so the baseline of 3 is appropriate.

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 names a specific verb ('Update'), an explicit resource ('an existing bill in QuickBooks Online'), and the key precondition (requires Id and SyncToken). This clearly distinguishes it from create_bill, delete_bill, and get_bill among the sibling tools.

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 phrase 'existing bill' and the requirement to supply the current SyncToken (fetch the Bill first) make it clear this tool is for updating an already-created bill. It does not explicitly name create_bill as the alternative for new bills, but the context leaves little ambiguity.

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