wafeq_bills_partial_update

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

Annotations already carry the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description only restates the write nature ('WRITE · updates data') and HTTP verb. It adds no behavioral context about PATCH merge semantics, whether an empty body is valid, status-transition side effects, or idempotency behavior beyond what the schema's idempotency_key parameter already documents.

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 redundant: 'Partial update bill' and 'Endpoint for partially updating an existing bill' say nearly the same thing, and the emoji-prefixed line also repeats the write/update idea. Three near-duplicate statements of one concept earned no structural credit.

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?

This is a complex tool — deeply nested body (line_items with amortization objects, debit_notes, custom_fields), no output schema, and a single required id. The one-line description leaves agents without guidance on partial-update semantics, which sub-fields are safely updatable, or how this endpoint relates to the dedicated line-items partial-update sibling.

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 67%, below the 80% baseline, so the description needed to compensate — it does not. The required 'id' parameter has no schema description and none in the tool description either. The body parameter's schema description ('Adds nested create feature') is a confusing DRF artifact that mischaracterizes a partial-update payload, and the description does nothing to clarify it.

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 a specific verb and resource ('partially updating an existing bill') and the PATCH /bills/{id}/ endpoint, making the operation unambiguous. It is clear but does not explicitly differentiate from siblings like wafeq_bills_update or wafeq_bills_line_items_partial_update — the 'partial' qualifier does that work implicitly.

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?

No guidance is given on when to use this tool versus the many bill-related siblings. With wafeq_bills_update, wafeq_bills_destroy, wafeq_bills_line_items_partial_update, and wafeq_bills_create all present, an agent gets no help selecting between full update, partial update, or line-item-scoped partial update.

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