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

With only readOnlyHint=false available, the description carries real weight: it discloses the mandatory two-step preview-then-commit flow with a confirmationToken, that omitting commit performs no write, that category null clears state, and the auth/role requirements. That is exactly the mutation-risk context annotations don't provide.

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-loaded with the core action and the two-step flow; every sentence carries operational information. The heavy capitalization and em-dash density make it slightly harder to scan than an ideal definition, but nothing is filler.

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?

Covers everything needed to call it correctly: fallback semantics, value choice, preview/commit sequence, clearing behavior, and auth prerequisites. With no output schema, the preview description ('current → new') adequately signals what comes back.

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 100%, so baseline is 3, but the description adds genuine semantics beyond the schema: it explains what 'A_NOVA_ZERO' actually means versus a concrete code and what null does to the default. It does not elaborate on reason or confirmationToken beyond the schema, keeping it below 5.

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?

States a specific verb and resource with explicit scope: set (or clear) ONE account's DEFAULT VAT category, defined as the fallback for products without their own. That definition distinguishes it from bulk-import siblings like import_vat_categories and from per-product settings.

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?

Gives concrete when-to-use guidance for the key decision: 'A_NOVA_ZERO' for zero-rated/VAT-outside-Nova sales vs a real code to apply one category catalog-wide, plus null to clear. Preconditions (OAuth connection, OWNER role) are stated. It does not explicitly route to a sibling alternative (e.g. import_vat_categories for bulk), so not a 5.

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