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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety bar is lower, and the description usefully adds true PATCH semantics ('the rest stay as they are') plus a payroll/invoice impact warning. However, the sentence 'Pay and bill rates change payroll and invoices' refers to fields that do not exist in this schema at all, which is a misleading behavioral signal for a mutation tool. No mention of failure modes for an invalid job_id.

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 tight sentences with the operation mode front-loaded and the endpoint last; almost every clause carries decision-relevant information. The pay/bill-rate clause is the one sentence that does not correspond to any schema parameter, so it is the sole dead weight.

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 10-parameter destructive mutation with no output schema, the description covers partial-update semantics, the field scope, the excluded fields, and a user-confirmation requirement. An agent could call this correctly from the definition alone; only response behavior and error handling on a bad job_id are left uncovered.

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?

At 40% schema coverage the description must compensate, and it does: it maps the updatable surface (title, overtime rule, workers' comp code, burden, per-diem/expenses/sick-time/meal-period flags) onto the nine optional properties and explicitly excludes the fields that look editable but are not. It stops short of explaining the boolean flags' on/off meaning or the burden_manual scale.

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?

Opens with an explicit 'WRITE:' marker, names the resource (contract job), and enumerates exactly which fields the call mutates, ending with the concrete PATCH /v1/ContractJobs/{jobId} endpoint. Among siblings like bilflo_create_contract_job, bilflo_terminate_contract_job and bilflo_reopen_contract_job, this is unambiguously the partial-field-mutation tool.

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?

It states explicit non-goals ('Client, contractor, dates and status cannot be changed here'), which routes the agent to terminate/reopen or other tools, and adds a confirmation instruction for rate changes. What's missing is a named alternative for the excluded operations rather than an implicit pointer.

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