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

With no annotations, the description carries the burden and discloses the key behavior: it validates active status, expiry, and hash, then makes the invoice ready to send. It does not mention error behavior or idempotency, but the core state-changing behavior is 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?

Three short sentences with no filler: action, validation logic, and consequence. All sentences contribute and the main verb is front-loaded.

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 one-parameter confirmation action, the description covers purpose, validation criteria, and the resulting state. It does not specify exact return values or error handling, but the low complexity and clear postcondition make it adequate.

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 single parameter approvalId is fully documented in the schema as 'ID approval request (UUID)' with 100% coverage. The description adds no parameter-level details, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the exact action (confirm an approval request), the target resource (approval), and the postcondition (invoice ready to send). It is clearly distinct from the sibling ksef_approval_request, which creates the request.

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 the sequencing context: request approval first, then confirm it, then send the invoice. It does not explicitly exclude alternatives or state when not to use it, but with only one approval-related sibling the use case 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?

With no annotations provided, the description carries the full behavioral disclosure burden. It does a good job by revealing the 15-minute expiry, the blocked-draft prerequisite, and the KSEF_APPROVAL_MODE=auto behavior. It does not mention error cases or side effects, but for a simple single-parameter tool this is meaningful transparency.

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 sentences with no filler. The core purpose is front-loaded, and each sentence adds distinct useful information: prerequisite, confirmation requirement, expiry, and auto-mode behavior.

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 one-parameter tool with no output schema, the description covers the purpose, prerequisite, expiry, and mode-dependent behavior. It does not specify what the response contains or how to pass it to ksef_approval_confirm, but the workflow is clear enough for an agent to invoke it correctly in most cases.

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 provides 100% coverage for the only parameter, id, with a clear description ('ID zablokowanego draftu (UUID)'). 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 clearly states the action ('Utwórz żądanie zatwierdzenia') and the specific resource ('zablokowanego draftu'), and it is naturally distinguished from the sibling tool ksef_approval_confirm, which handles confirmation rather than creation. The purpose is 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?

The description explains where this step fits in the workflow: approval must be confirmed before sending an invoice to KSeF, and it expires after 15 minutes. It also notes the auto-approval mode. However, it does not explicitly name alternative tools or state when not to use this tool.

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 signals a safe read operation. The description adds valuable behavioral context beyond that: the log contains all operation types and NIPs are SHA-256 hashed for security. 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 concise sentences: the first states the action and resource, the second adds scope and a security-relevant detail. Every sentence earns its place with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a simple read-only list operation with one optional parameter, and the description communicates the purpose, log scope, and NIP hashing. There is no output schema, so a bit more detail about returned entry fields could help, but it is adequate 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 coverage is 100%, and the only parameter, limit, is already fully described with its default and maximum. The description adds no additional parameter meaning, so the baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Wyświetl' — display) and resource ('wpisy z logu audytowego' — audit log entries), and further clarifies the log covers creating drafts, approvals, and shipments. No sibling tool targets the audit log, so it is clearly distinguished.

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 the tool is for viewing recent audit trail activity across operations, but it does not explicitly state when to use it versus alternatives or mention any exclusions. No sibling audit-log tool exists, so the lack of explicit routing is a minor gap.

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 only include readOnlyHint=false, which signals mutation. The description goes beyond that by revealing the multi-step OAuth-like flow and the final output (JWT access + refresh), giving the agent a clear picture of side effects: it will initiate network calls and create a session state. This is meaningful behavioral context beyond the annotation.

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, front-loads the core verb and resource, then gives the exact flow in a short chain. Every sentence is useful and no filler exists. The flow notation is concise and scannable for an agent.

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 session-initiation tool with 3 self-describing optional parameters and no output schema, the description adequately covers the main behavior, flow, and input sources. It does not mention error cases, token validation, or session timeout behavior, but those are not essential for selecting and 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?

The input schema covers 100% of parameters with descriptions and defaults, including the environment enum. The tool description adds the general concept that parameters can come from env vars, but it does not add detailed semantics beyond the schema. Per calibration, baseline 3 is appropriate when schema coverage is high.

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: 'Rozpocznij sesję KSeF' (start a KSeF session) using an authorization token, and explicitly mentions API v2. It distinguishes the action from sibling tools like ksef_auth_status or ksef_auth_terminate by naming the session-starting flow, though it does not directly name a sibling for contrast.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies this is the entry-point tool for starting a KSeF session and outlines the sequential flow (challenge → ksef-token → token/redeem → JWT). It gives context about when to use it, and the alternative options of passing arguments or env vars. It does not explicitly state when not to use it or name alternatives, but the flow structure provides solid usage 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 readOnlyHint annotation already communicates that this is a safe read operation. The description adds a bit of behavioral context by listing what the status check covers (activity, tokens, validity), but it does not describe return structure, error cases, or what happens when no session is active. This is acceptable 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?

A single, front-loaded sentence conveys the tool's purpose and the key check dimensions with no wasted words. It is appropriately concise for a parameterless status-check tool.

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 zero-parameter read-only tool, the description provides enough context: it names the resource and the main output dimensions (active, tokens, validity). Since there is no output schema, slightly more detail about the returned shape would improve completeness, but the current level is sufficient for basic 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?

The tool has zero parameters, so there is nothing for the description to document beyond confirming no inputs are required. The baseline of 4 applies because no parameter semantics are 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 uses a specific verb ('Sprawdź') and resource ('status aktywnej sesji KSeF'), and it clarifies what aspects are checked: activity, tokens, and validity. This clearly distinguishes the tool from auth lifecycle siblings like ksef_auth_init and ksef_auth_terminate.

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 makes the context clear: use this to check the status of the active KSeF session. It does not explicitly state when not to use it or name alternatives, but the single clear purpose provides adequate 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 annotations already signal a destructive mutation with readOnlyHint=false and destructiveHint=true. The description adds useful specificity beyond that: it invalidates the refresh token and explicitly warns that the operation is irreversible.

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, direct sentences with no filler. The core action is front-loaded and the irreversible warning is prominently stated without unnecessary explanation.

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 zero-parameter, destructive authentication tool with no output schema, the description covers the action, the object being invalidated, and the irreversibility. It could mention what happens after termination, but the low complexity makes the current description reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the schema is empty with 100% coverage, so no parameter documentation is needed. The description correctly omits parameter details because there is nothing to clarify.

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 ('Zakończ aktywną sesję KSeF') and the specific mechanism ('unieważnij refresh token'). It is precise about what the tool does, though it does not explicitly contrast itself with the overlapping-looking sibling ksef_token_revoke.

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 like ksef_auth_init, ksef_auth_status, or ksef_token_revoke. It states what the tool does but offers no context about when it is appropriate or what conditions should hold before invoking 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 destructiveHint annotation already signals that this operation is destructively finalizing. The description adds the useful context that an active KSeF session is required and that it should happen after all parts are sent. However, it does not explain consequences such as no further parts being accepted after closing, so it only partially supplements the annotation.

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, purposeful sentences with no filler: action, timing, and prerequisite. The essential information is front-loaded and every word contributes to the agent's ability to invoke 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?

For a single-parameter destructive operation with annotations and no output schema, the description is fairly complete: it names the action, the required reference parameter is covered by the schema, and it specifies both the timing and prerequisite. The main omission is an explicit statement of irreversibility or post-close behavior, but the destructiveHint partially covers that.

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 describes referenceNumber as 'Numer referencyjny sesji batch'. The description adds no additional detail about the parameter's format, origin, or how to obtain it, but the schema carries the parameter-meaning burden adequately.

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 states a specific action ('Zamknij' — close) on a specific resource ('sesję batch') and gives the sequencing condition 'po wysłaniu wszystkich części'. It is distinguishable from sibling operations like ksef_batch_open, ksef_batch_send_part, and ksef_batch_status, though it does not explicitly name an alternative 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?

Provides clear usage context: the tool should be used after all batch parts have been sent, and it requires an active KSeF session. It does not explicitly list alternatives or exclusion cases, but the sequencing and prerequisite give an agent enough guidance for when to invoke 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It explains that the tool opens a batch session, requires an active KSeF session, and returns a reference number plus pre-signed upload URLs. It stops short of describing lifecycle consequences, such as whether a session must later be closed or what happens if a session is already open.

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 compact single sentence that conveys purpose, prerequisite, inputs, and outputs without redundancy. Key information is front-loaded, and no sentence is wasted.

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 essential details needed to call the tool correctly: the action, the prerequisite of an active KSeF session, the required input categories, and the key return values. It does not mention the follow-up step of uploading parts via ksef_batch_send_part or finalizing with ksef_batch_close, but the returned pre-signed URLs strongly imply the next action.

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 detailed per-parameter descriptions in the schema. The description adds a useful summary of the expected inputs ('Podaj rozmiar pliku, hash i listę części') but does not add substantive detail beyond what the schema already contains, 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 and resource: 'Otwórz sesję batch do wysyłania wielu faktur jednocześnie (API v2)'. This clearly distinguishes the tool from batch_send_part, batch_close, and batch_status by indicating it starts a batch upload session.

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 a clear condition for use: sending multiple invoices simultaneously, and states a concrete prerequisite: an active KSeF session is required. It does not explicitly name alternatives or say when not to use this tool, but the purpose is specific enough that an agent can infer the situation.

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 provide destructiveHint=true, so the safety profile is covered. The description adds prerequisite context about the active KSeF session and open batch session, which is useful beyond the annotation, but it does not disclose other behavioral details such as idempotency, failure semantics, or side effects of uploading a part.

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?

A single Polish sentence conveys the action, the object, the source of the URL, and the prerequisites with no wasted words. The key identifying information is front-loaded.

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 captures the essential prerequisites and source of the upload URL, but the tool has 6 parameters, nested objects, and no output schema. It does not clarify the full batch workflow sequence (e.g., that this must happen between ksef_batch_open and ksef_batch_close, or that uploadHeaders typically come from partUploadRequests), so an agent may still need to infer important operational details.

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 baseline is 3. The description adds value by clarifying that uploadUrl must come from ksef_batch_open and that the request concerns a single part of a batch, which helps an agent understand how referenceNumber, ordinalNumber, and uploadUrl interrelate. It does not explain uploadMethod or uploadHeaders, but those are already well documented in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Wyślij') with a specific resource ('część paczki') and destination ('pre-signed URL'), and explicitly ties the URL to a sibling tool (ksef_batch_open). This clearly distinguishes it from batch management siblings like ksef_batch_open, ksef_batch_close, and ksef_batch_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear contextual prerequisites: an active KSeF session and an open batch session, and it references ksef_batch_open as the source of the upload URL. It implies the correct position in the batch lifecycle, though it does not explicitly state when not to use the tool or name alternatives.

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 safety profile is covered. The description adds one useful behavioral constraint (requires an active KSeF session) but gives no detail on response shape, possible statuses, or error conditions; with annotation coverage this is acceptable.

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?

A single front-loaded sentence, with the main action first and the prerequisite second. 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 one-parameter, read-only status check, purpose, parameter, and prerequisite are all present. The lack of an output schema is partly mitigated by the simple, self-explanatory nature of a status query, though possible status values are not documented.

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 covers the only parameter 100% with the same reference-number semantics, so the description doesn't add anything new. Baseline 3 is appropriate because the schema does the work.

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 the specific verb 'Sprawdź' (check) and identifies the resource as a batch/online KSeF session, which separates it from invoice/auth status tools in the sibling list. It is clear but does not explicitly name a sibling alternative, so stops short of full differentiation.

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?

States a concrete prerequisite: an active KSeF session is required. This tells the agent not to call it before authorization/session setup, but it doesn't spell out when this tool should be preferred over ksef_invoice_status or ksef_auth_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?

No annotations are provided, so the description carries the burden of explaining behavior. It discloses the key side effect: a new draft is created with the original's data, status 'draft', and a link to the original. It does not describe failure modes or confirm the original remains unchanged, but the main mutation is 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?

Two concise, front-loaded sentences. The action and precondition come first, and there is no filler or redundant restatement of the tool name.

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 creation tool with no output schema, this is nearly complete: it states the precondition, the input semantics, and the resulting side effect. It could optionally mention what the response returns or what happens when the original lacks ksefReferenceNumber, but the description is sufficient for selecting and invoking the tool.

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 baseline is 3. The description reinforces that originalDraftId must reference a KSeF-sent invoice, but it does not add significant new semantic detail beyond what the schema already provides for the two parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a specific verb, 'Utwórz korektę', and names a precise resource: an existing draft that has already been sent to KSeF. It clearly distinguishes itself from related tools like ksef_draft_create by stating it copies original data and links the correction to the original, making its scope 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?

The description gives an explicit precondition: the original invoice must be sent to KSeF and have a ksefReferenceNumber. This is clear, actionable context, but it does not explicitly discuss when to prefer this tool over ksef_correction_zero or other drafting tools, so it stops short of full alternative routing.

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?

No annotations are provided, so the description carries the burden. It discloses the mutation's key side effect (all item quantities are set to zero) and the prerequisite condition (no local draft of the original). It does not cover output or post-creation submission behavior, but the most safety-critical facts are present.

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, all informative: the action, the zeroing behavior, and the draft prerequisite. No filler, and the core verb-object is front-loaded.

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 15 parameters, nested items, and no output schema, the description is adequate for selecting and roughly calling the tool but leaves gaps: it does not say what the tool returns, whether it sends a correction to KSeF immediately or creates/stages it, or how the KSeF data should be supplied. The schema covers parameters, but operational context is thin.

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 parameters are already documented individually. The description adds context that the items list represents original positions and that quantity values will be zeroed, but it does not explain individual parameter mechanics 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?

Description uses a specific verb and object: 'Utwórz korektę zerującą' plus the concrete behavior 'Zeruje wszystkie pozycje (ilość → 0)'. This clearly distinguishes it from the generic ksef_correction_create sibling and tells an agent exactly what the tool produces.

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 states when it applies: corrections based on KSeF invoice data, and explicitly notes that no local draft of the original is required. It does not name an alternative tool or give an explicit when-not-to-use condition, so it stops 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?

With no annotations, the description carries the behavioral burden. It clearly discloses that the draft is saved locally, that it is not sent to KSeF yet, that it can be edited later, and that amounts are calculated automatically. This gives the agent useful non-obvious behavior without listing prerequisites or response details.

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, each adding meaningful information: what is created, where it is stored, and what auto-calculation happens. The description is front-loaded with the primary purpose 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 create operation with no output schema and no annotations, the description covers the core invocation context: local persistence, editability before validation/submission, and automatic amount cals. It does not describe the return value or draft identifier, but the schema provides all required parameter semantics and the workflow is understandable.

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 covers 100% of the parameters with descriptions, so the baseline is 3. The description adds no per-parameter detail, though it does note that net/VAT/gross amounts are computed automatically, which relates to how item values are interpreted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a precise verb and object: 'Utwórz nowy draft faktury' (create a new invoice draft). It further distinguishes this from sending or updating by stating the draft is stored locally and can be edited before validation and sending to KSeF.

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 a draft-first workflow by noting the draft can be edited before validation and KSeF submission, but it does not explicitly state when to choose this tool over siblings like ksef_draft_update, ksef_draft_validate, or ksef_send_invoice. Usage context is present but only implicitly.

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 provide destructiveHint=true, so the description does not need to restate destructiveness. It adds useful context by restricting deletion to draft/error statuses, but does not disclose other behavioral traits such as irreversibility, permission requirements, or side effects.

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, purposeful sentences with no filler. The verb and resource come first, and the important status restriction is clearly front-loaded.

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?

This is a simple one-parameter delete operation with a destructive annotation and a stated status constraint. The description provides everything essential for an agent to invoke it correctly, and no output schema exists to require return-value explanation.

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 already covers the sole 'id' parameter fully with 'ID draftu (UUID)', so schema coverage is 100%. The description adds no additional parameter-level 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 uses a specific verb ('Usuń' = delete) and resource ('draft faktury' = invoice draft), clearly indicating the operation. It also adds the draft/error status constraint, which helps distinguish this tool from sibling draft operations like ksef_draft_get, ksef_draft_update, and ksef_draft_validate.

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 states the explicit precondition: 'Można usunąć tylko drafty w statusie draft lub error' (only drafts in draft or error status can be deleted). This tells the agent when deletion is allowed, though it does not explicitly mention alternatives or when not to use the tool.

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 communicates that this is a safe read operation. The description adds useful behavioral context by stating that the response includes full draft data with calculated amounts, which matters because no output schema is provided. It does not contradict 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?

Two short sentences with no filler. The main operation is front-loaded, and the return-value note is placed second. 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 one-parameter get-by-ID tool, the description is largely complete: the parameter is clear from the schema, the safety profile is covered by annotations, and the description tells the agent what kind of data is returned. Exact response fields are unspecified, but the 'full data with calculated amounts' phrasing provides sufficient orientation.

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 fully covers the only parameter with type 'string' and description 'ID draftu (UUID)', so the description does not need to add much. The phrase 'po ID' adds no new semantic detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Pobierz') with a clear resource ('draft faktury') and lookup mode ('po ID'). It is easily distinguished from list/create/update/delete operations, though it does not explicitly compare itself to ksef_draft_render_xml or ksef_invoice_get.

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 usage when you have a draft ID and need full draft data, but it gives no explicit guidance about when to prefer this over ksef_draft_list, ksef_draft_render_xml, or ksef_invoice_get. No exclusions or alternatives are named.

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 indicates this operation is read-only, and the description is consistent with that by using 'Wyświetl' (display). It adds useful behavioral context that the list includes all drafts and status filtering is optional, which aligns with the annotation and clarifies the scope of the operation.

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 concise two-sentence Polish definition with no redundant wording. It front-loads the main purpose and then mentions the optional filter, which is efficient for a simple list tool.

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 operation with one optional parameter and no output schema, the description is adequate: it communicates the operation, the resource, and the filter. It does not detail pagination, ordering, or response details, but these are less critical for a straightforward list tool and no output schema is present to contradict.

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 the 'status' parameter with a full enum and a description, so schema coverage is 100%. The description only adds the fact that filtering is optional, which is a minor clarification; the parameter's meaning is already well-defined in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Wyświetl listę') and resource ('wszystkich draftów faktur'), making clear that this tool lists invoice drafts. It mentions optional filtering by status, which helps distinguish it from other draft-related tools, though it doesn't explicitly name a sibling alternative.

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 a list/query use case through 'Wyświetl listę' and notes the sole optional filter, giving the agent a sense of when to use it. However, it does not explicitly state when not to use it or point to an alternative like ksef_draft_get for fetching a single draft.

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?

With no annotations provided, the description carries the full behavioral burden and does disclose important side effects: rendering XML, calculating SHA-256, setting status to 'locked', and preventing subsequent editing. It does not cover failure modes or permission requirements, but the core mutation behavior is 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?

Three short sentences deliver the purpose, the concrete effects, the required precondition, and the irreversible consequence with no filler or repetition. The main action is front-loaded, making the tool's role immediately clear.

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 one-parameter state-changing tool with no output schema, the description covers purpose, behavior, prerequisite, and postcondition. It is adequate for an agent to call correctly, though details like error handling or return value would make it fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is only one parameter, id, and the schema already describes it as 'ID draftu (UUID)', giving 100% schema description coverage. The description does not add parameter-specific detail beyond what the schema already provides, so the baseline score 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 action and resource ('Zablokuj draft do wysłania') and then names concrete outcomes: rendering XML, computing a SHA-256 hash, and setting status to 'locked'. This clearly distinguishes it from sibling tools like ksef_draft_validate and ksef_draft_render_xml.

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 states the required precondition ('Draft musi być wcześniej zwalidowany (ksef_draft_validate)') and a key consequence ('Po zablokowaniu nie można go edytować'). This gives clear context for when to invoke it, though it does not explicitly mention alternatives to avoid.

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 set readOnlyHint=true, and the description reinforces this by clarifying that the tool only renders XML and does not send to KSeF. This adds meaningful behavioral context beyond the annotation, though it does not discuss authentication requirements or output structure.

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, each earning its place: the main action, the explicit non-behavior, and the prerequisite. The key information is front-loaded and there is no redundant 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 simple single-parameter tool, the description covers purpose, output format, side-effect exclusion, and a required precondition. No output schema exists, but the description already tells the agent that the result is an XML preview in FA(3) format, so nothing critical 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?

Schema description coverage is 100%, with the single 'id' parameter already documented as a draft UUID. The description adds no extra parameter-level meaning, which is acceptable given the schema fully describes the parameter and there is only one.

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 uses a specific verb ('Wygeneruj podgląd XML'), names the exact resource ('draftu') and format ('FA(3)'), and differentiates itself from sending to KSeF. This clearly distinguishes it from siblings like ksef_draft_validate, ksef_draft_get, and ksef_send_invoice.

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 what the tool does not do ('Nie wysyła do KSeF') and names a required precondition ('Draft powinien być wcześniej zwalidowany') with the relevant sibling tool. It does not explicitly enumerate alternative tools for sending or retrieving XML, but the guidance is sufficiently 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?

With no annotations provided, the description carries the full burden and it discloses three key behaviors beyond the name: patch semantics, automatic amount recalculation ('Przelicza kwoty automatycznie'), and the locked/sent immutability constraint. It does not state what happens if a locked/sent edit is attempted (error vs silent ignore) nor whether omitted fields keep their values, which is the remaining gap.

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: first states action and patch semantics, second lists editable scope plus the recalculation side-effect, third flags the constraint. The verb 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 flat 12-parameter patch tool with one required field, no output schema, and no annotations, the description covers the decisions an agent needs to call it correctly: partial update, editable fields, auto-recalc, and the immutable locked/sent states. Minor omissions – response format and the concrete error behavior for locked/sent drafts – do not block 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?

The schema documents all 12 parameters at 100% coverage, so the baseline is 3. The description adds only aggregate context – which field groups are editable and the recalculation side-effect on items – which is useful but does not supplement per-parameter detail beyond what the schema already provides.

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 states a specific verb+resource: 'Zaktualizuj draft faktury (patch)' – update (patch) the invoice draft – and enumerates the editable field groups (seller/buyer data, number, dates, items). This clearly distinguishes it from siblings like ksef_draft_create, ksef_draft_delete, and ksef_draft_get, and the '(patch)' qualifier signals partial-update semantics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear context: this is the tool for partial modifications of an existing draft ('Można zmienić dowolne pola') and imposes an explicit exclusion ('Nie można edytować locked/sent'), preventing misuse on locked or sent drafts. It stops short of naming alternatives or remedies (e.g., using ksef_draft_lock to manege lock state or ksef_draft_validate before updating), so a 5 is not warranted.

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?

No annotations are present, so the description carries the full burden. It explicitly discloses the key side effect: if validation passes, the status changes to 'validated'. It also lists the validation scope, but it does not describe the failure path or what is returned when validation fails.

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 efficient: a purpose clause, a compact list of checks, and a conditional outcome. Every sentence earns its place and no information is wasted.

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 input side is complete with one documented parameter, and the success side effect is stated. However, with no output schema, the description omits what the tool returns on failure or whether a validation report is produced, and it does not connect validation to the approval/send workflow.

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 already fully describes the single 'id' parameter as a UUID draft identifier, and schema description coverage is 100%. The tool description does not add further semantic detail about the parameter, so the baseline score of 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 opens with 'Zwaliduj draft faktury wg reguł FA(3)', a specific verb and resource, and then enumerates the exact validation checks (NIP checksum, required fields, dates, VAT rates, amount consistency). This clearly distinguishes it from sibling draft operations like get, create, update, lock, or render_xml.

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?

No guidance is given about when to call this tool versus siblings such as ksef_approval_request or ksef_send_invoice, nor about prerequisites like the draft existing or not being locked. The intended position in the draft lifecycle is only implied by the validation semantics.

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 valuable behavior beyond that: it reveals that NIP is masked, session status is included, and no login is needed. This is useful auth-context information not 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?

A single sentence that front-loads the purpose and appends the key usage caveat ('Nie wymaga logowania'). No filler or redundancy; 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 zero-parameter, read-only information tool, the description is complete: it states what is shown, that it is safe to call, and under what authentication condition. No output schema exists, but the three listed result items are sufficient for an agent to know 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 tool has zero parameters and the input schema is empty with 100% description coverage, so there is no parameter meaning for the description to add. The baseline of 4 for a parameterless tool applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Pokaż' — show) and resource (current KSeF environment) plus the concrete information returned: masked NIP and session status. It is clearly distinguishable from the sibling ksef_env_set, which is about changing the environment.

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 a clear usage context: it does not require login, so the agent knows this can be called before or without authentication. It does not explicitly name alternatives or when-not-to-use, but no sibling tool is a true alternative for this simple environment-info read.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose a meaningful trait: the change happens 'w runtime' and requires no restart. However, it does not state side effects such as whether switching environments invalidates the current token or affects subsequent KSeF calls, nor whether the change persists.

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 the main action front-loaded and the no-restart benefit stated immediately. There is no filler, no repetition of schema details, 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 configuration setter with three parameters and no output schema, the description states the purpose, the mutable settings, and the key runtime benefit. It is slightly incomplete only in not warning about side effects like token validity or global impact on subsequent calls, but the schema covers parameter details and the tool is low-complexity.

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 each parameter already has its own description. The tool description merely restates the parameter names and their optionality, adding no semantic detail beyond what the schema provides. Baseline 3 is appropriate because the schema handles parameter documentation.

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, 'Zmień' (change), and identifies the exact resource: KSeF environment, NIP, or token. It clearly distinguishes this configuration-mutation tool from sibling read/invoice/token tools by naming what it mutates. The second sentence reinforces the intended use case of switching between production and test environments.

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: use this tool to switch KSeF environment, NIP, or token at runtime without restarting. It does not explicitly name alternatives or exclusions, though a sibling like ksef_env_info exists for reading current environment state. This is clear context but lacks explicit when-not-to-use guidance.

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

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

Annotations already mark this as readOnlyHint=true, and the description adds genuinely useful behavior: it requires an active session and returns the full invoice XML. It does not disclose not-found or error behavior, but for a simple read operation with annotation coverage this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no unnecessary words. The main action and prerequisite are front-loaded, and every sentence contributes meaningful 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 single-parameter read-only tool with no output schema, the description covers the key context: what is returned, the identifier used, and the session requirement. It would be more complete if it distinguished itself from ksef_invoice_xml or described error behavior, but it is not deficient given the low complexity.

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 ksefNumber parameter is already documented. The description refers to retrieving by KSeF number but adds no additional format, validation, or usage nuance beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Pobierz') and the resource ('fakturę XML po numerze KSeF'), and specifies the return value. However, it does not differentiate itself from the similarly named sibling 'ksef_invoice_xml', leaving ambiguity about which tool should be preferred for the same apparent operation.

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 only usage guidance is the prerequisite that an active session is required. There is no mention of when to use this tool versus alternatives such as ksef_invoice_status or ksef_invoice_xml, nor any exclusions or fallback context.

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 this as readOnlyHint=true, and the description reinforces a non-mutating search behavior. The description adds useful context beyond annotations by stating that an active KSeF session is required and listing the metadata returned. It does not mention pagination despite the continuationToken parameter, but this is a minor gap given the read-only and schema-covered nature of the tool.

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, information-dense sentences. The core purpose is front-loaded, followed by the session prerequisite and the returned metadata. No filler or redundant restatement of the tool name.

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 search tool with full schema coverage, the description covers the essential usage context: what it searches, the needed session, and what it returns. It falls short of being fully complete by not mentioning pagination or the continuation token, but the schema makes these recoverable and the tool is otherwise well-specified.

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 description does not need to explain each parameter. It does add the overall date-range concept and return metadata, but it adds no deeper meaning about dateType, pageSize, subjectType, or continuationToken beyond what the schema already provides. 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 ('Wyszukaj faktury w KSeF' - search invoices in KSeF), a clear scope (date range), and the result type (metadata such as KSeF number, NIP, amount, date). This clearly separates it from invoice retrieval/status siblings that focus on a single invoice.

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 an explicit prerequisite ('Wymaga aktywnej sesji (ksef_auth_init)'), which is critical for correct usage. It does not explicitly name alternatives or say when not to use this tool, but the context of searching by date and returning metadata is clear enough to guide selection among the many ksef_invoice_* siblings.

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

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

The readOnlyHint annotation already signals a safe read operation, and the description adds the prerequisite of an active session. It does not disclose return behavior, possible statuses, or polling semantics, but the annotation lowers the burden and no contradiction is present.

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 deliver the purpose and prerequisites with no fluff. The main action 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 two-parameter read-only status check, the description adequately covers what the tool does, what prerequisites apply, and which references are needed. The lack of an output schema or status-value enumeration is a minor gap since the invocation requirements are fully specified.

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%, with both parameters clearly described as session reference number and invoice reference number. The description restates these in prose but adds no extra guidance about their format, origin, or relationship.

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 resource: checking the invoice processing status within a KSeF session. It is clear and matches the tool's name, though it does not explicitly differentiate itself from sibling status tools like ksef_batch_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a useful precondition: an active session is required, and it names the two reference numbers needed. However, it does not explicitly state when to prefer this tool over alternatives such as ksef_invoice_get, ksef_invoices_query, or ksef_batch_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?

The readOnlyHint annotation already indicates a safe read operation. The description adds meaningful behavior beyond that: it clarifies the required active session, the FA(3) format, and the alias relationship to ksef_invoice_get. No contradiction with annotations exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three short sentences with no filler. The core action is front-loaded, the alias relationship is stated, and the session requirement is included. Every sentence 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 single-parameter read-only tool, the description covers the key resource, the lookup key, the XML format, the alias relationship, and the session prerequisite. It does not describe error cases or response structure, but the tool name and description already convey that the result is invoice XML, and no output schema exists to elaborate further.

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 describes the sole parameter as 'Numer KSeF faktury' with 100% coverage. The description mentions 'po numerze KSeF', which aligns with the schema but adds no additional constraints, formatting, or disambiguation beyond what the schema provides.

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 ('Pobierz XML faktury'), a specific resource (invoice XML from KSeF), the lookup key (KSeF number), and the format (FA(3)). It also explicitly identifies itself as an alias for ksef_invoice_get, which removes ambiguity 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 gives useful context about requiring an active session and notes that it is an alias for ksef_invoice_get, but it does not explicitly explain when to choose this tool over related alternatives such as ksef_invoices_query or ksef_draft_render_xml. Usage is implied rather than fully guided.

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?

destructiveHint=true already flags the side-effecting nature, and the description adds value beyond it by disclosing the encryption pipeline (AES-256-CBC + RSA-OAEP), the state gating (locked/approved/hash match), and the fact that it submits to the external KSeF API. No contradiction with the annotation; the only missing behavior is post-send effects on the draft.

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, front-loaded with the primary action, followed by gating requirements and then the technical encryption detail. Every sentence carries load-bearing information with zero 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 complex, destructive external API call, the description covers the two most critical gaps: workflow prerequisites and transport encryption. What remains unsaid is post-send behavior (response contents, whether the draft becomes consumed/irreversible), but with a single well-documented parameter and a destructiveHint annotation, the remaining gap is small.

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 draftId parameter is self-documenting as a UUID, so the baseline of 3 applies. The description adds marginal meaning by constraining which draftId is valid (must be locked and approved), but does not explain return values or side effects on the draft after sending.

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: 'Wyślij zablokowaną i zatwierdzoną fakturę do KSeF' (send a locked and approved invoice to KSeF). It is clearly distinguishable from the 28 siblings: it is the terminal send action in the draft lifecycle, distinct from ksef_draft_* (preparation), ksef_approval_* (gating), and ksef_invoices_query/get/status (read-only lookups).

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 enumerates the conditions required before invocation: an active KSeF session, the draft in 'locked' status, and a confirmed approval with matching XML hash. This strongly implies the orchestration order (lock → approve → send) without naming sibling alternatives explicitly, so it earns a 4 rather than 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly discloses that the response is a reference number, not the token secret, that secrets are never exposed, and that the token arrives through a separate KSeF channel. It could additionally mention permission requirements or side effects, but the security-relevant behavior is well covered.

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, purposeful sentences with the action front-loaded. Every clause contributes necessary information: what the tool does, the session prerequisite, the return behavior, and the security constraint. There is no filler or redundancy.

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 generation tool with no output schema, the description adequately covers the return semantics, the prerequisite, and the critical security caveat. It is nearly complete, though it could be slightly stronger with an explicit pointer to ksef_token_get for retrieving the actual token value.

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 provides 100% descriptive coverage for both parameters: 'description' is explained as an identifier and 'permissions' as the token's permission list. The tool description adds no extra parameter-level meaning beyond what the schema provides, so the baseline score of 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 opens with 'Wygeneruj nowy token KSeF', a specific verb plus resource that immediately identifies the action. It is clearly distinguishable from sibling token tools such as ksef_token_list, ksef_token_get, and ksef_token_revoke because it is the only generate operation.

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 a key precondition: 'Wymaga aktywnej sesji KSeF', giving the agent clear context for when this tool can be invoked. It does not explicitly name alternatives or say when not to use it, but the warning that it returns a reference number rather than the token value implicitly routes value-retrieval needs toward ksef_token_get.

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 only mark readOnlyHint=true, so the description adds meaningful behavioral context: it requires an active session and explicitly states that it returns metadata and never the token value. This is valuable because it prevents misuse of a token-related tool.

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, each earning its place: the operation, the prerequisite, and the critical return-value distinction. No filler or redundant restatement of the tool name.

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, the description covers the essential invocation context: active session, output behavior, and safety guarantee. There is no output schema, but 'returns metadata' gives a useful expectation; specific returned fields would improve completeness but aren't required to call 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 100%: the only parameter, referenceNumber, is already documented as 'Numer referencyjny tokena'. The description adds no extra meaning about the parameter's format, source, or relationship to other token endpoints, so it stays at the baseline for full 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?

Description uses a specific verb and resource: 'Pobierz szczegóły tokena KSeF' — clearly a fetch-details operation. It doesn't explicitly contrast with siblings like ksef_token_list or ksef_token_generate, so the distinction is mostly carried by the name and the word 'details'.

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?

Provides a useful prerequisite: 'Wymaga aktywnej sesji'. However, it does not say when to prefer this over ksef_token_list, ksef_token_generate, or ksef_token_revoke, and it gives no exclusion cases. Usage context is implied rather than explicitly explained.

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 provide readOnlyHint=true, and the description adds meaningful behavioral context beyond that: it requires an active session and explicitly states that it returns only metadata and never token values. This is valuable safety-relevant transparency for an AI agent.

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, information-dense sentences. The main purpose is front-loaded, followed by the key prerequisite and a crucial behavioral warning. No filler or redundancy.

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 operation with two optional, fully documented parameters, the description is adequately complete. It covers the active-session requirement and the metadata-only output. It does not describe the return structure, but no output schema exists and pagination is inferrable from the continuationToken parameter.

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 completely (pageSize with range/default, continuationToken as the pagination continuation token). The description adds no additional parameter-level meaning, so the schema carries the burden and 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 clearly states a specific verb and resource: 'Wyświetl listę tokenów KSeF' (display the list of KSeF tokens). This distinguishes it from sibling tools like ksef_token_generate, ksef_token_get, and ksef_token_revoke, which perform different operations.

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 a clear prerequisite — 'Wymaga aktywnej sesji' (requires an active session) — which helps an agent understand when the call can succeed. However, it does not explicitly state when to use this tool versus alternatives like ksef_token_get, nor does it mention 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?

Beyond the destructiveHint annotation, the description discloses that the operation is irreversible, requires an active session and confirmed approval, and that the token cannot be restored after revocation. This is substantial behavioral context that helps an agent avoid dangerous misuse.

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 sentences with no filler. The action is front-loaded first, followed by the critical warning, prerequisites, and consequence. Every sentence earns its place, including the redundant-sounding final sentence, which reinforces the irreversible nature of the operation.

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 destructive tool with no output schema, the description covers the essential context: what it does, prerequisites, and irreversible consequences. It does not describe the return value, but given the simplicity of the operation and the strong safety warnings, this is a minor gap rather than a serious omission.

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%, with the referenceNumber parameter already documented as 'Numer referencyjny tokena do unieważnienia'. The tool description does not add further parameter-level detail, so it does not exceed the baseline for 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 opens with a specific imperative verb-resource pair, 'Unieważnij token KSeF' (revoke KSeF token), clearly identifying what the tool does. This distinguishes it from sibling token operations like ksef_token_generate, ksef_token_list, and ksef_token_get.

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 states explicit prerequisites for use: an active session and confirmed approval. This gives clear context on when the tool is appropriate, though it does not explicitly name alternatives or state 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 the description adds context by clarifying that UPO confirms system receipt and that an active session is required. It does not contradict annotations, though it does not reveal much beyond prerequisites and the document's purpose.

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. It front-loads the tool's core purpose, adds the UPO definition, and closes with the key prerequisite.

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 download tool with no output schema, the description provides purpose, domain context, and a prerequisite. It does not describe the downloaded file's format, but this is a minor gap given the low complexity and rich parameter schema.

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 explains both parameters. The description adds no additional parameter-level detail beyond the general idea of downloading a UPO for an invoice in a session.

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 and resource: 'Pobierz UPO' (download UPO) for an invoice in a KSeF session, and explains what UPO is. This clearly differentiates the tool from siblings like ksef_invoice_get or ksef_invoice_xml.

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 phrase 'Wymaga aktywnej sesji' gives a useful prerequisite, and the description implies the tool is used after an invoice has been submitted to obtain official receipt confirmation. However, it does not explicitly state when to use this tool over 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.