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

Annotations only declare it is a non-idempotent, destructive, open-world write; the description adds substantive behavior beyond that — uniqueness collisions are rejected, the record is shared across all legal entities, and the new supplier may sit in a pending-approval state before it is usable. It omits what happens on partial failure and does not explain why destructiveHint is set for a create.

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 plus the endpoint line, front-loaded with the operation type and followed by constraints in diminishing importance. Every sentence carries a distinct fact with no 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 the mutation's preconditions, sharing scope and approval caveat, but with 14 parameters, 36% schema coverage and no output schema, the description never says what the returned supplier contains or how to detect the pending-approval state. Adequate for the write itself, thin for the data contract.

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 only 36% across 14 parameters, so the description needs to compensate and largely does not: it only touches the name/uniqueness rule, leaving contacts, currencies, conditions, minimum_order_sum, delivery_period_days and address fields undocumented in both places. An agent must guess at validation and formatting rules for most inputs.

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?

Opens with a specific verb+resource ('WRITE: create a supplier') and names the exact endpoint (POST /suppliers). The verb alone separates it from the get_/list_ siblings, so no ambiguity remains about what the tool does.

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 real usage context: name must be unique in the company and a duplicate name, unique code or registration number is rejected, plus the caveat that approval settings may block use on orders. It does not point at an alternative (e.g. look up an existing supplier with precoro_get_supplier before creating), so it stops short of explicit when/when-not routing.

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