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

The annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context beyond that: the PDF can be saved locally or returned inline, and language selection affects the document. This clarifies the local side effect while remaining consistent with the read-only hint.

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 front-loads the action and resource, then adds the two most important behavioral options. Every clause earns its place without redundant filler or schema repetition.

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

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

For a single-resource download operation with four well-documented parameters, the description covers the core behavior and output modes sufficiently. Since there is no output schema, a brief note on return values is present via 'save it locally (or return it inline)', which is adequate; error handling or prerequisites are not essential here.

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 fully documented in the input schema. The description's mention of Bulgarian/English and inline vs. local save restates what the 'language' and 'delivery' parameter descriptions already provide, adding no new 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?

The description uses a specific verb ('Download') and resource ('PDF of an invoice'), and adds scope with Bulgarian/English language support and two output modes (save locally or return inline). This clearly differentiates it from sibling tools like nula_search_invoices and nula_lookup_company, which operate on search/lookup rather than file retrieval.

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 tool's purpose immediately clear: retrieve an invoice PDF. It does not explicitly state exclusions or alternatives, but none are needed because no sibling tool offers PDF retrieval; the closest siblings are for searching or listing invoices, so the usage context is unambiguous.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=false, covering the read-only safety profile. The description adds that the tool returns account IDs, which is useful behavior context, but it does not disclose pagination, ordering, or the effect of all_companies. Given the annotation coverage, this is adequate but not rich.

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

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

A single sentence that front-loads the action, names the resource, and states the purpose with zero filler. 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 simple read-only list tool with one optional parameter and no output schema, the description covers the purpose, scope, and downstream use. It does not explicitly mention that accounts are scoped to the current company context, but the all_companies parameter hints at that, so it is sufficiently complete.

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

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

Schema description coverage is 100%, so the all_companies parameter is fully documented in the input schema. The description does not add anything about this parameter, but the schema carries the meaning. 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 verb ('List') and resource ('bank accounts connected in nula.bg') and further clarifies the output's purpose ('with their ids for nula_list_bank_transactions'). This clearly distinguishes it from sibling tools that handle invoices, bills, or other resources.

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 links this tool to nula_list_bank_transactions by stating the IDs are intended for that downstream tool. This gives the agent a concrete trigger: invoke this tool when bank account IDs are needed for listing transactions. It effectively names the alternative and the condition for use.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safe, non-destructive nature is covered. The description adds useful context that the operation is scoped to one account and can be time-bounded. It does not discuss pagination behavior or how omitted date filters are handled, but those are partially visible in the schema.

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, front-loaded with the core action and scope, no filler. The cross-reference to nula_list_bank_accounts is directly useful and 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?

The tool is read-only and simple, and the key prerequisite for the required parameter is provided. However, the lack of an output schema means the description could have mentioned the return shape, and the phrasing 'for a period' may mislead an agent into thinking date filters are mandatory when the schema marks them optional.

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 describes page, limit, and bank_account_id, and provides date format patterns. The description adds meaning to bank_account_id by identifying it as an internal id obtainable from nula_list_bank_accounts, and 'for a period' maps loosely to date_from/date_to. It does not clarify that the date parameters are optional, leaving some semantic ambiguity.

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?

Clearly states the operation ('List bank transactions'), scopes it to a single account and a period, and distinguishes it from nula_list_bank_accounts (accounts vs transactions) and nula_match_bank_transactions (list vs match). The Bulgarian gloss reinforces meaning without adding noise.

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 valuable prerequisite: get account ids from nula_list_bank_accounts. However, it does not explicitly state when to prefer this tool over alternatives like nula_match_bank_transactions, nor does it describe scenarios where this tool should not be used. The usage context is implied rather than directly stated.

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 a meaningful behavioral detail: empty categories are excluded. This goes beyond the structured annotations and helps set expectations about the result set.

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

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

The description is a single, focused sentence that front-loads the core purpose and adds the key filtering condition without extra wording. Including the Bulgarian equivalent is a minor addition but does not hurt clarity.

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 listing tool with optional pagination and no output schema, the description captures the essential selection and inclusion behavior. It could mention pagination defaults or result format, but those are less critical given the schema constraints and annotations.

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 description does not explain the pagination parameters, and the schema only documents 'page', not 'per_page'. However, both parameter names are reasonably self-explanatory and the constraints (min, max) provide additional guidance, so the gap is moderate rather than severe.

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 ('List') and resource ('item categories'), and adds a meaningful constraint: only categories with at least one item are returned. It is unambiguous, though it does not explicitly distinguish itself from sibling tools.

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

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

The inclusion criterion 'that have at least one item' implies when this tool is useful, but there is no explicit guidance on when to prefer it over alternatives like nula_search_items or nula_lookup_company. The usage context is inferable rather than directly stated.

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 readOnlyHint=true already declared, the description doesn't need to restate safety. It adds useful context: the lookup happens via external sources ('Commercial Register / VIES') and warns 'Never invent an EIK', which is a behavioral constraint. However, it omits details like potential multiple results for name searches or error behavior, which would be relevant for an agent. The description is adequate but not rich.

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

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

The description is two sentences, each earning its place: the first states the core capability, the second adds critical usage guidance. It is front-loaded with the verb and resource, and no filler or redundancy exists. The warning 'Never invent an EIK' is a valuable addition in the same sentence.

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

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

The tool has no output schema, so the description should clarify what is returned. It states 'get the exact legal name and VAT number', but doesn't specify the response structure or whether name searches may return multiple matches. The tool is simple with all optional parameters, but the lack of return-type information leaves the agent guessing about the result shape. While not severely incomplete, it's a noticeable 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?

The schema already provides full descriptions for all three parameters (coverage 100%), including patterns and examples. The description only says you can look up by EIK, VAT, or name, which mirrors the schema without adding new semantics. Since the schema already carries the burden, a baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Look up') and the resource ('a company by Bulgarian EIK, EU VAT number or name via nula.bg'). The purpose is unambiguous and clearly distinct from sibling tools like invoice/bill management or customer search. The added usage context (before creating an invoice) further disambiguates its role.

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

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

The description explicitly states when to use this tool: 'Use it BEFORE creating an invoice or bill for a counterparty you have not seen'. This provides clear contextual guidance. However, it does not mention alternatives (e.g., nula_search_customers) or explicitly state when not to use it, so it stops short of a full when/when-not contrast.

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 goes beyond the readOnlyHint annotation by clarifying that no changes are made and by specifying the exact follow-up action (using another tool after user consent). This adds valuable behavioral context without contradicting 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 efficient sentences front-load the primary purpose and include the key constraint (non-destructive) and a distinct follow-up action. No fluff 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 suggestion tool, the description covers the core behavior and follow-up, but does not describe return format or any edge cases. Given the tool's low complexity and the presence of annotations, this is reasonably complete, though mentioning the output (a list of suggested matches) would be a minor addition.

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

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

Schema coverage is only 33% (only bank_account_id has a description). The description does not explain the date_from and date_to parameters or how they relate to the matching logic. It mentions matching criteria but not the role of each parameter, leaving gaps that the schema doesn't fill.

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

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

The description clearly states the tool's function: suggesting matches between bank transactions and unpaid invoices, with specific matching criteria (amount, invoice number, customer name/EIK). It distinguishes itself from purely search or update tools by being a suggestion-only 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?

It explicitly says 'Only suggestions: nothing is changed' and instructs to use nula_update_invoice_metadata after user agreement, giving clear when-to-use and follow-up guidance. It does not explicitly name alternative tools for when not to use, but the instruction to not modify data is implicit differentiation.

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

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

Annotations already mark the operation as read-only, and the description adds useful behavioral context: results are ordered newest first, single-document retrieval returns recognised lines, and the remaining OCR quota is included. This goes beyond the annotations without contradicting them.

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

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

Two compact sentences cover the main listing behavior, the single-document mode with its required parameters, and the quota reporting. Information is front-loaded and nothing 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?

With no output schema, the description appropriately names key return concepts: recognition status, document lines, and OCR quota. Given the schema's coverage of parameters and the read-only annotation, the description is sufficiently complete for an agent to know what this tool returns and when to call it.

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

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

Schema coverage is high at 83%, so the schema documents most parameters such as limit, since, id, and include_quota. The description reinforces the id/document_type pairing and the quota flag but does not add meaning for status or limit beyond the schema, keeping it at the baseline.

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

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

The description names a specific verb and resource ('List documents sent to OCR'), states the sorting ('newest first'), and defines the second mode ('get one recognised document with its lines'). It leaves no ambiguity about what the tool does and is clearly distinct from the sibling tools, none of which cover OCR.

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 conditional: use the listing mode by default, or provide 'document_type and id' to fetch a single recognised document with lines. It does not explicitly name alternatives or exclusions, but the sibling context shows no overlapping OCR tool, and the two-mode instruction is enough for an agent to choose correctly.

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 include readOnlyHint=true and openWorldHint=false, so the description doesn't need to explain that operations are read-only. The description adds critical context by explicitly stating that the summary is 'indicative only' and NOT the official VAT return, which is valuable for setting expectations. However, it doesn't disclose other behavioral traits like performance characteristics or whether it covers partial periods, which might be relevant. No contradiction with annotations.

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

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

The description is concise, front-loaded with the core purpose, and includes a clear limitation. It does not waste words or restate the title. The structure is effective for quick comprehension.

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 a simple output, no output schema, and readOnly annotation, the description covers the main purpose and an important limitation (not official VAT return). However, it leaves ambiguity about how to specify a custom period (via date_from/date_to) and what happens if neither month nor dates are provided. The tool is moderately complex with 3 optional parameters, and the description could be more explicit about parameter interactions and output contents.

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

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

Schema description coverage is only 33%, with only the 'month' parameter described. The description mentions 'month or period' but doesn't clarify how to specify a period (e.g., using date_from and date_to) or whether both are required together. It adds some context beyond the schema but doesn't fully compensate for the low coverage on the two date 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 clearly states that the tool provides a summary of sales and purchases for a month or period, including counts, totals, VAT, and top customers/suppliers. It distinguishes itself from sibling tools like nula_search_invoices or nula_receivables_report by focusing on aggregation rather than individual records. However, it does not explicitly differentiate from potential summary siblings, but given the list, it stands out as the only summary tool.

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

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

The description implies usage for monthly/period summaries but does not explicitly state when to use this over alternatives. It doesn't say 'use when you need aggregated totals' or direct the agent to other tools for detailed data. The mention of 'indicative only' hints at limitations but not at alternative tools. This leaves some inference to the agent.

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

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

Annotations already declare readOnlyHint=true, so the description's 'Read-only' is redundant but not contradictory. The description adds useful behavioral context: it groups by customer, provides aging buckets with specific day ranges, and is as-of a date. It does not disclose pagination or output format, but for a read-only report tool with no output schema, the description covers the key behavior. No contradiction with annotations.

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

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

The description is a single, dense sentence that front-loads the core purpose, includes the aging-bucket detail, and ends with 'Read-only.' Every word earns its place; no filler or repetition.

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

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

For a read-only report tool with 4 optional parameters and no output schema, the description is nearly complete. It explains the report's content, grouping, and aging buckets. It could mention that the output is a list/table and whether it includes totals, but the absence of an output schema makes that a minor gap. The read-only annotation covers safety, so the description doesn't need to repeat it.

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 75%, so the schema documents most parameters. The description adds meaning by explaining the report's structure (aging buckets, grouping by customer), which helps an agent understand how parameters like min_days_overdue and date_from affect the output. It doesn't detail every parameter, but the schema already covers them. A 4 is justified because the description complements the schema well.

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

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

The description states a specific verb ('Unpaid and overdue sales invoices... as of a date'), a clear resource (receivables/overdue invoices), and a distinctive grouping/aging-bucket structure. It also includes Bulgarian terms for disambiguation and explicitly says 'Read-only', which distinguishes it from mutation tools. It is clearly differentiated from siblings like nula_search_invoices (which searches invoices) and nula_period_summary (which summarizes periods).

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 when to use it: when you need receivables/aging as of a date, grouped by customer. It does not explicitly name alternatives or exclusions, but the context signals and sibling list make the use case clear. A 4 is appropriate because the context is clear but there is no explicit 'use this instead of X' guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: passing bill_id returns a single bill in full with its lines, while the normal search filters by period, supplier, or number. It does not detail pagination or result shape, but those are partially handled by the schema.

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

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

Two short sentences carry all essential information, starting with the tool's main function and then the special bill_id behavior. There is no filler, no repetition of the title, and no unnecessary 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?

For a read-only search tool with no required parameters, the description plus schema covers the main invocation paths: list search by period/supplier/number and single-bill retrieval by bill_id. Minor gaps remain around how response_format=detailed interacts with bill_id and the lack of output-shape or error notes, but these are not blocking for correct selection and 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 schema documents page, limit, number, bill_id, and response_format; the description supplies semantic grouping for the five undocumented parameters: date_from/date_to as 'period', supplier_eik/supplier_name/supplier_vat_number as 'supplier', and 'number'. This adds real meaning beyond the raw schema, though it stops short of explaining exact-match vs partial-match behavior.

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 ('Find') and a clear resource ('purchase documents'), reinforced with Bulgarian equivalents, and explicitly names the search dimensions: period, supplier, and number. It also explains the bill_id path for fetching one bill in full with lines, distinguishing this from sales-invoice siblings like nula_search_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?

The description makes the tool's context clear: this is the purchase-bill search tool, and the bill_id mode is stated. However, it never names an alternative such as nula_search_invoices or says when not to use this tool, so the agent must infer the boundary from the word 'purchase'. No exclusions or alternative routing are provided.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds meaningful behavioral context: it explains that nula.bg has no direct customer-creation API and that nula_create_invoice auto-creates missing customers. This helps an agent understand the system's behavior beyond the schema. It doesn't mention pagination or response details, but those are partially covered by the schema's page/limit/response_format 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?

Two sentences with no filler. The core search capability is front-loaded, and the note about nula_create_invoice is a valuable addition that earns its place. Every sentence contributes.

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 100% schema coverage and no output schema, the description is nearly complete. It covers what the tool does, the search keys, and the key system constraint (no direct customer creation). The only minor gap is that it doesn't explicitly mention pagination behavior, but the schema's page/limit parameters already cover 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%, so the schema already documents all five parameters. The description adds a little semantic value by grouping the search parameter as 'Name, EIK or VAT number' and mentioning 'get one by id', but it doesn't add meaning 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 verb ('Find') and resource ('customers/counterparties'), and enumerates the search keys: name, EIK, VAT number, or id. It also distinguishes itself from the sibling create-invoice flow by noting that nula.bg has no direct customer-creation API, which helps an agent understand the tool's role in the broader workflow.

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 when to use this tool: when you need to find a customer by name, EIK, VAT, or id. It also gives a useful exclusion/alternative note: nula_create_invoice creates a missing customer automatically, so an agent knows not to expect a create-customer tool. It doesn't explicitly say 'use this instead of nula_lookup_company', but the search-by-EIK/VAT framing is enough 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 declare readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds meaningful behavioral context beyond annotations: the default exclusion of proformas when document_type is absent, and the full-document behavior when `number` is supplied.

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 earning their place. The main action and scope are front-loaded, followed by the two most important behavioral caveats. No filler or repetition of obvious type 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 read-only search tool with no required parameters and no output schema, the description provides enough orientation: search facets, the number shortcut, and the proforma default. Output expectations are largely covered by the response_format parameter schema, so the definition is complete 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?

With schema description coverage around 60%, the description only partially compensates. It reiterates the `number` behavior already present in the schema and adds the proforma-default nuance for document_type. The generic mention of "customer" gives little semantic value for the three undocumented customer-related 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?

Description opens with a specific verb and resource: "Find sales documents", enumerates the document types in Bulgarian, and lists search dimensions (period, customer, type, number). This clearly distinguishes the tool from sales-oriented siblings like nula_search_bills and nula_get_invoice_pdf.

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, actionable usage context: passing `number` returns a full document with lines, and omitting `document_type` excludes proformas. It does not explicitly name sibling alternatives or when-not-to-use conditions, but the sales scope plus parameter guidance makes invocation conditions clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the read-only nature is known. The description adds useful behavior context: it returns price/stock data, supports exact SKU matching, and name-based matching. 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?

Two sentences with no filler. The core action and result are front-loaded, and the usage guidance is compact. The parenthetical Bulgarian terms add clarity for the target domain without bloating the description.

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 6 optional parameters, the description covers the key behavioral expectations: what is searched, what is returned, and when to call it. Pagination and response_format are already documented in the schema. Without an output schema, a more explicit statement of returned fields would push this to a 5.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds value by clarifying the relationship between sku and query/name: 'Give sku for an exact match, or query/name to match the name.' This goes beyond the raw field descriptions.

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

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

The description starts with a specific verb and resource: 'Find products/services (артикули) with prices and available stock (наличност).' It clearly identifies the domain (items/stock) and differentiates this from sibling tools like nula_search_invoices or nula_search_customers.

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

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

The description explicitly tells the agent when to use it: 'Use it before invoicing to reuse the correct item name, sku and price.' It also gives guidance on how to search: exact sku versus query/name. It stops short of naming excluded alternatives or when not to use it, 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.