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

Beyond the annotations (which only flag non-readOnly, idempotent, non-destructive, closed-world), the description discloses a rich behavioral contract: partial submissions are supported, the response drives a follow-up question loop, the access_token is the sole handle to the order and must be forwarded to other tools, and the order remains unpaid until the user follows the get_payment_link flow.

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, each carrying distinct load: purpose, partial-data workflow, token handling, and payment state. The most important operational facts (create + partial fill) are front-loaded 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?

With no output schema, the description partially compensates by explaining that the response contains missing fields, the next question, and the access_token. However, for a 9-parameter nested create tool it does not fully describe the response shape or the relationship to get_certificate_order_requirements, leaving a small gap.

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 schema already documents all 9 parameters including idempotency_key, fields paths, and enum options. The description adds no parameter-level syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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 and resource: 'Tworzy zamówienie świadectwa charakterystyki energetycznej.' It is immediately distinguishable from sibling readers/mutators like get_certificate_order and update_certificate_order, and it ties itself into the broader flow by naming get_payment_link.

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 gives concrete guidance on how to invoke: partial data is acceptable ('NIE musisz mieć wszystkich danych — podaj, co już wiesz'), and it explains the iterative fill-in workflow where the response surfaces missing fields and the next question. It lacks explicit exclusions (e.g. when to prefer update_certificate_order over creating a new order), so it falls short of a full 5.

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