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

Annotations already declare destructiveHint=true and idempotentHint=true, so 'Veilig om te herhalen' largely restates the idempotency hint and earns little. The description does add genuine beyond-annotation context: empty fields do not overwrite existing values, and an unknown eigenschappen key raises an error because custom fields must pre-exist. It stops short of explaining why destructiveHint is set (i.e., non-empty fields can overwrite existing data).

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?

Four short sentences, front-loaded with the upsert purpose before the matching rule and the error caveat. Every sentence except 'Veilig om te herhalen' adds information, and that one duplicates the idempotentHint annotation. Minor redundancy only; no filler or restated title.

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 22-parameter, zero-required, nested-object mutation with no output schema, the description covers the highest-risk behaviors (dedupe key order, non-destructive empty fields, custom-field errors). It leaves open what happens when neither domein nor naam is given, and whether the call reports created-versus-updated status or an identifier. Those are the gaps that keep this from being complete.

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?

With 22 parameters and only 32% schema description coverage, the description must carry weight; it does so for the identity/matching parameters (domein, naam) and for eigenschappen, which is correctly flagged as restricted to pre-registered custom fields. The other ~18 fields (adres, bcg, lifecycle, jaaromzet, etc.) receive no meaning beyond their names and sparse schema hints. Partial compensation, not full.

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 first clause names a specific verb pair and resource ('Maak of werk een bedrijf bij') and immediately clarifies the operation as an upsert. It further specifies the dedupe key order (domein, then naam), which no sibling like crm_bedrijf or crm_bedrijven implies. An agent can distinguish this write/upsert path from the read siblings by entity name alone.

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?

It states the operative context clearly: use this to create-or-update without producing duplicates, and it is safe to repeat. The matching precedence (domein before naam) gives concrete guidance on how an existing record is located. What is missing is an explicit statement of when NOT to use it (e.g., versus crm_bewaar_contact or crm_bewaar_deal, or what to do when neither domein nor naam is supplied).

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