employees__get_couriers_by_role

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.