wafeq_simplified_invoices_partial_update

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

The annotations already convey readOnlyHint=false and idempotentHint=true; the description merely restates 'WRITE · updates data' and adds the PATCH endpoint without any behavioral depth. It discloses nothing about partial-update semantics, validation failures, or leftover-field behavior — the valuable idempotency detail lives in the schema, not the description. No contradiction with 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 three lines contain clear redundancy: 'Partial update simplified invoice' and 'Endpoint for partially updating an existing simplified invoice' say the same thing. The endpoint banner earns its place, but the repetition wastes space that could have been used for usage guidance.

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 tool with a large nested body, strict enums, and no output schema, this description is too thin. An agent is left without essential operational context: whether line_items replaces or merges, which body fields are valid to send on a partial update, and what a successful response looks like. The strong idempotency_key schema documentation is the only compensating factor.

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 description itself mentions no parameters, but schema coverage at 67% means most of the load is already carried by the schema, which documents idempotency_key thoroughly and every body field individually. The cryptic 'Adds nested create feature' and the DRF ModelSerializer boilerplate for line_items remain unexplained, but that is a schema gap, not a description gap.

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 clearly identifies the operation (partial update) and resource (simplified invoice), reinforced by the PATCH /simplified-invoices/{id}/ endpoint banner. The word 'partial' implicitly differentiates it from the full-update sibling, though it never names that sibling or explains when one is preferred over the other.

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 on when to use this tool versus wafeq_simplified_invoices_update, wafeq_simplified_invoices_destroy, or the dedicated line-items endpoints. Nothing states that only supplied body fields are modified, or what the behavior is when line_items is provided.

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