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

Goes well beyond the annotations: discloses approval requirement, upsert-in-place semantics, and three specific pre-write validations (TIN format, 5-digit MSIC, state_code against the LHDN state table). It stops short of saying what happens to fields omitted on update (are 19 optional fields cleared or preserved) — material for an update path, and there is mild tension with idempotentHint=false despite the upsert framing.

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?

Front-loads the approval flag and the core action, then validation rules, then the handoff to the next tool — a logical order with no filler. Some phrasing ('the door checks', 'the row moves') is colorful rather than precise, and the 19-field payload is never summarized.

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 19-parameter upsert with no output schema and no per-field schema docs, the description covers approval, upsert semantics, three validations and the downstream consumer — enough to call it safely at a high level. It is not complete: field-level expectations, update-vs-overwrite behavior, and failure modes are absent.

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 0% across 19 properties, so the description carries the full burden — yet it only explains validation for tin, msic_code and state_code. The other 16 (country_code, default_currency, invoice_prefix, brn, sst_number, tourism_tax_number, address fields, default_payment_terms) get no format, default, or requiredness guidance anywhere. It does add real value for the three validated fields, but leaves most of the surface undocumented.

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?

Specific verb + resource ('Save the one-time LHDN supplier profile'), with the upsert behavior spelled out ('checks for an existing row on your tenant and creates or updates in place'). It also implicitly distinguishes itself from the read/list siblings in the myinvois_settings family by calling itself 'the only write you ever call'.

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?

States the gate clearly ('[REQUIRES APPROVAL]'), that this is a single one-time write, and names the follow-up tool (myinvois_invoice_generate reads the profile). Missing an explicit when-not-to-use note (e.g. when to call myinvois_settings_read/list first to inspect the existing row before overwriting).

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