Ś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?

Annotations declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds important behavioral context: the price is binding and backend-computed, and the access_token is sensitive and must not be shown to the user. It also warns against using memory for prices. This goes beyond the annotations and provides useful operational constraints.

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 concise and front-loaded: it states the core purpose first, then the two usage modes, then the critical warning. Every sentence earns its place, and the warning is emphasized with 'NIGDY' (never). No wasted words.

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 tool with no output schema, the description covers the key decision (order vs. indicative) and the critical constraint (don't calculate prices). It doesn't describe the return format, but since there's no output schema, that's a minor gap. The description is complete enough for an agent to invoke the tool correctly in most scenarios.

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 80%, so the schema already documents most parameters. The description adds meaning by explaining the relationship between order_id/access_token and property_type, and by warning about the access_token's sensitivity. It doesn't detail the options object, but the schema covers those fields. Overall, the description complements the schema well.

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's purpose: it calculates a binding price for a certificate. It distinguishes two modes: exact price for a specific order (order_id + access_token) or an indicative quote (property_type alone). It also explicitly warns against calculating prices independently, which differentiates it from any pricing-related 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 provides explicit usage guidance: when to use order_id + access_token vs. property_type alone. It also gives a strong exclusion: never calculate the price yourself or provide amounts from memory. This is clear, actionable guidance for an agent.

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 include idempotentHint=true)Skip, which is consistent with the description's idempotency_key guidance. The description adds context about the access_token being essential, that the order is not paid until a link is used, and that it doesn't require all data. However, it doesn't mention error handling or rate limits, but the idempotency and partial-data behavior are well disclosed beyond 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, well-structured paragraph in Polish with clear sentences. It front-loads the purpose and then provides key behavioral notes. It's concise but not overly terse, using bold for emphasis on critical points (access_token). It earns its place without unnecessary 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 complex tool with 9 parameters and nested objects, the description covers the main operational aspects: creation, partial data acceptance, response containing missing fields, access_token handling, and payment status. With no output schema, the description compensates well by telling the agent what to expect in response. It also hints at integration with sibling tools like get_payment_link.

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%, so most parameters are already described. The description adds crucial semantics for the 'fields' parameter: it explains the path-value format from get_certificate_order_requirements and warns about exact enum usage. It also clarifies the idempotency_key usage, which is essential for correct invocation. This adds value beyond the 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 clearly states that it creates an energy performance certificate order, and distinguishes it from siblings like get_certificate_order (which retrieves) and update_certificate_order (which modifies). It also mentions not all data is needed, which sets it apart from a full-form submission tool.

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 tells when to use it: 'podaj, co już wiesz' (provide what you know) and indicates that it returns missing fields and next questions. It also mentions that access_token should be passed to other tools, implying it's a prerequisite for follow-up operations. It signals that the order is not paid until a payment link is used, guiding the agent's next steps.

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?

The description discloses the key behavioral outcome: it creates only a draft, does not complete payment or consents, and returns a resumeUrl plus accepted/rejected and missing-field information. This adds value beyond the annotations, which only indicate a mutating, non-idempotent operation; 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?

Three dense sentences with no filler; the core action, output, and caveat are all front-loaded. Every sentence contributes behavioral or workflow 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?

The description covers the main return payload and the user's required next step, compensating for the absent output schema. It does not detail the workflow ordering relative to get_form_fields or create_certificate_order, but the schema and sibling tools provide enough context for a competent agent.

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 with 100% coverage, including the propertyType enum and the fields array with path/value semantics. The description reinforces the general purpose but adds no parameter-level detail, so the schema carries the semantic load.

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 and resource: 'Creates a DRAFT energy-certificate order' and immediately distinguishes it from a placed order, which separates it from create_certificate_order. It also names the key output (resumeUrl), so the agent knows exactly what the tool accomplishes.

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: this tool creates a draft that the user must finish on the website, and it explicitly states 'A draft is NOT a placed order.' It does not name an alternative tool or spell out when to prefer create_certificate_order or update_draft, but the exclusion is clear enough.

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, so the description need not repeat that. It adds a useful behavioral note about providing enum values EXACTLY as they appear, which helps the agent avoid mistakes. However, it does not disclose any other behavioral aspects like response size, formatting, or potential errors. Given the annotation coverage, this is adequate but not rich.

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 zero filler. The main purpose is front-loaded, followed by the caveat about enum values. Every sentence contributes meaning, making it highly concise and well-structured.

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 options tool with one optional parameter and no output schema, the description sufficiently covers what is returned and the key caution about enum exactness. It lacks details on response structure or nested objects, but those are not critical for invoking the tool correctly. The provided information is complete enough for an agent to use it as a lookup.

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% because the property_type parameter has an explicit description ('Zawęź listy wartości do jednego typu nieruchomości'). The description does not add any further parameter-specific context beyond that, so 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?

Description clearly states the tool returns 'opcje zamówienia' (order options) and enumerates the specific categories: property types, paid add-ons (express, paper), supported document types, and key value lists. This is a specific verb+resource with concrete content, fully separating it from siblings like get_property_types or get_form_fields.

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?

Description implies usage by listing the content, but it does not explicitly state when to use this tool versus alternatives such as get_certificate_information or get_pricing. No exclusions or alternative conditions are provided; an agent must infer when to call this instead of other options-retrieval tools.

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?

The annotation readOnlyHint is set to true, and the description describes a read-only operation ('Returns...'). There is no mention of side effects or mutations, and the description does not contradict the annotations. The behavior is fully transparent.

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 concise—two sentences—and covers all essential aspects: what is returned, the input parameter, and the intended usage. No redundant information is included, and the structure is clear and to the point.

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?

Since there is no output schema, the description provides useful context about the response content (paths, types, enum options, optionality) and the usage context (with create/update). It does not specify the exact response structure (e.g., JSON format), but given the read-only nature and the closed-world hint, this is adequate for an agent to understand what to expect.

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 provides a description for the propertyType parameter ('Property type slug') and an enum of three values, so coverage is 100%. The tool description connects the parameter to the purpose by stating 'Returns the full field catalog for a property type,' reinforcing its meaning. However, the description does not elaborate on the enum values themselves, though they are self-explanatory in context.

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 field catalog for a given property type, specifying exactly what is included (dot-separated paths, types, enum options, optionality). It also explicitly mentions the intended use with create_draft/update_draft, making the purpose unambiguous and distinct from sibling tools that focus on drafts, certificates, or property types themselves.

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 direct guidance: 'Use these exact paths and options with create_draft/update_draft.' This tells the agent when to call this tool (before creating or updating a draft) and how to apply the results. It is explicit and leaves no ambiguity about the tool's role in the workflow.

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 declare readOnlyHint=true, so the safety profile is covered. The description adds that the price is 'server-computed' and in PLN, which clarifies that the tool performs authoritative calculation and returns a gross price. It doesn't detail response structure, but with readOnlyHint covering the main behavioral concern, this is solid.

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 core purpose is front-loaded, and the usage directive is a single clear sentence. Every word 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 read-only pricing tool with one required parameter and a clear directive, the description is nearly complete. It doesn't describe the return value shape, but there is no output schema and the tool's purpose implies a price result. The addons object could use a bit more explanation, but the overall context is sufficient 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?

Schema description coverage is only 33% (only propertyType has a description), so the description must compensate. The description names the three parameter groups (property type, add-ons, discount code) and clarifies that the price is gross and in PLN, but it doesn't explain the addons object fields or the discountCode format beyond what the schema shows. This is adequate but not fully compensating.

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 ('get'), a resource ('server-computed gross price in PLN'), and the scope ('for a property type with optional add-ons and an optional discount code'). It also explicitly distinguishes itself from manual computation, which helps an agent understand its unique role among 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 explicitly says 'Always use this instead of computing prices yourself,' which is a clear directive on when to use this tool. It also implies the tool is the authoritative pricing source, and the sibling list contains no other pricing tool, so no alternative routing is needed.

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?

The description states what data is returned (property types, base prices in PLN gross, paid add-ons) and implies a read-only operation, consistent with the readOnlyHint annotation. It does not describe the exact response structure, but given no output schema is provided, this summary is adequate. No side effects are mentioned, which is consistent with readOnlyHint true.

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, focused sentence that delivers both the functionality and the usage recommendation. It is concise, well-structured, and avoids unnecessary words or repetition.

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 tool with no parameters and no output schema, the description provides sufficient context: it explains what is returned (3 property types with prices and add-ons) and when to call it (first if property type not specified). There are no missing critical details that would prevent an agent from using 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 description correctly omits any parameter details. Both the schema and description agree there are no inputs, receiving the baseline score of 4 for parameter semantics.

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 'Lists the 3 supported property types with base prices (PLN, gross) and available paid add-ons.' This is specific and informative. However, a sibling tool named 'get_property_types' exists, and the description does not explicitly differentiate between them, leaving a small ambiguity about when to prefer one over the other.

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 an explicit usage instruction: 'Call this first if the user has not specified the property type.' This gives clear when-to-use guidance. It does not mention when not to use it or how it compares to the similarly named 'get_property_types' sibling, so it could be slightly more comprehensive.

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.

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.