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

Beyond the annotations, the description discloses concrete behavior: there is no separate 'point' entity, parent_person_code links to the parent card, the tool requires write mode, and repeating with the same code updates rather than creates. This is valuable added context and matches idempotentHint and destructiveHint.

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

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

Three dense sentences, each carrying distinct information: purpose, modeling, write-mode requirement, and idempotent behavior. No filler or redundancy; the key gotcha is front-loaded.

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

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

For a 10-parameter mutation tool with no output schema, the description covers the essential modeling rule, the write-mode precondition, and upsert semantics. It does not describe the return shape, but the schema already documents the parameters and the annotations carry safety flags.

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

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

Schema coverage is high (90%), so the baseline is 3. The description enriches two critical parameters by explaining that parent_person_code models a network point and that code determines update-vs-create behavior, adding meaning not explicit in the schema.

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

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

Description states clearly 'Создаёт юрлицо в справочнике' and explains what a 'точка сети' is in terms of this tool. This precisely frames the tool's purpose and separates it from siblings like smartup_contractors or reference/setup tools.

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

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

The description gives usage context: it is for creating a legal entity or network point, requires write mode, and warns about upsert behavior when reusing a code. It does not explicitly name alternative sibling tools, but the precondition and modeling guidance are enough for correct selection.

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 readOnlyHint, idempotentHint, and destructiveHint=false, so the description does not need to repeat those. It adds valuable behavioral/data-model context beyond them: 'Точка — это юрлицо с родительской карточкой, отдельной сущности «точка» в API нет', which helps the agent interpret parent_code and returned entities.

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 short yet dense: it names the resource, the questions it answers, adds a crucial data-model clarification, and keeps front-loaded orientation with no filler. Every sentence earns its place.

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

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

For a read-only lookup tool with 0 required parameters and no output schema, the description covers the essential scope and return semantics anyway. The main gap is the lack of any explanation of filial_code and limit, which could leave some edge use cases underspecified.

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

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

Schema coverage is 50% (query and parent_code have descriptions). The description adds meaning for query (search by name/INN/code) and parent_code (show outlets of a contractor), but leaves limit and filial_code unexplained. Since coverage is moderate and description does not compensate for the unannotated parameters, a baseline 3 is appropriate.

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

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

The description states the concrete resource (legal entities/contractors and their outlets) and the query intents it answers: existence check, retrieving INN/code, and listing related outlets. It also clarifies the data model ('a point is a legal entity with a parent card'), which clearly separates it from transactional or creation siblings like smartup_orders and smartup_contractor_create.

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 conveyed through the example questions the tool answers: 'is there a client', 'what is their INN/code', 'what outlets do they have'. This gives implicit usage guidance but no explicit when-not-to-use or alternatives; for example, it could mention smartup_contractor_create for adding contractors.

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

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

Annotations already mark the tool as readOnly, idempotent, openWorld, and non-destructive. The description adds meaningful behavioral context beyond those flags: the exact formula, the fact that it depends on three data extracts, and the accepted date formats ('2026-09-06', '06.09.2026', 'вчера', '-7d'). It does not fully describe output shape, but the annotations lower the required burden.

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

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

The description is compact: four short sentences, front-loaded with the core definition, followed by use cases, data sources, and date syntax. Every sentence contributes information and there is no redundant filler or boilerplate.

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 calculation tool with no required parametersising and a well-covered schema, the description provides the essential formula, answerable questions, data origin, and date syntax. It does not describe output row contents or explain filial_code, but those omissions are minor because the tool is non-destructive, annotations cover behavior, and the schema covers defaults.

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 high (86%) and already explains begin, end, limit, query, person_code, and only_debtors. The description adds extra value by specifying date input formats for begin/end and by clarifying that the result is a period-based calculation. The only gap is filial_code, which has no schema description and is not explained here either, but overall the description supplements the schema usefully.

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 computation: 'отгрузки минус оплаты минус возвраты за период' (shipments minus payments minus returns), and names the exact business questions it answers: 'кто сколько должен', 'есть ли долг у клиента', 'кому пора звонить'. This distinguishes it from sibling tools like smartup_orders, smartup_payments, and smartup_returns by explaining that it is calculated from those three sources.

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

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

The description clearly frames when to use the tool by giving the questions it responds to, such as 'кто сколько должен' and 'кому пора звонить'. It does not explicitly list alternatives or say 'use X instead' for non-debt scenarios, but the phrase 'Считается из заказов, оплат и возвратов — трёх выгрузок' implies that raw-order, payment, or return queries belong in sibling tools.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful context by explicitly banning write methods and clarifying that the connector only reads. This goes beyond the annotations without contradicting them; no error or rate-limit behavior is discussed, but that is acceptable for a generic endpoint.

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

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

Two sentences with no filler. The purpose is front-loaded, and the constraint about forbidden write methods is placed immediately after the purpose, so an agent gets the critical information quickly.

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

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

For a deliberately generic tool with no output schema, the description is sufficiently complete: it explains when to use it, what endpoints are allowed, and references the body, path, and entity parameters through the schema. The lack of return-value documentation is mitigated by the entity parameter that identifies the response root key.

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

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

Schema description coverage is 75%, and the schema itself documents path with an example, body with the filial_code substitution note, and entity with its fallback behavior. The tool-level description adds no parameter detail of its own, and the 'limit' parameter remains undocumented. This matches the baseline for high coverage where the schema carries the load.

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

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

The description opens with a specific verb-resource pair: 'Прямой вызов любого метода $export' (direct call of any $export method). It clearly positions the tool as a generic fallback for when ready-made tools are insufficient, which distinguishes it from all specialized siblings without ambiguity.

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

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

It explicitly states when to use the tool: 'когда готового инструмента не хватает' (when a ready-made tool is not enough). It also gives a clear exclusion, prohibiting write methods like $import, $change_status, and $attach_data. It does not enumerate specific sibling tool names, but for a generic fallback the reference to 'ready-made tools' is sufficient.

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, idempotent, and non-destructive behavior. The description adds useful context about what the tool returns (header, composition, status) and its intent to explain why an order was not shipped. No contradictions with annotations.

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

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

Two concise sentences with examples and no filler. The core behavior and lookup identifiers are front-loaded.

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

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

Given the annotations and schema, the description is largely sufficient for selecting and invoking the tool. Minor gaps remain around what happens when both identifiers are provided or when neither is provided, and filial_code is undocumented.

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

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

Schema description coverage is 80%, so the schema already documents most parameters. The description reinforces deal_id/external_id as lookup keys but adds no extra meaning for filial_code or the begin/end date behavior.

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

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

Description states a clear retrieval purpose: 'Один заказ целиком' by deal or external number, and names the return contents (header, lines, status). It distinguishes itself from the plural-list sibling smartup_orders and the status-focused smartup_order_status.

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

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

Concrete example queries ('что в заказе 283581248', 'почему заказ не отгружен') make the intended use case clear Acronyms. It does not explicitly name alternatives or say when not to use the tool, so it falls short of a 5.

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

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

Annotations already carry readOnlyHint=false, idempotentHint=true, and destructiveHint=true; the description adds genuinely useful behavior: default draft status that blocks warehouse until manager posts, the requirement of write mode, and the upsert semantics for external_id. This goes beyond the structured annotations and clarifies what the destructive/update behavior actually means.

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 dense sentences, each earning its place: purpose, autofill, default draft, write mode, idempotency. No filler, and the most important behavioral caveats (draft, external_id upsert) are included.

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 write operation with 13 parameters and no output schema, the description covers defaults, autofill, write-mode requirement, and update semantics. The only real gap is that it never states what the tool returns (e.g., order ID), which an agent would likely need after creation; still, the key behavioral constraints are present.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining how optional parameters (room_code, sales_manager_code, price_type_code, warehouse_code) are autofilled from historical orders unless no_autofill is set, and by clarifying external_id's role in updates. This enriches the flat schema descriptions meaningfully.

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

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

Clearly states the action ('Заводит заказ в учётной системе' – creates an order in the accounting system) and the minimal input needed (client + products). It is distinguishable from sibling status/note/read tools by the explicit creation semantics, though it doesn't name a specific sibling alternative.

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

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

Provides contextual guidance: the autofill rule (work zone, manager, price type, warehouse taken from past orders), default draft state, and idempotent update behavior. However, it never explicitly states when to prefer this tool over siblings such as smartup_order_status or smartup_order_note, so usage conditions are only implied.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description reinforces this with 'Ничего не меняет' and adds value by explaining what data is returned (codes for specific fields and their origin). This goes beyond the annotations by detailing the content of the response, which helps the agent predict what it will receive.

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

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

The description is two sentences long, with the core purpose stated first and usage context second. Every sentence earns its place: the first lists exactly what is returned, the second gives a concrete use case. No fluff or repetition.

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

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

The tool is simple (read-only preview) and the description tells what it returns and when to use it. However, it does not describe the output structure or format, and without an output schema an agent may not know how to interpret the result. It also doesn't mention potential errors or the role of the optional parameters in detail. Adequate but leaves some ambiguity about the response shape.

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

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

Schema coverage is 50%: only person_code has a description, filial_code has none. The description does not elaborate on either parameter. It does not explain what filial_code represents or how person_code affects the results beyond the schema's note that codes are more precise for a client. The description adds no parameter information beyond what the schema already provides, and it fails to compensate for the undocumented filial_code.

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

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

The description clearly states the tool returns the default codes for order creation and their sources (work zone, manager, price type, warehouse, robot). It distinguishes from creation tools by emphasizing this is a preview before recording. The phrase 'Полезно посмотреть до записи' differentiates it from the actual order creation flow.

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

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

The description provides explicit usage context: use it before recording an order, especially if the order was previously rejected. It implies this is a pre-check tool rather than the creation step. However, it does not explicitly name an alternative tool like smartup_order_create, so the guidance lacks an explicit 'use this instead of X' comparison. Still, the 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?

Beyond the annotations, the description discloses that the previous note is replaced entirely ('Прежнее примечание заменяется целиком'), that the order composition is untouched, and that write mode is required. These are concrete behavioral details an agent needs and they do not contradict the annotations.

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

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

Three short sentences, each carrying essential information: action and scope, prerequisite, and side effect. No filler or redundancy.

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

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

For a simple mutation tool with annotations and schema descriptions, the description covers the core behavior, the prerequisite, the destructive side effect, and what remains unchanged. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 67%, and the schema already explains deal_id and note. The description adds context like 'header' and 'existing order', which slightly enriches the deal_id/note meaning, but it does not clarify the undocumented optional parameter filial_code. The added value over the schema is limited.

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

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

Description states a specific action and resource: 'Пишет примечание в шапку существующего заказа' (writes a note in the header of an existing order). The clarification 'не трогая его состав' (without touching its composition) clearly distinguishes this from order creation or full-order updates.

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

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

The description implies when to use the tool: when a note must be added to an existing order without modifying line items. It also gives a clear precondition: 'Требует включённого режима записи' (write mode must be enabled). However, it does not explicitly compare with alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds that it returns orders with composition and status over a period, and provides date format examples (e.g., 'вчера', '-7d'), which is useful context beyond annotations.

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

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

Two concise sentences: the first states the tool's purpose and scope, the second provides concrete date syntax. No wasted words, and the key purpose is front-loaded.

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

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

For a read-only query tool with 8 optional parameters and no required fields, the description is complete. It explains what data is returned (orders with composition and status), gives date format guidance, and relies on the schema for parameter details. No output schema is present, but the description does not need to cover return structure beyond what it states.

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% with all parameters described, so baseline is 3. The description adds value by specifying acceptable date formats (e.g., '2026-09-06', '06.09.2026', 'вчера', '-7d') which directly clarifies the 'begin' and 'end' parameters, going beyond the schema's generic descriptions.

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

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

Description clearly states it returns orders (deals) over a period with composition and status, and enumerates the specific questions it answers ('what was ordered', 'order status', 'how much shipped'). This is specific and distinguishes it from siblings like smartup_order (single order) and smartup_sales (analytics).

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

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

The description implies when to use it by listing the queries it answers, but does not explicitly mention alternatives or when not to use it. However, the intent is clear enough for an agent to select it for order-listing questions, so it earns a 4.

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

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

Annotations already mark the operation as destructive, but the description adds meaningful specifics: cancellation is irreversible from the connector side and can only be reversed in the accounting system. It also adds the write-mode requirement, giving the agent important operational context beyond the annotations.

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

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

Three short sentences with no filler. The purpose is front-loaded, and the remaining sentences add essential prerequisite and risk information without redundancy.

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

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

The description covers the tool's purpose, prerequisite, destructive irreversibility, and core required parameters. Missing pieces include filial_code semantics and any indication of return behavior, which is more salient because there is no output schema, but the core invocation details are sufficiently clear.

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 67%, covering deal_id and status. The description enriches status semantics by mapping to business actions ('провести, отменить, вернуть в работу'), but it does not explain filial_code, which remains undocumented in both schema and description. The value syntax for statuses is already in the schema.

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

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

Description states a specific verb and resource: 'Меняет статус существующего заказа' and enumerates the status kinds. This clearly distinguishes it from sibling tools like smartup_order_create or smartup_order_note, which have different purposes.

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

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

The description provides clear context: it is for changing statuses of existing orders, and it discloses a prerequisite ('Требует включённого режима записи'). It does not explicitly name alternatives or say when not to use it, but the sibling context makes the intended use obvious.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the date-parsing behavior ('вчера', '-7d') and the query purpose, but does not disclose details like whether only successful payments are returned, whether results are aggregated, or any rate/auth considerations.

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 purposeful sentences with no filler: the first defines the tool's function and scope, the second provides concrete date syntax examples. Information is front-loaded and each sentence earns its place.

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

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

The combination of description and schema covers core usage: period, date formats, and client/document search. But there is no output schema, two parameters (limit, filial_code) are unexplained, and the description does not clarify how to distinguish payments from returns or debt, leaving meaningful gaps for an agent facing many payment-related siblings.

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

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

The schema covers begin, end, and query; the description adds useful date-format semantics beyond the schema ('2026-09-06', '06.09.2026', 'вчера', '-7d'). However, limit and filial_code are left undocumented in both schema and description, so the description only partially compensates for the 60% schema coverage.

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

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

The description clearly identifies the tool as a cash-receipts/payments query resource ('Приходы денег за период') and states the kinds of questions it answers ('платил ли клиент', 'сколько пришло за неделю'). This distinguishes it from order/inventory siblings, though it never names an alternative, so it stops short of full differentiation.

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

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

The intended use is clear: use this tool for payment-receipt questions over a time period, with date-filtering syntax provided. There is no explicit when-not-to-use guidance or referral to alternatives such as smartup_orders or smartup_debt, but the context is strong enough for an agent to route simple payment queries here.

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?

Аннотации уже покрывают readOnlyHint, idempotentHint и destructiveHint, поэтому базовая безопасность ясна. Описание добавляет полезные детали: цены «действующие», группировка «по типам прайса», вывод названия товара, а не только кода. Этого достаточно, но поведение в части фильтров, лимитов и формата ответа не раскрыто.

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?

Описание компактное, состоит из двух коротких предложений, начинается с главной сути «Действующие цены товаров по типам прайса». Примеры вопросов полезны и не раздувают текст, хотя одно из предложений могло бы быть информативнее.

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?

Для простого read-only списка с пятью опциональными параметрами описание даёт базовое понимание, но не объясняет возвращаемые данные, поведение limit, filial_code and with_zero. Отсутствие 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?

Схема описывает 3 из 5 параметров (query, with_zero, price_type_code), то есть покрытие 60%. Описание косвенно объясняет price_type_code через «по типам прайса» и query через «показывает название товара, а не только код», но limit и filial_code остаются без пояснений ни в схеме, ни в описании.

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?

Имя «smartup_prices» и title «Цены» дополнены конкретным описанием: «Действующие цены товаров по типам прайса» и примерами вопросов «почём отгружаем», «какая цена у этого товара». Это ясно указывает на ресурс и назначение, хотя явное отличие от sibling-инструмента smartup_products не сформулировано.

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?

Описание задаёт понятный контекст применения — инструмент для получения текущих цен товаров по типам прайса, с примерами пользовательских запросов. Однако нет явных указаний, когда его НЕ использовать или какой sibling-инструмент выбрать вместо него, поэтому не 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 cover the read-only, idempotent, non-destructive, and open-world nature of the tool. The description adds useful behavioral context by listing the product fields available and by framing it as an existence/code lookup. It does not discuss pagination or the open-world caveat, but those are secondary given the annotations.

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

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

The description is two short sentences with no filler. It front-loads the resource and its fields, then gives concrete user-facing questions the tool answers. Every word earns its place.

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

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

For a low-complexity, optional-parameter lookup tool, the description combined with schema and annotations covers most needs: purpose, available fields, query semantics, and safety profile. The only notable gap is the unexplained `filial_code` parameter, which keeps it from being fully complete.

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

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

Schema coverage is already high (3 of 4 parameters), and the description adds meaning beyond it by listing likely values for the `fields` parameter (name, code, article, packaging, brand) and reinforcing searchable attributes. The `filial_code` parameter remains undocumented, which prevents a perfect score.

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

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

The description identifies a clear resource (product directory) and enumerates its contents: name, code, article, packaging, brand. It also states concrete questions the tool answers, such as 'is there such a product' and 'what is its code'. It does not explicitly differentiate from siblings, but the product-focused purpose is unambiguous.

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

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

The description explicitly frames intended use: checking whether a product exists and retrieving its code. This gives clear context for when to invoke the tool. It does not mention alternatives or exclusions, but the quoted use cases make the appropriate scenario clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. However, the description adds no behavioral context beyond the list of directories—nothing about pagination, response shape, how limit/query/filial_code affect results, or any other operational behavior.

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

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

The description is compact—one sentence that immediately lists all available directories in a scannable format. It is not padded with unnecessary detail, though it could have been slightly more structured with an explicit verb up front.

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 four parameters, no output schema, and only 50% schema description coverage, the description leaves important semantics unexplained, especially limit and filial_code. The agent can invoke the tool with just 'name', but it lacks enough context to use optional parameters confidently or understand what the returned data will look like.

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

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

The description adds useful Russian-to-enum mappings for the 'name' parameter, helping an agent understand what each directory represents. However, it does not clarify 'limit' or 'filial_code', and some parenthetical keys (e.g., 'product_group', 'natural_person') do not match the actual camelCase enum values, creating potential confusion.

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 enumerates the specific reference directories available (warehouses, product groups, producers, etc.), and the required parameter's description ('Какой справочник выгрузить') makes the action an export/read operation. It lacks an explicit verb in the description itself, but the resource scope is well-defined and distinct enough from siblings.

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

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

The phrase 'Остальные справочники' implies this tool is for reference data not covered by the more specific sibling tools, but it does not explicitly state when to use it versus alternatives like smartup_products or smartup_contractors. Usage is mostly inferable from the listed directory names, not explicitly guided.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by listing accepted date formats ('вчера', '-7d', absolute dates), but it does not disclose output shape, pagination behavior, or scope limitations.

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

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

Two compact sentences: the first states purpose, the second gives concrete date examples. There is no filler, though the date list is slightly telegraphic.

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 5-parameter, no-output-schema read tool, this definition is enough to get started, but an agent would have to guess at limit and filial_code semantics and cannot anticipate the response shape. The rich annotations and clear purpose keep it from being inadequate.

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 documents end, begin, and query, but limit and filial_code have no descriptions, so 40% of parameters are undocumented. The date-format note helps interpret begin/end, but the description does not compensate fully for the missing parameter meaning.

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

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

The description clearly identifies the resource as goods returns over a period and specifies the concrete questions it answers: 'what was returned' and 'how many returns a customer has'. It does not explicitly contrast with siblings like smartup_sales or smartup_orders, but the subject matter is specific enough to distinguish it.

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

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

The description implies the tool is for return-related analytical queries and gives useful date syntax, so an agent can infer when it is appropriate. However, it provides no explicit guidance about when to prefer a sibling tool or when not to use this one, which matters given the large sibling family.

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 readOnly, idempotent, and non-destructive behavior. The description adds that the tool returns a 'свод' (summary), which is a mild behavioral hint. However, it doesn't disclose other traits like result size, aggregation details, or any performance caveats. Given the annotations carry the safety profile, a 3 is appropriate for the minimal additional 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?

The description is two concise sentences. The first sentence front-loads the core purpose and grouping options; the second provides concrete query examples and date formats. No filler or repetition. Every word contributes to understanding the tool's function and invocation.

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 6 parameters and no output schema, the description could be more complete. It explains what questions the tool answers but not the exact structure of the returned report (e.g., fields like revenue, quantity, date). This could lead to ambiguity about expected output. The examples partially compensate, but for a complex tool like this, a bit more detail on return format would improve completeness.

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 high (83%), so the description doesn't need to explain every parameter. It does add valuable examples for date formats ('06.09.2026', 'вчера', '-7d') that are not in schema, and clarifies the group_by options in natural language. However, this is minor enrichment; the description doesn't provide deeper semantics beyond what schema already offers. Baseline 3 is justified.

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

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

The description clearly states it's a sales summary over a period with breakdowns by client, product, or day. It uses a specific verb 'свод' (summary) and resource 'продажи', and gives concrete example questions. This distinguishes it from sibling tools like smartup_orders (individual orders) and smartup_products (catalog), making its purpose unmistakably unique.

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

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

The description provides explicit usage context with example queries ('что продавалось лучше всего', 'сколько отгрузили за месяц', 'кто крупнейший клиент'). It also gives date format examples, helping the agent understand input. While it doesn't explicitly state when not to use it, the nature of a sales report implies it's for aggregated metrics rather than transactional detail, and sibling names suggest alternatives. Overall, solid 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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: the list is not a complete directory but a derived set from posted orders, so it may not contain all staff, only those that have been used. This goes beyond annotations and helps set expectations.

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

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

The description is two sentences, front-loaded with the resource and fields, and the important caveat about derivation is placed second. Every sentence earns its place with no redundancy.

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

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

For a read-only list tool with no output schema and two optional parameters, the description covers the essential context: what the list contains, how it's derived, and its limitation. The only minor gap is the undocumented filial_code parameter, but the overall context is sufficient for an agent to use the tool correctly.

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

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

Schema description coverage is 50%: the 'query' parameter is described as search by name or code, but 'filial_code' has no description. The description mentions work zones and staff codes but doesn't explicitly explain the filial_code parameter. Baseline 3 is appropriate since the schema covers half the parameters and the description adds some context but doesn't fully compensate for the undocumented parameter.

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

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

The description clearly identifies the resource (sales managers/staff accepted in orders), the specific fields (staff code, name, work zones), and the key limitation (no dedicated staff directory in SmartUp API). It distinguishes itself from sibling tools by explaining it is a derived list, not a direct reference lookup.

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

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

The description explains that the list is assembled from completed orders, implying it should be used when you need staff codes that are known to work in orders. It doesn't explicitly name alternatives or exclusions, but the context of siblings and the explanation of derivation provide clear usage context.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description only needs to add context. It adds 'free balances' and 'at a date,' which clarify the data scope, but it doesn't discuss behavior like response shape, default limits, or performance implications. No contradiction with annotations.

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

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

Two compact, meaningful sentences: the first states the function and scope, the second gives example user questions. No filler, redundancy, or unnecessary detail.

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

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

For a simple read-only query with no required parameters and high schema coverage, the description plus schema gives enough to select and invoke the tool correctly. The absence of an output schema is partially mitigated by the description's explicit statement of the questions answered, though the exact row structure is not specified.

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

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

Schema description coverage is 86%, well above the 80% threshold, so the schema carries most parameter semantics. The description adds little parameter-level detail and doesn't clarify the one undocumented parameter (filial_code), but it doesn't need to repeat what the schema already documents.

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

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

The description clearly identifies a stock-balance query tool: free balances per item and warehouse as of a date, and it explicitly states the questions it answers ('how much is left', 'is the item in stock'). This makes the resource and action clear, though it does not explicitly contrast it with sibling tools beyond the 'stock' 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?

It gives useful usage context for date-based stock inquiries and names the exact questions it answers, so an agent can infer when to call it. However, it doesn't say when not to use it or point to alternatives from the long sibling list, leaving exclusion guidance 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?

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful context about limits being shared with production work, which helps agents anticipate quota impact. No contradictions with annotations.

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

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

Two sentences, front-loaded with the core information (what it reports) followed by the practical usage hint. Zero waste, perfectly concise.

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 query tool with no parameters and annotations covering safety, the description is fully adequate. It implies the output includes numbers (requests made and limit), which is sufficient for an agent to know what to expect.

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

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

The tool has zero parameters, so the baseline is 4. The description correctly omits any parameter details, as there is nothing to explain beyond what the schema already indicates.

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

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

The description clearly states the tool reports the number of requests made today and the limit, with a specific resource (connector usage) and a clear purpose. It distinguishes itself from sibling tools that operate on specific business objects (orders, stock, etc.) by focusing on quota/usage.

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

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

The description explicitly advises checking this tool before large exports, providing concrete timing guidance. While it doesn't name alternatives, no alternative exists for usage checks, and the context 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.