Świadectwo Energetyczne 24

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

Annotations already provide idempotentHint=true, readOnlyHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: file_id is scoped to a specific order and property_photo is required for the certificate. However, it does not explain what happens on repeated calls, whether documents can be replaced, or what the API returns after attaching.

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 long, front-loads the main action, and then adds the two most important caveats: file_id provenance and the property_photo requirement. There is no filler or redundant restatement of the title or 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?

The description is sufficient for an agent to understand the core workflow: upload first, then attach with a scoped file_id, and note the business consequence of missing a property_photo. The lack of an output schema and any statement about response/confirmation is a minor gap, but the action and its prerequisites are fully covered.

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?

The schema describes file_id, order_id, and access_token, covering 60% of parameters. The description adds critical semantics for file_id (must come from create_document_upload_url for the same order) and for document_type (property_photo is required for the certificate). However, filename and other document_type values are left without additional explanation, so the description only partially compensates for the schema coverage gap.

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 the action: 'Dołącza wgrany wcześniej plik do zamówienia' (attaches a previously uploaded file to an order). It also distinguishes this from the upload step by explicitly requiring file_id from create_document_upload_url, which separates it from sibling tools.

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: the tool is used after a file upload, and it explains the consequence of omitting the property_photo (the user will have to add it on the payment page). It does not explicitly state when not to use this tool or compare it with other sibling mutations, but the prerequisites and business impact are clear.

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 readOnlyHint annotation already marks it non-mutating; the description adds genuinely useful behavioral guardrails: the price is binding and backend-computed, and the agent must never self-calculate or quote amounts from memory. There is no contradiction, and the added constraint goes beyond what annotations alone convey.

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, front-loaded with purpose, then input modes, then a necessary safety warning. Every sentence earns its place; there is no repetition of schema content.

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 read-only price tool with no output schema, the description covers the core calling scenarios and the main behavioral rule. It leaves minor ambiguity around what happens if both order_id and property_type are supplied and does not explain options, but the schema and the simple purpose make the tool usable.

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 80% schema description coverage, the schema already documents most parameters. The description adds value by stating the relationship between the two call modes (order_id + access_token vs property_type) and reinforcing that property_type is used 'alone'. It does not clarify the meaning of options or the interaction with discount_code, but that is a moderate gap given high schema coverage.

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 identifies the action and result ('Wiążąca cena wyliczona przez nasz backend') and gives two concrete input modes, so an agent knows what the tool is for. It does not explicitly differentiate from closely related siblings like get_pricing or get_certificate_options, so it falls short of a 5.

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 explicit when-to-use conditions: order_id + access_token for a specific order or property_type alone for an indicative quote, plus a strong 'never calculate yourself' instruction. It doesn't mention exclusions or alternative sibling tools, but the guidance is unambiguous.

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: partial input is allowed, the response carries missing fields and a follow-up question, the access_token is the sole key and must be forwarded to other tools, and the order is unpaid until the get_payment_link step. It does not contradict the annotations and gives important operational detail.

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 short, front-loaded sentences with no filler. It leads with the core action, then the key partial-data behavior, then the critical access_token and payment-state warnings. 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?

Given the complex 9-parameter nested schema and the absence of an output schema, the description covers the essential flow: initial creation with partial data, missing-field/question feedback, access_token handling, and unpaid order state. It could go further on response structure or error cases, but the schema and annotations make it sufficiently usable.

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 parameters and their constraints. The description itself mostly reinforces that partial data is acceptable rather than adding new parameter-level semantics. The heavy lifting is done by the schema's per-property 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 states a specific verb and resource: 'Tworzy zamówienie świadectwa charakterystyki energetycznej' (creates an energy performance certificate order). It is clear and not tautological, but it does not explicitly differentiate from siblings like update_certificate_order or create_draft beyond the create/resource framing.

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 for when to call: incomplete data is acceptable, the response returns missing fields and the next question, and payment is deferred to get_payment_link. It does not explicitly state when not to use the tool or name alternatives such as update_certificate_order for existing orders.

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 are all false/default and carry no safety meaning, so the description bears the burden. It adds genuinely useful behavior: the URL is one-time ('jednorazowy'), uses the PUT method, and — critically — MCP never downloads files from the internet, which prevents an agent from assuming it will fetch the byte content. This is real context beyond the structured fields.

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 filler. The primary return value and method are front-loaded, and the second sentence debunks a common misconception about MCP file handling. Every clause 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 correctly names both return values (URL, file_id) and links them into the broader workflow. The one-time nature of the URL is surfaced. Minor gaps remain: URL expiry, upload size limits, and what happens if the upload is never performed, but the essentials for a correct call are present.

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 50%; access_token, order_id, and mime are documented in the schema, while filename, size_bytes, and document_type get no prose. The description does not add parameter-level semantics, but it provides flow context that explains why the upload URL and file_id matter for later steps. It partially compensates but does not reach the 4 baseline.

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 uses a specific verb ('Zwraca' / returns) tied to a concrete resource: a one-time PUT upload URL plus a file_id. It explicitly names the successor tool add_property_document, so an agent can distinguish this preparation step from the attach step 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?

The workflow is clearly sequenced: first obtain the URL and file_id, then attach the file via add_property_document. The second sentence clarifies the division of labor (the client sends bytes; MCP never fetches them). It stops short of stating explicit when-not-to-use conditions or alternatives, but the placement in the flow is unambiguous.

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?

It significantly goes beyond the default false annotations by disclosing the key behavior: a draft is created, the user must open a resumeUrl, and the order is not placed until external steps are completed. Also states partial acceptance and missing fields. This is valuable behavioral context with no contradiction.

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 compact sentences: creation, return behavior, and a critical caveat. No redundant wording, and the most decision-relevant facts are front-loaded in the first sentence.

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 creation tool with no output schema, the description covers what is created, what is returned, what the user must do next, and what the draft is not. Combined with the fully described schema, this gives an agent everything needed to invoke it correctly.

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?

Input schema coverage is 100%, with both parameters already described meaningfully. The description adds general context about 'collected field values' and accepted/rejected fields, but it doesn't add per-parameter detail beyond the schema. 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 states a specific action ('Creates'), a precise resource ('a DRAFT energy-certificate order'), and immediately clarifies the boundary with 'A draft is NOT a placed order.' This clearly separates it from siblings like get_draft and update_draft by signaling creation rather than retrieval or modification.

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 clearly positions this as the creation step: it operates on 'collected field values' and produces a draft that must later be finished on the website. It doesn't explicitly name alternatives like update_draft, but the context makes when to use this tool clear.

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 the description adds useful behavioral detail: the exact categories of options returned and the requirement that enum values be reproduced exactly as displayed. This goes beyond the structured 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?

Two sentences with no filler: the first states the resource and contents, the second gives the critical canonical-enum instruction. It is front-loaded and 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?

For a simple optional-parameter read-only tool with no output schema, the description gives enough context about the response categories and downstream use. It could name the overlapping siblings or clarify whether the lists are exhaustive, but the core information is present.

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 the schema already explains that property_type narrows the value lists. The description itself adds no additional parameter semantics, so the baseline score of 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 opens with a specific verb+resource ('Zwraca opcje zamówienia') and enumerates the returned content: property types, paid add-ons, supported document types, and value lists. This clearly distinguishes get_certificate_options from order/status/requirements siblings.

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 to reuse returned enum values later ('Wartości enum podawaj później DOKŁADNIE tak, jak tu wyglądają') implies the tool is the source of canonical values for subsequent calls, but there is no explicit when-to-use vs alternatives. It does not mention overlapping siblings like get_property_types or list_property_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 mark the tool as read-only and non-destructive. The description adds useful behavioral context by explaining that the tool returns the full order state and, importantly, that personal data is only returned to the access_token holder. This goes beyond the annotation-provided safety profile without contradicting it.

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 short, information-dense sentences. The first front-loads what the tool returns, and the second adds a critical access-handling caveat. There is no filler or redundant restatement of the tool name or 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?

Given the absence of an output schema, the description adequately covers what the agent should expect in the response: fields, documents, price, status, and deficiencies. Combined with the access_token safety note and the read-only annotation, this is largely complete for a simple read operation, though it could mention response format or explicitly distinguish itself from the status-only sibling.

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 both order_id and access_token well. The description adds one relevant semantic point about personal data being restricted to the token holder, but it does not expand much on parameter meaning beyond what the schema provides, warranting the baseline score.

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 the full state of an order, enumerating the included content: field values, documents, price, status, and deficiencies. This makes it distinct from narrow siblings like get_certificate_order_status, though it uses a noun phrase rather than an explicit verb and does not name the sibling it differs from.

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 no guidance on when to use this tool versus alternatives such as get_certificate_order_status or get_certificate_order_requirements. The context signal of 'full state' implies a use case, but the description itself does not provide explicit when-to-use or when-not-to-use direction.

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?

The annotations already declare readOnlyHint=true and openWorldHint=false. The description adds meaningful behavioral context beyond that: the result deliberately omits personal data and field values, making it privacy-safe for user-facing updates. This helps the agent understand what kind of data the tool will and will not return.

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 carry the full purpose, scope, and usage guidance with no redundant wording. The core constraint ('no personal data, no field values') is front-loaded, making the description easy to parse quickly.

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 two-parameter read-only tool, the description adequately explains the tool's purpose and output scope. Since there is no output schema, it would be slightly stronger if it enumerated possible status values, but that is not essential for selecting or invoking the tool correctly.

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 the schema already documents order_id and access_token, including the one-time issuance warning for access_token. The description adds no additional parameter-specific meaning, so the baseline score of 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 states a specific, scoped purpose: a shortened order status with no personal data and no field values. This clearly differentiates it from the sibling get_certificate_order, which presumably returns full order details. The intended resource and output scope are unambiguous.

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 explicitly says to use the tool to inform the user about order progress, which gives clear usage context. However, it does not explicitly say when not to use it or name the full-detail alternative, though the distinction is implied by 'shortened status.'

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, so the safety profile is established. The description adds meaningful behavioral context by enumerating what the response will include, especially missing required fields and resumeUrl, which an agent could not infer from the minimal schema alone.

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?

One sentence, no filler, and the most important output categories are listed upfront. Every word contributes to the agent's ability to call the tool correctly.

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 carries the burden of explaining return value semantics, which it does by naming the four parts of a draft state. It does not discuss error/not-found behavior, but for a simple read-only, single-parameter tool the description is largely 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 the single parameter's description already explains that resumeToken comes from create_draft. The tool description adds no additional parameter-level meaning, so the baseline of 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 names a specific verb ("Returns"), a clear resource (draft), and specifies what is returned: stored field values, missing required fields, status, and resumeUrl. This distinguishes it from sibling tools like create_draft and update_draft without needing to open the 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?

Usage is implied: the resumeToken parameter is described as "returned by create_draft," which signals sequencing after draft creation. However, the description never explicitly states when to prefer get_draft over update_draft or other siblings, nor does it mention exclusions.

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, and the description is consistent with that, so there is no contradiction. The description goes beyond annotations by specifying what the returned catalog contains: dot-separated paths, types, Polish enum options, and optionality. This gives the agent useful expectations about the tool's output behavior.

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: two sentences, no filler, front-loaded with what the tool returns and followed by a practical usage pointer. 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?

For a single-parameter read-only tool with no output schema, the description is complete: it explains the purpose, the content of the return value, and how to use that output with sibling tools. An agent has everything needed to call it correctly and interpret its result.

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%: propertyType is a required string enum with four Polish slugs and the description 'Property type slug'. The tool description adds general context about using the returned fields, but it does not add much beyond the schema for the parameter itself, so the baseline of 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 states a specific action ('Returns the full field catalog') on a specific resource ('for a property type') and enumerates exactly what the catalog includes. It is clearly distinct from siblings like get_draft, get_pricing, and list_property_types, so an agent can select it without ambiguity.

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: this tool provides the exact paths and options to use with create_draft/update_draft, which implies it should be called before those mutation tools. It does not explicitly name alternatives or exclusion conditions, so it stops short of a 5, but the intended workflow is apparent.

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 signal readOnlyHint=false and idempotentHint=true. The description adds useful behavioral context: the returned link leads to a page where the user sees the summary, may add a building photo, accepts terms, and pays at an external operator, while MCP itself never handles card data. 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?

Three sentences with no filler: the first states the purpose, the second summarizes the payment page flow, and the third gives a hard precondition and a security note. The most important usage constraint is highlighted in caps for emphasis.

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 tool with no output schema, the description provides the return value, the precondition for invocation, the user-facing flow, and a security boundary. Nothing essential for an agent to invoke it correctly is missing.

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?

The input schema already documents both parameters at 100% coverage, including that order_id comes from create_certificate_order and that access_token is returned once and must be kept secret. The description does not add parameter-level detail, but it does not need to because the schema covers it.

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 action and object: returns a secure payment-page link for a complete order. This clearly distinguishes it from sibling tools that deal with certificates, drafts, documents, or pricing, and it makes clear the tool does not execute a payment itself.

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 explicitly states when to call the tool: only after showing the user the price and receiving explicit consent. It also adds a relevant boundary by stating that MCP never accepts card data, giving the agent a clear safety-context rule.

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 the tool as read-only, so the bar is lower. The description adds that pricing is server-computed and in PLN, which is useful, but it does not disclose behaviors such as discount-code validation, add-on availability, or response 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 tight sentences: the first defines the tool's function and inputs, the second states the usage rule. There is no redundant or filler wording.

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 read-only pricing getter with no output schema, the description conveys the result (gross price in PLN), the key inputs, and why this tool should be preferred. It leaves some edge-case behavior unspecified, but the core information needed for correct invocation is present.

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 only 33% schema description coverage, the description partially compensates by identifying add-ons and discount code as optional inputs to the price calculation. It does not explain the meaning of express24h/paperVersion or give discount-code format hints beyond the schema's names and constraints.

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 specific resource and result: a server-computed gross price in PLN for a property type, with optional add-ons and discount code. It is immediately distinguishable from the sibling draft/form tools.

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 explicitly says to always use this tool instead of computing prices yourself, which gives a clear when-to-use instruction. It does not name an alternative tool or detail when not to use it beyond the self-computation exclusion.

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 annotations already indicate readOnlyHint=true and openWorldHint=false, covering the safety and completeness profile. The description adds context that the result includes base gross prices, which is useful, but it does not disclose more behavioral details such as output structure or potential edge cases.

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: the first states the return value and key data, and the second gives actionable usage guidance. It is concise, front-loaded, and contains 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?

For a parameterless lookup tool with readOnlyHint and openWorldHint annotations, the description covers what is returned and when to call it. There is no output schema, but the description provides enough detail about the returned content for an agent to invoke it correctly.

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?

The tool has zero parameters and the schema coverage is 100%, so there is nothing for the description to clarify. The baseline of 4 applies because no parameter documentation is needed.

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 the tool returns property types that are eligible for a certificate, along with their base gross price in PLN. It is specific enough to identify the resource and the returned data, though it does not explicitly differentiate itself from the similarly named sibling list_property_types.

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 explicitly instructs the agent to call this tool first when the user has not specified a property type. It provides clear context for when to use it, but it does not mention alternatives or when not to use it.

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 useful context about the closed, fixed set of four property types, the PLN gross currency, and available add-ons, going beyond what annotations alone convey. No contradiction 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 short sentences with no filler. The core content and the usage guidance are both front-loaded, and every phrase contributes useful 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 simple read-only list tool with no parameters and no output schema, the description fully covers what the agent needs to know: what is returned (the four property types, base prices, add-ons) and when to call it. Nothing essential is missing.

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?

The tool has zero parameters, so schema coverage is trivially 100%. Per the baseline for zero-parameter tools, no parameter explanation is needed; the description focuses on the output, which 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 the verb 'Lists' and the resource ('the 4 supported property types') plus what is included (base prices in PLN gross and paid add-ons). It is specific and understandable, though it does not explicitly differentiate from the sibling get_pricing, which may also relate to 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 guidance: 'Call this first if the user has not specified the property type.' This clearly identifies a primary use case, but it does not mention alternatives or exclusions, such as which tool to use once the property type is known.

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 annotations (mutating, non-destructive, idempotent), the description discloses meaningful behavior: merge semantics, atomic all-or-nothing saves ('NIC nie zostaje zapisane'), the INVALID_FIELD_VALUE error for out-of-range values, and a response summarizing status and remaining gaps. 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?

Two compact sentences with no filler. The core partial-update behavior is front-loaded, followed by return value and error semantics. 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?

For a complex 9-parameter, nested-object mutation with no output schema, the description provides the essential return information (status and remaining deficiencies) and the error contract. The rich schema covers field-level details, but the description could add more about order state preconditions or response structure.

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?

The input schema already covers 100% of parameters with descriptions, so the baseline is 3. The description adds valuable parameter-level semantics by clarifying that only specified fields are set and omitted fields are preserved, which is essential for knowing how to invoke a partial update.

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: 'Częściowa aktualizacja zamówienia' (partial update of an order), and adds the key scoping rule that only the provided fields are changed. This clearly distinguishes the tool from create/get siblings.

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 establishes clear context: use it for partial updates where unspecified fields remain untouched, and it returns current status plus remaining deficiencies. It does not explicitly name alternative tools or state when not to use it, so it stops short of full routing 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?

The description adds meaningful behavior beyond the annotations: it explicitly says values are 'overwritten,' and it discloses return values (updated state, remaining missing fields, resumeUrl). It does not contradict the idempotentHint=true or destructiveHint=false 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 a single, front-loaded sentence that covers what the tool does, what it operates on, and what it returns. No filler or repetition of schema details.

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 tool with rich schema descriptions, the description covers the operation, the identifying token, and the return payload. Lacking an output schema, the return-value summary is especially helpful. The main omission is explicit guidance on choosing between this and sibling tools, but that is a secondary 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 resumeToken and the fields array in detail with examples and constraints. The description adds only the overwrite semantics and result context, which is useful but not necessary for parameter understanding.

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 action ('Adds or overwrites field values') on a specific resource ('an existing draft') identified by its resumeToken. This clearly distinguishes it from create_draft (which creates a new draft) and get_draft (which reads state).

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 implies this is for an existing draft started elsewhere, so the agent can infer it is used after create_draft rather than instead of it. However, it does not explicitly mention alternatives, when not to use it, or why it would be preferred over get_draft.

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