Zavod Stanki CNC Catalog

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

Annotations already mark the tool as non-read-only and non-idempotent; the description adds useful behavioral context by disclosing that the answer is delivered asynchronously to the client via the provided contacts, and that an API key is required. It does not contradict annotations, though it does not cover rate limits or exact delivery mechanics.

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 and front-loaded: action first, then scope, prerequisite, and outcome. Every sentence earns its place, and there is no redundant 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 human-mediated question-submission tool with an output schema and annotations, the description provides the essential context: purpose, topics, required key, and contact-delivery behavior. It does not specify which contact channels are supported or expected response time, but those are secondary given the output schema and simple request semantics.

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

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

Schema description coverage is 0%, so the description must compensate. It tells the agent that api_key is required and that name/email/phone are the contacts to fill in, which adds meaningful guidance beyond raw parameter names. However, it does not explain each parameter individually, and there is a mismatch: the description says 'Требуется API-ключ' while the schema lists api_key as optional.

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 ('Задать вопрос менеджеру завода') and enumerates concrete use cases: non-standard configuration, special conditions, deadlines, leasing. This makes the tool clearly distinct from automated siblings like get_faq or search_machines.

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

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

The description gives clear context for when to use the tool ('нестандартная комплектация, спецусловия, сроки, лизинг') and states a prerequisite ('Требуется API-ключ'). However, it does not explicitly name alternatives or say when not to use it, such as pointing standard questions to get_faq.

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

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

Annotations already declare readOnlyHint and idempotentHint; the description adds that the result is only an estimate ('Ориентировочная цена') and that final pricing comes from the manager's quote. This is useful behavioral context beyond the structured hints and does not contradict them.

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

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

Two sentences deliver purpose, option pricing, model argument semantics, output fields, and a caveat without filler. The core purpose is front-loaded, making it easy to scan.

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 and safety annotations present, the description provides everything needed to call the tool correctly: required model argument, optional parameters, pricing logic, currency, and the estimate-versus-final caveat. No critical information 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?

Although the schema already documents all three parameters, the description adds meaning by specifying the accepted model formats (product_number or model name) and concrete surcharge amounts for spindle power and vacuum table. This goes beyond the schema's field descriptions and helps an agent construct correct inputs.

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 clear verb+resource: it calculates an estimated machine price with options and returns base_price, options, and estimated_total. The focus on price configuration with option surcharges distinguishes it from siblings like get_machine_detail and compare_machines.

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 clearly conveys when to use it: when an approximate price with spindle-power and vacuum-table options is needed. It also sets expectations by noting the final price is in the manager's quote, though it does not explicitly name alternative tools or exclusions.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral context beyond that: the operation produces a comparison table for client responses and is limited to 2–4 machines. It does not detail errors or edge cases, but this is a minor gap given the read-only nature.

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 and front-loaded: it leads with the core purpose, then covers input variants and output format in two clear sentences. There is no filler, repetition of annotations, 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?

Given the read-only, idempotent annotations, full schema coverage, and presence of an output schema, the description is complete enough for correct invocation. It specifies the input variants, the supported machine count, the compared fields, and the expected output form (a table for the client). Nothing essential for selecting or calling the tool 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?

The input schema already covers 100% of parameter descriptions, but the description adds meaningful constraints not present in the schema: the tool compares 2–4 machines, and 'ids' is an alternative to 'id_a/id_b'. The concrete example with product numbers further helps invocation, so the description adds value beyond the raw 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 ('Сравнение' / compare) and a precise resource: 2–4 factory machines by technical characteristics and price. It lists the compared fields (working field, spindle, price, availability, description), which makes the tool's purpose unmistakable and clearly differentiates it from sibling tools like get_machine_detail or search_machines.

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

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

The description clearly implies when to use the tool: when a client needs a comparison of 2–4 machines and a tabular answer. It does not explicitly name alternatives or state 'when not to use', so it misses the top level of guidance, but the context is clear enough for an agent to select it appropriately.

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 openWorldHint=false, so the safety profile is covered. The description nonetheless adds genuinely useful behavioral scope by disclosing that webpage requests, deals, and personal data (phones, e-mail) are excluded from results, which is not derivable from 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 definition is a single front-loaded sentence that leads with what the tool returns before adding the city filter and the exclusion caveat. It is efficient, though the parenthetical field list and trailing exclusion clause make it slightly denser than necessary.

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 the description needn't explain return values, yet it still summarizes them briefly. Combined with the explicit exclusion list and the filter note, it is nearly complete; only pagination/limit semantics are left untouched, and those are covered by 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 100%, so both parameters are already documented by the schema itself. The description mentions the city filter, matching the 'city' param, but adds no syntax, format, or default/limit detail beyond what the schema provides (city description and 'default 10, max 30' limit already live there). 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 resource (active production-capacity exchange orders) with a concrete scope ('milling, cutting, sawing'), and states what it returns (id, material, quantity, budget, deadline, link). This resource is clearly distinct from every sibling tool, which deal with machines, categories, FAQ, and leads, so an agent can route unambiguously.

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: the description notes an optional city filter and that it returns 'active' orders, which hints at when to use it, but it names no alternative and gives no explicit when/when-not guidance. Nothing tells the agent, for example, why to pick this over ask_manager for a sourcing 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 idempotentHint=true, so the safety profile is covered. The description adds value by enumerating the specific data fields, especially the discovery-URLs, which are not inferable just from the tool name. It provides useful context about what the agent 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 a single dense sentence that front-loads the company context and discovery-URL list, then immediately gives the usage instruction. Every word earns its place; there is no redundancy or 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 read-only, zero-parameter tool with an output schema, the description sufficiently covers what to expect (company fields and discovery URLs) and when to call it (first for manufacturer info). No crucial behavioral or usage gap remains.

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 (input schema is empty) and schema description coverage is 100%. With no parameters to document, the description does not need to add parameter semantics; the baseline score of 4 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 clearly defines what the tool returns: company context including name, brand, city, address, contacts, websites, and all discovery-URLs (llms.txt, llms-full, server-card, OpenAPI). It also positions the tool as the first call for manufacturer info, making its purpose and scope unambiguous even without an explicit verb.

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

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

The description explicitly states 'Вызывай первым для справки о производителе' (Call first for manufacturer info), giving clear context for when to invoke it. It does not mention when to avoid it or name alternative tools, but among the siblings none directly overlaps with this company-info function.

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

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

The description adds behavior beyond annotations: it explains that a query filters the FAQ and that omitting the query returns the entire FAQ. This complements the readOnlyHint and idempotentHint annotations without contradicting them.

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

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

Two concise sentences cover scope, examples, and behavior with no redundant content. The most important usage instruction is front-loaded after a clear topic summary.

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

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

For a single optional-parameter read-only tool with an output schema, the description is largely complete. It covers what the FAQ contains and how query behavior works; a minor gap is not routing non-FAQ questions to the ask_manager alternative.

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 the query parameter with examples, and the description adds meaningful behavior: query enables search, absence returns the full FAQ. This clarifies optionality and effect beyond the schema's keyword description.

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: answering common questions about the factory and machines, with an explicit list of topics such as prices, warranty, delivery, and leasing. It is distinct from machine search or pricing tools, though it does not explicitly name sibling tools for 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 description gives practical usage guidance: pass a query for search, and omit it to get the full FAQ. However, it does not explicitly state when to prefer this tool over siblings like ask_manager or compare_machines, so alternative selection is 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 declare the tool read-only and idempotent. The description adds useful behavioral context by noting that fractional IDs like '1.1' are supported and by listing the broad set of data returned, which goes beyond the structured annotations.

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

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

The description is a single dense sentence with the purpose front-loaded and the returned data arranged in a clear colon-separated list. It contains no filler and does not repeat annotation facts.

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

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

With one required parameter, full schema coverage, an output schema, and annotations covering read-only and idempotent behavior, the description supplies all needed call context. It covers the ID format and the full scope of returned data, leaving no critical gaps.

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

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

The schema already fully documents id as product_number, so the baseline is 3. The description adds the important detail that fractional IDs such as '1.1' are accepted, which is not present in the schema and helps prevent incorrect calls.

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 a complete machine card for a product_number and enumerates the content: characteristics, price in RUB/USD, images, options, 3D models, video, and URL. This distinguishes it from siblings like get_machine_images or calculate_machine_price, even without naming them.

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 strongly implies when to use the tool: when a full machine card is needed by product_number. It does not explicitly name alternatives or exclusions, but the enumerated return fields make the boundary with narrower sibling tools evident.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds that images are high-resolution and include both gallery and cover versions, which is useful content context. However, it does not disclose other behaviors such as response format or error handling, so it provides only moderate added value beyond annotations.

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

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

The description is a single concise sentence that immediately states the core content and purpose. There is no filler or redundancy; every phrase contributes meaningful information.

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

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

The tool is simple (one parameter, read-only) and has an output schema (not shown but indicated), so return structure is documented elsewhere. The description covers what images are included and their intended use, which is sufficient for an agent to invoke correctly. Minor gap: it does not explicitly state that 'id' refers to a machine identifier, but this is inferable from the tool name and sibling context.

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

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

Schema description coverage is 0%, so the parameter 'id' has no schema-level explanation. The description does not mention the id at all, leaving the agent to infer it refers to a machine identifier from the tool name. This fails to compensate for the missing schema description, making the parameter semantics unclear for an agent unfamiliar with the domain.

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 (machine images) with modifiers (high resolution, gallery + cover) and enumerates use cases (cards, comparisons, publications, presentations). This clearly distinguishes it from siblings like get_machine_detail or search_machines, which serve 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 gives clear context on when to use the tool by listing concrete use cases (cards, comparisons, publications, presentations). It does not explicitly mention alternatives or exclusions, but the stated purpose is sufficiently directive for an agent to infer appropriate usage.

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, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds that the response includes category names with model counts and example categories, which is meaningful behavioral 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?

A single sentence that is dense and information-rich, front-loading the core action and result before giving examples. Every phrase earns its place without unnecessary elaboration.

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, read-only listing tool with an output schema and comprehensive annotations, the description is complete. It tells the agent what the tool returns, what the data represents, and how it fits the catalog overview, so nothing critical is missing.

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

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

The tool has zero parameters, so parameter semantics are not applicable. Baseline 4 is appropriate because the description doesn't need to compensate for any schema gaps; there is nothing for an agent to misunderstand.

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 factory machine categories with model counts. It also gives concrete examples (milling, laser, plasma, stone-cutting, turning), which clearly distinguishes it from sibling tools that search or compare individual machines.

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 'быстрый обзор ассортимента' (quick overview of the assortment) communicates the intended use case of browsing available categories. It doesn't explicitly rule out alternatives, but the tool is clearly the sole category-listing operation among siblings, making the usage context strong enough.

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

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

The annotations already mark this as read-only and idempotent. The description adds context beyond that: it is a full-text search, it returns a markdown version plus a text fragment, and it identifies the authoritative source. No contradiction with the annotations is present.

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

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

Three short sentences with no filler; the core action, scope, return components, and source are all front-loaded. It is tight and readable, missing only an explicit sibling pointer that would make it exceptional.

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 low parameter count, the rich annotations, and the presence of an output schema, this description is nearly sufficient for safe invocation. The only meaningful gap is the lack of explicit sibling distinction versus search_machines.

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 both parameters completely (100% coverage), so the baseline is met. The description adds semantic value by enumerating the searchable domains and formats, helping the agent formulate better query terms than the schema description alone.

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

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

The description names a specific verb and resource ('Полнотекстовый поиск по обучающим курсам завода') and lists the topical scope (фрезы, механика, электроника, Mach3, ArtCAM, etc.). It is clear and precise, though it does not explicitly contrast with sibling tools like search_machines.

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 domain and the example queries in the schema imply when this tool is appropriate: technical questions about factory training materials and guides. However, the description itself does not state when not to use it or name alternatives, so the routing guidance is 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 declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds that the tool returns a list of machines with specific fields, which is helpful, but it does not disclose any additional behavioral traits like pagination, error handling, or result ordering. This is acceptable given the annotations, so a 3 is appropriate.

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 plus an example. It front-loads the core purpose, then specifies the output fields, and closes with a concrete usage example. There is no redundancy or unnecessary detail, making it highly efficient.

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

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

With an output schema present, the description doesn't need to explain return values in detail, yet it still lists the key returned fields. It covers the main search criteria and provides an example, which is sufficient for an agent to call the tool. Minor gaps include not mentioning the 'q' and 'limit' parameters explicitly, but those have schema descriptions. Overall, it's complete for a search tool of this complexity.

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

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

Schema description coverage is 50% (q, limit, material, working_area have descriptions). The description compensates by stating that search is by type, material, working area, category, and price, thereby adding meaning to type, category, max_price, and min_price. The example further illustrates valid values. However, it does not fully detail each parameter's accepted values or formats, leaving some gaps.

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

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

The description clearly states the tool's purpose: searching CNC machines by type, material, working area, category, and price. It also specifies the return fields (id, name, price, working area, spindle, link) and provides a concrete example, making it easy to distinguish from sibling tools like get_machine_detail or calculate_machine_price.

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 says 'Первый шаг подбора' (first step of selection), which gives clear usage context but does not mention any alternatives or when not to use this tool. It doesn't compare itself to get_machine_detail, compare_machines, or other siblings, so an agent lacks guidance on routing between them.

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

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

The description goes beyond annotations by disclosing that the lead enters the CRM and a manager Telegram chat, that an API key is required via header or argument, and that client consent for contact processing must be confirmed. This is very useful behavioral context for a write operation, especially since readOnlyHint is false and idempotentHint is false.

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 concise sentences front-load the verb, resource, and required fields, then add auth, destination, and compliance guidance. There is no filler or repetition of schema contents.

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 auth, consent, destination, and required/optional input in a compact way. An output schema exists, so return values need no explanation. The main gap is the ambiguous mapping of 'model' to machine_id and the implied requirement of phone/email that conflicts with 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?

With 0% schema description coverage, the description must compensate, and it does partially: it explains name, phone/email, comment, API key, and references a model. However, it does not map 'модель' to the actual machine_id parameter, and it suggests phone/e-mail are required while the schema marks them optional. This leaves room for misinterpretation.

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: 'send an application to the factory manager' with required and optional fields. It is clearly distinct from sibling tools like ask_manager or subscribe_to_factory_events, since it describes a lead submission rather than a general question or subscription.

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 practical conditions: name is required, phone/email are expected, API key is needed, and client consent must be confirmed. However, it does not explicitly contrast this tool with alternatives such as ask_manager or subscribe_to_factory_events, so an agent must infer when this tool is preferred over those.

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

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

Annotations already flag non-readonly, open-world, and non-idempotent behavior; the description adds that the factory will send POST events and names the event types. It does not cover retries, duplicates, or subscription lifecycle, but these are secondary given the annotation coverage.

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 with front-loaded action and resource, a compact list of event types, and a closing purpose statement. Every sentence earns its place.

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

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

With an output schema present and only three simple parameters, the description covers the essential call: what events to subscribe to and where the webhook is delivered. It is slightly incomplete on agent_id semantics and subscription lifecycle, but sufficient for a basic correct invocation.

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

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

The description clarifies webhook_url (HTTPS POST endpoint) and event_types (price_change, new_birzha_order, stock_update) beyond the schema. However, agent_id is neither described in the schema nor in the description, and schema coverage is only 67%, leaving a real gap.

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

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

The description uses a specific verb-resource pair: 'Подписать ИИ-агента на webhook-события завода' (subscribe an AI agent to factory webhook events), and enumerates the three event types. This clearly differentiates it from sibling read tools like get_birzha_orders and search_machines.

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 intended usage context: the agent uses this so factory data stays current ('Так агент держит данные завода актуальными'). It does not explicitly name alternatives or exclusions, but the push-vs-poll context is clear.

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