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

Beyond the readOnlyHint annotation, the description discloses rich behavior: six check categories, possible statuses (ok/warning/error/not_applicable/skipped), explanation and row limits, closingCreatedAt semantics, analyticsRefs mapping, and the caveat that regulatory operation Posted=false is normal. This is substantial context for interpreting results.

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 dense but front-loaded and organized with numbered checks. It is appropriately sized for a complex multi-check tool, though some output-navigation details could be considered lengthy for a single paragraph.

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's complexity, the description is complete: it explains the checks, result statuses, caveats, and reference navigation. An output schema exists, so the description need not explain return values further, and it already provides enough context to call and interpret the tool correctly.

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

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

The schema already covers all three parameters at 100%, so baseline is at least 3. The description adds some interpretive meaning by referring to month-level checks and explaining related output fields, but it does not add parameter-specific guidance beyond what the schema provides.

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

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

The description clearly states a specific verb and resource: it checks month-close accounting via six explicit checks. It distinguishes itself from sibling read tools by focusing exclusively on month-close validation, and the enumerated checks make the scope unmistakable.

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

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

It gives clear context for use: an accountant reviewing the month before reporting and after closing. It also states an important boundary — read-only, cannot close the month through OData — but does not explicitly name alternative tools for related tasks.

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=true, so safety is covered. The description still adds genuine behavioral detail: results are reconciled with the register ("сверено с регистром, consistent") and storno entries arrive as negative amounts in debit/credit — a non-obvious quirk that prevents misreading totals. It says nothing about truncation behavior when the movement count exceeds limit (default 200, max 2000), which matters for a per-movement listing.

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?

Everything is front-loaded: what the card contains, then the filters, then the investigative use cases, with no filler sentences. It is a single dense block rather than separated sections, and the enumerated output fields are somewhat verbose, but each sentence carries information an agent needs.

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 an output schema present and 100% schema description coverage, the description doesn't need to restate return structure, and it wisely spends its budget on filters, accounting quirks, and investigative framing. The only real gap is the phantom documentCreatedAt parameter and the absence of any note on how limit/pagination affects completeness of the card.

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

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

Schema coverage is 100%, so the baseline is 3, and the description does add examples (account as "51", "62.01", "26"; dimensionRef widened to include "документ расчётов"). However it introduces documentCreatedAt, a parameter that does not exist in the input schema — an agent following the description could pass an invalid argument. That defect offsets the added examples and keeps this at baseline rather than above 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 names a concrete artifact (the account card for a period) and enumerates its contents down to the field level: date, document, content, Debit/Credit, corresponding account with analytics, running balance, opening balance, turnovers, closing balance. An agent can tell this is a per-movement ledger extract, distinct from a pure turnover summary. It stops short of naming the sibling it overlaps with (read.accounting.get_account_turnover), so it isn't a 5.

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

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

It gives real investigative framing: "Для разбора: откуда остаток на 26, кто дал красное сальдо, как сложился долг", plus practical advice ("Если остаток сложился до периода — возьмите период шире") and a note that document creation time helps find entries made after month close. What's missing is explicit exclusion — it never says when to prefer get_account_turnover or get_document_postings instead.

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

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

Beyond readOnlyHint and openWorldHint, it discloses the underlying 1C register and virtual table, prefix expansion to every matching subaccount, total-plus-subaccount granularity, expanded balance analytics, and inclusive period boundaries. These are concrete, invocation-visible behaviors rather than repetitions of the safety 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 purpose is front-loaded, followed by precise account, balance-granularity, filtering, and date semantics in a compact block. The accounting and 1C terminology is dense but functional, with no filler or redundant discussion of read-only safety.

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?

Together with the fully described input schema, output schema, and annotations, the description supplies enough detail to construct a correctly scoped call. Its remaining gap is selection guidance: it does not explain how this aggregate report differs from get_account_card or get_balance_origin when an agent is choosing among accounting reads.

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 100% schema description coverage, the baseline is 3. The description adds value by clarifying that account acts as a code prefix selecting all matching subaccounts and that the from/to dates are inclusive, although its examples, organization filter, and YYYY-MM-DD wording largely overlap with 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 precisely identifies the artifact and scope: a turnover-balance report for an accounting account over a period, including opening and closing debit/credit balances and debit/credit movements, totaled and broken down by subaccount. This is much more specific than the title, but it does not explicitly distinguish the report from siblings such as get_account_card or get_balance_origin.

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 references to a standard ОСВ по счёту, subaccount totals, and expanded analytics establish a clear use case for obtaining period-level account balances and movements. There is no explicit when-not guidance or explanation of when another accounting read tool would be preferable.

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/openWorldHint already declaring the safety profile, the description adds substantive behavior: two computation modes (method = documents for 62/60/76 in БП, otherwise method = movements with continuous-holding moment and per-document surviving share) and a bounded lookback of maxYears. It also explains what `since` and `documentCreatedAt` mean, though it says nothing about cost or behavior when no origin documents are found.

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?

Purpose is front-loaded in the first clause, followed by method branching, then return-field meaning, then filters — a logical order with no filler. The semicolon-chained sentences are dense but each clause carries 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 seven-parameter read tool with an output schema, the description covers purpose, mode selection, field meaning, and filtering adequately. Minor gaps remain: no statement of cost when scanning many years back and no explicit fallback to the sibling card/turnover tools.

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 seven parameters. The description adds a little framing (maxYears as a backward search horizon, dimensionRef as contract/nomenclature/bank account), but this largely restates schema text and leaves account, asOf, database, and organization to 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 names a specific operation on a specific resource — the composition/origin of an account balance as of a date — and immediately scopes it ('для старых хвостов, которых не видно в карточке за месяц'), which separates it from read.accounting.get_account_card and read.accounting.get_account_turnover without the agent needing to open schemas.

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

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

It states the use case clearly (old balances invisible in the monthly card) and implicitly names the alternative by describing that card. It does not name the sibling tool explicitly nor state when the tool should NOT be used, so it stops just short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered, but the description adds real behavioral context: inherited settings are not substituted, an empty organization GUID means all organizations in counterparty/group mode, and a missing or incompatible schema blocks the call. That last point in particular is non-obvious operational risk information not present in the structured fields.

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

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

The sentences are dense but front-loaded, leading with what is read and immediately qualifying it with the no-inheritance rule. The final note about the legacy name is useful disambiguation rather than filler, though the reference to a 'scope' field with no matching parameter costs some 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?

With annotations covering safety and an output schema covering return values, the description only needs to explain mode selection and constraints, which it largely does. The remaining gap is that the mode-selection logic is expressed via an abstract 'scope' rather than the actual contractRef-emptiness rule an agent must apply.

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 20% (only 'database' is documented), so the description must carry the load. It does clarify contractRef (omit it for counterparty/group mode) and organizationRef (empty GUID = all organizations), but it gives no guidance on the three settlementKind enum values or on the counterpartyRef vs group distinction beyond the vague 'в том же поле Контрагент_Key'.

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 concrete verb and resource ('Читает точную настройку независимого регистра') and signals that inherited settings are NOT substituted, which implicitly contrasts with the sibling get_settlement_settings. It stops short of explicitly naming that sibling or stating the distinguishing rule outright.

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 explains how the mode is derived (contract vs counterparty/group based on whether a contract is supplied) and that organization and settlement kind are mandatory, which is genuine usage context. However, it frames this around a 'scope' concept that does not exist as a parameter in the schema, and it never explicitly says when to prefer this over read.accounting.get_settlement_settings.

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

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses an important behavioral nuance: dimensionsStatus values distinguish 'confirmed empty' from 'cannot be determined' (not_in_schema/not_returned), which prevents the agent from misreading missing analytics as zero subconto. It also mentions the returned totals and correspondence summary; with an output schema present, the return description is partly redundant, which keeps this from a 5.

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?

It is a single dense paragraph, front-loaded with the resource definition before the field breakdown and parameter hints. Every sentence carries information, though the long run-on construction and repeated 'Только чтение' (already in annotations) cost a bit of tightness.

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 tool with an output schema and full annotation coverage, it covers what the data is, how to obtain the required inputs, how to interpret the ambiguous status flag, and that it works for all document types. Remaining gaps (pagination, database default behavior beyond the schema) are minor.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds the provenance of both required parameters (list_entities with class=document, and search_documents) that the schema itself does not state. It does not explain the optional database parameter, relying on the schema for that.

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

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

The description states a specific verb and resource: postings generated by one document (registrar) from the Хозрасчетный accounting register, broken down into Дт/Кт with account code, name, Ref_Key, subconto, amounts and totals. It also states scope ('Подходит для любого вида документа (Document_*)' and read-only), which separates it from siblings like get_account_card or get_account_turnover that are keyed by account rather than document.

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

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

It gives the concrete prerequisite chain for the required arguments: documentEntity must come from list_entities (class=document) and documentRef from search_documents, and it notes applicability to any document type. It does not name an explicit alternative or state when NOT to use it (e.g. per-account analysis should use get_account_card), so it's a clear context but not a full routing rule.

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

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

Beyond the readOnly/openWorld annotations, it discloses two important behavioral traits: inherited settings are never substituted (so the result is exact, not inherited), and a missing or incompatible schema blocks the operation entirely. It doesn't discuss permissions or side conditions such as default database resolution, which the schema handles separately.

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?

Seven short sentences, front-loaded with purpose and scope rules, with the legacy-name note sensibly placed last. Some sentences are dense with domain jargon (Контрагент_Key, 'независимый регистр') that an agent without 1C context must infer, but nothing is redundant.

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 six-parameter read tool with an output schema, the description covers the non-obvious selection rules, the conditional requirement that the schema cannot express, and the failure mode. The only gaps are the meaning of the database parameter and the settlement-kind enum values, both documented in the schema itself.

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 at 17%, the description carries most of the burden and does so for the critical logic: the conditional contract requirement not expressed by the schema's required list, the shared counterparty field for counterparty/group scopes, and the empty-GUID organization meaning 'all organizations' while the subject stays exact. Settlement-kind enum values and the database parameter are left to 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 opens with a specific verb and resource ('Читает точную настройку независимого регистра') and immediately scopes it by 'scope' values, which lets an agent distinguish it from write.accounting.set_settlement_settings and from the legacy read.accounting.get_contract_settlement_settings, whose narrower behavior is explicitly stated.

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

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

It gives per-scope eligibility rules: contract requires a договор, while counterparty/group use the same Контрагент_Key field without a contract. It also flags the legacy alternative as contract-only. It stops short of an explicit 'use X instead when Y' routing instruction, which keeps it from a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description is not burdened with the safety profile. It goes beyond them by disclosing the aggregation buckets returned (available = 50+51+52, special = 55, inTransit = 57) and the handling of currency accounts (amount in currency), which are non-obvious behaviors an agent would otherwise guess at.

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 definition is front-loaded with the resource and its account breakdown, then the return buckets, then the asOf rule. It is dense but every clause carries information; the only minor redundancy is the asOf explanation, which duplicates the schema property 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?

With an output schema present and full parameter coverage, the description only needs to frame what is counted and how totals are grouped, which it does. The main residual gap is the lack of explicit guidance relative to sibling analytics tools, but nothing required for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the asOf end-of-day semantics (matching the schema wording) but says nothing about the database or organization parameters, so it adds no meaning beyond the structured data.

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 the exact resource (cash and bank account balances), the source register (Хозрасчетный), and enumerates the specific accounts read (50, 51, 52, 55, 57). An agent can distinguish this snapshot-balance tool from flow-oriented siblings like get_cashflow or get_account_turnover without opening the schema.

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

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

The opening phrase 'Сколько денег сейчас' implies a point-in-time snapshot use case, and the asOf sentence clarifies the historical variant. However, there is no explicit statement of when to prefer this over get_cashflow or get_account_turnover, and no exclusions or prerequisites are given, so routing must be inferred.

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=true, so safety is covered. The description adds real value by specifying that only posted documents ('по проведённым') are counted and by listing the three returned aggregates; however it says nothing about currency, per-account breakdown or how unposted drafts are handled.

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?

Four short sentences, front-loaded with what is computed before the filter and date hints. The date-format sentence duplicates the schema and is the only clearly dispensable line.

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 an output schema exists and all four parameters are fully described in the schema, the description need not explain return values in detail. It covers the posted-documents basis and the optional org filter; minor gaps remain around multi-currency and whether results are per-account or consolidated.

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 'from', 'to', 'database' and 'organization' are already documented, including the YYYY-MM-DD format. The description's 'Можно ограничить организацией' and 'Период — даты YYYY-MM-DD' merely restate the schema, earning the baseline 3 rather than more.

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 resource and verb-equivalent: cash inflow and outflow over a period, computed from posted bank and cash documents, returning inflow, outflow and balance. This clearly differs from get_cash_balance (a point-in-time balance) even though no sibling is named explicitly, so it stops short of a 5.

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

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

There is no explicit guidance on when to choose this tool over get_cash_balance, get_payments_breakdown or get_account_turnover, nor any stated prerequisites or exclusions. Only the org filter is mentioned, which is a parameter hint rather than 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?

Beyond readOnlyHint/openWorldHint, it discloses the sign convention that drives the result: credit balance is our debt, debit balance is our prepayment and is netted out, and only positive debt is returned. It does not cover performance characteristics or how large result sets behave, but the domain semantics are unusually well explained.

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?

Front-loaded with the core definition, then parameter guidance in descending importance. The semicolon-chained clauses make it dense and slightly run-on, but nearly every sentence carries distinct information rather than restating the title.

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 seven-parameter read tool with an output schema, the description covers the accounting semantics, filtering behavior, and scope exclusions that structured fields cannot express. The only gap is the phantom olderThanYear reference, which is not backed by the schema and slightly undermines trust in the parameter list.

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

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

Schema coverage is 100%, so baseline is 3, and the description adds real meaning: asOf is defined as the end-of-day balance, aging is spelled out as maturity buckets plus payment dates, and overdueOnly is stated to imply aging. It loses a point for describing olderThanYear, which does not exist in the input schema and could mislead an agent into passing an unsupported argument.

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?

States a precise verb-and-resource: the balance of account 60 (supplier settlements) from the Хозрасчетный accounting register, broken down by counterparty. It also names the boundary case explicitly (account 76 for rent/telecom is not included), which lets an agent separate it from read.accounting.get_account_turnover and the receivables sibling read.analytics.get_debtors.

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?

Gives concrete when-to-use routing for each mode: aging=true for maturity buckets and payment dates, overdueOnly=true for overdue only, and an explicit when-not (account 76 items belong in ОСВ по счёту 76). It even warns that olderThanYear debt is often unsettled netting rather than real liability, which is exactly the interpretive guidance an agent needs.

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 openWorldHint, so the safety profile is covered. The description adds genuine behavioral detail beyond that: results are chronological, they include aggregated totals and a closing balance, and dealKey is matched as a server-side substringof over the payment-purpose text (implying possible partial/false-positive matches). It does not mention result ordering guarantees, truncation at limit, or how the default database is resolved.

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?

Roughly four sentences, front-loaded with what the tool returns before the parameter constraints. Almost every clause earns its place (the dealKey example, the mutual-exclusivity rule, the optional period default). Minor density issue: the dealKey explanation is packed into a parenthetical that takes a second read.

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, so return values need not be described, and the description still summarizes them. The cross-field 'exactly one of' constraint, the optional period default, the default database, and the organization filter scoping are all covered. The only gap is behavior at the limit boundary (default 200, max 1000, truncation), which the schema documents but the description does not acknowledge.

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

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

Schema description coverage is 100%, so the baseline would be 3. The description still adds meaning: it explains what dealKey actually is (a bank identifier appearing in the payment purpose, with a concrete example) and that contractRef is the Ref_Key of a contract obtained via find_counterparty. That is interpretive context beyond the schema's one-line parameter notes.

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+resource: the chronological list of bank and cash movements for one deal or contract, including inflows, outflows, totals and balance. That is far more than a restatement of the name. What it lacks is an explicit contrast with closely related analytics siblings (get_cashflow, get_payments_breakdown, get_document_postings), so an agent still has to infer the boundary.

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

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

It states a hard selection rule that the schema cannot express: exactly one of dealKey or contractRef must be supplied, and the period is optional (all time by default). It also hints that contractRef comes from find_counterparty plus a contract, which routes the agent to a prerequisite tool. There is no explicit when-to-use/when-not-to-use statement against sibling analytics tools, which keeps it from a 5.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantive behavior beyond that: results are filtered to debt > 0, credits are netted out, overdueOnly sorts descending by overdue days and falls back to 60+ day debt when no contract terms exist, and olderThanYear is explicitly flagged as often unclosed settlements rather than real debt. That fallback and caveat context is exactly what an agent needs and is nowhere in the structured fields.

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

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

The purpose and sign convention are front-loaded, then parameter behavior follows in a logical order, with no filler sentences. It is dense and somewhat run-on as a single block, but every clause carries information rather than restating the name.

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

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

With seven optional parameters, an output schema, and only two annotations, the description supplies the missing behavioral context — filtering, sorting, fallbacks, and data-source caveats — so an agent can call it correctly. The remaining gap is the mismatched olderThanYear reference and the absence of any pointer to the sibling payables/reconciliation tools.

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

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

Schema coverage is 100%, so all seven parameters are already documented; the description reinforces the meaning of aging (byAge buckets, contract payment date = document date + contract days) and the defaultTermDays 'don't guess' rule. However it also describes an `olderThanYear` parameter that does not exist in the input schema, which could lead an agent to attempt an invalid argument — a real semantic defect against an otherwise strong 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 names a specific verb and resource — 'кто и сколько должен компании' — and pins the exact data source: сальдо счёта 62 из регистра бухгалтерии Хозрасчетный, сгруппированное по контрагентам. It also states the sign convention (debit = client debt, credit = advances, subtracted), so an agent knows precisely which figure it gets and can distinguish it from the payables sibling get_creditors.

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

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

Usage is clear at the parameter level: asOf for audit/historical reporting, overdueOnly for 'who is late paying', olderThanYear for long-stale balances, aging for term breakdowns. What is missing is tool-level routing — it never says when to prefer this over get_creditors, get_reconciliation, or get_unpaid_invoices, leaving that 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 and openWorldHint=true, so the description's job is to add domain context — and it does: which accounting accounts are the source, that results are aggregated by nomenclature, that quantity and amount are returned, and a useful 1C-specific caveat that BP 3.0 keeps stock on accounting accounts rather than a separate balance register. It does not discuss pagination behavior of limit or result size trade-offs, which keeps it below 5.

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 first sentence front-loads the resource and data source; return values, then the optional filters, then the asOf mode follow in a logical order. The trailing parenthetical about BP 3.0 accounting is useful context but could arguably be trimmed; overall there is little waste.

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 an output schema present, the description needn't explain return shapes, and it still summarizes them (quantity and amount). It covers data source, defaults, one optional filter, and the point-in-time mode, which is sufficient for a zero-required-parameter read tool; only result-size/pagination expectations are left implicit.

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 every parameter is already documented in the schema, including asOf's date format, the organization filter options, database selection and the limit bounds. The description adds a use-case rationale for asOf (inventory/audit) and restates the organization filter, but supplies no syntax or semantics beyond the schema, so the baseline 3 applies.

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

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

The description names the concrete resource (goods/materials balances in warehouses), the data source (balances of accounts 41/10/43 in the Хозрасчетный register) and the grouping (by nomenclature), which lets an agent separate it from siblings like get_account_turnover or get_cash_balance. It stops short of explicitly naming the sibling tools it replaces, so it lands at a clear-but-not-differentiating 4.

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

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

It states the default behavior (current balances) and the condition that selects the alternative mode: asOf=YYYY-MM-DD for inventory counts or audits. It also notes the filter is optional (organization narrows results). No explicit 'use X instead' routing and no prerequisites are given, but the when-to-use context is 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 establish readOnlyHint and openWorldHint, but the description adds genuinely useful non-obvious behavior: counterparty is stored polymorphically in bank documents and that filter is applied in the connector, while cashflow item, purpose, period and organization are filtered server-side in 1C. That explains result differences an agent could otherwise misread. It does not discuss volume limits, performance, or how totals are computed, so it stops short of 5.

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 first sentence front-loads the core operation and grouping, followed by a compact filter inventory and then example questions. It is dense but organized, and the final sentence on connector-vs-server filtering is high-value. The example question list is slightly redundant with the filter enumeration and could be trimmed.

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 an 11-parameter analytical read with an output schema present, the description covers the grouping dimension, the period format, all filter families, and where each filter executes. Return shape is handled by the output schema, so nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents every one of the 11 parameters, including accepted formats (code / name fragment / Ref_Key) and enum meanings. The description's filter list largely restates that, adding only light framing such as the period being YYYY-MM-DD and the grouping options, which the schema also carries. 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 opens with a specific verb and resource: it sums posted bank and cash documents over a period, broken down by a chosen attribute. It enumerates the grouping dimensions (operation/month/counterparty/cashflowItem/total), so an agent knows exactly what the tool produces. It does not name the closest sibling (read.analytics.get_cashflow) or state how it differs, which keeps it from a 5.

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

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

Usage is conveyed indirectly through example questions ('сколько процентов получили за год от такого-то банка', 'приход по месяцам'), which tell the agent the kind of question this answers. There is no explicit when-not guidance and no named alternative such as get_cashflow or get_purchases_breakdown for overlapping money-movement questions, so selection between siblings is left to inference.

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 openWorldHint, so safety is covered. The description adds one genuinely useful behavioral fact, that only 'проведённые' (posted) receipts are counted, but says nothing about ordering of 'top' results, pagination beyond limit, or how totals treat VAT.

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 purpose and breakdown dimensions are front-loaded, followed by filters and example questions. The trailing 'Период — даты YYYY-MM-DD' duplicates the schema pattern and could be dropped, but overall it is tight.

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 an output schema, full parameter coverage, and annotations present, the description covers what the tool aggregates, how it can be grouped and filtered, and typical questions. It leaves the relationship between groupBy and limit (limit = number of groups) and result ordering implicit, which is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including date patterns, enum values, and defaults. The description only restates the date format and the available filter dimensions, adding no meaning 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 states a specific verb and resource: it aggregates posted receipts (purchases) over a period with a breakdown by supplier, month, contract, or total. The word 'закупки'/'поступления' clearly separates it from the sales-analytics sibling tools, though no sibling is named explicitly.

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 concrete example questions ('топ поставщиков за год', 'закупки по месяцам', 'сколько закупили у ИП') and lists the filters that narrow the result. It never states when NOT to use it or which sibling (e.g. get_sales_breakdown, get_payments_breakdown) to pick for a different but similar question.

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=true, so the safety profile is covered. The description adds real behavioral context beyond that: only POSTED (проведённым) sales documents are counted, and the sum is taken on a specific field (СуммаДокумента), which defines exactly what the aggregate includes and excludes. It does not state currency or how period boundaries are treated (inclusive/exclusive), which would be the remaining useful detail.

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

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

Three short sentences with the metric definition front-loaded, followed by the optional filter and the date format constraint. Each sentence serves a purpose, though the YYYY-MM-DD restatement partially duplicates the schema pattern.

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 aggregate with an output schema, the description covers what is summed, over which documents, over which period, and with which optional filter — enough to call it correctly. Minor gaps remain around currency and boundary inclusivity, but nothing blocking given the rich schema.

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

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

Schema description coverage is 100%, with from/to, database and organization all documented in the schema, including the date pattern. The description reinforces the YYYY-MM-DD requirement and the fact that omitting organization means all organizations, but adds little beyond the schema. Baseline 3 is appropriate when the schema carries the semantics.

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

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

The description states a concrete metric and scope: total revenue from posted sales documents for a period, computed on the СуммаДокумента field, optionally narrowed by organization. That is a specific verb-plus-resource statement an agent can act on. It does not, however, distinguish itself from the sibling read.analytics.get_sales_breakdown, so an agent cannot tell which sales tool to pick from the description alone.

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

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

Usage is implied by the phrasing (aggregate revenue over a period), and the optional organization filter is flaggable from the text. There is no explicit when-to-use or when-not guidance, and no mention of the sibling get_sales_breakdown for per-dimension breakdowns, so the agent must infer the boundary.

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 openWorldHint, so the safety profile is covered; the description adds the non-obvious constraint that only *posted* realizations are summed, meaning drafts are excluded from totals, which materially affects interpretation of results. It does not discuss grouping/null-counterparty handling or the limit's truncation effect, leaving some behavioral gaps.

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?

Front-loaded with the core operation, then filters, then example questions, then the date format — a logical order with little waste. The date-format sentence ('Период — даты YYYY-MM-DD') duplicates the schema pattern and descriptions, so one clause could be dropped.

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 an output schema present, return values need no explanation, and the description covers the aggregation semantics, filter surface, and date format for a 9-parameter tool. The main omission is how limit interacts with grouped results and whether totals are truncated when groups exceed the limit.

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 every parameter is already documented, and the description largely restates groupBy modes and counterpartyKind values that the schema enumerates. It adds no meaning for limit, organization, database, or the Ref_Key filters beyond what the schema says, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Суммирует проведённые реализации (СуммаДокумента) за период') plus the four possible aggregation axes (counterparty/month/contract/total), which lets an agent separate it from the flat sibling get_sales. It never names a sibling tool explicitly, so differentiation is inferential rather than stated.

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 four example questions ('топ покупателей за год', 'выручка по месяцам', 'сколько продали ИП', 'продажи по конкретному договору') map directly to groupBy/filter combinations and give strong when-to-use context. There is no explicit when-not guidance and no named alternative (e.g. get_sales for raw rows), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful domain behavior beyond that: it discloses the exact detection criterion (bank debits with a specific ВидОперации) and thereby its inherent limitation — only bank-executed tax payments are counted, not accruals. It does not cover empty-result behavior or whether untranslated/unmatched taxes are excluded, keeping it below a 5.

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 definition is front-loaded: the core measurement rule and its rationale come first, followed by grouping, parameter hints, and example questions. Some parenthetical asides (the long enumeration of tax types and the «в БП 3.0» justification) are dense but each earns its place by justifying the marker's reliability.

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 an output schema present, return values need no explanation, and the description still supplies period format, database defaulting, organization filter scope, and grouping semantics. The main gaps are the groupBy default mismatch and no mention of currency or what an empty/non-matching period yields — small but real for a financial aggregate.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does add value for cashflowItem by giving concrete tax-type examples («УСН», «Страховые», «НДФЛ», «ЕНП») and matches the groupBy breakdown options. However, it states the default output is «итог», while the schema declares groupBy default = "cashflowItem" — this discrepancy could cause the agent to mis-predict the default response shape.

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+resource (sum of paid taxes/insurance contributions for a period) and pins down the exact data source — outgoing bank debits with ВидОперации=«ПеречислениеНалога». It enumerates the covered tax types (ЕНП, НДФЛ, страховые взносы, УСН/ПСН, налог на прибыль), so an agent can distinguish it from generic siblings like get_cashflow or get_payments_breakdown without opening the schema.

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

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

Usage context is clear and reinforced with concrete example questions («сколько налогов мы заплатили в прошлом году», «помесячная нагрузка»), plus the default mode (total) vs. breakdown mode. What is missing is an explicit negative boundary — it never names an alternative tool for total outgoing payments or states when NOT to use this one, so the agent must infer the routing.

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

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

Beyond the readOnlyHint and openWorldHint annotations, it discloses a non-obvious behavioral rule: invoices older than 90 days appear only when from is passed explicitly. It also explains how payment and shipment linkage is computed and what customerBalance is for, which the agent could not infer from annotations or 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?

It is dense but well ordered: what is returned, how status is derived, then status semantics, then period defaults and the 90-day caveat. The semicolon-chained clauses make it slightly heavy, but every sentence carries operational 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 analytical tool with six optional parameters and an output schema, the description covers derivation logic, status vocabulary, defaults, and the age-visibility caveat. Nothing an agent needs to call it correctly or interpret the result 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: what open versus all actually select, that status is derived from payments against the invoice, and that from controls visibility of invoices older than 90 days rather than only filtering the range.

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 resource (customer invoices for a period) and the exact data returned: invoice amount, paid amount, remainder, shipped, status, and age in days. It also names the derivation sources (the «Оплата счетов» register, sales linked to the invoice), so an agent can distinguish it from aggregate siblings like get_debtors or get_sales without opening the schema.

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

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

It gives explicit conditions: status=open (default) returns unpaid and partially paid invoices with the customer balance on account 62 for reconciliation, while all returns everything; the period is by invoice date with a default of the last 90 days. It does not name an alternative tool to use instead for aggregate debt figures, so routing to siblings is left implicit.

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

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses the most important behavioral traits: refCreatedAt is confidence=derived (UUIDv1-based, NOT verified creation/posting time), actual execution and modification times are unavailable, DataVersion is returned uninterpreted, and register movements are presence-only. This is exactly the caveat surface an agent needs to avoid over-claiming.

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 core constraint ('what can be provably said about time') is front-loaded, and every clause carries real caveat value. It is dense and clause-heavy with semicolons and parentheticals, which hurts scannability slightly, but nothing is truly redundant.

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

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

For a tool whose whole point is auditable honesty about data provenance, the description fully covers the returned fields, their confidence caveats, and the explicit limitations. An output schema exists so return values need not be explained, yet the description frames them usefully, leaving no gap an agent must bridge.

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

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

Schema description coverage is 100% and the description largely restates what the schema already documents (documentEntity = Document_*, documentRef = Ref_Key GUID). The only marginal addition is pointing to list_entities for the entity name, so baseline 3 is appropriate.

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

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

The description names a specific verb and resource: it returns what can be provably said about a document's timing (documentDate and derived refCreatedAt), and it is emphatic about what it will NOT return (actual execution/last-modification time). This is a concrete, well-differentiated purpose that an agent can distinguish from get_document or search_documents.

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

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

It gives useful context on obtaining the parameters (documentEntity from list_entities, documentRef as Ref_Key) and frames the scope as 'provably sayable via standard OData', which implies when the tool is appropriate. However, it never explicitly states when to choose this over sibling read tools like get_document, nor does it state any exclusion condition.

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=true; the description adds real behavior on top: the default is counterparties only, validity of Parent_Key/DataVersion for safe group modification, and the roles/contracts fields that disambiguate namesakes. It does not mention result limits or pagination behavior, which are relevant for a search tool.

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

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

A single front-loaded paragraph that leads with what is searched, then narrows to defaults, return fields, and examples. Every sentence carries actionable information, including the example queries that pin down the expected phrasing.

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

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

For a 4-parameter read search with an output schema and safety annotations, this covers the searchable fields, defaults, and downstream chaining well. The gaps are minor: no guidance on behavior with zero matches or how limit interacts with result ordering.

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 75% and the description explicitly supplies the meaning of subjectKind values (group = groups in the same catalog, all = both kinds, default = counterparties only), which is meaning beyond the bare enum. query is restated (partial name or INN) without adding syntax detail, and limit/database are left entirely to 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?

States a specific verb (searches), resource (counterparties), and matching modes (partial name or INN), and immediately explains what subjectKind=group/all do. An agent can distinguish it from read.counterparty.get_counterparty and from write.counterparty.* siblings without any further context.

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?

Gives concrete usage context — Ref_Key returned here is meant to be fed into get_counterparty and settlement-history tools, plus two worked example queries. It stops short of an explicit exclusion rule (e.g. "if you already have a Ref_Key, use get_counterparty directly"), so it is clear but not fully routing.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that a 'full' card is returned with identity fields, but says nothing about missing-record behavior, error modes, or the default-database fallback. With an output schema present, describing return contents is largely redundant, so the added behavioral value is modest.

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

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

Two short sentences with zero filler; the core action and return content are front-loaded, and the dependency on find_counterparty follows as a compact second clause.

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

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

For a simple two-parameter read with a full output schema and readOnly annotations, the description covers purpose, return content, and key provenance adequately. Only the optional database parameter's default behavior is left entirely to the schema, which is acceptable.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine provenance the schema lacks: it tells the agent that the Ref_Key value must be sourced from find_counterparty rather than invented. It says nothing about the optional 'database' parameter, though the schema already documents that fully.

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 ('Возвращает полную карточку контрагента по его Ref_Key') and enumerates the returned fields (ИНН/КПП, наименования, код). It also explicitly separates this tool from the sibling find_counterparty by stating that the key comes from there, so an agent can pick the right tool without opening either schema.

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

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

It gives a clear usage chain: obtain the Ref_Key via find_counterparty, then call this tool to get the full card. There is no explicit when-not or mention of the history/reconciliation siblings (get_customer_history, get_reconciliation) that also take a counterparty, so routing is implied rather than fully enumerated.

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=true, so safety is covered. The description adds that results are period-bounded and amount-oriented, but says nothing about ordering, whether invoices include both issued and received, or how the limit truncates results — meaningful gaps for a history feed.

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, no filler, with the resource scope front-loaded and the prerequisite pointer placed last where it is needed. Every sentence carries information the agent uses.

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 an output schema present and full parameter coverage in the schema, the description does not need to explain return values. It is nearly complete for a read-only history query; only result ordering and the distinction from adjacent analytics/reconciliation tools are unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns an extra point by documenting the provenance of the sole required parameter ('Ref_Key — из find_counterparty'), telling the agent how to obtain ref rather than leaving it to guess. Period semantics are also restated at the description level.

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?

States a concrete verb+resource pair: sales documents (документы реализации) and invoices for a buyer-counterparty over a period, plus what the data shows (amounts sold). The 'покупателю' scoping separates it from the mirrored read.counterparty.get_supplier_history, though that sibling is never named explicitly.

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

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

Usage is only implied by the 'за период' framing and the note that Ref_Key comes from find_counterparty, which usefully documents the prerequisite lookup chain. There is no explicit when-to-use vs. read.counterparty.get_reconciliation, read.analytics.get_deal_history, or get_supplier_history, so the agent must infer which report it needs.

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 cover read-only and open-world hints, and the description adds genuinely non-obvious semantics: only accounts with movements or balances appear in accounts, advance offsetting within the same counterparty is excluded from lines to mirror the 1C act, and printNumber is the number as it appears in the printed form. It does not mention performance, volume limits, or empty-result behavior, but the interpretive context it supplies is substantial.

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 purpose and scope are front-loaded in the first clause, and the dense semicolon-separated structure packs a lot of useful detail without filler. The final sentence about the print form is short and sets a real expectation. It is long, but each clause carries information an agent would otherwise have to discover.

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 six-parameter read tool with a full output schema and read-only annotations, this is nearly complete: scope, account coverage, exclusion rules and counterpartyRef provenance are all present. The row-level return explanation is somewhat redundant given the output schema exists, but it is harmless and reinforces interpretation.

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

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

Schema description coverage is 100%, and the description largely repeats what the schema already documents (counterpartyRef sourced from find_counterparty, contractRef limited to a single contract, organization filter). The one marginal addition is the explicit 'only one contract' limitation on contractRef, which the schema already implies. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description opens with a precise verb+resource+scope: settlements with a counterparty for a period, for a reconciliation act. It goes further by naming the accounting scope (accounts 60, 62 and 76 excluding 76.АВ/76.ВА) and the exact output rows (opening/closing balances, document lines, turnover, contract breakdown), which clearly separates it from sibling reads like get_account_turnover or get_debtors.

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 makes the intended use case clear (data for a reconciliation act) and routes the agent to find_counterparty for the counterpartyRef value, plus a constraint that contractRef accepts only one contract. It also sets an expectation boundary by stating the actual 'Акт сверки' print form is generated in 1C, so the agent won't expect this tool to produce it. It stops short of explicitly naming when to prefer an alternative 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 declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds that only receipt (purchase) documents are returned, which is useful behavioral context, but says nothing about ordering, truncation at the default limit of 100, or cross-base scope — all relevant for a query tool that can be capped.

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

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

Three short sentences, front-loaded with the resource and period, then the practical hint about where to get the ref. No filler, though the middle sentence ('Показывает закупки у поставщика') largely repeats the first.

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 an output schema present and all six parameters fully documented, the description only needs to convey purpose, scope and the ref dependency — which it does. It stops short of noting the default limit of 100 / max 500 or how this differs from the customer-history counterpart, which would make it airtight.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns an extra point by stating the provenance of the required 'ref' parameter ('Ref_Key — из find_counterparty'), which the schema only labels as 'Ref_Key контрагента'. The period semantics of from/to are restated only loosely.

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

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

The description names a specific resource and scope: 'Документы поступления по контрагенту-поставщику за период' — receipt documents for a supplier counterparty within a date range, plus the clarifying 'Показывает закупки у поставщика'. That is enough to separate it from the sibling read.counterparty.get_customer_history, though the alternative is not named explicitly.

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

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

Usage is implied by the scope ('закупки у поставщика', 'за период'), and the prerequisite 'Ref_Key — из find_counterparty' gives the agent a starting point. However, there is no explicit when-to-use/when-not guidance and no mention of the sibling read.counterparty.get_customer_history or the analytics purchase tools as alternatives.

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

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

The annotations already mark this as a read-only, open-world tool, so safety is covered. The description adds one useful behavioral fact: the result includes every field and tabular sections, which signals a potentially large payload. It says nothing about size, cost, or truncation behavior, so it adds some value but not rich context.

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

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

Two short sentences with no filler. The core behavior comes first, and the Ref_Key provenance follows as supporting context.

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 fetch with full schema coverage and an output schema, the description covers what the tool returns and how to get the required identifier. Nothing necessary is missing, although a note about payload size for documents with many tabular rows would have made it 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 coverage is 100%, so all three parameters are already documented, including the hint that database defaults when omitted. The description only reinforces that the lookup needs a document type and a Ref_Key, plus where the Ref_Key comes from, which is marginal value over the schema. The baseline 3 is right.

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?

States a concrete verb and resource: returns a document by type and Ref_Key, with all fields including tabular sections. This is enough to distinguish it from read.document.search_documents, which it names as the source of the Ref_Key. It falls slightly short of a full 5 because it does not explicitly contrast with the other per-document readers such as read.accounting.get_document_postings.

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?

Gives an implicit workflow by saying the Ref_Key comes from search_documents or payment history, which tells an agent that this is a fetch-by-id step after a search. It does not state when not to use it, for example instead of get_document_postings for accounting entries, so it is clear on context but stops short of explicit alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description adds real behavioral context beyond that. It discloses that number matching is fuzzy ("33" resolves to 0000-000033 and also to a counterparty's incoming invoice number) and that 1C numbering resets annually, so a single number may hit documents from several years — a non-obvious trait that changes how an agent should query. It does not mention result truncation or ordering, which is a minor remaining gap.

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

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

The purpose is front-loaded in the first clause, followed by routing rules and then the numbering caveat, and each sentence contributes distinct information. It is dense but well ordered; the one weak spot is that the kind enumeration at the start partially restates the enum already in the schema.

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

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

For an 11-parameter, all-optional search tool with an output schema and read-only annotations, the description covers the essential decision points: type selection, the numbering pitfall, and the default scope. It omits pagination/limit behavior and what happens if kind and entitySet are both supplied, but these are secondary given full schema coverage and a defined output schema.

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

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

Schema description coverage is 100% and every parameter is documented in the schema, so the baseline is 3. The description does add genuine meaning on top: the human-vs-technical number semantics, the kind/entitySet mutual exclusivity, and the note that entitySet is the only route for rare document types. That pushes toward the upper end of 3, but much of the parameter guidance duplicates what the schema already states.

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

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

The description opens with a specific verb and resource ("Ищет документы") and immediately enumerates the filterable dimensions: period, number, counterparty, organization, posting status, and amount. It distinguishes the two type-selection modes (kind vs. entitySet from list_entities) and defines the default fallback across all main document types, so an agent can tell this apart from read.document.get_document without opening a schema.

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

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

It gives explicit routing rules: use kind for common categories, entitySet for rare types like payroll or regulatory operations, and neither for a broad sweep, reinforced with example phrasings ("все документы за 10 сентября", "документ №33"). It also advises narrowing by period when searching by number. It stops short of naming a sibling such as get_document for single-record retrieval or analytics tools for aggregates, so one exclusion-style comparison is missing.

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=true, yet the description still adds real behavioral context: for ООО the director comes from the 'Ответственные лица организаций' register only if it is published in OData, otherwise a note is returned telling the user to add it to the OData composition. That graceful-degradation behavior is exactly the kind of trait an agent cannot learn from annotations or schema, though nothing is said about not-found or ambiguous-name handling.

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?

Purpose is front-loaded in the opening clause, and the subsequent sentences about director resolution and organization selection each carry distinct information. The long enumeration of returned fields is somewhat redundant given an output schema exists, but it is compact enough not to be wasteful.

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 an output schema present the description does not need to explain return values, and it still covers the two things an agent must know to call it correctly: how the organization is resolved and what happens when the responsible-persons register is absent from OData. For a two-parameter read-only tool this leaves no meaningful gap.

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

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

Schema coverage is 100%, so both parameters (database, organization) are already documented, including the name/ИНН/Ref_Key matching modes. The description adds the auto-selection rule when only one organization exists, but this sits in mild tension with the schema's statement that omitting organization returns all organizations of the base, leaving the multi-org default 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 states a specific verb and resource: it returns the full requisites of a legal entity from 1C settings, and enumerates the concrete fields (ИНН/КПП/ОГРН, наименования, ОКВЭД, bank account, director/chief accountant). This clearly separates it from list-style siblings such as read.system.list_organizations, but it never names a sibling explicitly, so the differentiation is inferred rather than stated.

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 text explains how the target organization is resolved (by name, or automatically when the base holds only one) and notes the ИП-vs-ООО director logic, which implies when the tool is applicable. It never states when to prefer this over read.counterparty.get_counterparty or read.system.list_organizations for discovery, and gives no exclusions or prerequisites.

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

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

The annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds real context beyond that: the result comes from $metadata, meaning this is schema introspection rather than a query against business data, which tells the agent not to expect document rows. Return shape itself is covered by the output schema, so no further disclosure is required.

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

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

Three short sentences, front-loaded with what is returned, then the input format, then when to call it. No filler, no repetition of annotation or schema content beyond what aids selection.

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

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

For a two-parameter, read-only introspection tool with an output schema and full annotation coverage, this is nearly complete. The only minor gap is the absence of any note about what happens with an unknown or misspelled entitySet, but that is a small omission at this complexity level.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents both parameters. The description still adds value by giving two EntitySet examples with different prefixes (Catalog_ and Document_), which conveys the naming convention across entity kinds better than the single schema example. The database parameter is left entirely to the schema, which is acceptable at full coverage.

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

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

The description states a specific verb and resource: it shows the fields (with types) and relations of one specific 1C entity. The word 'конкретного' (a single, specific entity) implicitly separates it from the sibling read.schema.list_entities, so an agent can pick between the two without opening either schema.

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

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

It gives an explicit when-to-use: call this before searching so you know which fields are available. There is no explicit when-not condition and no sibling is named as the alternative, but the ordering guidance relative to search tools is clear and actionable.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that results are grouped by class and that filtering is optional, but says nothing about result volume, truncation, or whether the map is complete for large databases. Modest added value beyond the structured fields.

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

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

Three short sentences with the purpose front-loaded, then the usage rationale, then the filtering options. No filler, and the most decision-relevant information comes first.

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 an output schema present and all three optional parameters documented, the description covers what an agent needs to call the tool correctly. The remaining gap is the unstated relationship to read.schema.describe_entity, which would make the discovery workflow explicit.

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%, including the enum for class and the note that database takes a name from list_databases with a default fallback, so the schema does the heavy lifting. The description only restates the class and name-substring filtering, adding no syntax or semantics beyond the schema; baseline 3 applies.

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

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

The description states a specific verb and resource: it returns a map of 1C business objects grouped by class (catalogs, documents, registers, enums). That is concrete and distinguishable from the write.* siblings, but it never mentions read.schema.describe_entity, the closest read-only sibling, so an agent must infer the two-step discovery flow on its own.

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?

"Используйте, чтобы понять, какие данные доступны в базе" gives a clear when-to-use context (initial exploration of the database), and the filtering sentence tells the agent how to narrow the listing. It stops short of stating exclusions or naming the alternative (describe_entity) for drilling into a single object.

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

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

Annotations only say readOnlyHint and openWorldHint; the description adds real context beyond them — that it re-reads $metadata and updates the schema cache (a state-affecting side effect worth knowing about), that it validates authorization, and what it returns (OData version, visible object count). It stops short of noting cost or latency of a metadata refresh, which would matter on large bases.

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

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

Three short sentences with a clear order: what it checks, what it refreshes and returns, when to call it. Nothing is redundant or buried, and the usage trigger is placed last where it is easy to find.

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

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

For a one-optional-parameter diagnostic tool with full schema coverage, annotations, and an output schema, the description covers purpose, side effect, and usage trigger. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single optional parameter is already documented with its default and its link to list_databases. The phrase 'для выбранной базы' merely echoes the parameter, so the description adds essentially nothing the schema does not already carry.

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?

States a specific verb and resource: verifies availability of the 1C OData service and correctness of authorization for the selected database, then refreshes $metadata and returns the OData version plus visible object count. This is unmistakably distinct from every read/write sibling in the list, none of which touch connectivity or schema cache.

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?

Explicitly instructs 'Вызывайте первым, если другие инструменты выдают ошибки' — a concrete diagnostic trigger that names the condition for use. The database parameter's own schema description ties it to list_databases, so the agent also knows where the input comes from.

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 and openWorldHint annotations already declare the safety profile, and the description adds behavior the annotations cannot: that results identify a primary database and that the names are the input keys for the rest of the toolset. It does not discuss permissions, enumeration scope, or failure behavior for unconfigured servers, so it is not exhaustive.

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

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

Three sentences, each doing distinct work: what is returned, how the result is consumed downstream, and when to call it. The most decision-relevant information (which databases are available) is front-loaded with no filler.

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

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

For a no-parameter discovery tool with an output schema already documenting the return shape, this covers everything an agent needs: what it lists, that one entry is primary, and how to use the values afterwards. Nothing important is left implicit.

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 zero input parameters, so the baseline is 4 and nothing more is required of the description for the schema. It does add cross-tool meaning by telling the agent where the database value produced here is used elsewhere, which is a genuine value-add.

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 concrete verb and resource ('Показывает настроенные базы 1С') and states the scope precisely: the databases this server is connected to and which one is primary. It also distinguishes it from its siblings by explaining that the returned names are consumed by the 'database' parameter of other tools, so an agent knows this is the entry point rather than another analytics read.

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

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

It gives explicit call triggers ('если нужно понять, какие базы доступны или сравнить данные нескольких баз'), which covers both the discovery and the multi-database comparison cases. It stops short of naming an alternative tool or a when-not condition, so it falls just below the top mark.

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=true, and an output schema exists, so the safety and return-shape burden is lifted. The description adds genuinely useful cross-tool behavior: the result values are meant to be fed into the 'organization' parameter of analytical tools, which is context the annotations cannot convey.

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

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

Two sentences, zero filler, with the core definition front-loaded and the downstream usage note following. The sibling tool list in parentheses is compact and directly actionable.

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

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

For a simple one-optional-parameter read tool with an output schema, the description covers what is returned (organizations/legal entities), the scoping to a database, and how the values are consumed downstream. Nothing an agent needs in order to call it correctly is missing.

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

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

There is a single optional parameter with 100% schema description coverage, so the schema already explains that 'database' is a name from list_databases with a default fallback. The description only echoes the notion of a 'selected database' without adding format or default details, so baseline 3 applies.

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

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

The description states a specific verb and resource: listing organizations (legal entities) inside a chosen 1C database, and clarifies the entity type with '(юрлиц)'. It does not explicitly distinguish itself from siblings such as list_databases or get_organization_card, so it lands just short of the top mark.

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

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

It gives a concrete use case: the returned organization name is what you pass as the 'organization' parameter of analytics tools (get_sales, get_debtors, get_cashflow, get_inventory) to narrow data to a single legal entity. That clearly explains when to reach for this tool, but there are no exclusions or guidance on when to use get_organization_card instead.

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?

Goes well beyond the annotations: it discloses the CAS/If-Match protocol, explicitly warns that when metadata has no DataVersion there is no atomic concurrency protection, lists the validations performed (organization, IsFolder, no deletion; plus owner, organization and currency for contracts), and describes the preview-then-confirm flow with operationId idempotency. The destructiveHint=false annotation is consistent with the stated 'deletion unavailable' constraint.

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 content is front-loaded and information-dense, but it is delivered as a single run-on paragraph where security caveats, scope rules, validation lists and preview flow all run together. The dangling 'scope=contract' reference and the trailing remark about loan/expense interpretation add confusion rather than 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 an 11-parameter mutation with a preview/confirm protocol, the description covers the workflow, concurrency model and validation well, and an output schema exists so return values need not be explained. The remaining gap is the entirely undescribed accounts payload and the scope parameter that appears in prose but not in the schema.

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

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

Schema description coverage is only 27%, so the description must compensate, and it does explain expectedDataVersion/If-Match, singleWriter, operationId and confirm semantics well. However, it says nothing about the accounts object's four UUID fields (customerAdvance, supplierAdvance, customerSettlement, supplierSettlement), the settlementKind enum values, or the mode enum, and it introduces a scope concept absent from the schema.

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

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

The description states a concrete verb pair and resource: it creates a missing settlement-account setting (create) or changes explicitly listed resources (update), and it carves out scope by noting that global settings and deletion are not available. It does not name the closest sibling (write.accounting.set_settlement_settings) directly, so the differentiation is implied through the global-settings exclusion rather than stated.

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?

Strong when-to-use content: create vs update, when singleWriter is mandatory, that scope=contract requires a contract while counterparty/group do not, and that a preview must precede confirmation with identical arguments and operationId. The guidance is slightly muddied by referencing a scope parameter that does not exist in the schema and by the confusing note about the old tool name.

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