wafeq_simplified_invoices_create

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

The description adds real value beyond the annotations. While idempotentHint=false declares non-idempotency, the description explains the actual consequence ('calling twice creates two records') and provides the mitigation strategy (pass idempotency_key or let the server generate one). The WRITE/creates data label aligns with readOnlyHint=false. 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 description is short and scannable, but redundant: 'Create simplified invoice' and 'Endpoint for creating a new simplified invoice' both restate the information already in the first line's 'Simplified Invoices · POST /simplified-invoices/'. The valuable idempotency guidance is appropriately placed at the end.

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 create tool with a complex nested body, the schema covers parameter details well. However, with no output schema, the description doesn't mention return behavior, and notable constraints like the UAE place_of_supply requirement are only documented in the schema. Adequate but with clear gaps for a high-complexity operation.

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 baseline of 3 applies. The description mentions idempotency_key and its retry-safety role, but this largely mirrors the schema's own detailed description of the parameter. No new meaning is added for the body fields, which the schema already documents thoroughly.

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+resource: 'Create simplified invoice' with the endpoint 'POST /simplified-invoices/'. The 'Simplified Invoices' resource naming differentiates it from sibling tools like wafeq_invoices_create and wafeq_quotes_create. However, it doesn't explicitly contrast with those alternatives, so it stops short of a 5.

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 explicit when-to-use guidance or alternative tool routing is provided. The idempotency note addresses how to invoke safely, not when to choose this tool over wafeq_invoices_create, wafeq_quotes_create, or other invoice-family tools. The agent is left to infer usage context from the resource name alone.

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