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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to repeat that. It adds meaningful behavioral context: the MCP-server throttling (1 request per 60 seconds) and a caching recommendation, plus the response grouping per-organization. This goes beyond annotations and gives the agent practical operational knowledge.

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 three concise sentences: purpose, dependency, and throttling/caching. Each sentence earns its place with no redundant wording, 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 simple read-only tool with a single request object, the description covers the purpose, the source of required IDs, the rate limit, and caching advice. The response grouping is also noted. Missing explicit response format details are minor since annotations already convey safety, and the schema covers parameter definitions.

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 mentions that organizationIds can be obtained from organizations__get_organizations, which is a more actionable pointer than the schema's reference to the raw API operation. However, it does not elaborate on includeDeleted or other parameter nuances. Since schema coverage is 0% and the schema itself already documents both parameters, the description partially compensates with the source hint but not fully.

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

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

The description states 'Города организаций' (Cities of organizations) with the added detail that the response is grouped per-organization. This clearly identifies the resource and distinguishes it from sibling tools like addresses__get_regions and addresses__get_streets_by_city. The verb and resource are specific, making the tool's purpose 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 provides a dependency hint by pointing to organizations__get_organizations for obtaining organizationIds, which is actionable usage guidance. However, it does not explicitly state when to use this tool over alternatives or when not to use it, so the guidance is partial.

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

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

Beyond the readOnly/destructive annotations, the description discloses a precise operational constraint: MCP-server throttling is limited to 1 request per 60 seconds, distinguished from iikoCloud limits, and it advises caching results. This is high-value behavior an agent must know before invoking the tool.

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

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

Three short sentences cover purpose, parameter source, and rate-limit/caching guidance. Each sentence adds distinct value, and the most important information 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 simple read-only one-parameter tool, the description covers purpose, parameter acquisition, and a critical rate limit. It does not describe the exact return shape, and no output schema exists, but the absence is minor given the tool's simplicity.

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 schema description coverage is 0%, the description compensates by explaining where the single parameter organizationIds comes from via organizations__get_organizations. It does not restate the array/UUID format, but for one parameter the source mapping is the most important missing semantic.

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

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

The description names the resource and scope: 'Регионы (районы) организаций' (regions/districts of organizations), so an agent can infer the tool returns region data for given organizations. It lacks an explicit verb and does not contrast with sibling address tools, but it is still specific and unambiguous enough to be useful.

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

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

The description gives concrete usage context: where to get organizationIds ('organizationIds → organizations__get_organizations') and instructs caching because of MCP-server throttling. It does not state explicit exclusion or alternative conditions, but the provided 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.

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

Annotations already mark this as read-only/non-destructive. The description adds an explicit rate-limit notice (1/60s) and advises caching the result, which are non-obvious behavioral traits beyond the structured annotations. It doesn't describe return format, but that's less critical for a lookup.

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

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

Two short sentences, each with a distinct job: state scope, give ID sources, and warn about throttling. No filler.

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

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

For a simple lookup tool, the description covers scope, parameter provenance, and an important rate limit. Still, without an output schema, it never states the return shape (e.g., list of street names/IDs), and doesn't mention includeDeleted semantics, leaving the agent with minor uncertainty.

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 source instructions for the two required IDs, which is genuinely useful given the schema has no top-level descriptions. However, it doesn't clarify the nested request wrapper or the includeDeleted parameter, so it only partially compensates for the 0% schema description 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?

Description states the resource ('streets of city') and a key constraint ('single organization_id'), which is more specific than the name alone. It does not use an explicit verb, and it doesn't directly differentiate from addresses__get_streets_by_id, but the ID-sourcing hints and the 'single organization_id' qualifier give enough signal.

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

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

It explains where to obtain cityId and organizationId, and the single-organization qualifier hints at a use case. However, it never explicitly contrasts with alternatives like addresses__get_streets_by_id or tells the agent when to prefer this tool, so routing is left mostly to the name.

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 destructiveHint=false. The description adds substantial behavioral context beyond that: an MCP-specific rate limit (1 request per 60s), a caching recommendation for dialog use, and a note that correlation_id in the response is optional. This is exactly the extra context that helps an agent plan calls.

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 Russian sentences, each earning its place: purpose, ID provenance, and operational constraints (throttling/caching). 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?

Combined with the schema and annotations, the description covers safety (read-only) and key operational constraints (rate limit, caching). But it does not describe the return shape (no output schema exists) or clarify whether at least one of ids/classifierIds should be supplied when both are nullable. These are meaningful gaps for a tool with a nested request object.

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 mentions ids, classifierIds, and points to how to source organizationId, partially mapping to the schema's inner fields. However, schema description coverage is 0% at the top-level 'request' parameterwaters, and the description does not explain how to structure the wrapper request (e.g., that organizationId is required while ids and classifierIds are both nullable alternatives). It partially compensates but leaves the relationship between parameters ambiguous.

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

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

The description states the resource ('streets') and the lookup keys ('ids or classifierIds'), which distinguishes it from sibling tools like addresses__get_streets_by_city. It lacks an explicit verb, but the tool name supplies 'get'. The optional correlation_id note adds minor scope clarification.

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?

No comparison with alternatives such as addresses__get_streets_by_city or guidance on when to prefer this tool. The only usage advice is a provenance chain for organizationId (organizations__get_organizations) and a throttling/caching tip, which are operational but not decision-oriented.

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 destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond annotations: a concrete MCP-server throttle limit (20 requests per 60 seconds) and a caching recommendation. This is valuable operational transparency, though it does not describe response contents or pagination.

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 with no filler. It front-loads the purpose, then gives the ID source, then the throttling/caching constraint. Every clause earns its place and the information is 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?

For a read-only listing tool, the core is covered: purpose, ID source, and throttling/caching. But it lacks explicit usage guidance, an explanation of the required 'request' object structure, and any indication of the output format (no output schema exists). It is adequate but leaves several gaps an agent must resolve via schema or trial.

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 meaning to organizationIds by pointing to organizations__get_organizations as the source of IDs. However, it does not explain the required 'request' wrapper object or the other nested fields (includeDisabled, returnExternalData, returnAdditionalInfo). With schema description coverage reported at 0% for the top-level parameter, the parameter semantics are under-specified.

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 resource (organizations) and the scope ('available for reservation') in the opening phrase. It also references organizations__get_organizations as the source for IDs, which helps differentiate it from the general organizations tool. However, it uses a noun phrase rather than an explicit verb like 'get' or 'list', so it is clear but not maximally explicit.

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

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

There is no guidance on when to use this tool versus alternatives or when not to use it. The description only provides an ID-source pointer (organizations__get_organizations) and throttling/caching advice. Usage is implied by the purpose but never explicitly stated, and no sibling or alternative tools are mentioned.

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 destructiveHint=false, so the description is not required to repeat that. It adds valuable behavioral context: the MCP server throttling (20 requests per 60 seconds) and the recommendation to cache results in the dialog. This goes beyond annotations and helps agents plan calls safely.

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: purpose, parameter provenance, and throttling advice. The information is front-loaded and every sentence contributes critical operational context. 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?

The description covers the main purpose, points to the ID source, and warns about rate limits, which is good for a read-only tool. However, it does not mention the 'returnSchema' parameter's effect on the output shape (despite the description claiming 'with table layout') and does not describe the response format (no output schema exists). This leaves some ambiguity for an agent about what fields to expect and how to toggle layout information.

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% from the description text, so the description must compensate. It only addresses terminalGroupIds by pointing to the sibling tool for getting the IDs, which adds value. However, it does not explain 'revision' or 'returnSchema' (which controls the table layout output mentioned in the description). The schema's own property descriptions carry that burden, but the description does not fully compensate for the 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 states the resource clearly: 'Секции (залы) ресторана со схемой столов' (restaurant sections/halls with table layout). Although it lacks an explicit verb, the intent is unambiguous and it distinguishes from generic 'get sections' by mentioning table layout. It is not a tautology and adds specific meaning.

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 a prerequisite pointer for obtaining terminalGroupIds ('Где взять ID: terminalGroupIds → terminal_groups__get_terminal_groups') but does not explain when to choose this tool over alternative banquet tools (e.g., banquets__get_restaurant_sections_workload). No exclusions or alternative comparisons are given. The guidance is about input preparation, not 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 the operation read-only and non-destructive. The description adds genuinely useful behavioral context: MCP-server throttling (no more than 20 requests per 60 seconds), explicitly distinguishing it from the iikoCloud limit, and instructing the agent to cache results in the dialog.

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 consists of three short, purposeful sentences: purpose first, then ID sourcing, then throttling/caching advice. There is no filler, and the most important operational constraint is both explicit and actionable.

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

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

For a simple read-only ID lookup, the description covers the operation, how to obtain the organization ID, and the server rate limit. It does not describe the exact response shape or where reserveIds come from, but the schema and annotations cover the remaining structural requirements.

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% top-level schema description coverage, the description must compensate for parameter documentation, and it partially does: it maps organizationId to organizations__get_organizations and implies that reserveIds are the identifiers being queried. However, it does not explain sourceKeys or the nested request structure fully, so the compensation is incomplete.

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 operation clearly: it returns reserve statuses for the supplied identifiers ('Статусы резервов по их идентификаторам'). It is specific about the resource and lookup key, but it does not name or contrast sibling banquets lookup tools, 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 description does not explain when to choose this tool over sibling banquets tools such as get_reserve_available_organizations or get_reserve_terminal_groups. It only gives a prerequisite hint about obtaining organizationId from organizations__get_organizations, which is not 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds a specific MCP-server throttling limit (20 requests/60s) and advises caching the result in the dialogue, which is useful operational behavior 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 sentences, each with a distinct purpose: what the tool returns, how to get input, and a usage constraint. The most important information is front-loaded, 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?

For a single-parameter read-only lookup, the description covers the return subject, input sourcing, and an operational constraint (caching/throttling). It doesn't describe the output structure, but with no output schema and low complexity, this is acceptable especially given the annotations.

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

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

Schema description coverage is 0% at the top level, but the description compensates by mapping organizationIds to the sibling tool organizations__get_organizations, telling the agent exactly where to obtain valid IDs. It reinforces the nested schema's own note, adding a direct MCP-level pointer.

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 resource ('terminal groups of organizations') with the key qualifier 'available for reservation', which distinguishes it from the generic terminal-group siblings like terminal_groups__get_terminal_groups. It uses a noun phrase rather than an explicit verb, but the intent 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 implies a reservation use case via 'available for reservation' and gives a concrete prerequisite: where to obtain organizationIds (organizations__get_organizations). It does not explicitly contrast this tool with generic terminal-group tools or state when not to use it, leaving some ambiguity.

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 discloses a key behavioral trait: the MCP-server throttling limit (no more than 20 requests per 60 seconds) and advises caching the result. This goes beyond the annotations (readOnlyHint, destructiveHint) by adding operational constraints. It does not contradict the annotations; readOnlyHint aligns with the read-only nature implied. The description could also mention what happens if the limit is exceeded, but the current disclosure is valuable and specific.

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 extremely concise, consisting of two short sentences. It front-loads the primary purpose and immediately adds the critical throttling constraint, which is essential for proper usage. There is no redundant or filler content; every word contributes to the tool's understanding. This is a model of efficiency for a tool description.

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

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

The tool is a read-only query with no output schema, so the description should explain what the returned workload data looks like or how to interpret it. It does not. It also omits any explanation of the parameters beyond the schema's own descriptions, and it does not clarify the meaning of 'workload' (e.g., occupancy, reservations count, capacity). Given that the tool has multiple parameters and no output schema, the description is insufficient for an agent to call it correctly without external knowledge.

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 description coverage is 0% — the tool description provides no explanation of the parameters (dateFrom, dateTo, restaurantSectionIds). While the input schema itself contains descriptions for each parameter, the description does not compensate for the low coverage. It adds no extra meaning about parameter formats, defaults, or how they relate to the workload query. The description's mention of 'from the specified date' loosely refers to dateFrom but does not clarify dateTo or the ID collection.

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 tool's purpose clearly: 'Загруженность секций ресторана с указанной даты' (Restaurant sections workload from the specified date). It identifies the resource (restaurant sections) and the action (retrieve workload), which distinguishes it from sibling tools like banquets__get_reserve_restaurant_sections (which deals with availability, not workload). However, it does not explicitly name the verb 'get', though the tool name implies it, and it lacks a direct statement of what the returned data represents beyond 'workload'.

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 no guidance on when to use this tool versus alternatives. It does not mention any sibling tools or conditions that would make this the appropriate choice. It only offers operational advice (throttling and caching), not usage context. This is a significant gap, as the agent must infer the tool's place among many related banquet and reservation 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?

Beyond the readOnly and destructive annotations, the description adds critical throttling information (1 request per 60 seconds) and advises caching the result in the dialog. This goes beyond what annotations provide and helps the agent avoid rate-limit errors.

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 no waste. It front-loads the purpose, then the ID source, then the throttling note—all essential information in logical order.

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

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

For a simple read-only list tool, the description covers purpose, ID sourcing, and throttling. It doesn't describe the return structure, but 'Все категории' implies a list of categories, which is sufficient given the lack of an output schema.

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

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

Schema coverage is 0%, but the description compensates by telling the agent exactly where to get the organizationId value (organizations__get_organizations). This adds meaning beyond the bare UUID type 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?

The description clearly states it returns all customer categories for an organization ('Все категории гостей организации'), specifying both the resource and scope. It distinguishes itself from sibling tools by being the only one focused on customer categories, and it is not a tautology of the name.

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 guidance on where to obtain the required organizationId (from organizations__get_organizations), which is a key usage step. It doesn't compare to alternative tools, but none exist for this specific purpose, so the guidance 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 indicate readOnlyHint=true and destructiveHint=false. The description adds a valuable behavioral trait beyond annotations: it is a wrapper with no own throttling but consumes the underlying API quota, and advises caching the result in the dialog. This gives actionable rate-limit and caching context.

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

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

Two sentences with no filler. The first states the core function, the second delivers the behavioral warning and caching recommendation. Every word earns its place.

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

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

For a simple two-parameter read-only lookup, the description covers the purpose and a key behavioral constraint, but it omits parameter semantics and any indication of return value structure. Since no output schema exists, the agent is left to infer what the returned customer object looks 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?

Schema description coverage is 0%, so the description must compensate for missing parameter details. It does not: card_number is only labeled as the loyalty card number (redundant with the property name), and organization_id is not explained at all. No format, constraints, or purpose are added.

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: 'Получить клиента по номеру карты лояльности' (get customer by loyalty card number). This clearly identifies the verb, resource, and lookup key, distinguishing it from siblings like get_customer_by_phone or get_customer_by_id.

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 does not provide explicit when-to-use or alternative guidance. The usage context is implied by the tool name and purpose statement, but no direction is given for choosing between this and sibling customer lookup 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 declare readOnlyHint=true and destructiveHint=false. The description adds that the tool is a thin wrapper with no throttling of its own and that calls consume quota from the underlying API, recommending caching in the dialog. This is valuable 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?

The description is two sentences long, with the primary purpose first and the operational note second. No unnecessary words; each sentence adds relevant information.

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

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

For a simple read-only lookup with two parameters and no output schema, the description covers the purpose and one operational caveat (quota usage). However, it does not describe the return payload or clarify the precise format of card_track, leaving some gaps for an agent that needs to parse the result.

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 has no descriptions and the description does not explain the parameters either. The names 'card_track' and 'organization_id' are somewhat self-explanatory, but the expected format of 'card_track' (e.g., raw magnetic stripe data, track 1/2/3) is not specified, so the description does little to compensate for the 0% 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 states a clear action: retrieving a customer by the card's magnetic stripe. It is distinguishable from sibling tools that look up by phone, id, email, or card number, though the difference from 'by_card_number' is not explicitly spelled out.

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 no guidance on when to choose this tool over alternatives like customers__get_customer_by_card_number, by_phone, or by_id. It only gives operational advice about caching and quota usage, which does not help with tool 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?

Beyond the already-provided readOnlyHint=true and destructiveHint=false annotations, the description discloses that this is a wrapper with no own throttling but consumes the underlying API method's quota, and explicitly recommends caching results in the dialogue. This is concrete operational context that annotations do not cover.

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 redundancy: the first states the purpose, the second adds an operational caveat. The description is front-loaded and 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 simple get-by-email tool, the description covers the core purpose and the quota/caching behavior. However, it omits the role of `organization_id` and gives no hint about the return value or error semantics, which matters given the absence of an output schema and zero parameter coverage. It is minimally workable but has clear 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?

Schema description coverage is 0%, so the description must compensate for both parameters. It clarifies that `email` is the lookup key, but `organization_id` is left completely unexplained. The description adds minimal semantic value beyond the schema, leaving one of two required parameters underdocumented.

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: 'Получить клиента по email' (Get customer by email). This clearly distinguishes it from sibling lookup tools that search by phone, ID, card track, or other criteria. The purpose is immediate and 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 provides no guidance on when to choose this tool over alternatives like customers__get_customer_by_phone or customers__get_customer_by_id. It offers caching advice for the tool itself, but that is not selection guidance. The intended usage is implied but not explicitly contrasted with siblings.

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 readOnlyHint=true and destructiveHint=false, but the description adds significant behavioral insight: it is a wrapper with no own throttling, yet consumes the underlying API's quota. It also advises caching results in the dialogue. This goes beyond annotation data and helps the agent plan calls safely.

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 extremely concise: two sentences, with the core purpose front-loaded and the behavioral note placed after. Every word adds value, with no repetition or filler. It is structurally optimal for quick agent parsing.

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 get-by-id tool with low complexity, the description covers purpose and a key behavioral caveat. However, it omits meaning for organization_id and does not describe the return value or any pagination/error behavior (no output schema exists). An agent could call it, but might misuse organization_id or misinterpret the response.

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 for both parameters. It only clarifies customer_id as 'loyalty customer id'; organization_id is not mentioned at all. The description does not explain the role or format of organization_id, leaving a significant gap in parameter understanding.

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 operation: 'Get a customer by ID (loyalty customer id)'. It names the exact resource (customer) and the identifier type (loyalty customer id), distinguishing it from sibling lookup tools that use phone, email, or card track. This makes the purpose unambiguous and differentiable.

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 only implies usage: when you have a loyalty customer ID. It does not explicitly state when to use this tool versus alternatives like get_customer_by_phone or get_customer_by_email, nor does it provide conditions or exclusions. The caching advice is operational guidance, not tool-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 description goes beyond the annotations by disclosing that the tool is a wrapper with no own throttling but consumes the underlying API's quota, and advises caching the result in the dialog. This is valuable operational context that annotations (readOnlyHint=true, destructiveHint=false) do not cover. It does not describe return behavior, but given the safety annotations are already present, this extra context earns a high score.

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

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

The description is concise: a single sentence for purpose plus a second sentence for behavioral advice. It is front-loaded with the core action and adds only essential context. No unnecessary fluff. This is efficient and well-structured.

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

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

For a tool with only two parameters and no output schema, the description covers the purpose and some behavioral nuances but omits parameter semantics (especially organization_id) and does not clarify what exactly is returned (though this is implied by the name). The caching advice is useful, but the missing parameter explanation makes it incomplete for a fully informed call.

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 for parameter meaning. It only mentions the phone number in the purpose, but does not explain the organization_id parameter, its format, or why it is required. The schema itself provides no descriptions, leaving the agent without adequate understanding of the second parameter. This is a significant 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 clearly states the action and resource: 'Get customer by phone number'. It is specific and distinct from sibling tools like get_customer_by_id, get_customer_by_email, and get_customer_by_card_track. However, it does not explicitly mention the organization scoping (which appears in the parameters), so it is slightly less than perfectly clear.

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 no guidance on when to use this tool versus the many sibling customer lookup tools. It does not mention that this is the appropriate choice when only a phone number is available, nor does it explain alternatives or exclusions. The agent must infer usage from the name alone.

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 destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: MCP-server throttling (100 requests per 60s) and a caching recommendation, which goes 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?

The description is structured with Args/Returns and separate notes, making it easy to scan. It front-loads the purpose and adds relevant operational advice (throttling, caching) without excessive verbosity. Minor redundancy in the Returns line, but overall 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?

Given the presence of many sibling tools and the nested request schema, the description is incomplete. It does not explain the structure of the request object (the required 'type' and optional 'organizationId'), nor does it clarify how it differs from the specific customer lookup tools. The throttling note is useful but does not compensate for the missing schema explanation.

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 lists possible identifier types (phone, id, email, card) but does not explain the required 'type' field or how these map to it. The 'organizationId' parameter is only hinted via the note about where to get it. This is inadequate for an agent to correctly construct the request object.

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 purpose: 'Get customer information' with a list of possible identifiers (phone, id, email, card, etc.). It identifies the resource and action distinctly, but does not explicitly differentiate from the specific customers__get_customer_by_* siblings, which limits it to a 4.

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

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

No guidance is provided on when to use this general tool versus the more specific customer lookup tools (by phone, by id, etc.). The description only mentions where to get organizationId and throttling/caching advice, which is operational context, not selection criteria.

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?

Read-only nature is already covered by annotations; the description adds a concrete MCP-server rate limit (10 requests per 60 seconds) and advises caching, which is useful behavioral context beyond the annotations. It does not cover response behavior, but that is less critical given the read-only 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 compact sentences with no fluff; the purpose is front-loaded, and the parameter/rate-limit notes are directly actionable. It could be slightly better structured but is 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?

Given the nested request and no output schema, the description is usable but incomplete: it covers the main inputs and rate limit, but does not explain guestIds or the shape/interpretation of the returned counters.

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

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

With schema description coverage at 0%, the description compensates partly by explaining the metrics and periods enums and telling users where to get organizationId. However, it omits guestIds and does not describe the request wrapper, leaving a clear 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 identifies the resource as guest loyalty counters with order counts/sums by period, which is specific enough to distinguish from generic customer info tools. However, it is a noun phrase without an explicit verb and does not name sibling differentiators.

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 operational guidance—where to obtain organizationId and a throttling/caching recommendation—but it does not explicitly address when to prefer this tool over siblings or state 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 mark this as read-only/non-destructive. The description adds valuable behavior beyond annotations: dates are in local terminal time, data availability is guaranteed for 7 days, the tool is a wrapper consuming underlying API quota, and caching is recommended. This is strong additional transparency, though it omits details like pagination.

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 with no filler. The first front-loads the purpose, the second bundles three important operational constraints efficiently.

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 critical operational details (timezone, availability, caching) and indicates a flat list result, but it does not describe return fields or the semantics of organization_ids. Given there is no output schema, this leaves the agent partially under-informed.

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 for parameter documentation. It indirectly explains 'phone' and 'last N days', but never mentions the required organization_ids parameter nor the days parameter's default of 7. This leaves a key parameter undocumented.

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: retrieve customer orders by phone over the last N days as a flat list. It is clear about the tool's scope, but it does not distinguish it from closely related siblings like deliveries_retrieve__get_deliveries_by_delivery_date_and_phone or deliveries_retrieve__get_delivery_history_by_date_and_phone.

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 operational advice (cache results, quota consumption, 7-day availability) but gives no explicit guidance on when to choose this tool over alternatives. With many similar deliveries_retrieve siblings, the lack of selection criteria is a significant gap.

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 destructiveHint=false, so the description doesn't need to restate safety. It adds valuable context about the 7-day data availability guarantee and the throttling constraint (10 req/60s), which are not in the annotations. However, it doesn't mention response size, pagination behavior, or rate limit specifics beyond the basic guidance, so it adds some but not rich behavioral context beyond what annotations already cover.

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

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

The description is concise (about 3 sentences) and front-loads the key purpose and scoping constraint. The instruction to get IDs and the throttling note are useful, but the throttling detail is somewhat buried at the end. Overall, it's efficient with no fluff, but the parameter guidance is missing, which the conciseness cannot fully compensate for.

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

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

Given the tool's complexity (many optional parameters, no output schema, no schema descriptions for parameters), the description is incomplete. It lacks guidance on how to use the filter parameters effectively, what date formats to use, the meaning of startRevision, and the impact of rowsCount/sourceKeys. The annotation says read-only, so the destructive risks are covered, but the operational details are missing. An agent would struggle to correctly fill the request object without additional knowledge.

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%, meaning the schema provides no descriptions for individual parameters (only the request wrapper is described). The description mentions phone, dates, and revision but does not explain the full set of parameters (rowsCount, sourceKeys, startRevision, deliveryDateTo). For a tool with many optional parameters and zero schema descriptions, the description should compensate by explaining key parameters and their formats (e.g., date format, UUID for organizationIds). This is a significant 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 clearly states the tool retrieves orders by phone number and date range, and mentions 'revision' as a secondary search mode, distinguishing it from sibling tools like get_delivery_by_id and get_deliveries_by_delivery_date_and_status. It also provides a critical scoping detail: the guarantee is only for the last 7 days, which clarifies the tool's core purpose.

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

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

The description explicitly tells where to get organization IDs (via organizations__get_organizations), which is essential for effective use. It also notes the throttling limit and advises caching, which guides usage behavior. However, it does not explicitly contrast with sibling tools like get_delivery_history_by_date_and_phone for older data, though the schema's deliveryDateFrom description hints at that alternative. The where-to-get-ID guidance is a strong use-case clarification.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description adds valuable behavioral constraints: a 10-requests-per-60-seconds MCP-server throttle, a caching recommendation, and the 7-day data availability guarantee. No contradiction with 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?

The description is three short sentences with no filler: purpose first, then the ID prerequisite, then the throttling/caching guidance. 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 retrieval tool, the description covers the key operational constraints and the organizationIds prerequisite, which is useful. It omits any comparison to nearby sibling tools and does not mention return or pagination behavior, but the annotations and schema provide enough for 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?

With schema description coverage reported at 0%, the description needed to compensate for undocumented parameters, but it only maps high-level filters (statuses/dates/couriers) and tells where to get organizationIds. It leaves date formats, courierIds semantics, statuses, and sourceKeys unexplained, which is weak compensation.

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 resource (orders) and the main filter dimensions (statuses, dates, couriers), which is concrete and specific. It is distinguishable from phone-based, revision-based, and single-ID delivery tools among the siblings, though it does not explicitly name an 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?

The description gives clear operational context: where to obtain organizationIds and a throttling/caching rule for repeated calls. However, it does not explicitly say when to prefer this tool over siblings like search_deliveries or get_deliveries_by_delivery_date_and_phone, so exclusions are missing.

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

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

Annotations already declare readOnlyHint=true, so no safety surprise. The description adds error conditions (ValueError on invalid input), the XOR constraint, and MCP throttling limit (10/60s) with caching advice. This adds useful behavioral 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?

The description is compact, with main purpose first, then error conditions, ID sources, and throttling. It's well-structured and front-loaded, with no fluff.

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 retrieval with a nested request object, the description covers the key constraints (XOR, max 200, error), ID sourcing, and rate limiting. Optional parameters are documented in schema, and no output schema exists, so completeness is adequate.

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 has detailed descriptions for parameters (orderIds, posOrderIds, etc.), but the description adds the XOR constraint, max 200, and where to get IDs. However, it doesn't cover all parameters (returnLockedByUser, returnExternalDataKeys) and relies on schema for those. Since schema coverage is low per context signal, the description only partially compensates.

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 retrieves orders by ID, with the XOR constraint and maximum 200. It doesn't explicitly differentiate from the sibling get_delivery_by_id (singular), but the plural and list usage make it distinct. The purpose is clear enough.

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 where to get IDs (from other tools), and mentions throttling/caching, but does not explicitly state when to use this vs alternatives like search_deliveries or get_delivery_by_id. The guidance is implied but not explicit.

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 safe read-only behavior, and the description adds meaningful context beyond that: the 3-hour revision window, MCP-server throttling at 10 requests per 60 seconds, and a caching recommendation for the dialogue. There is no contradiction with the readOnlyHint or destructiveHint 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 compact and front-loaded: purpose and window first, then ID sourcing, then rate-limit/caching guidance. Every sentence adds operational value, and there is no filler or repetition of the tool name beyond the minimal necessary context.

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

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

The description covers the core purpose, the window, the source of organization IDs, and throttling behavior, which is good for a read-only polling tool. However, it does not explain startRevision semantics, sourceKeys, or the response shape, and with no output schema the agent must infer these details from the parameter names alone.

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?

Given the reported 0% schema description coverage, the description carries a heavy burden for explaining parameters, but it only addresses organizationIds by pointing to organizations__get_organizations. The critical startRevision parameter and the optional sourceKeys parameter are not meaningfully explained beyond the generic phrase 'from revision'; an agent is left without enough detail to construct a fully correct request.

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's function: retrieving orders changed since a revision, with a 3-hour window and incremental polling. It distinguishes itself from the many sibling delivery tools by the revision-based mechanism, so an agent can immediately tell it apart from date-, phone-, status-, or ID-based retrieval 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 phrase 'incremental polling' and the 3-hour window imply when this tool should be used, and the pointer to organizations__get_organizations for organizationIds is helpful. However, there is no explicit statement of when to prefer this tool over alternatives or when not to use it, so the guidance remains implied rather than explicit.

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 destructiveHint=false, and the description adds valuable context: it is a wrapper with no own throttling, consumes the underlying API quota, and recommends caching. It also states the None-return behavior. This exceeds the baseline set by 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 sentences with no fluff. The core purpose is front-loaded, and the caching/quota note is a single addition. Every word earns its place.

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

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

For a simple get-by-id tool with 2 parameters and no output schema, the description covers the return behavior (None if not found) and the caching/quota aspect. It does not describe the structure of the returned order, but that is not required given the absence of an output schema. It is sufficiently complete for an agent to call 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 description coverage is 0%, and the description does not explain the parameters order_id or organization_id beyond the generic 'by id'. It fails to clarify that organization_id is required for scoping or that order_id is the primary identifier. The parameter names are self-explanatory, but the description adds no semantic value to compensate for the lack of 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 states a specific verb ('get'), resource ('delivery by id'), and behavior ('returns None if not found'), which clearly distinguishes it from the plural sibling get_deliveries_by_id. The singular nature is explicit in the text, making the purpose 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 does not explicitly contrast with sibling tools or state when to use this versus alternatives like get_deliveries_by_id or search_deliveries. Usage is implied by the singular 'by id', but no explicit guidance or exclusions are provided, leaving the agent to infer the appropriate context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral details beyond that: data retention (90 days), result size cap (rows_count ≤ 200), error behavior (ValueError for rows_count outside 1..200), and server throttling limits. This goes beyond the annotation's safety profile and discloses constraints and failure modes.

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 extremely concise—three lines in Russian. It front-loads the purpose, then packs constraints, error handling, ID sourcing, and rate limiting into a compact block. Every sentence carries essential information with no filler, 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?

Given the tool's simplicity (one nested request object) and the read-only annotation, the description covers the essentials: purpose, constraints, error conditions, ID sourcing, and throttling. It lacks an explicit mention of optional date filters or the revision parameter, but those are documented in the schema. The lack of an output schema means return format is not required, so the description is sufficiently complete for a competent agent.

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 provides guidance for rowsCount (range ≤ 200) and organizationIds (source via organizations__get_organizations), but it does not mention phone, deliveryDateFrom/To, sourceKeys, or startRevision. The schema itself has descriptions for these, but the description adds only partial value over the schema, missing several parameters.

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

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

The description clearly states the purpose: 'Order history by phone' (История заказов по телефону). It specifies the resource (order history) and filter (phone), and adds constraints (90 days storage, rows_count ≤ 200). It distinguishes from generic 'deliveries' tools but does not explicitly differentiate from the nearly identical sibling 'get_deliveries_by_delivery_date_and_phone', so it stops short of a 5.

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

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

The description provides concrete usage guidance: where to obtain organizationIds (organizations__get_organizations), a rate limit (≤10 requests per 60 seconds), and a caching recommendation. It does not mention when to use this tool over alternatives like the sibling 'get_deliveries_by_delivery_date_and_phone', so it lacks explicit exclusions but still offers actionable context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds a behavioral constraint beyond that: no more than 10 MCP-server requests per 60 seconds and advice to cache results. This is useful and does 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 front-load the purpose, then provide ID-sourcing and rate-limit guidance. Every sentence earns its place with no filler.

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

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

For a read-only search tool with one nested request object, the description covers the main purpose, parameter sources, and operational constraints. It does not describe the response shape, but the tool name and read-only annotations imply a list of deliveries, and the nested schema provides the remaining filter 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?

The description adds provenance for three key parameters (orderIds, organizationIds, terminalGroupIds) and names filter categories, which is helpful. However, the single top-level request parameter has no description in the schema per the coverage signal, and the description does not explain the request object structure or remaining fields such as deliveryDateFrom/To, rowsCount, or sourceKeys; the nested schema carries most of the semantic 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 states the verb ('search') and resource ('orders/deliveries') and names the key filters (text, statuses, problem, sorting). It is clear, but it does not explicitly contrast this tool with sibling tools such as get_deliveries_by_delivery_date_and_status, so an agent must infer the differentiation from the mention of text search.

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 actionable context: it tells where to get orderIds, organizationIds, and terminalGroupIds from sibling tools, and warns about the MCP-server throttle plus caching guidance. It does not state when not to use this tool or name alternatives, but the provided context is concrete enough to guide invocation.

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 destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond annotations: the exact response composition (is_allowed + allowed_items with durations + rejected_items with rejection codes) and a server-side throttle of 20 requests/60s that is explicitly distinguished from the iikoCloud limit, with a caching recommendation. 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?

Three sentences with no filler: purpose first, then response shape, then ID sourcing plus throttling/caching guidance. Each sentence earns its place and the most decision-relevant information is front-loaded. The structure is clean and scannable despite the density of 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?

Given a complex nested request schema, no output schema, and annotations covering safety, the description covers the essential ground: purpose, summarized response shape, ID sourcing, and rate-limit/caching behavior. Since there is no output schema, the response summary is especially valuable. Minor gaps remain (precise response structure, error behavior, date format), but the tool is adequately callable with this description.

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 carries the parameter-semantics burden. It compensates partially by mapping three key ID fields (organizationId, organizationIds, streetId) to their source tools and stating the core selection criteria (address/sum/date). However, it leaves other fields unaddressed — orderItems structure, the distinction between deliverySum and discountSum, deliveryDate format, and the required isCourierDelivery flag — which is a meaningful gap for a complex nested request.

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 purpose (identifying suitable terminal groups for a delivery address/sum/date) with a clear verb+resource. It further clarifies by naming the output fields (is_allowed, allowed_items, rejected_items). It doesn't explicitly contrast with the close sibling delivery_restrictions__get_delivery_restrictions, but the scope is clear enough to prevent confusion.

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

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

There is no explicit when-to-use/when-not-to-use guidance against sibling tools like delivery_restrictions__get_delivery_restrictions or terminal_groups__check_terminal_groups_availability. However, the description gives practical operational guidance: where to source organizationId/organizationIds/streetId from sibling lookup tools and a directive to cache results due to the rate limit. This is useful but implicit rather than explicit 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?

Annotations already declare the tool read-only and non-destructive. The description adds a meaningful behavioral trait beyond those annotations: the MCP server throttles at 1 request per 60 seconds and the result should be cached. This is valuable operational transparency, though it does not cover response format or pagination.

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 states the content first, then the ID source, then the throttling and caching guidance. Every clause earns its place with 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 simple read-only, single-parameter tool, the description covers the essential operational context: what is returned, how to get the required IDs, and rate-limiting behavior. The lack of an output schema and explicit sibling differentiation are minor gaps given the low complexity and present annotations.

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

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

Schema description coverage is 0%, so the description must compensate. It tells the agent where to obtain `organizationIds`, which is the key semantic gap. However, it does not explain the `request` wrapper or the expected array/UUID structure, so compensation is only partial.

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 the resource precisely: a delivery restrictions reference containing zones, minimum amounts, and intervals. It is clear and not a tautology, but it does not explicitly differentiate itself from the closely named sibling `delivery_restrictions__get_allowed_delivery_restrictions`.

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

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

The description gives concrete usage context: it tells the agent where to obtain `organizationIds` (from `organizations__get_organizations`) and advises caching because of the 60-second throttle. However, it does not state when to choose this tool over the sibling `get_allowed_delivery_restrictions`, so exclusions/alternatives are missing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds useful behavioral context beyond that: an MCP-level throttling threshold and an explicit caching directive. It does not describe error behavior or response details, but for a read-only dictionary lookup with this annotation support, the added transparency is solid.

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 with the core purpose, and the Args/Returns/throttle structure is easy to scan. It loses a point because 'Ответ со списком причин отмены Где взять ID' runs two sentences together without a clean break, and the Args line provides little new information.

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

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

For a one-parameter read-only tool, the essential facts are present: what is returned, where the required ID comes from, and the throttle/caching constraint. It omits any mention of the similarly purposed sibling dictionaries__get_cancel_causes_by_organization, which is important selection context given the large sibling list, and there is no output schema to cover return-shape details.

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 single parameter is a nested CancelCausesRequest object, and the description's Args line mostly restates the parameter name and type without adding semantic detail. The only real parameter-level addition is 'Где взять ID: organizationIds → organizations__get_organizations', which tells the agent where to source the required IDs. Given the stated 0% schema coverage, this is meaningful but only partial compensation.

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 'Получить причины отмены доставки' ('Get delivery cancellation causes'), a specific verb-plus-resource statement that clearly identifies what the tool does. It loses the top score because it does not differentiate this tool from the closely named sibling dictionaries__get_cancel_causes_by_organization.

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 operational guidance: organizationIds can be obtained via organizations__get_organizations, and the MCP server throttles to 1 request per 60 seconds so caching is recommended. It does not, however, tell the agent when to choose this tool over the near-identical sibling or any other dictionary lookup, so exclusion/alternative guidance is missing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable behavioral context beyond the annotations: it states that the call consumes the quota of an underlying API method, that there is no dedicated throttling, and recommends caching the result in the dialog. This is transparent and useful for an agent planning repeated calls.

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 well-structured: purpose first, then Args and Returns, then a brief caching note. Every sentence adds information, and there is no filler or redundancy. The front-loaded purpose makes it immediately scannable for an agent.

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

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

Given the tool's low complexity (one parameter, no nested objects, no output schema), the description covers the essential points: what it returns, the required parameter, and the quota/caching caveat. The absence of an output schema is mitigated by the explicit statement that the response contains a list of cancellation causes. A minor gap is not naming the generic sibling as an alternative, but overall the agent has enough to call this 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?

With schema description coverage at 0%, the description must compensate for missing parameter explanations. It does restate that organization_id is 'ID организации (str или UUID)', which mirrors the schema's anyOf type and format. It adds a human-readable label but no deeper meaning such as where to obtain the ID or validation constraints. For a single simple parameter this is adequate, though not rich.

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 action: getting cancellation causes for an organization. The phrase 'для организации' (for organization) distinguishes this from the sibling 'dictionaries__get_cancel_causes', which likely returns all cancellation causes without organization scoping. This is a specific verb+resource combination that an agent can act on immediately.

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 implied by the purpose and the required organization_id parameter: call this when you need cancellation causes for a specific organization. However, the description provides no explicit guidance about when to choose this over the similar 'dictionaries__get_cancel_causes' tool, nor does it mention any exclusions or prerequisites. It is adequate but leaves the choice to inference.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds valuable behavioral context by disclosing the MCP server rate limit (1 request per 60 seconds) and advising caching, plus a hint about the return type (list of order types). No contradiction with annotations.

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

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

The description is concise and well-structured, with clear sections for purpose, arguments, returns, and throttling. It is front-loaded with the main purpose and avoids unnecessary verbosity.

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 operation with one parameter, the description covers the core aspects: purpose, ID source, rate limit, and return type. However, it does not address potential error scenarios or clarify the difference from the sibling tool, leaving some gaps for an agent to infer.

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 only repeats the parameter name and type, but does provide a useful pointer to the source of organization IDs (organizations__get_organizations). The schema itself describes organizationIds, but the description adds minimal extra meaning beyond that pointer.

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 retrieves delivery order types, which is a specific verb and resource. However, it does not differentiate from the sibling tool 'dictionaries__get_delivery_order_types_by_organization', which likely serves a similar purpose, so it lacks sibling distinction.

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 guidance on where to obtain organization IDs and mentions throttling, but does not explain when to use this tool versus alternatives like the by-organization variant. There is no explicit comparison or condition for 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 declare readOnlyHint=true and destructiveHint=false. The description adds beneficial context by noting it is a tool wrapper with no own rate limiting but consumes the underlying API quota and recommends caching. This goes beyond annotation coverage and provides practical behavioral transparency.

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 well-organized: a one-line purpose, followed by structured Args and Returns sections, and a brief but important caching note. Every sentence contributes value, and the key information 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 simple read-only tool with one parameter and no output schema, the description covers the essentials: what it returns, the shape of the input, and a notable side-effect (API quota). It misses only explicit reference to alternatives, which would improve completeness given the large sibling list.

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

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

Schema description coverage is 0%, so the description carries the burden. However, it only restates the parameter name and type ('ID организации (str или UUID)'), which the input schema already specifies via anyOf string/uuid. It adds minimal semantic meaning beyond the schema.

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

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

The description states a specific verb ('Получить' = get) and resource ('типы заказов доставки для организации' = delivery order types for an organization), which is clear. It does not explicitly contrast with the sibling tool dictionaries__get_delivery_order_types (without the organization scope), so it falls short of full sibling 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?

There is no guidance on when to use this tool versus the sibling dictionaries__get_delivery_order_types or other by_organization variants. The caching note is operational advice, not usage direction. No when/when-not conditions are given.

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 destructiveHint=false. The description adds value by disclosing the MCP-server throttling limit (1 request per 60 seconds) and advising caching—behavioral details not present in annotations. It does not contradict annotations and helps the agent plan for latency and rate limits.

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 covers multiple essential aspects (purpose, args, return, ID sourcing, throttling) in a short space. However, the formatting is a bit run-on—'Response with a list of discounts Where to get ID' lacks clear separation—and mixing Russian/English reduces polish.

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 tool with one nested parameter and no output schema, the description provides enough to call it: parameter purpose, ID sourcing, return type, and a critical throttling note. It lacks explicit differentiation from a closely related sibling, but that is more a usage-guideline issue than a completeness gap for 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?

Even though the top-level parameter has no description in the schema (0% coverage signal), the schema's nested DiscountsRequest does describe organizationIds. The description augments this by pointing to organizations__get_organizations as the source for IDs, which is more actionable than the schema's generic '/api/1/organizations' reference. It helps the agent correctly populate the parameter, though it stops short of explaining the full request structure.

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 'Get discounts' with a clear verb and resource, but it does not distinguish this from the sibling tool dictionaries__get_discounts_by_organization. The parameter and return type are mentioned, yet the differentiation needed to pick between these two similar tools is absent.

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 useful context: where to get organization IDs (organizations__get_organizations) and a throttling/caching recommendation. However, it does not explicitly say when to use this tool versus the alternative by_organization variant, nor does it mention any exclusions or prerequisites beyond ID sourcing.

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 destructiveHint=false. The description adds valuable context: 'Это тул-обёртка: своего троттлинга нет, но вызов расходует квоту нижележащего метода API — кэшируйте результат в диалоге.' This discloses quota consumption and recommends caching, which goes 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?

The description is compact, with the core purpose stated first, followed by a brief parameter list and a practical caching note. No redundant text; 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?

For a simple one-parameter getter with readOnlyHint annotations, the description provides the essential context: the parameter meaning, the return type (list of discounts), and the caching advice. It does not describe the discount object structure or error cases, but given the tool's simplicity and no output schema, it is sufficiently complete.

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

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

The schema has one parameter with zero description coverage (0%). The description compensates by documenting the parameter in the Args section: 'organization_id: ID организации (str или UUID)', clarifying the semantic meaning beyond just the type definition.

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 'Получить скидки для организации' (Get discounts for an organization), which is a specific verb+resource. The sibling list includes both 'dictionaries__get_discounts' (without organization) and other per-organization tools, so the purpose is clear even though the description does not explicitly name alternatives.

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

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

There is no guidance on when to use this tool versus alternatives like 'dictionaries__get_discounts' or 'discounts__get_loyalty_programs'. The description only mentions the wrapper nature and caching advice, but does not help an agent choose between 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 declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: the MCP server throttling (1 request per 60 seconds) and a caching recommendation, which are not available in annotations. It also mentions where to obtain required IDs, contributing to transparency.

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 relatively concise with a clear Args/Returns structure and an additional note on throttling. It is front-loaded with the purpose and avoids unnecessary fluff, though the separate sections could be tightened.

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

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

For a simple one-parameter read-only tool with annotations covering safety, the description covers basic usage and throttling. However, it lacks differentiation from the sibling tool and does not describe the return format beyond 'list of payment types'. Given the existence of a nearly identically named tool, more context about when to use this specific variant is needed.

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 only restates the parameter type ('payment_types_request: Параметры запроса PaymentTypesRequest') without explaining its structure or content. However, it does provide a practical hint: organizationIds can be obtained from organizations__get_organizations. The schema itself includes a description for organizationIds, so the description's contribution is limited but non-zero.

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 'Получить типы оплаты' (Get payment types), which clearly identifies the action and resource. However, it does not differentiate from the sibling tool 'dictionaries__get_payment_types_by_organization', so it fails to distinguish between the two similar 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 provides a useful cross-reference for obtaining organizationIds (via organizations__get_organizations) and warns about rate limiting and caching. However, it gives no guidance on when to use this tool versus the sibling 'dictionaries__get_payment_types_by_organization', which is a significant omission given the similarity in names.

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 destructiveHint=false. The description adds significant behavioral context: it is a tool wrapper, has no own throttling, consumes quota of the underlying API method, and advises caching the result in the dialog. This goes beyond the annotations and helps the agent understand cost/implications of calls.

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

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

The description is concise and well-structured with an Args section, Returns section, and a note about caching. The purpose is front-loaded. There is minor run-on punctuation ('организации Это'), but overall it is efficient and earns its place.

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

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

The tool is simple (one parameter) and annotations cover safety. The description explains the return type (list of payment types) and the quota implication. However, it does not mention the closely related sibling 'dictionaries__get_payment_types', nor does it describe the structure of the returned payment types. Given the absence of an output schema and low schema coverage, a bit more context would help, but it is still adequate for a straightforward read-only lookup.

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. However, it merely repeats the schema's type information ('ID организации (str или UUID)'), which adds no semantic value beyond what the schema already specifies. It does not explain where to obtain the organization_id, how it is used, or any constraints on the value. The parameter is straightforward but the description barely enhances it.

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

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

The description states a clear verb and resource: 'Получить типы оплаты для организации' (get payment types for an organization). It is specific and scoped by organization_id. However, it does not explicitly differentiate from the sibling 'dictionaries__get_payment_types' (which likely fetches all payment types without an organization filter), so it lacks explicit sibling 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 does not provide any guidance on when to use this tool versus alternatives. It does not mention the sibling 'dictionaries__get_payment_types' or state any condition (e.g., 'use this when you need payment types for a specific organization'). The purpose statement implies organization-scoped usage but offers no explicit selection criteria 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 declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: a strict throttling limit (not more than 1 request per 60 seconds) and a recommendation to cache results. It does not contradict annotations and provides extra operational behavior beyond the structured hints.

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 uses a labeled structure (Args, Returns, where to get ID, throttling). The first sentence clearly states the purpose, and each line adds distinct information. Minor redundancy: 'Returns' restates the tool's purpose, but overall it is 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?

The description covers ID sourcing, throttling, and return type, which is sufficient for a single-parameter read-only tool with annotations. However, it fails to clarify the relationship to the sibling 'dictionaries__get_removal_types_by_organization', leaving an agent uncertain about which variant to select. No output schema exists, but the return description is basic yet acceptable.

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

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

The single parameter 'removal_types_request' is not described at the top level (schema coverage 0%), but the nested schema does describe organizationIds and mentions the API endpoint. The description adds a more direct pointer to the MCP tool 'organizations__get_organizations' for obtaining IDs, which helps. However, it does not further explain the meaning or format of the removal type request beyond what the schema already offers.

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 verb and resource clearly: 'Получить типы списания' (get removal types). However, it does not differentiate from the sibling tool 'dictionaries__get_removal_types_by_organization', which likely performs a similar operation with a possibly different parameter shape. The purpose is clear but lacks sibling discrimination.

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?

No guidance is provided on when to use this tool versus the alternative 'dictionaries__get_removal_types_by_organization' or other dictionary tools. The description only gives a throttling hint (1 request per 60s) and caching advice, but does not explain selection criteria 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?

Beyond annotations (readOnlyHint=true, destructiveHint=false), the description discloses that this is a tool wrapper without its own throttling but consumes the quota of the underlying API method, and recommends caching the result. This adds meaningful behavioral context about quota impact and performance, which is valuable for an agent deciding whether to reuse results.

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

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

The description is concise and well-structured with clear 'Args' and 'Returns' sections. The primary purpose is stated first, and additional behavioral notes are appended. The entire text is brief and to the point, with 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 simple one-parameter read tool with annotations, the description is mostly complete. It explains return type (list of types) and quota behavior. However, it fails to mention the sibling tool without organization filtering, which is a key distinction that could lead to incorrect selection. Lacking output schema, the description doesn't detail the response structure, but 'list of types' may suffice. Overall, adequate but with a notable gap in tool-selection 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?

The only parameter, organization_id, is described as 'ID организации (str или UUID)' which directly mirrors the schema's anyOf string/uuid. The description adds no information about sources, formats, constraints, or usage beyond the schema. With schema description coverage at 0%, the description should compensate but does not.

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 function: 'Получить типы списания для организации' (Get write-off types for an organization). It specifies the resource (write-off types) and scope (by organization), making the purpose distinct. However, it does not explicitly differentiate from the sibling tool 'dictionaries__get_removal_types' (without organization filter), though the phrase 'for an organization' implies a scoped version.

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 no guidance on when to use this tool versus alternatives, notably the sibling 'dictionaries__get_removal_types' which likely returns all types. It does offer a caching recommendation due to quota consumption, but that addresses invocation behavior, not tool selection. No context on prerequisites or conditions for choosing this tool is given.

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 destructiveHint=false, so the description doesn't need to restate safety. It adds value by disclosing a throttling limit: no more than 1 request per 60 seconds and advises caching. This is important behavioral context beyond annotations. However, it doesn't describe error handling or what happens on rate limit, but that's acceptable.

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: one for purpose, one for return and throttling. It's front-loaded and every sentence adds value. No fluff.

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 simplicity (no params, no output schema) and annotations covering read-only safety, the description covers the essential information: what it returns and the rate limit with caching advice. It could mention whether it's organization-specific, but the tool name implies a general dictionary. For a simple getter, it's reasonably 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?

The tool has zero parameters, so the schema trivially covers all parameters. The description correctly omits parameter details. Baseline 4 applies because there are no parameters to document.

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 'Get tip types' (Получить типы чаевых), which is a specific verb and resource. It clearly distinguishes itself from sibling dictionary tools like dictionaries__get_cancel_causes or dictionaries__get_payment_types by explicitly naming the subject. The name and description align perfectly.

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 no guidance on when to use this tool versus alternatives. It doesn't mention any context, prerequisites, or scenarios. An agent must infer that it's for retrieving tip types. No explicit exclusions or comparisons to sibling tools are given.

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 destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context: it is a high-frequency call, subject to MCP-server throttling of 1000 requests per 60 seconds, and results should be cached. It also flags obsolete fields and directs the agent to the correct current location, which goes beyond what annotations provide. No contradiction.

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 main purpose is front-loaded in the first sentence. The long ID lookup list is dense but each entry earns its place, and the throttling/caching note is practical. The structure could be improved with bullet formatting, but it is still efficient and scannable as a logical mapping list.

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

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

For a tool with a large nested schema and no output schema, the description covers the critical invocation concerns: deprecated fields, ID sourcing, and rate limiting. It does not explain the return value, but the tool's purpose implies the output. Given the complexity, it is reasonably complete, though a note on expected response would make it fully so.

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 does this well by mapping many request IDs (comboGroupId, comboId, manualConditionId, marketingSourceId, etc.) to the exact sibling tools that provide them, and by clarifying that coupon/manual_conditions/dynamic_discounts at the top level are obsolete and belong in order.loyalty_info. It does not cover every field, but the most error-prone IDs are addressed.

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 'Расчёт скидок/лояльности для заказа' which clearly states the tool calculates discounts/loyalty for an order. The verb and resource are specific, but it does not distinguish this from the sibling tool `discounts__calculate_order_loyalty`, so it misses the differentiation that would earn a 5.

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

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

The description gives important usage guidance: which top-level fields are obsolete and where to place them (order.loyalty_info), plus a detailed mapping of ID fields to source tools. However, it never says when to use this tool instead of the closely related `discounts__calculate_order_loyalty`, and no exclusions are given. The context is present but the when-vs-alternative guidance is absent.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description adds valuable behavioral context: it is a tool wrapper with no throttling, consumes quota of the underlying API method, and recommends caching the result in the dialog. It also flags that top-level request fields are obsolete, directing to order.loyalty_info. No contradiction with annotations.

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

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

The description is compact and front-loaded with the primary purpose, followed by practical usage notes and caching advice. It is not overly verbose, though the obsolete-fields note ('верхнеуровневые поля request — obsolete') is somewhat convoluted and could be clearer.

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 schema has 0% coverage and no output schema, the description provides helpful guidance on item construction and ID sourcing, but leaves several parameters unexplained and does not describe the return value or expected output. The ambiguity around order.loyalty_info and the obsolete top-level fields makes the definition incomplete for an agent to call the tool with full confidence.

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 compensates somewhat by explaining how to build items and where to obtain combo/nomenclature IDs. However, it references order.loyalty_info which does not appear in the provided schema, creating ambiguity about whether to use top-level fields or a nested structure. Several parameters (phone, organization_id, terminal_group_id, etc.) remain unexplained.

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 calculates discounts/loyalty for an order ('Расчёт скидок/лояльности заказа'), which is a specific verb+resource. It aligns with the tool name and distinguishes from sibling calculate_loyalty_checkin by focusing on 'order', though it does not explicitly name the 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?

The description provides practical guidance on constructing items (via build_product_item / build_compound_item), where to find IDs (menu__get_combos_info, menu__get_nomenclature), and advises caching results. However, it does not explicitly state when to use this tool versus sibling alternatives, nor does it give exclusion criteria.

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 destructiveHint=false, but the description adds valuable behavioral context: it specifies MCP-server throttling (10 requests per 60 seconds) and recommends caching results in the conversation. This goes beyond annotations and helps the agent manage rate limits.

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 brief and efficient, front-loading the core purpose in the first sentence. The additional guidance on organizationId and throttling is relevant and not verbose. Every sentence earns its place without 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 tool with annotations covering safety, the description covers purpose, a key parameter source, and throttling. However, it does not explain the 'series' parameter, nor does it describe the return format or potential error conditions. Given the low schema coverage, these gaps leave the description only moderately 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?

With 0% schema description coverage, the description must compensate for parameter meaning. It implicitly explains 'number' as the coupon number and tells where to get organizationId, but it completely omits the 'series' parameter. The nested 'request' structure is also not clarified. This partial coverage is insufficient for a 3-parameter 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 clearly states the tool's purpose: providing coupon information by number ('Информация о купоне по номеру'). It specifies the resource (coupon) and the key identifier (number). While it doesn't explicitly differentiate from sibling tools like discounts__get_coupon_series, the purpose is unambiguous and not a tautology.

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 practical guidance on obtaining a required parameter (organizationId) by referencing organizations__get_organizations, and advises throttling and caching. However, it does not explicitly state when to use this tool versus alternatives, nor does it give exclusion criteria or when-not-to-use conditions.

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 destructiveHint=false, covering the safety profile. The description adds useful operational context: MCP-server throttling (1 request per 60s) and caching advice. This goes beyond the annotations and informs the agent about rate limits and caching strategy, which is valuable for correct 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 extremely concise: two sentences (or three short clauses) that cover purpose, ID source, and throttling. It front-loads the core purpose first, then practical usage notes. 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 simple read-only tool with one required parameter, the description covers the essential usage: what it returns, where to get the ID, and rate-limit considerations. It lacks a description of the return format (no output schema exists), but the tool is straightforward and the annotations cover safety. Given the simplicity, it is nearly complete, though mentioning the output structure would improve it.

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

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

Schema description coverage is 0%, so the description must compensate. It explains where to get organizationId (from organizations__get_organizations) but does not elaborate on the parameter structure beyond that. It gives one useful hint but does not fully explain the meaning or any edge cases. The parameter itself is simple (a UUID), and the description provides minimal extra value beyond the schema field name.

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 coupon series that have non-deleted, non-activated coupons. It specifies the resource (series) and the filter (non-deleted, non-activated coupons), which is specific. However, it does not explicitly distinguish from sibling tools like discounts__get_non_activated_coupons_by_series, so it misses the chance to preempt confusion. Overall clear but not perfectly differentiated.

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 helpful guidance on where to obtain the organizationId (from organizations__get_organizations) and gives throttling instructions. However, it does not mention when to use this tool versus alternatives (e.g., discounts__get_coupon_info or discounts__get_non_activated_coupons_by_series). It implies usage for series with non-activated coupons but does not state exclusions or alternative conditions.

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 destructiveHint=false, so the safety profile is known. The description adds valuable behavioral details beyond annotations: the specific ValueError condition and the throttling constraint with a caching recommendation. This meaningfully helps the agent anticipate side effects.

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 purpose sentence, one error/source statement, and one throttling note. Every sentence adds practical value, though the error and ID-source details are packed into a single run-on section rather than cleanly structured.

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, one-parameter tool with no output schema, the description covers purpose, parameter source, error behavior, and rate limiting. The main gaps are the lack of response-shape details and a fuller explanation of what 'manual conditions' means, but an agent can still invoke it correctly with the given information.

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 compensates by explaining that a missing organizationId raises ValueError despite the schema default null, and directs the agent to organizations__get_organizations for the correct ID. It does not fully describe the 'request' wrapper, but it adds critical parameter meaning that the schema lacks.

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

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

The description 'Все ручные условия организации' names the resource but lacks an explicit verb; it essentially restates the tool name's object without defining 'manual conditions' or showing how this differs from sibling discount getters. It is not misleading, but it relies on the tool name for action clarity.

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

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

The description gives concrete operational guidance: a ValueError is raised when organizationId is missing, the ID should be sourced from organizations__get_organizations, and MCP-server throttling limits calls to 1 per 60 seconds so results should be cached. It does not discuss when to choose this tool over siblings, but for a simple getter the provided context is strong.

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 destructiveHint=false, so the safety profile is known. The description adds the throttling constraint (1 request per 60 seconds) and the caching recommendation, which is valuable behavioral context beyond the annotations. This is a good addition for a read-only tool with rate limits.

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, concise and front-loaded with the core purpose. The throttling and caching note is relevant but slightly verbose with the parenthetical. Overall, it is well-structured and earns its length.

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

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

For a simple read-only list tool with one required parameter, the description covers the essential aspects: purpose, ID sourcing, and throttling. It lacks details on the output structure (no output schema) but the tool is simple enough that the missing return format is not critical. The throttling guidance is a significant plus.

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 description coverage is 0%, but there is only one required parameter (organizationId) and an optional boolean (withoutMarketingCampaigns). The description does not explicitly explain the meaning of withoutMarketingCampaigns, but the schema provides a basic description. Since the description is minimal on parameter detail, it does not fully compensate for the 0% coverage, but the schema itself provides some help, so a 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 tool retrieves all loyalty programs of an organization. It clearly maps to the get_loyalty_programs name and makes the resource explicit. However, it does not explicitly differentiate from sibling tools like discounts__get_coupon_series, though the name and context make the purpose fairly clear.

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 a clear instruction on where to get the organizationId (via organizations__get_organizations) and explicitly warns about throttling with a caching recommendation. It does not explicitly state when not to use this tool versus alternatives, but the guidance is strong for the main use case.

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 destructiveHint=false, so the description adds value by disclosing the MCP server rate limit (10 requests per 60 seconds) and recommending caching, which is not covered by annotations. This goes beyond the structured metadata and helps the agent manage usage safely.

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

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

The description is concise, front-loaded with the core purpose, and includes essential usage details in two sentences. Every sentence adds value: the first defines what the tool does and the second provides ID sourcing and throttling/caching guidance. No unnecessary 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?

There is no output schema, so the description does not explain the return format or structure. It covers the key input (organizationId, series, pagination) and operational constraints, but it omits details about response fields, potential errors, or behavior when series is null (though the schema mentions it can be null). For a read-only query, this is somewhat sufficient but leaves gaps for an agent expecting to interpret results.

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%, meaning the schema provides minimal field descriptions (only 'series' has a description). The description mentions 'page/page_size-пагинация' which clarifies the purpose of those parameters, but it does not explain each parameter's meaning or defaults. It partially compensates for the low coverage but does not fully describe the nested 'request' object's fields.

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 resource ('non-activated coupons of a series') and the filtering mechanism (series, pagination). The tool name itself is descriptive, and the description adds the pagination detail. It distinguishes itself from related discount tools by specifying 'non-activated' and 'by series'.

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 guidance on where to obtain the organizationId (from organizations__get_organizations) and advises caching due to throttling. It implies when to use this tool (when needing non-activated coupons of a specific series) but does not explicitly contrast it with alternatives like discounts__get_coupon_series or discounts__get_coupon_info.

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 destructiveHint=false, covering safety. The description adds valuable behavioral context by mentioning MCP-server throttling (20 requests/60s) and advising caching, which is not present in annotations. This enriches the agent's understanding of operational constraints.

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

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

The description is concise, consisting of two sentences with no fluff. It front-loads the core purpose ('Черновик по id') and immediately provides actionable ID sourcing and rate-limit information. Every word earns its place.

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

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

For a simple getter with annotations covering safety and a clear description of ID sourcing and throttling, the description is largely complete. It does not describe the return format, but given the absence of an output schema and the simplicity of the operation, this is a minor gap. The agent has enough to call 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 0%, so the description must compensate. It does so by explaining exactly where to obtain each parameter: orderId from deliveries_retrieve__get_deliveries_by_delivery_date_and_status and organizationId from organizations__get_organizations. This is meaningful guidance beyond the bare UUID type 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?

The description clearly states 'Черновик по id' (draft by id), which is a specific verb+resource. It distinguishes itself from siblings like drafts__get_delivery_drafts_by_filter (filter-based) and deliveries_retrieve__get_delivery_by_id (delivery, not draft) by emphasizing the 'by id' retrieval. It also provides explicit guidance on where to obtain the required IDs, reinforcing its unique role.

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

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

The description gives context on how to source the IDs (orderId from a specific tool, organizationId from another) but does not explicitly state when to use this tool versus alternatives like the filter-based draft retrieval. It implies usage when a specific draft ID is known but lacks explicit exclusions or alternative routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description correctly does not repeat that. It adds value by disclosing MCP server throttling (max 20 requests per 60 seconds) and advising to cache results, which is behavioral context beyond annotations. It does not describe the return format, but that is not required given the annotations cover safety.

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

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

The description is concise—two sentences—and front-loaded with the core purpose ('Drafts by filter'). It efficiently packs essential info: key filters, ID sources, and throttling guidance. Every sentence earns its place without verbosity.

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 filter tool with a well-documented request schema, the description is largely complete. It provides critical integration details (ID source mappings) and operational constraints (throttling). While it does not describe the response structure, that is not required given the absence of an output schema and the read-only nature. Slight gap: it does not mention that organizationIds is required, but the schema already indicates that.

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

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

The schema itself provides detailed descriptions for every parameter, so the description does not need to compensate for missing schema documentation. The description mentions phone, dates, and pagination, which maps to some parameters, but adds little beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool retrieves drafts by filter, listing key filters (phone, dates, pagination). It distinguishes from the sibling 'get_delivery_draft_by_id' by implying a list operation. While not explicitly naming the alternative, the purpose is specific and 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 provides helpful context: where to obtain IDs for organizationIds and terminalGroupIds, and mentions throttling and caching. However, it does not explicitly state when to use this tool over alternatives (e.g., when a list of drafts is needed vs. a single draft). The guidance is implicit rather than explicit.

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 destructiveHint=false. The description adds meaningful behavioral context beyond the annotations: MCP-server throttling limits (not iikoCloud limits), a caching recommendation, and the note that the rate limit applies to the MCP server. This gives the agent actionable information about operational constraints.

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 states the resource in the first phrase, then provides essential usage and throttling guidance in two short sentences. Every clause earns its place, and there is no redundant restating of the tool name or schema.

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

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

Given the tool's low complexity (one required parameter, no enums, no nested objects) and read-only annotations, the description covers the key operational needs: what the tool returns, where to get the ID, and how to respect rate limits. There is no output schema, so a bit more detail about the shape of the returned locations could be useful, but it is not essential for correct invocation.

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

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

The schema provides only a nested description of `organizationIds` as a list of organizations, and top-level schema coverage is 0%. The description compensates by explicitly telling the agent where to source `organizationIds` from (`organizations__get_organizations`), which is highly relevant for correct invocation. It does not fully detail all parameter semantics, but for the single parameter this guidance is sufficient.

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 resource clearly: 'Локации активных курьеров' (locations of active couriers), which is a specific deliverable and distinct from the sibling tools. It lacks an explicit verb like 'returns' or 'gets', but the tool name plus the noun phrase make the operation unambiguous. The 'active couriers' qualifier helps differentiate it from history or terminal-scoped variants.

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

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

The description gives concrete usage guidance: where to obtain `organizationIds` (via `organizations__get_organizations`) and that results should be cached due to MCP-server throttling of 10 requests per 60 seconds. It does not explicitly say when to prefer this over `employees__get_active_courier_locations_by_terminal`, but it provides clear practical context for calling the tool safely.

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 indicate read-only and non-destructive behavior. The description adds a valuable operational detail beyond annotations: MCP-server throttling (10 requests/60s) and the recommendation to cache results in the conversation. This is relevant behavioral context that helps the agent plan calls correctly.

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: purpose first, ID-source mapping second, rate-limit and caching guidance last. Every sentence earns its place and there is no filler or repetition of schema data.

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

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

For a tool with no output schema, the description does not describe what the returned courier locations look like (coordinates, timestamps, courier IDs, etc.). It covers required inputs and rate limiting, but an agent still has to infer the return shape and the 'active' semantics from the tool name.

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?

Even though the schema includes descriptions for the nested IDs, schema_description_coverage is 0%, so the description must compensate. It does so by mapping each required parameter to a concrete sibling MCP tool (organizations__get_organizations and terminal_groups__get_terminal_groups), which adds meaning beyond raw field names.

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

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

The description names the resource ('courier locations') and the scope ('of the terminal'), which matches the tool name and distinguishes it from global variants like employees__get_active_courier_locations. It is a noun phrase rather than an explicit verb statement, and it does not explicitly say 'active couriers', so it stops short of a fully self-contained purpose definition.

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 guidance on where to obtain organizationId and terminalGroupId, which helps an agent prepare required inputs. However, it does not say when to prefer this tool over the similarly named employees__get_active_courier_locations or employees__get_courier_location_history, so the when-vs-alternatives guidance is only implied by the tool name.

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 destructiveHint=false, covering safety. The description adds behavioral context about MCP-server throttling (not iikoCloud) and suggests caching, which is useful for an agent managing API rate limits. It does not describe return format, but that is not critical given the read-only nature and no output schema.

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

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

The description is two concise sentences. The first states the purpose and offset, the second provides ID sourcing and throttling advice. It is front-loaded with the core functionality and avoids unnecessary fluff, making it efficient for an agent to parse.

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 tool with two parameters and clear annotations, the description covers the essential aspects: purpose, ID source, and rate limit. It does not explain the exact behavior of offsetInSeconds when null, but the schema already covers that. The lack of output format information is acceptable given no output schema and the straightforward nature of the data.

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 descriptions for both parameters are detailed, covering offsetInSeconds and organizationIds semantics. The description adds marginal value by explaining offset is in seconds and pointing to where to get IDs, but it largely repeats schema information. With high schema coverage, 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 tool retrieves courier coordinate history ('История координат курьеров') and specifies the offset parameter. It clearly identifies the resource and action, though it doesn't explicitly contrast with sibling tools like 'get_active_courier_locations'. The word 'История' (history) sufficiently implies the distinction from current-location 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?

It provides a concrete usage hint: where to obtain organizationIds via 'organizations__get_organizations'. It also gives throttling guidance (max 10 requests per 60s) and recommends caching. However, it does not state when to choose this tool over alternatives like 'get_active_courier_locations', nor does it mention any preconditions beyond ID sourcing.

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 (readOnlyHint=true, destructiveHint=false), the description discloses a critical behavioral constraint: 'Троттлинг MCP-сервера... не чаще 1 запрос(ов) за 60 с — кэшируйте результат в диалоге.' This rate-limit and caching instruction is exactly the kind of behavioral context that adds value beyond structured data.

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 fluff: purpose first, then ID source, then throttling/caching. Every sentence carries operational value, and the most important scoping information 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 simple read-only list tool with one parameter, the description covers purpose, input sourcing, and a critical rate limit. It lacks explicit differentiation from employees__get_couriers_by_role and has no output schema, but nothing essential about invoking it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate. It does add meaning by explaining where organizationIds come from ('organizationIds → organizations__get_organizations'), but it does not explain the request wrapper structure or the array semantics beyond what the schema already shows. This is partial compensation, not full.

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 resource clearly: 'Сотрудники-курьеры организаций' (organization courier employees), and the tool name supplies the get verb. It is clear this returns couriers for given organization IDs, but it does not differentiate from the sibling employees__get_couriers_by_role, so it stops short of a 5.

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

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

The description gives a concrete prerequisite: 'Где взять ID: organizationIds → organizations__get_organizations' tells the agent exactly how to obtain the required organizationIds. It also adds operational guidance to cache results due to throttling. However, it does not explicitly state when to prefer this tool over alternatives like get_couriers_by_role.

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 destructiveHint=false, and the description adds genuinely valuable behavioral context on top: the MCP-server throttling limit of 1 request per 60 seconds (explicitly distinguished from the iikoCloud limit) and the recommendation to cache results within the dialog. This goes beyond what the annotations provide and helps the agent plan calls correctly.

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 earning its place: purpose, ID provenance, and throttling. The most operationally critical detail (rate limit and caching) is placed last but clearly delimited. Slightly verbose phrasing ('не чаще 1 запрос(ов) за 60 с') and the format in Russian is a minor readability cost, but overall it is tight and 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 simple read-only tool with annotations covering the safety profile, the description covers the key operational need (throttling) and the ID source, but leaves gaps: it does not explain rolesToCheck semantics, does not state what the response contains (which fields identify a courier), and offers no guidance on result shape since no output schema exists. Adequate for a competent agent but not self-sufficient.

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% and the description only partially compensates: it names organizationIds and gives a concrete cross-reference to organizations__get_organizations, which is more actionable than the schema's raw '/api/1/organizations' hint. However, rolesToCheck — the parameter most likely to confuse an agent ('the short name of employee's position') — receives no explanation, no examples, and no pointer to where role names come from.

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 'Курьеры с проверкой ролей' ('Couriers with role checking') is essentially a paraphrase of the tool name get_couriers_by_role, so it borders on tautology. It hints at the distinguishing feature (role filtering) but never states the actual behavior — that it returns couriers for given organizations who match the specified roles. It adds no verb or resource beyond what the name already conveys.

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?

No guidance is given on when to use this tool versus the closely related siblings employees__get_couriers, employees__get_active_courier_locations, and employees__get_courier_location_history. The only usage-adjacent hint is the data-dependency pointer 'organizationIds → organizations__get_organizations', which tells where an input comes from, not when to select this tool over alternatives.

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

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

Annotations already show readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable extra context: a MCP-server throttle of 1 request per 60 seconds and a caching recommendation, which goes beyond the structured 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?

The description is two sentences with no filler: the first states the purpose, the second gives a parameter source and throttling advice. It is well-structured and front-loaded, though slightly more detail on the id parameter could be added without losing conciseness.

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

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

For a simple two-parameter lookup tool, the description covers purpose, one parameter source, and rate limiting. However, it omits how to obtain the employee id and does not describe the return value or error conditions, leaving the description adequate but not complete.

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

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

Schema description coverage is 0% at the top level, so the description must compensate for parameter meaning. It only explains how to obtain organizationId via organizations__get_organizations, but leaves the employee id parameter source unexplained, providing incomplete semantic guidance.

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 provides employee information by ID, a specific verb and resource. It is easy to distinguish from sibling employee tools focused on couriers or sessions, though no explicit differentiation is made.

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 tells the agent where to get organizationId via organizations__get_organizations and includes a rate-limit note. However, it does not specify when to use this tool over alternative employee info tools or provide 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 destructiveHint=false, so the safety profile is covered. The description adds significant behavioral context beyond annotations by disclosing an MCP-server-specific throttling limit (10 requests per 60 seconds) and recommending caching the result in the conversation, which directly affects how an agent should invoke the tool.

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

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

The description is three sentences: purpose, ID sourcing, and throttling/caching advice. Each sentence earns its place, the purpose is front-loaded, and there is no redundant filler or repetition of schema information.

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

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

For a read-only tool with a simple nested request and no output schema, the description covers purpose, parameter sourcing, and rate-limit guidance. It does not explicitly describe the return value (e.g., whether it returns a boolean), but the question phrasing implies a yes/no outcome, making it adequately complete though not exhaustive.

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 maps each parameter to a specific sibling tool that provides the value (employeeId → employees__get_employee_info; organizationId → organizations__get_organizations; terminalGroupId → terminal_groups__get_terminal_groups), giving the agent actionable parameter sourcing. It does not describe parameter meaning in depth, but this mapping is highly valuable given the minimal schema.

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

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

The description opens with a direct question 'Открыта ли личная сессия сотрудника' (Is the employee's personal session open), clearly identifying the resource (employee personal session) and the action (checking its status). This distinguishes it from the many getter tools in the sibling list by its unique focus on personal session state, though it is phrased as a question rather than an explicit verb like 'get' or 'check'.

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 explicit guidance on where to obtain each required ID (employeeId → employees__get_employee_info; organizationId → organizations__get_organizations; terminalGroupId → terminal_groups__get_terminal_groups), which is a useful prerequisite. However, it does not explicitly state when to use this tool over alternatives or provide exclusions/when-not-to-use conditions, leaving the usage context 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 and destructiveHint, so the description does not need to repeat that. It adds valuable operational behavior: a rate limit (10 requests per 60s) on the MCP server and a caching recommendation. This goes beyond annotations and helps the agent avoid throttling.

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 no fluff. The purpose is front-loaded, followed by a usage hint and a rate-limit note. 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?

The description covers purpose, ID source, and rate limiting, which is solid for a simple read-only tool. However, it lacks differentiation from sibling tools and does not describe the response shape (though no output schema exists). Given the many similar tools in the sibling list, more guidance on when to use this one 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?

The schema has 0% description coverage for parameters. The description mentions where to get employeeId but does not explain its meaning or any constraints beyond the schema's UUID format. It provides a pointer rather than semantic depth, which is insufficient given the low 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 states the tool returns terminal groups where the employee has an open session. It is specific about the resource and condition, and the tool name already indicates 'get'. It distinguishes from generic terminal group tools by the 'open session' qualifier, but it is phrased as a noun phrase rather than an explicit action sentence.

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

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

The description gives a prerequisite (where to obtain employeeId) but does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusion criteria. No sibling differentiation is provided, so an agent may not know to choose this over terminal_groups__get_terminal_groups or similar 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 declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to repeat that. It adds a throttling constraint ('no more than 100 requests per 60 seconds') and a caching recommendation ('cache the result in the dialog'), which are behavioral traits beyond the annotations. This is valuable context for the agent, so a score of 4 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 concise and front-loaded with the purpose. It then adds two useful operational notes: where to get IDs and a throttling constraint. It is well-structured and efficient, though the throttling note could be considered extra but is relevant to usage.

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

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

The tool has a nested request structure (request object with items array) and no output schema. The description gives ID sourcing and throttling but does not explain the request structure, required fields (like dateIncoming), or the return format. The schema covers the structure, but the description could be more complete about the overall context and expected behavior.

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%, and the description only provides sourcing hints for organizationId and productId. It does not explain other parameters like dateIncoming, storeId, or amountFactor. The schema itself has descriptions for these fields, but the description fails to compensate for the low coverage beyond two IDs, leaving the agent to rely entirely on the schema for the rest.

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: 'Calculate the cost of goods in warehouses.' It uses a specific verb ('calculate') and resource ('cost prices of goods in warehouses'), and while it doesn't explicitly name sibling alternatives, none of the listed sibling tools perform this function, so it naturally stands out.

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 no guidance on when to use this tool versus alternatives. It only gives hints on sourcing IDs (organizationId and productId) and a throttling note, which are operational details, not usage context or exclusions. There is no mention of when not to use this tool or how it compares to other invoice_processing 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 declare readOnlyHint=true and destructiveHint=false, so the read-only nature is known. The description adds a concrete rate-limit warning and caching recommendation, which is valuable behavioral information beyond the annotations. It does not contradict the annotations and provides extra operational detail.

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

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

The description is short and front-loaded with the purpose, followed by the ID source and throttling note. Each sentence earns its place without redundancy. It could be slightly more compact, but it is well-structured and 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?

For a simple get-by-id tool with annotations covering safety, the description covers the main operational aspects: what it retrieves, where to get one required ID, and a rate-limit/caching hint. The missing piece is the source for documentId (likely from a list endpoint), but overall it is adequate for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. The description adds the source for organizationId (from organizations__get_organizations), which is helpful, but it does not explain where documentId comes from or its role. The schema's simple 'GUID' descriptions are minimal, so the description only partially bridges the 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 states 'Акт прихода услуг по id' which clearly identifies the tool as retrieving an incoming services act by ID. It also provides a pointer for where to obtain the organizationId, adding useful context. However, it does not explicitly differentiate from sibling tools like list_finance_incoming_services or get_finance_outgoing_service, though the name itself is fairly descriptive.

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 usage context: it tells the agent where to get the organizationId (from organizations__get_organizations) and advises caching due to MCP-server throttling (10 requests per 60 seconds). It does not explicitly state when to use this tool versus a list alternative, but the prerequisite and rate-limit guidance are directly useful.

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 destructiveHint=false, covering the safety profile. The description adds a specific throttling constraint (10 requests per 60 seconds) and advises caching results, which is beyond the annotations and gives the agent actionable operational context. No contradiction with annotations.

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

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

The description is concise with two sentences that front-load the purpose, then give a sourcing tip, then the rate-limit advice. No unnecessary words or repetition. It is efficient and readable, though it could be more structured with explicit sections.

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 get-by-id tool, the description covers the purpose, one ID source, and rate limiting. However, it omits how to obtain the documentId, which is essential for calling the tool. Given the annotations cover safety and the schema describes parameter types, the main gap is the missing documentId sourcing, making the description adequate but not 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?

The schema provides descriptions for documentId and organizationId individually, but the tool description adds no explanation of how to obtain the documentId, which is a required parameter. It only hints at organizationId sourcing. The description does not clarify that the 'request' parameter is an object containing these two fields, leaving the agent to rely solely on the schema for parameter structure.

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 specific resource: 'Акт расхода услуг по id' (act of expense of services by id), clearly indicating a retrieval operation. It does not explicitly contrast with the sibling get_finance_incoming_service, but the resource name and the 'расхода' (expense) wording sufficiently distinguish it from the incoming variant.

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 guidance on sourcing the organizationId via organizations__get_organizations, which is a useful prerequisite hint. However, it does not explain when to use this tool versus alternatives (e.g., list_finance_outgoing_services to find documentId) or state the condition for invoking it. No exclusions or alternative routing are mentioned.

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 destructiveHint=false, so the tool's safety profile is covered. The description adds a valuable behavioral constraint: the MCP server rate limit (10 requests/60s) and a recommendation to cache results, 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 two sentences, front-loads the primary purpose, and contains no filler. It efficiently communicates the action, the ID source, and the throttling constraint, making every sentence earn 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 list tool with a safe annotation profile, the description covers the essential operational details: purpose, ID sourcing, and rate limiting. It does not describe the response format, but with no output schema and a straightforward list return, this is acceptable. The absence of an explicit note about the 'request' wrapper in the schema is mitigated by the schema itself.

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

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

With 0% schema description coverage at the top level, the description needs to compensate for parameter meaning. It adds one useful piece: how to source organizationId via organizations__get_organizations. However, it does not explain the type, limit, or offset parameters, leaving them entirely to the schema's nested descriptions.

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

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

The description states 'List of counterparties' (Список контрагентов), which is a specific verb and resource. It clearly identifies the tool's purpose, and no sibling tool targets the same resource, so it is distinguishable. However, it does not explicitly mention the 'inventory' context beyond the tool name, which slightly limits 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 provides explicit guidance on obtaining the organizationId via organizations__get_organizations, and includes a concrete rate-limit and caching instruction. This gives the agent clear operational context, though it does not explicitly contrast the tool 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=true and destructiveHint=false, so safety is covered. The description adds valuable behavioral context: MCP-server throttling (max 10 requests per 60 seconds) and a caching recommendation, which are not present in annotations and help the agent plan calls appropriately.

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 concise, with three short sentences each serving a distinct purpose: core action, ID source, and throttling guidance. The main purpose is front-loaded, and there is no filler or redundant repetition of schema 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 description covers purpose, organizationId source, and throttling, but omits where to obtain the documentId (likely from the list endpoint) and provides no information about the return value. Given the absence of an output schema and the need to call this tool correctly, this is a notable gap in 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 0%, so the description must compensate. It explains where to obtain organizationId, but does not clarify the source of documentId or its relationship beyond 'по id'. This adds partial meaning but leaves the agent to infer documentId semantics from the bare GUID schema 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 states 'Акт разборки по id' (disassembly act by id), which clearly identifies the action and resource. The explicit 'по id' distinguishes it from sibling list tools like list_inventory_disassemble_documents, and the instruction on obtaining organizationId further clarifies the scope.

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 by explaining where to obtain the organizationId via organizations__get_organizations, implying this tool is for fetching a single document by ID. It does not explicitly mention alternatives or when-not cases, but the get-by-id purpose is evident and no exclusions are stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds genuine behavioral value by disclosing the MCP-server throttling limit (10 requests per 60 seconds) and advising dialog-level caching, which the annotations do not provide. This is useful, non-contradictory 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?

Three short sentences each earn their place: purpose is front-loaded, ID sourcing follows, and the rate-limit/cache note is a compact operational warning. No filler or repetition.

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

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

For a get-by-ID tool with two required parameters, the description explains only organizationId provenance and omits how documentId is obtained or what its identifier semantics are. It also fails to point to the natural sibling list_inventory_incoming_invoices for discovering document IDs. The rate-limit note is helpful but does not fill these 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?

With schema description coverage at 0%, the description must compensate, but it only explains how to source organizationId and leaves documentId implicit despite it being a required field. The request-wrapper structure and additional_properties are also unaddressed. Partial value at best.

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 the resource ('Приходная накладная') and the access mode ('по id'), which clearly distinguishes it as an incoming-invoice-by-ID lookup from the many sibling get/list invoice tools. It lacks an explicit verb and does not spell out how it differs from sibling get_inventory_* tools, so it stops short of a 5.

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

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

The description gives a useful prerequisite directive for obtaining organizationId via organizations__get_organizations, but it does not say when to choose this tool over list_inventory_incoming_invoices or over the similar get_inventory_returned_invoice/get_inventory_outgoing_invoice tools. No alternatives or exclusions are mentioned, so usage context is incomplete.

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