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

Annotations indicate readOnlyHint=false and destructiveHint=false, so the agent knows it modifies state without destruction. The description adds that the document is indexed for advisory retrieval, providing additional context beyond annotations. However, it lacks details on idempotency, side effects, or behavior on duplicates.

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

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

The description is a single, concise sentence with no filler. It is front-loaded with the core action and purpose, earning its place without 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?

Given the tool has 5 parameters, no enumerated values, and an output schema, the description is too brief. It omits essential context such as whether the tool requires an active session, how it handles duplicates, or any constraints on content size. The output schema exists but the description does not hint at return values or error conditions.

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 0%, but the description adds no parameter-level information. Parameter names (title, content, content_type, origin, metadata) give some meaning, but the description does not clarify their roles, defaults, or constraints, leaving a significant gap for the agent.

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

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

The description clearly states the tool stores a local source document and indexes it for advisory retrieval. It uses a specific verb ('Store') and resource ('local source document'), effectively distinguishing it from siblings like ksef_search_source_documents (search) and ksef_extract_invoice_source (extract).

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 on when to use this tool versus alternatives or when not to use it. The description does not mention prerequisites, context, or exclusions, leaving the agent to infer usage based solely on the action described.

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 and idempotentHint, making the tool's safety profile clear. The description adds that it suggests an 'advisory' rate for VAT purposes, which provides some behavioral context but not extensive 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?

The description is a single, front-loaded sentence with no wasted words. However, it is too brief relative to the tool's complexity, especially given the four parameters and zero schema descriptions.

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

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

Despite having an output schema, the description omits input parameter details and usage context. For a 4-parameter tool with 0% schema coverage, this is a significant gap.

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

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

Input schema has 0% description coverage and the tool description provides no parameter explanations. Parameter names (e.g., basis_type) are ambiguous, leaving the agent unable to infer valid inputs or formats.

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

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

Description clearly states that the tool suggests the advisory NBP average rate for a VAT exchange-rate basis date using a specific verb and resource. However, it does not differentiate from sibling tools like ksef_lookup_exchange_rate.

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 on when to use this tool versus alternatives such as ksef_lookup_exchange_rate. The description lacks context for selection criteria.

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, destructiveHint=false, idempotentHint=true, so the safety and idempotency are clear. The description adds 'never mutates drafts,' reinforcing the behavior, and specifies the advisory nature (suggesting candidates and missing facts), which goes beyond annotation metadata.

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?

Single sentence, 10 words, with the main verb 'Suggest' front-loaded. No wasted words. However, the extreme brevity sacrifices useful context that could be structured into a few more sentences without losing conciseness.

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

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

Despite having 13 optional parameters and an output schema, the description is minimalistic. It does not explain the purpose of parameters, the nature of the advisory output, or usage scenarios. The output schema exists but is not leveraged in the description. The tool's complexity demands more contextual 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?

Schema coverage is 0%, and the description provides no information about the 13 parameters. Parameter names alone (e.g., draft_id, transaction_type) are insufficient for agents to understand expected values or semantics. The description entirely fails to compensate for the missing schema descriptions.

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

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

Description clearly states a specific verb ('Suggest') and resource ('advisory VAT treatment candidates and missing facts'). It distinguishes from sibling tools by emphasizing it never mutates drafts, setting it apart from mutation tools like ksef_update_invoice_draft.

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 on when to use this tool vs alternatives. The description does not mention prerequisites, typical scenarios, or provide exclusions. The agent has no context for selecting this tool over other ksef tools.

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

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

The description explicitly states 'require confirmation,' which adds behavioral context beyond the annotations (which only indicate it's not read-only, destructive, idempotent, or open-world). This alerts the agent that user interaction may be needed. However, it does not detail what happens on confirmation or failure.

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

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

The description is a single concise sentence that includes a key behavioral note. No unnecessary words. However, it could be slightly restructured to front-load the main purpose more clearly.

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

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

Despite having an output schema, the description lacks sufficient context for a complex operation with 6 required params. It does not explain the confirmation process, how the draft is modified, error scenarios, or the relationship to source documents. The agent will likely need to consult additional documentation.

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 are 6 required parameters with zero schema description coverage. The description provides no explanation of their meanings, types, or expected formats (e.g., 'field_path' could be a JSON path, 'confidence' might be a 0-1 range). The agent must rely entirely on parameter names, which may be ambiguous.

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 ('attach'), the resource ('source-backed field provenance to a draft'), and a behavioral detail ('require confirmation'). This distinguishes it from sibling tools that handle other aspects of invoice drafts, such as validation or update.

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. It does not mention prerequisites, typical workflow context (e.g., after extraction), or situations where this tool is not appropriate.

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 idempotentHint=true, so the description adds limited behavioral context beyond the specific subject (FA(3) attachments). No contradictions.

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?

Single, well-structured sentence with no wasted words. Front-loaded with key 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?

Given the tool has no parameters and an output schema exists, the description is sufficient. However, it could elaborate on the 'current KSeF context' for clarity.

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?

Tool has zero parameters, so baseline is 4. No parameters to describe.

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

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

The description clearly states the verb 'check' and the resource 'permission' for issuing invoices with FA(3) attachments. It distinguishes this tool from siblings like ksef_validate_fa3_xml by focusing on permission checking.

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 on when to use this tool versus alternatives. It does not specify prerequisites or when not to use it.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, covering safety and idempotency. The description adds the requirement of a 'known KSeF session', which is useful behavioral context beyond annotations. However, it does not detail error handling or multiple reference scenarios.

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

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

The description is a single sentence, making it concise and front-loaded. However, it omits critical parameter information, so the brevity comes at the cost of completeness. It earns a middle score for efficiency without sacrificing the need for more detail.

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

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

Despite an output schema being present, the description does not cover parameter semantics or usage patterns. With four optional parameters potentially requiring specific combinations, the lack of explanation leaves the tool incomplete for effective use. The plain description is insufficient given the 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 0%, yet the description fails to explain the purpose or relationship between the four parameters (session_reference, ksef_reference_number, invoice_reference_number, upo_reference_number). The agent cannot determine which parameter to provide or how they combine, severely hindering correct invocation.

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

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

The description clearly states the tool retrieves an invoice or session UPO for a known KSeF session, using specific verbs and resources. It distinguishes from siblings like ksef_get_invoice by specifying UPO retrieval, though it assumes domain knowledge of what 'UPO' means.

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 no guidance on when to use this tool versus alternatives (e.g., ksef_get_invoice, ksef_session_status). It does not mention prerequisites or scenarios to avoid, leaving the agent without decision support.

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, destructiveHint=false, and idempotentHint=true. The description adds that it uses a local LLM, which is a key behavioral trait. However, it does not disclose potential latency, model availability, or that results may vary, which are relevant for a tool dependent on local inference.

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

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

The description is a single, well-formed sentence of 14 words that efficiently conveys purpose, mechanism, and constraint without 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?

Despite strong annotations, the description omits prerequisites (e.g., source documents must exist), output details (output schema exists but not referenced), and parameter interdependencies. For a tool with 4 parameters and a local LLM dependency, this is insufficient for reliable agent use.

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

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

With 0% schema description coverage, the description must explain parameters but does not mention any. While names like 'source_document_ids' are suggestive, 'draft_id', 'target_fields', and 'max_candidates' lack explanation of their roles and interactions, leaving the agent to guess.

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

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

The description clearly states the tool uses a local LLM to propose source-backed invoice fields without mutating drafts, providing a specific verb (propose) and resource (invoice fields from sources). It distinguishes from siblings by emphasizing non-mutation, though it could explicitly contrast with similar advisory tools like ksef_advise_vat_treatment.

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 proposing fields before mutation but does not explicitly state when to use it over alternatives like ksef_update_invoice_draft or ksef_advise_vat_treatment. Given the sibling list, more guidance on appropriate contexts would be helpful.

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 the tool as read-only, idempotent, and non-destructive. The description adds the specific capability categories but does not disclose additional behavioral traits beyond what annotations provide.

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?

Single sentence containing all necessary information with no redundancy or fluff.

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

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

With zero parameters, existing output schema, and complete annotations, the description is fully adequate for an agent to understand and invoke 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?

No parameters exist and schema coverage is 100%. The description does not need to add param details, baseline for zero params is 4.

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

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

Description clearly states the tool reports categories of capabilities (supported, advisory, unsupported, manual-smoke), distinguishing it from sibling tools that perform specific operations like submitting invoices or validating NIPs.

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 use for capability discovery but does not explicitly state when to use it versus alternatives, nor provides guidance on prerequisites or when not to use it.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint as true, so the safety profile is clear. The description does not add or contradict any behavioral details; it simply states 'Fetch,' which aligns with the read-only nature. No extra context on side effects or return behavior is given, but annotations cover the key aspects.

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

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

The description is a single, front-loaded sentence with no extraneous words. Every part ('Fetch a KSeF invoice by reference number') is essential and directly communicates the core action.

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 tool is simple (two parameters, one required) and has an output schema, so the description provides a minimal viable understanding. However, it lacks parameter details and any context about the reference number's origin or format, which reduce completeness for an agent unfamiliar with the domain.

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 0%, meaning the description provides no explanation of the parameters. The description does not clarify what 'ksef_reference_number' is, what format it requires, or what 'include_xml' does. With two parameters and no elaboration, the agent must infer from names alone, which is insufficient.

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 (Fetch), the resource (KSeF invoice), and the identifier method (by reference number). This is specific and distinct from sibling tools like ksef_list_invoices or ksef_submit_invoice, making the tool's purpose 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?

There is no guidance on when to use this tool versus alternatives, such as ksef_list_invoices for finding invoices or ksef_prepare_invoice for creating. No prerequisites, contexts, or exclusions are mentioned, leaving the agent without decision support.

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, destructiveHint=false, idempotentHint=true. The description adds context about querying metadata but does not disclose pagination behavior, which is inferred from parameters.

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

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

The description is a single short sentence, which is concise, but it lacks structure and could include more information about the parameters without being verbose.

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

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

Given the tool has 5 parameters and an output schema, the description is too minimal. It fails to explain pagination or the nature of the metadata returned, leaving gaps for agent understanding.

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 0%, so description must add meaning. It only mentions 'date range and role' for the three required params but ignores optional pagination params page and page_size.

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

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

The description clearly states the verb 'Query' and the resource 'KSeF invoice metadata' with scope 'date range and role'. It is specific but does not explicitly differentiate from siblings like ksef_get_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 implies usage for querying metadata by date range and role, but does not provide exclusions or mention alternatives such as ksef_get_invoice for single invoices.

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 readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds the source names but does not elaborate on behavior like rate limits, authentication, or data freshness. It does not contradict annotations.

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

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

The description is a single, front-loaded sentence with no redundancy. Every word adds value, making it highly efficient.

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?

An output schema exists, reducing the need to describe return values. However, given the complexity of multiple data sources, the description omits details on source priority, fallback behavior, or error conditions, leaving gaps for robust agent usage.

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 0%, and the description does not explain any parameters. While parameter names like identifier_type and identifier_value are somewhat self-explanatory, the description fails to define valid values or formats, leaving the agent to rely solely on the schema names.

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

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

The description clearly states the verb 'look up' and the resource 'advisory counterparty data', and lists specific data sources (MF, VIES, KRS, GUS). This distinguishes it from sibling tools like ksef_lookup_exchange_rate and ksef_validate_nip.

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 explicit guidance on when to use this tool vs alternatives, nor any prerequisites or exclusions. The description merely states the sources, leaving the agent to infer usage context without clear direction.

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

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

Annotations already declare read-only and idempotent. The description adds meaningful context: the data is 'advisory' and 'requires basis confirmation', which warns the agent about reliability. This goes beyond annotations.

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

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

The description is extremely concise—one sentence with a semicolon separating purpose and behavioral note. No redundant words; each part adds value.

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

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

Despite rich annotations and output schema, the description lacks critical parameter format details. Without this, the agent may misuse the tool (e.g., wrong date format). Behavioral notes are helpful but incomplete for safe usage.

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 0%, so description must compensate. It does not explain currency format (e.g., ISO code), target_date format (e.g., YYYY-MM-DD), or table options (e.g., A, B, C). Parameter names give some hint, but insufficient for correct invocation.

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

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

The description clearly states the tool fetches official NBP exchange-rate data, which distinguishes it from sibling tools focused on invoices and VAT. The verb 'fetch' and resource 'exchange-rate data' are specific.

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 on when to use this tool versus alternatives. The phrase 'advisory and requires basis confirmation' is about behavior, not usage context. No exclusions or alternatives are mentioned.

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 no behavioral details, but the description adds key traits: it builds/validates without sending and refuses to operate until TEST readiness passes. This goes beyond annotations, though it could clarify what 'TEST readiness' entails.

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

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

The description is a single, front-loaded sentence with no wasted words. It is very concise, though it sacrifices parameter detail. For structure, it earns a high score for efficiency.

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

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

With one parameter and an output schema, the description covers the main purpose and a critical behavioral constraint. However, it omits any detail about the parameter or what the output contains, leaving gaps that the output schema alone may not fill.

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 only parameter (draft_id) is not described; the schema has 0% description coverage and the description adds nothing about it. No guidance is given on its meaning, format, or how to obtain it.

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

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

The description clearly states the tool builds and validates invoice XML without sending it, which is a specific verb and resource. It distinguishes from siblings like ksef_submit_invoice (sends) and ksef_validate_invoice_draft (pure validation) by emphasizing the build step and refusal behavior.

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 should be used after creating a draft and before submission, but it does not explicitly mention alternatives or when not to use it. The sibling list provides context but the description lacks explicit 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?

Description only states it renders a locally. With annotations having all hints false, the description does not disclose side effects, whether it modifies the XML, or file handling behavior (e.g., overwriting). Minimal behavioral information beyond the action.

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?

Single sentence of 16 words, highly concise with the core information front-loaded. No unnecessary text.

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?

Description is insufficient given 4 parameters, 1 required, and available output schema. It does not explain prerequisites (e.g., confirmation_token from ksef_prepare_invoice) or output format. Context about the workflow 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 0%, and the description does not explain any parameter meaning or usage. The description adds no value beyond the schema's parameter names and types.

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

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

Description clearly states the verb 'Render', the resource 'local KSeF-like PDF', and the key distinction 'from prepared FA(3) XML without sending to KSeF', effectively distinguishing from sibling tools like ksef_submit_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 phrase 'without sending to KSeF' implies when not to use this tool, but it does not explicitly name alternative tools or provide direct usage guidance. It lacks clear when-to-use and when-not-to-use compared to siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that matches are advisory provenance only, which goes beyond annotations by clarifying the non-authoritative nature of results. No contradictions.

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

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

The description is a single, front-loaded sentence of 10 words, with no redundancy or extraneous information. Every word contributes to the core purpose.

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 search tool with 3 parameters and an output schema, the description is minimal. It adequately states the action and result nature, but lacks details like search scope or mode implications. The output schema likely covers return values, so completeness is adequate but not thorough.

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

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

With 0% schema description coverage, the description should compensate by explaining parameter meaning. It does not mention query, limit, or search_mode at all, leaving the agent to infer from schema titles alone.

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 it searches local source documents and that matches are advisory provenance only, which distinguishes it from sibling tools like add_source_document. However, it does not elaborate on what constitutes a source document, leaving some ambiguity.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives (e.g., ksef_extract_invoice_source). It only states the verb and resource, without context on when not to use it or which sibling to prefer.

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 indicate read-only, non-destructive, idempotent, and not open world. The description adds value by explicitly stating it reports 'without exposing secrets,' which is not conveyed by annotations alone.

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

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

A single sentence of 11 words that is front-loaded with the main action. Every word earns its place; no redundancy or fluff.

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 no parameters and the presence of an output schema, the description is fully sufficient. It explains what is reported (environment and auth state) and what is avoided (exposing secrets).

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

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

The tool has zero parameters, so schema coverage is 100%. Per guidelines, baseline is 4. The description does not need to add parameter information since none exist.

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

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

The description clearly states the tool reports 'configured KSeF environment and auth state without exposing secrets.' It uses a specific verb ('report') and resource ('environment and auth state'), distinguishing it from sibling tools that handle invoices, documents, or other 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 implies the tool is for checking environment and auth state, but does not explicitly tell when to use it or when to avoid it. No alternatives are mentioned, though the tool's uniqueness among siblings makes its purpose relatively clear.

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

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

Annotations are all false, so they do not convey behavioral traits (e.g., readOnlyHint=false implies mutation but not destructive; idempotentHint=false suggests need for caution). The description merely says 'Create' without detailing side effects, authorization needs, rate limits, or data persistence behavior. With no annotation support, the description fails to adequately disclose behavioral characteristics.

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

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

The description is a single, no-filler sentence that immediately conveys the tool's function and output. It is concise and front-loaded. However, it could slightly improve with minimal structural optimization (e.g., separating main action from output with a period, not a comma).

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

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

Given the two parameters with no schema descriptions, the description is minimally complete: it states creation and a checklist return. But it does not clarify whether the draft is persisted locally, requires an active session, or how the seed object influences the draft. The existence of an output schema is known from context signals, but the description doesn't leverage that to reduce the burden. Still, it provides a basic functional outline.

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 0%, and the description adds no explanation for the two parameters ('seed', 'source_document_ids'). The parameter names are vaguely self-documenting at best, leaving the AI agent without guidance on their format, purpose, or relationship to the missing-field checklist. This is a critical gap.

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

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

The description explicitly states the core action ('Create an invoice draft') and the unique output ('return the missing-field checklist'), distinguishing it from other invoice tools in the sibling list like ksef_prepare_invoice, ksef_update_invoice_draft, or ksef_submit_invoice. The verb 'Create' clearly indicates a new draft being initiated.

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 no guidance on when to use this tool versus alternatives (e.g., whether to start a fresh draft or use update_invoice_draft). It does not mention prerequisites (e.g., required session or authorization), nor does it exclude scenarios where other tools would be more appropriate. Without such context, an AI agent may misuse 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?

Annotations already flag destructive and idempotent. Description reinforces with 'irreversibly' and adds 'legally binding' context. No contradictions. Adequately discloses key behavioral traits beyond annotations.

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

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

Two sentences, no fluff, front-loaded with purpose. Every sentence earns its place.

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

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

With one parameter, annotations covering destructive/idempotent, and existence of output schema, the description covers purpose, prerequisite, and irreversibility. Lacks failure mode details but adequate for simple 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?

Single parameter 'confirmation_token' has 0% schema description coverage. Description explains its purpose (from ksef_prepare_invoice) but not format or constraints. Provides minimal but useful context connecting to sibling tool.

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?

Explicitly states it 'irreversibly issues a legally binding invoice to KSeF', giving a specific verb and resource. Distinguishes from siblings like ksef_prepare_invoice by noting prerequisite token.

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?

Clearly states prerequisite ('Requires a confirmation_token from ksef_prepare_invoice'), implying the tool is used after preparation. No explicit when-not-to-use, but context is sufficient for typical workflow.

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

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

Description claims 'persist readiness' which implies a state change, contradicting the readOnlyHint=true annotation. This is a serious inconsistency. No additional behavioral traits disclosed beyond annotations.

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

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

Single sentence is concise and front-loaded, but lacks essential detail. The description is too brief to be fully informative, though it avoids verbosity.

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

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

Despite having output schema and annotations, the description is incomplete. It fails to explain the tool's behavior beyond a vague authentication/persist claim, and contradicts annotations. Missing clarity on what 'persist readiness' means.

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 has one optional boolean parameter 'use_real_nip_ack' with 0% description coverage. The description does not explain its meaning or effect, providing no value 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?

Description clearly states the verb 'Authenticate' and resource 'KSeF TEST' with purpose 'persist readiness before invoice XML generation'. It distinguishes from siblings which focus on other operations like submitting or validating invoices.

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 explicit guidance on when to use this tool versus alternatives like ksef_session_status or ksef_get_capabilities. Only implies usage before invoice generation but lacks comparative 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?

The description provides minimal behavioral information beyond 'update'. It does not disclose idempotency, side effects of confirmations, or whether patch is a partial or full update. Annotations (readOnlyHint=false, destructiveHint=false) are not contradicted, but the description adds little 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 a single sentence that starts with the verb 'Update', making it concise and front-loaded. However, it omits essential details, so conciseness slightly compromises completeness.

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

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

Given the tool has three parameters, nested objects, and an output schema, the description is inadequate. It does not explain how patch works, what confirmations are for, or how this differs from other draft-related tools. Significant gaps remain.

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

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

With 0% schema description coverage, the description must clarify parameter meaning. It mentions 'facts or confirmations' but does not explain how 'facts' map to the patch object or the role of confirmations (a map of booleans). This adds minimal value 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 tool updates an invoice draft with user-provided facts or confirmations. It specifies the verb and resource, but does not differentiate it from sibling tools like ksef_prepare_invoice or ksef_validate_invoice_draft.

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 on when to use this tool versus alternatives such as ksef_start_invoice_draft or ksef_submit_invoice. The description lacks any context about prerequisites or workflows.

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 destructiveHint=false, so the agent knows it's a safe read operation. The description adds that validation is against an XSD, but does not elaborate on error handling, performance, or other behavioral traits. Some value added beyond annotations.

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

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

The description is a single sentence, efficiently front-loading the core purpose. No wasted words, but could incorporate more detail without harming conciseness.

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

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

Given the tool has an output schema and annotations, the description still lacks information on validation results, error types, or how to interpret outputs. For a validation tool, this is insufficient for complete understanding.

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 0%, so the description must compensate. However, it only mentions the XML parameter implicitly, without describing expected format, constraints, or examples. The input schema provides no additional description, leaving the agent with minimal guidance.

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

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

The description clearly states the tool validates FA(3) XML against the vendored official XSD, specifying the resource (FA(3) XML) and action (validate). This differentiates it from sibling tools like ksef_validate_invoice_draft and ksef_validate_nip.

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 no guidance on when to use this tool versus alternatives. It omits context such as prerequisites, typical scenarios, or comparisons with other validation tools.

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

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

Annotations already declare readOnly, non-destructive, idempotent behavior. Description adds no further behavioral context (e.g., what 'completeness' checks entail, prerequisites).

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?

Single sentence, no wasted words, front-loaded with key action and resource.

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 1-parameter tool with output schema and annotations, the description is adequate but omits what the output represents and any prerequisites or error conditions.

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

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

With 0% schema description coverage, the description should explain the 'draft_id' parameter meaning. It only repeats the tool name's implication, offering no additional semantic detail.

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 explicitly states verb (validate), resource (invoice draft completeness), and context (before XML preparation), distinguishing it from sibling tools like ksef_validate_fa3_xml which focus on XML validation.

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?

Implies usage before XML preparation but gives no explicit when-to-use or when-not-to-use guidance, nor alternatives among siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds 'Validate a Polish NIP checksum,' which confirms read-only behavior but provides no additional behavioral traits beyond annotations. No contradiction.

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

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

The description is a single sentence, concise and front-loaded with purpose. It efficiently conveys the core action without extraneous words, though it could benefit from slightly more detail without losing conciseness.

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

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

Given the tool has one parameter, rich annotations, and an output schema (not shown), the description is adequate but minimal. It correctly identifies the action but does not elaborate on return values or edge cases. The output schema covers return expectations, so the description is sufficient but not thorough.

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 0% for the 'nip' parameter. The description does not explain the parameter's format, length, or expected value. Despite the tool name hinting at NIP, the description fails to add meaning beyond the raw schema, leaving ambiguity for the AI agent.

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

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

The description clearly states the tool validates a Polish NIP checksum, with a specific verb (validate) and resource (NIP checksum). It differentiates from sibling validation tools like ksef_validate_fa3_xml or ksef_validate_invoice_draft by focusing on NIP.

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 for validating a NIP checksum, but does not explicitly state when to use this tool over siblings or provide context like input format or validation scope. No exclusions or alternatives are mentioned.

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