Zavod Stanki CNC Catalog

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

Adds substantial context beyond the annotations: API key is optional, a public mode exists with a 2-questions-per-hour-per-IP rate limit, and the answer is delivered out-of-band to the supplied contacts. It still does not say what happens on rate-limit failure or whether a request record is created, but the rate limit and delivery channel are genuinely useful disclosures.

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 dense sentences, no filler: purpose first, then operational constraints, then the parameter instruction. Every clause 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?

An output schema exists, so return values need not be described, and the description covers auth mode, rate limit, and delivery. The one incomplete area is contact-field requirements, since only 'question' is marked required in the schema and the description implies contacts are needed without stating the rule.

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 carry the burden, and it does: it marks api_key as optional and explains that name plus phone/e-mail are the delivery channels. It stops short of saying whether at least one contact field is required or what format is expected, leaving a gap across the 5 params.

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

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

States a specific verb and resource ("Задать вопрос менеджеру завода") and immediately scopes it with example topics (non-standard configuration, special conditions, deadlines, leasing), which separates it from get_faq and submit_lead 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?

Gives clear when-to-use context through the enumerated topic list (non-standard build, special terms, lead times, leasing). It does not explicitly exclude the FAQ tool or say when to prefer submit_lead, so the alternative routing is left implicit.

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

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

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?

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety/behavioral profile is covered structurally. The description adds useful domain disclosure — that this is authoritative 'unique factory data' and which topics it covers — but says nothing about freshness, caching, or fallback behavior when a region is unavailable. With annotations carrying the main load, this is adequate but not rich.

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

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

Two dense sentences with the region list and covered topics front-loaded; no wasted preamble. The trailing clause about 'unique factory data' is slightly promotional but still earns its place as a trust/source signal.

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 optional parameter at full schema coverage, an output schema handling return values, and annotations covering read-only/idempotent behavior, the description supplies what remains: what data is inside and which regions exist. Only the routing story (vs get_faq/ask_manager) is left implicit.

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

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

Schema description coverage is 100%, so the region parameter and its valid values (ru/kz/by/uz, ru default) are already documented. The description repeats the region codes and adds 'дальнее зарубежье' (far abroad), which slightly muddies semantics since the schema enum has no such value — marginal value over structured data.

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

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

The description states a concrete resource (delivery/export conditions for Twait factory machines) and enumerates the payload (lead times, customs, ST-1, documents, far abroad) plus the four supported regions. It is clearly a regional reference lookup, though it does not explicitly contrast itself with siblings like get_faq or get_company_info that could plausibly cover overlapping topics.

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: 'Уникальные данные завода для расчёта клиенту' hints this feeds client price calculation (alongside calculate_machine_price), but there is no explicit when-to-use, when-not-to-use, or named alternative. An agent can infer the context but gets no routing guidance.

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

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

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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safe-read profile is covered. The description adds two useful facts beyond that — the 200 KB payload limit and the shape of the analysis (statistics, errors, recommendations, savings estimate). It does not say how malformed or oversized G-code is handled, nor whether the analysis is deterministic or model-generated, so it adds context without being rich.

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

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

The entire definition is a single front-loaded sentence that leads with what the tool is and what it returns, with the size constraint appended last. It is dense and unusual to read, but every clause carries information and there is no filler.

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

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

An output schema exists, so return values need not be spelled out, and annotations cover the safety profile for a 2-parameter tool. The description supplies the payload limit and the nature of the analysis, leaving only minor gaps such as error behavior on invalid input.

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 (gcode, machine) are already documented with types, requiredness, and the 200 KB limit. The description restates the size cap but adds nothing about the optional machine-model parameter or how it influences the analysis, so the baseline of 3 applies.

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

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

The description names a specific verb+resource pair (analysis/optimization of a CNC control program) and enumerates the concrete outputs: statistics (lines, moves, feeds), typical errors, AI-driven optimization recommendations, and a savings estimate. No sibling tool (machines, orders, guides, leads) does anything comparable, so an agent can route to it unambiguously without opening the schema.

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

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

Usage is only implied: 'if you have G-code, send it here for analysis.' There is no explicit when-to-use, when-not-to-use, or prerequisite/permission statement, and no alternatives are named. The 200 KB input cap is the only boundary given, and it functions as a constraint rather than selection 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?

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?

While annotations cover the fundamental safety profile (readOnlyHint: false), the description adds key operational behaviors that are missing from structured data, such as the downstream effects (CRM and Telegram integration) and the rate limit logic based on API key usage.

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 highly efficient, front-loading the main action and then providing necessary operational detail (API limits and downstream delivery). It avoids fluff, though the single dense paragraph could be slightly broken up for maximal readability.

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 definition is highly complete for an invocation tool. It tells the agent exactly what data is needed, what success looks like (submission to CRM/Telegram), and what operational limits apply (rate limits/consent requirement).

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?

Since schema description coverage is 0%, the description must define parameters. It successfully defines required parameters (name + contact), optional parameters (model, comment), and the functional purpose of the API key parameter (access level/limits).

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 purpose is stated clearly and concisely in the title and description: 'Отправить заявку менеджеру завода' (Submit lead to factory manager). Given the sibling tools are mostly for retrieval or calculation, this action-oriented submission tool is easily distinguished.

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 provides critical usage rules, such as the required fields (name + contact) and operational constraints (API key mode and rate limits). Most importantly, it mandates a compliance step: confirming client consent for data processing.

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.