Świadectwo Energetyczne 24

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

Annotations already declare write (readOnlyHint=false), idempotent, non-destructive behavior, so the safety profile is covered. The description adds a real constraint beyond the schema: file_id must have come from create_document_upload_url for THIS specific order, plus the business consequence of omitting the property photo.

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?

Three sentences with the purpose front-loaded, followed by the file_id provenance constraint and the photo/payment nuance. Every sentence adds actionable information with no repetition or 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 and 60% parameter coverage, the description carries real weight and handles the two highest-risk points (file_id origin, optional property photo). It stops short of covering the other document_type values or the outcome of a successful attach, which keeps it from being fully 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?

Schema coverage is 60%, and the description adds meaning beyond it for file_id — that it must originate from the upload URL for the same order, not just any upload. It also explains the semantics of one document_type value (property_photo), though filename, order_id and the rest of the enum are left to the schema.

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 ("Dołącza wgrany wcześniej plik do zamówienia") and situates it in the sibling workflow by tying file_id to create_document_upload_url and the order to create_certificate_order. An agent can distinguish this attach step from the upload-URL and order-creation siblings without opening any schema.

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 conditional guidance for the property_photo case: it is required to issue the certificate but does not block payment, and the user can supply it on the payment page or later on the order page. This clarifies when the document matters, though it does not state when to prefer this tool over update_certificate_order for other document types.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds meaningful behavioral context by stating the result is binding and backend-computed, and by forbidding the agent from computing or recalling prices independently. No contradiction with annotations exists.

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?

The description is two tightly written sentences with the key constraint front-loaded: the price is binding and backend-calculated. Every sentence earns its place, and the do-not-hallucinate warning is immediately actionable.

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 pricing tool with no output schema, the description covers the core call patterns and the critical anti-fabrication rule. The schema covers individual parameters in detail. It is slightly incomplete only in not describing return value shape or handling of the optional options/discount_code fields in the two modes.

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 high, so the baseline is 3. The description adds value beyond the schema by clarifying the order_id+access_token pairing for exact pricing versus property_type alone for approximate pricing. It does not elaborate on discount_code or the nested options object, but those are reasonably covered by the schema.

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 clearly states that the tool returns a binding certificate price calculated by the backend, with two distinct invocation modes. It is specific about the resource and action, though it does not explicitly differentiate itself from sibling tools like get_pricing.

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?

The description gives explicit when-to-use guidance: provide order_id plus access_token for a specific order, or property_type alone for an indicative quote. It also strongly warns against self-calculating or quoting prices from memory, but it does not name alternatives or exclusion conditions relative to siblings.

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

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

Beyond the sparse annotations (idempotentHint=true, destructiveHint=false), the description reveals a rich behavioral contract: partial input is allowed, the response contains missing fields and a follow-up question, the access_token is the only handle for the order, and payment is deferred until the payment link is followed. This is precisely the kind of workflow context an agent needs to invoke the tool correctly and is not available from the schema or annotations.

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, information-dense sentences with zero fluff. The front-loaded first sentence states the core action, followed immediately by the most important behavioral constraint (partial data allowed), then the access_token guidance, then the payment-state note. Every sentence earns its place and the structure is easy to scan.

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?

Given there is no output schema, the description properly conveys essential return semantics: missing fields, a next question, and the access_token. It also clarifies the payment status, which is critical for the agent's next actions. However, it does not explicitly indicate how to proceed after receiving the missing fields (e.g., calling update_certificate_order), leaving a small gap in the broader workflow context.

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% — every parameter is already explained, including enum values for property_type, the role of idempotency_key, and the scope of doors/windows/fields. The description adds only the general note that all data is not required, which is already apparent from the single required property in the schema. Per the coverage baseline, the description does not need to compensate further.

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 starts with a concrete verb-resource pair: 'Tworzy zamówienie świadectwa charakterystyki energetycznej' (creates an energy performance certificate order). It further distinguishes this tool by immediately stating that it accepts partial data, returns missing fields, and issues a unique access_token — none of which is true for siblings like create_draft or calculate_certificate_price.

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?

The description gives clear usage context: it explicitly says the tool can be invoked with incomplete data and that the resulting access_token must be carried into other tools. It also notes the order is unpaid until the get_payment_link link is used)Skip the exact phrase 'when not to use'; however, it does not mention alternatives or exclusions, so it drops just short of a 5.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false), so the bar is lower, yet the description still adds real behavioral value: the URL is one-time, the transfer is a PUT, and MCP itself never fetches files from the Internet (the caller supplies the bytes). It omits URL expiry and any permission constraints, hence not a 5.

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?

Two sentences, zero waste, and front-loaded with the primary outcome (one-time URL + file_id) before the flow detail. The final clause about MCP not fetching files disambiguates an easily misunderstood transfer model in a single short clause.

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?

There is no output schema, so the description must convey returns, and it does name both the URL and file_id. It also defines the upload method, which an agent would otherwise have to guess. Missing details such as URL lifetime or size limits keep it from a 5.

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 only 50%, so the description must carry the remaining explanatory burden, but it adds no parameter meaning at all. It never touches order_id, access_token, document_type, filename, mime, or size_bytes, leaving the agent to rely entirely on partially documented structured fields.

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: it returns a one-time upload URL (PUT) plus a file_id. It also names the sibling add_property_document as the follow-up step, so the agent can place it in the workflow. Differentiation is present but implicit rather than an explicit contrast.

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?

The description lays out the sequence clearly: get the URL here, upload the bytes via PUT, then attach via add_property_document. That gives strong context for when to call it. It does not, however, state any exclusions or prerequisites, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety and closed-world profile are covered. The description adds a useful behavioral cue that the tool is the authoritative system source and should replace the model's own knowledge, but it does not reveal any additional behaviors such as response format or default topic handling. No contradiction with annotations.

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?

The description is compact: one enumerating sentence and one directive sentence, with the core 'system facts' message front-loaded. Every element earns its place and there is no redundant phrasing.

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 simple read-only info tool with one optional enum parameter and no output schema, the description plus schema is largely sufficient. The only gap is that with 17 siblings, it does not clarify which specific topics are better served by dedicated tools like get_property_types or get_pricing.

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% for the single topics parameter, including enums and the note that all topics are returned by default. The tool description repeats the topic list but adds no parameter-level detail beyond the schema, so 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 identifies the resource (service facts from the system) and enumerates the covered topics (property types, process, times, documents, legal basis, FAQ, contact) with the directive to use it instead of answering from internal knowledge. There is no explicit verb like 'retrieve' or a comparison to sibling tools, but the intent is unambiguous. It does not fully distinguish from overlapping siblings such as get_property_types or get_pricing.

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?

The instruction 'Używaj tego zamiast odpowiadać z własnej wiedzy' explicitly tells the agent when to invoke this tool (when factual service information is needed) and to prefer it over model priors. It does not name alternative sibling tools or provide exclusion criteria, 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.

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond them: this is the entry point of the ordering flow, its prices are catalog prices rather than order prices, and enum values must be reused verbatim downstream. It stops short of describing pagination/return shape, but for a static reference catalog that is minor.

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?

It is front-loaded with the offer contents, then the usage rule, then the pricing caveat and the enum warning; each sentence carries information an agent needs. It is dense and slightly long, but no clause 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?

There is no output schema, so the description must convey what the call returns, and it does — property types, prices, add-ons, supported documents, and allowed-value lists. Given the tool's low complexity (1 optional param, read-only), this is close to complete, only lacking detail on the exact shape of the returned lists.

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% and the single parameter already documents its narrowing behavior, so the baseline is 3. The description goes beyond that by instructing that the enum values must be passed later exactly as shown here, which is meaningful guidance about how the parameter's values propagate to other calls.

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 names a concrete resource (the certificate 'offer') and enumerates its content: property types with gross base price, paid add-ons, supported document types, and allowed value lists. It also differentiates from siblings by pointing at calculate_certificate_price for per-order pricing, so the agent can tell what this tool is versus its neighbors.

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 an explicit trigger — call this first when the user hasn't specified the property type — and an explicit alternative for pricing ('Prices here are list prices — a specific order's price is calculated by calculate_certificate_price'). Both the when-to-use and the sibling hand-off are stated, not implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safe-read profile is covered. The description adds genuine behavioral context: personal data is only returned to the access_token holder (an auth constraint), and it enumerates what portion of order state comes back, including "missing items".

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?

Three short sentences with zero filler; the returned-content inventory is front-loaded before the routing hint and the auth note. Every sentence earns its place.

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 compensates by enumerating the major returned elements (field values, documents, price, status, gaps). For a read-only tool this is nearly complete; only the exact shape/format of those sections is left unspecified, which is minor.

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 both order_id and access_token are already well documented in the schema (including the warning to never show the token to the user). The description adds no additional parameter syntax or format detail beyond that, making the baseline 3 appropriate.

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+resource (reading the full certificate order state) and enumerates the returned content: collected field values, attached documents, price, status, and missing items. It explicitly distinguishes itself from the sibling get_certificate_order_status, so an agent can pick the right tool without opening schemas.

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 explicit when-to-use ("when you need to read what has already been saved") and names the alternative for a narrower need (get_certificate_order_status for fulfillment progress alone). This is a clear routing rule between two similar siblings.

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

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

Annotations already mark readOnlyHint=true, so the description doesn't need to restate read-only behavior. It adds useful behavioral context: the tool returns a ready-made Polish question and allowed values, and it explicitly says the backend decides what is missing, preventing the agent from guessing. This goes beyond the annotations without contradicting them.

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?

The description is two sentences with no redundant words. The first sentence front-loads what the tool returns and its purpose; the second sentence adds a critical behavioral constraint. Every part earns its place.

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 simple read-only tool with two well-documented parameters and no output schema, the description sufficiently explains the return content (missing fields, Polish question, allowed values) and the expected agent behavior. No critical information is missing for correct invocation.

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 parameters are fully documented in the schema itself. The tool description does not add parameter-level meaning, but it doesn't need to because the schema already explains order_id and access_token, including the security note to never show the token to the user. Baseline 3 is appropriate.

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 clearly states a specific verb ('Zwraca' = returns) and resource ('listę pól, których brakuje' = list of missing fields) plus the purpose ('żeby zamówienie było gotowe do płatności' = for order to be ready for payment). It also distinguishes from siblings like get_certificate_order or get_certificate_order_status by focusing specifically on missing fields needed for payment readiness.

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?

The description gives clear context: call this to learn what fields are missing for payment, and the backend is the authority. The instruction 'nie zgaduj i nie pytaj o pola spoza tej listy' (don't guess and don't ask about fields outside this list) provides practical guidance. However, it does not explicitly name alternatives or state when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds genuinely useful behavioral context: the payload is a reduced view that omits personal data and field values, which matters for privacy and for deciding what to show a user. It does not cover rate limits, polling behavior, or return shape.

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?

Two short sentences with the scope constraint front-loaded and the use case second. Nothing is redundant and every clause carries information.

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 two-parameter read-only lookup with no output schema, the description conveys enough: it says what the status represents and which stages to report. Since no output schema exists, it could say a bit more about the returned status values or whether results are polled, but it is broadly sufficient.

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%, and both parameters carry detailed guidance (order_id from create_certificate_order; access_token returned once and never displayed). The description adds no parameter-level meaning beyond that, so the baseline 3 is appropriate when the schema does the heavy lifting.

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 resource and scope: a shortened order status that deliberately excludes personal data and field values. This scoping implicitly separates it from the fuller get_certificate_order fetch, though that sibling is never named, so an agent must infer the contrast rather than being routed explicitly.

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?

'Używaj do informowania użytkownika o postępie realizacji' gives a clear intended context and enumerates the stages it covers (payment, certificate preparation, shipping). It stops short of naming when NOT to use this tool or pointing at get_certificate_order for full details, so exclusions are missing.

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

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

Annotations declare the safety profile (readOnly=false, idempotent=true, non-destructive), and the description adds real behavioral context beyond that: payment happens at an external operator, MCP never accepts card data, and the building photo can be added later or sent after payment. It stops short of describing rate limits, re-invocation semantics, or link expiry.

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 purpose, then the page behavior, then the hard usage constraint. Every sentence carries information, though the sentence about the building photo is somewhat tangential to the tool's invocation decision.

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 correctly explains what is returned (a secure link) and the downstream flow the user experiences, plus the critical consent precondition and the card-data exclusion. It does not cover link validity/expiry or failure modes, which keeps it from a 5.

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% — both order_id and access_token are already documented in the schema, including the warning to never expose the token. The description adds no parameter-level detail on top, 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?

States a specific verb (returns), a specific resource (secure payment page link), and the scope ('kompletnego zamówienia'), making it clearly distinct from siblings like create_certificate_order or get_certificate_order_status.

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 an explicit, strongly-conditioned when-to-call ('WYWOŁUJ WYŁĄCZNIE po tym, jak pokażesz użytkownikowi cenę i dostaniesz od niego wyraźną zgodę'), which effectively defines a when-not as well. No sibling/alternative is named for the cases where this should not be used, so it falls just short of a 5.

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

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

The description adds meaningful behavioral context beyond the annotations: omitted fields are left untouched, invalid values abort the whole update, and no changes are persisted when INVALID_FIELD_VALUE occurs. This atomic partial-update behavior is essential for correct invocation and is not already present in the annotations.

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?

The description is three sentences with no filler; it front-loads the main purpose, then states the update semantics, the return behavior, and the failure mode. Each sentence adds necessary information that is not already implied by the structured schema.

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?

Despite having a complex 9-parameter schema with nested objects and no output schema, the description clearly covers the two most important operational aspects: partial updates and the all-or-nothing behavior. The schema further clarifies parameter sourcing such as order_id from create_certificate_order and paths from get_certificate_order_requirements, so the overall definition is sufficient for correct use.

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?

Because schema description coverage is 100%, the baseline here is a 3. The description adds an important global semantic that any omitted parameter is simply preserved, and that a single out-of-range value invalidates the entire request. This is substantial additional value beyond the field-level schema descriptions.

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 opens with 'Częściowa aktualizacja zamówienia' (partial order update), which names the specific verb and resource. It further clarifies that only the submitted fields are changed while the rest remain untouched, making the update scope of the tool clear. It does not explicitly call out sibling update_draft, but the terms 'zamówienie' (order) versus draft give reasonable distinction.

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?

The description provides clear contextual guidance: it is for partially updating an existing order and for checking 'aktualny status i pozostałe braki' (current status and remaining gaps), so the agent can infer it is the right tool when completing an existing certificate order. However, there is no explicit when-not-to-use guidance or naming of alternatives such as update_draft, leaving some inference to the agent.

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