AnySkills

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the description doesn't need to restate those. It adds context that the note is visible to managers in the deal card, which is useful. It doesn't mention any side effects beyond visibility, but for a simple note-adding tool this is 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, front-loaded with the main action and purpose, followed by a note about visibility. It's concise and every sentence adds value.

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 2-parameter tool with no output schema, the description covers the core purpose and visibility. It lacks explicit guidance on when to use it vs add_deal_task, and doesn't describe the return value or error conditions, but these are minor for a note-adding tool.

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 the purpose of the text (call outcome, agreement, objection) but doesn't add detail about deal_id beyond what the schema shows. The description gives some semantic context for the text parameter but not for deal_id.

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 the resource (deal feed/note), and gives examples of content (call outcome, agreement, objection). It distinguishes itself from siblings like add_deal_task by focusing on notes rather than tasks, though it doesn't explicitly name the sibling.

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

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

The description implies when to use it: when you need to add a note to a deal, and mentions that managers will see it in the deal card. However, it doesn't explicitly state when not to use it or contrast it with alternatives like add_deal_task.

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 offers strong behavioral detail—case-insensitive matching, auto-creating missing tags, replacing previous 'one of' group tags, and logging to the deal feed. However, it explicitly says 'Повторная метка ничего не меняет' (repeating the tag changes nothing), which contradicts the annotation idempotentHint=false; this is an annotation 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?

All five sentences carry substantive behavioral information and the main action is front-loaded. 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 two-parameter tool with no output schema, the description covers the core function, edge cases (missing tag, group tag replacement, repeat call), and side effect (feed event). It lacks explicit error/permission details, but those are not essential for invoking this simple tool.

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. It richly explains the 'name' parameter (case-insensitive, auto-created when missing) and implies deal_id through 'сделке', but it does not explicitly define deal_id or its expected format. 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 opens with a specific verb and resource ('Поставить сделке метку по имени') and then details the exact operation: set a tag on a deal by name. This clearly distinguishes it from siblings such as add_deal_note, add_deal_task, and remove_deal_tag.

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

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

Usage is implied rather than explicit: an agent can infer this tool is for adding a tag, but the description never states when to prefer it over alternatives or when not to use it. It provides useful context about tag behavior but no direct 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?

Beyond the annotations, it reveals meaningful behavior: the responsible party is the deal key owner, and tasks without a due date will not appear in 'Сегодня' and will be forgotten. This is useful, non-obvious context that helps the agent predict consequences. No contradiction with annotations was found.

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. It front-loads the action and provides the most important constraint (deadline required) with a concrete reason, 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 simple tool with three required parameters and no output schema, the description covers the core inputs and an important behavioral consequence. The only minor gaps are the lack of a stated return value and the somewhat niche internal term 'хозяин ключа', which may need domain knowledge to resolve.

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

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

With 0% schema description coverage, the description must compensate, and it partially does: 'по сделке' maps to deal_id, the examples map to text, and 'со сроком' maps to due_at. However, it does not explain the date-time format expected for due_at or give precise semantics for each parameter by 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 states a specific action and resource: 'Поставить задачу по сделке со сроком' — to create a task on a deal. It is not a tautology and clearly conveys the tool's function. However, it does not explicitly contrast itself with the sibling add_deal_note, relying on the task/note distinction in the names.

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 use examples ('позвонить, отправить договор') and emphasizes a hard precondition (deadline is required). It does not, however, say when to prefer this tool over alternatives like add_deal_note, or mention any 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, idempotentHint, and destructiveHint, covering the safety profile. The description adds value by explaining the operation is non-publishing, returns errors/warnings with meaning, and that each entry includes a node number and text. 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 three compact sentences with no filler. It front-loads the core safety property (does not publish) and then gives interpretation rules and output format, all in an organized way.

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 check with no output schema, the description covers purpose, result categories, and record format. It could state what an empty result means, but the current level is sufficient for an agent to invoke and interpret the tool.

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, but it does not mention funnel_id at all. The parameter name and tool title allow some inference, but the description adds no explicit meaning about what ID to pass or how it relates to the draft.

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 action ('check'), the resource ('funnel draft'), and a clear behavioral boundary ('does not publish anything'). It also explains the output categories (errors/warnings), making the tool's purpose distinct from sibling create/update/get/list operations.

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 implies when to use it: as the same pre-publication check but without side effects. The error/warning semantics further guide the agent on how to interpret results. It lacks explicit alternatives or 'use instead of' statements, but the context is clear enough.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: the percentage counts only mandatory published lessons, last-access information, cohort completion share, and the privacy rule that names only appear on stage 3. These details tell the agent what kind of data to expect and how it is computed beyond what any structured annotation provides.

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 packs several distinct facts into three compact sentences without redundancy. It leads with the central output (per-student percentage), then adds recency data, cohort-wide completion, and the anonymization rule. Every sentence carries a distinct piece of useful information; nothing is wasted.

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 single parameter and no output schema, the description communicates what data will be returned: student name or placeholder, percentage, last visit, days since, and completion share. It does not document the exact response format or JSON shape, but with no output schema, giving the natural-language semantics of each field is reasonable and sufficient for an agent to call the tool and interpret 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?

There is only one parameter, cohort_id, and the schema title says 'Cohort Id' while the description implies it identifies the cohort. With schema description coverage at 0%, the description partially compensates by making clear the output is for the cohort's students, but it does not spell out where to find cohort_id or that it must be an existing cohort. Baseline for one clearly-implied parameter is acceptable.

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

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

The description names a specific verb and resource with precise scope: per-student progress in a cohort. It details exactly what is computed (course percentage, last activity, days since, completion share), how the percentage is calculated (mandatory published lessons), and the name anonymity rule by stage. Even without pushing the title, it does not merely restate 'cohort progress'—the resource is well delimited and distinct from siblings such as stuck_students or get_school_summary.

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 say when to use this tool versus alternatives and gives no exclusions or alternative names. However, its level of detail clearly implies that it is the cohort-level progress view: to inspect completion and activity across a cohort's students, use this tool. It does not instruct the agent when not to use it (e.g., for a single student or for school-wide stats), so the guidance remains implicit.

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

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

The annotations are mostly false hints, so the description carries the behavioral burden. It discloses key behaviors: draft visibility, publication dependency, unlimited drafts, access-mode semantics, author identity as key owner, and idempotent replays with the same Idempotency-Key. The conditional idempotency does not contradict idempotentHint=false because it only applies when the client supplies that key.

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

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

Four dense sentences, each adding a distinct fact: draft status, publishing step, tariff policy, access modes, ownership, and idempotency. The most important behavior is front-loaded, and nothing repeats what the schema or annotations already provide.

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 creation tool with an output schema and one required parameter, the description covers lifecycle, visibility, access-mode semantics, ownership, and retry behavior. An agent has enough information to decide whether to call it and what to expect.

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

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

Schema description coverage is 0%, so the description must compensate. It fully explains the only non-obvious parameter, access_mode, with all three enum values and their meanings. The title and description parameters are self-explanatory from their names and schema constraints, so their omission is acceptable.

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 starts with a specific verb and resource: it creates a course draft, not a published course, and clearly states that the course is invisible to students until published via `publish_course`. This distinguishes it from publish_course and from the sibling create_lesson/create_module/create_test tools. The access-mode details reinforce the tool's 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 gives clear usage context: use this tool to create a draft, then publish it with `publish_course`, and drafts are unlimited on any plan. It does not explicitly enumerate when not to use this tool versus sibling create_* tools, but the resource type makes the main decision obvious.

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

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

Beyond the annotations, the description discloses important behaviors: a new group will be created if needed, and a name conflict with another tag or a former name results in a refusal and guidance to use the existing tag. This adds meaningful behavioral context that annotations do not provide.

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-loads the main purpose. The parameter-specific explanations are terse and information-dense, though the final sentence about name conflicts is a bit awkwardly phrased. Overall, it contains little waste.

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 most important domain-specific quirks, such as group creation and duplicate-name handling. However, it omits color semantics, and with no output schema it does not indicate what a successful response looks like. This leaves some gaps for an agent calling the tool with minimal 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?

With 0% schema coverage, the description must explain parameters, and it does explain group and is_source meaningfully. It also touches on name conflict behavior. However, it leaves the color parameter completely unexplained, so parameter documentation is only partially complete.

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 new tag in the deals directory), which clearly specifies the action and resource. It also implicitly distinguishes this tool from sibling add_deal_tag by emphasizing the directory-level creation rather than adding a tag to a deal.

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 usage context: create a new deal tag in the directory, and if the name is already taken, return the existing tag instead of failing. However, it does not explicitly contrast this tool with add_deal_tag or other sibling tools, nor does it state when creating versus updating is appropriate.

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 only declare readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds substantial behavioral context beyond that: nothing is sent to users, publishing requires a human in the admin panel, the response includes editor_url, and the response carries validation results (errors, warnings). This is exactly the kind of safety-relevant disclosure an agent needs before invoking a write operation.

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, each earning its place: purpose, safety/response behavior, and format/validation guidance. The most decision-relevant fact (nothing is sent to people) is front-loaded, and there is no filler. The second sentence is slightly dense with three clauses, but the overall structure 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?

For a tool with a complex nested graph object and no output schema, the description covers the essentials: purpose, the non-distribution guarantee, response contents (editor_url, errors, warnings), and the correction workflow. Delegating the graph structure to get_funnel_format is a reasonable completeness strategy, though it doesn't clarify how the draft is later published or whether it appears in funnel listings.

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% and none of the three required parameters (bot_id, name, graph) have descriptions. The description partially compensates by pointing to get_funnel_format for the graph parameter's structure — the most complex parameter — but adds nothing about bot_id or name semantics, leaving the agent to infer them from titles. Partial compensation warrants a 3.

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 action: creating a new bot funnel as a draft ('Новая воронка бота черновиком'). The draft qualifier distinguishes it from publish/create siblings, and the references to get_funnel_format and editing the draft orient the agent among related tools. However, sibling differentiation is implicit rather than explicit — it never names a tool like update_funnel_draft as the alternative for modifying the draft.

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 conveys when this tool is appropriate: to create a draft with no user-facing impact ('Людям ничего не уходит'), and it routes the agent to get_funnel_format for the graph structure and to 'правкой черновика' (editing the draft) for fixing validation errors. It lacks explicit when-not-to-use statements or a named alternative, so the guidance is clear context rather than full exclusion logic.

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 substantial behavior beyond the sparse annotations: duplicate persons are not re-created, repeat requests become notes on the open deal, and the Idempotency-Key header guards against double submission. This is exactly the kind of non-obvious behavior an agent needs, and it 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 sentences with no filler: the main action, the required contact condition, duplicate handling, and idempotency are each front-loaded in compact form.

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?

Despite 11 parameters and no output schema, the description omits parameter semantics for most fields and says nothing about the response shape. The duplicate/idempotency logic is valuable, but the tool is not fully specified for an agent to call it with 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 and 11 parameters, the description must compensate, but it only explains the contact triad (email/phone/telegram) and the semantic requirement that at least one be present. It provides no meaning for course_id or the six UTM parameters, leaving most parameters semantically opaque.

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

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

The description uses a specific verb 'Завести' and defines the resource as a lead ('заявку') with a unique scope: creating a person and a deal in one request. This clearly distinguishes it from sibling creation tools like create_course or create_lesson, even without naming them.

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

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

It establishes the key precondition that email, phone, or Telegram must be provided, and explains what happens with duplicate persons. It does not explicitly say 'use this instead of X' or list when not to use it, but the context is clear enough for an agent to select it for lead creation.

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 it's a non-read-only, non-destructive, non-idempotent write operation. The description adds that it appends to the end of the module, that old Editor.js format is accepted and converted, that video is provider+id not iframe, and that unknown fields are dropped. This is useful behavioral context beyond annotations, though it doesn't cover permissions or 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 dense and somewhat stream-of-consciousness with a raw JSON snippet inline. It's front-loaded with the key behavior (appends to end) but the formatting could be clearer. Every sentence adds some value, but the JSON example makes it bulky.

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 an output schema exists, return values needn't be described. For a mutation tool with 6 params and 0% schema coverage, the description covers the most complex parameter (document) well and notes video handling and unknown field dropping. It's missing guidance on `kind` enum, `is_required`, and `duration_minutes`, which would fully complete 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 carries the burden. It explains the `document` parameter's expected TipTap JSON structure and that Editor.js format is also accepted, which is crucial since the schema only says 'object'. It doesn't explain kind, is_required, or duration_minutes, but the document guidance is substantial.

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 makes clear it creates a lesson appended to the end of a module, and mentions the document format. It distinguishes itself reasonably from update_lesson and create_module by focusing on lesson creation. It doesn't explicitly compare to siblings, but the verb+resource is 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 statement 'Урок встаёт в конец модуля' implies when to use it (adding a lesson to an existing module), and it points to get_lesson for node examples. However, there are no explicit when-not-to-use conditions or direct comparisons to update_lesson.

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

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

The description adds meaningful behavioral context beyond the annotations: the module is placed at the end of the course, only module metadata is created here, and module order is mutable later. Annotations only indicate a non-read-only mutation, so this placement and scope information is useful.

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 filler. It front-loads the key placement behavior, then gives the most important sibling-tool pointer and reorderability note.

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 create operation with two straightforward parameters and an output schema available, the description covers what the tool does, where the module is placed, what it does not do (lessons), and how ordering can be handled. Nothing essential is missing 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% and the description does not define course_id or title. It only refers to the course and module conceptually, leaving the parameter meanings to self-descriptive names. With low schema coverage, 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 states a clear action: a module is appended to the end of a course. It also explicitly distinguishes this tool from create_lesson by noting that lessons are added separately, so an agent can tell what resource this tool operates on.

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 routes lesson creation to create_lesson ('Уроки добавляются в модуль отдельно, create_lesson'), and it tells the agent that module order can be adjusted later, so ordering is not a concern at creation time. This is clear when-to-use and when-not-to-use guidance.

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

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

The description adds valuable behavioral context beyond the annotations: the step is 'ВСЕГДА выключенный' and 'до этого он ничего не делает', meaning it is created inert and only becomes active when the owner enables it in the dashboard. This is meaningful and not present in 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 dense and contains no filler, but it is structured as one long run-on paragraph with semicolon-separated clauses. This makes it harder to parse quickly. A structured list or clearer separation between event, action, and modifiers would improve readability.

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

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

The description covers most of the 13 parameters and the core behavior, but it omits lost_reason and does not describe what the tool returns or what happens after creation. With no output schema and no required parameters, the agent is left to infer some operational 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?

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It does well: it explains event choices (tag_id/stage_id), action choices (bot, tag_add, tag_remove, stage, task, goal), delay_minutes, skip_if_replied, and target fields, and even adds constraints like «Оплачено» нельзя. However, the lost_reason parameter is not mentioned at all.

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 title "Собрать шаг правила продаж выключенным" and tool name create_sales_rule clearly indicate that the tool produces a sales-rule step, and the description emphasizes it is created in an always-disabled state. It is distinguishable from siblings like update_sales_rule and create_sales_stage, though the description itself never explicitly states a verb such as 'creates'.

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 when-to-use guidance is provided. The description explains the structure of the rule but does not say when to use create_sales_rule versus update_sales_rule, list_sales_rules, or create_sales_stage, and it gives no exclusions or prerequisites.

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 are all neutral (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so they carry little information. The description adds genuine behavioral value: «Людям это ничего не шлёт» discloses that no notifications are sent, and «Удалить этап может только человек в кабинете» warns that the created stage cannot be deleted via API. This goes beyond the structured fields 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?

Four short sentences with zero filler. Purpose and placement are front-loaded first, followed by the color domain, then two distinct behavioral notes. Every sentence earns its place and the whole description is compact relative to the information it conveys.

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 3-parameter creation tool with no output schema, the description covers purpose, positioning, allowed colors, and side-effect constraints. Minor gaps remain: the return value is not hinted at, and the target funnel is only implied as «воронка продаж» since no funnel_id parameter exists. These are small omissions for a simple tool.

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

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

With 0% schema description coverage, the description must compensate, and it largely does: it enumerates the valid color values (secondary, azure, blue, purple, yellow, orange, green, red) matching the color parameter, and explains after_stage_id semantics including the null case. The required name parameter is left self-evident, so meaning is added for two of three 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 opens with «Новый этап „в работе“ в воронке продаж», a specific verb+resource: creating a new sales-funnel stage. It adds distinguishing details — exact placement relative to after_stage_id or to «Оплачено»/«Отказом» — which clearly separates it from siblings like update_sales_stage, list_sales_stages, and create_sales_rule.

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

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

The description gives clear context about where the stage lands (right after after_stage_id, or before «Оплачено»/«Отказом» when omitted), which helps an agent understand behavior, but it never states when to choose this tool over alternatives or when not to use it. No sibling is named and no exclusion condition is given, so usage guidance is 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?

The description contradicts the annotation idempotentHint=false by explicitly stating that the same link arguments will not create a new link and will return the existing one with created=false. This makes the operation idempotent in effect, so the description conflicts with the annotation. Otherwise it adds useful details about automatic UTM tagging, UTM override precedence, and 400 error responses.

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

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

The description is a single dense paragraph but contains no filler. It front-loads the main purpose and then moves through parameter semantics, deduplication behavior, example, and error handling in a logical order, though the lack of visual structure reduces readability.

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

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

Given 9 parameters, no output schema, and moderate annotation coverage, the description covers most parameter meanings, deduplication behavior, and an example return shape. It omits the title parameter and does not fully describe the response structure, but it is largely sufficient 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 carry the parameter burden. It explains 8 of 9 parameters with meaningful semantics: url, bot_username, start_code, platform (with enum-like examples), utm keys and precedence, path, button, and set_id. The title parameter is not described, preventing a perfect score.

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

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

The description states exactly what the tool produces: a short link on the school domain pointing either to a URL or to a bot, with automatic UTM tagging. It distinguishes itself from the sibling suggest_link_path by naming it for path suggestions, and the example makes the output concrete.

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

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

The description gives clear context for what the tool does and mentions suggest_link_path for generating path variants, but it does not explicitly say when to use this tool versus alternatives like update_short_link or list_short_links. Usage is implied by the create operation.

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

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

The description adds meaningful behavioral context beyond annotations: the whole test is created in a single call, question types have specific answer semantics, and placement rules are stated. Annotations already signal a non-read-only, non-idempotent, non-destructive operation, and the description clarifies what the mutation actually does.

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, front-loaded with the core promise, and organized into clear blocks for question types and placement. Every sentence contributes value without 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?

The description covers the most complex parts of the schema: question kinds, correct-answer fields, and placement semantics. It works well with the schema's constraints, though it omits subtle validation guidance such as options being needed for one/many and the meaning of max_attempts=0; with no output schema, a little more would make it fully complete.

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

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

With 0% schema description coverage, the description must document parameters. It explains the important nested semantics: kind values, correct_text for text/number, reference_answer and criteria for open, and lesson_id/module_id placement. However, pass_score, max_attempts, and the meaning of weight/is_correct are not addressed, leaving 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 opens with a specific verb+resource: creating a complete test with questions in one call. It enumerates question kinds and placement targets, making it unambiguous and distinguishable from sibling create_course/create_lesson/create_module 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?

Clear placement guidance is provided: lesson_id places the test as a block at the end of a lesson, module_id as the module's final test, and both or neither are allowed. It does not explicitly name sibling alternatives or state when not to use this tool, so it stops short of a 5.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds valuable behavioral detail: modules are in order, lessons are in order, each lesson includes type/duration/mandatory flag, and module final tests are named by number. It also discloses what is NOT included, preventing false expectations.

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

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

Three focused sentences deliver the core behavior, ordering guarantees, and cross-references to sibling tools. The most important information 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 read-only single-parameter tool with no output schema, the description fully conveys the return shape: ordered modules, ordered lessons with relevant metadata, and the naming convention for final tests. It also tells the agent where to go for related content, leaving no critical ambiguity.

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 never explains course_id. It does not say how to obtain it, what format is expected beyond the schema's integer type, or that it selects which course to fetch. The parameter is simple, but the description provides no explicit guidance to compensate for the missing 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 exactly what the tool returns: one complete course with modules and lessons in order, including lesson type, duration, and mandatory flag. It also distinguishes itself from get_test and get_lesson by naming what those tools cover instead.

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 routes to get_lesson for lesson text and get_test for module test questions, making the boundaries between sibling tools clear. It also implies the appropriate use case: retrieving the full structural skeleton of a single course.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context by detailing the types of events returned (manager notes, transfers, access opening, payments) and the limit of 30 events. This goes beyond 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 waste. It front-loads the main purpose and provides useful context about the timeline events. It is concise 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?

Given the tool's simplicity (one parameter, read-only, no output schema), the description adequately covers what it returns (fields, person, events) and its purpose. It does not describe error handling or output structure, but for a getter this is sufficient. The description is complete enough for an agent to use 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?

The input schema has only deal_id (integer) with 0% description coverage. The description does not explicitly explain deal_id, but the tool name and context make it obvious. Since there is only one parameter and its purpose is self-evident, the lack of description is acceptable, but it does not add 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 clearly states the tool retrieves one deal with its fields, person, and last 30 timeline events. It distinguishes itself from sibling tools like list_deals (which lists deals) and move_deal (which updates). The verb 'get' and the resource 'deal' are explicit, and the scope is specific.

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 context for when to use it: to understand what is happening with a person and what was agreed. It does not explicitly mention alternatives or exclusions, but the context is clear enough that an agent can infer it is for retrieving a single deal with timeline, not for listing or modifying.

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 read-only, idempotent, and non-destructive annotations already cover the safety profile. The description adds useful behavioral context: it returns both draft and published versions, includes a version number for editing, and explicitly warns that people counts are numbers without names.

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: the main deliverable appears first, and every clause adds information. The final clarification about counts being numeric and omitting names is valuable, not redundant.

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 adequately conveys the expected return contents. It does not explain possible edge cases like a missing draft or published version, but the core information needed to call it is present.

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

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

The schema has 0% description coverage, so the description should compensate by explaining funnel_id. It does not mention the parameter at all, although the parameter name itself is fairly self-explanatory.

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 exactly what the tool returns: the draft and published funnel versions, the draft version number, and per-block counts. It is clear and maps to the resource, though it lacks an explicit verb and does not name a sibling to differentiate from.

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 note that the draft version number is 'нужен для правки' (needed for editing) implies a use case for this tool. However, it does not give explicit when-to-use versus alternative tools such as get_funnel_format or check_funnel.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: the tool returns the structural format of a funnel and clarifies that drafts are sent entirely in this format. 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: two short sentences that front-load the core definition of the tool and then provide actionable usage context. No redundant or filler content.

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 zero-parameter, read-only reference tool, the description is complete. It explains what the format contains, when to read it, and how drafts relate to the format. No output schema exists, but the description adequately conveys what the agent will learn from the tool.

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 and an empty schema, so there are no parameter semantics to explain. Per the baseline for zero-parameter tools, a 4 is appropriate; the description does not need to compensate for missing parameter documentation.

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

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

The description clearly identifies the tool as describing the funnel format ('Формат воронки: блоки, их настройки и стрелки') and explains that it should be read before assembling or editing a funnel. It distinguishes itself from data-reading tools like get_funnel or check_funnel by focusing on the structural format rather than funnel contents.

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

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

The description explicitly states when to use the tool: 'Прочитать до того, как собирать или править воронку' (read before assembling or editing a funnel). It does not explicitly name alternatives or exclusions, but the timing guidance is clear enough for an agent to understand when this reference is needed.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive/openWorld=false, so the safety profile is covered. The description adds real context about the returned document shape and that unopened lessons are also served in this format, but says nothing about permissions, error behavior for a missing lesson_id, or 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 a dense wall of format specification that front-loads node types rather than the tool's purpose. Much of the enumeration (node list, attr names) is authoring detail more relevant to create_lesson than to calling get_lesson, so it is not well-sized for the selection decision.

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

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

With no output schema, the description carries the entire return-value burden and does so thoroughly, enumerating the TipTap/ProseMirror document structure. It omits failure behavior and whether metadata (title, module) accompanies the document, but the core output contract is well covered.

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%, so the single lesson_id parameter is documented nowhere. The description never mentions the parameter, adding no semantics beyond the self-evident name; with only one obvious integer id this is tolerable, but it does not compensate for the coverage 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 centers on the output — 'Документ урока в формате TipTap/ProseMirror' — which, paired with the name get_lesson and title 'Урок целиком', makes it clear this retrieves a full lesson document. It never states a retrieval verb explicitly and does not name a sibling to distinguish itself from get_course/update_lesson, but the purpose is unambiguous.

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

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

There is no when-to-use guidance, no prerequisites, and no exclusions (e.g. vs get_course for structure or update_lesson for editing). The only cross-tool hint is 'Ответ годится как образец для create_lesson', which is about reusing the output rather than when to call this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description adds real value the annotations cannot: the metric vocabulary returned and the time-window semantics (Moscow time, inclusive dates, default 30 days, days=0 meaning all time). No output schema exists, so disclosing the return shape here is genuinely useful.

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?

Front-loads the purpose, then the return payload, then the period rules — a sensible order. Dense but nearly every clause adds an actionable detail; the long metric enumeration could be trimmed slightly.

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 stats tool with no output schema, the description supplies both the return-payload structure and the full date-window contract, which is what an agent needs to call it correctly. Only sibling routing guidance 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 carries the burden and does so for the date parameters: since/until are YYYY-MM-DD, inclusive, Moscow time; omitted means last `days` (default 30); days=0 means all time. Only link_id is left implicit, which is acceptable given the 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?

States a specific verb and resource: returns what a single short link produced over a period, and enumerates the metric groups (funnel, daily, paths, referrers, devices). It implicitly distinguishes itself from siblings like question_stats or check_funnel by scoping to one link, but never names those alternatives explicitly.

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

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

Usage is implied rather than stated: the worked example ("сколько оплат дал ролик за сентябрь") shows a valid call, but there is no when-to-use/when-not guidance and no routing against the many sibling read 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 readOnly, idempotent, non-destructive behavior. The description adds useful context by stating that the numbers are real and come from the same key, implying data scoping and authenticity. It also guides the AI’s downstream presentation behavior, which is beyond what annotations provide.

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 each part serves a purpose: the first sentence states the returned data, the second explains invocation timing and presentation, and the third reinforces data authenticity. No redundant wording is present.

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 parameterless read-only summary tool, the description covers what the tool returns, when to invoke it, how to interpret the data, and how to use it in conversation. Annotations handle safety, and the lack of an output schema is mitigated by the explicit field list in the 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?

The tool has zero parameters and schema coverage is 100%, so there are no parameter semantics for the description to add. The description instead focuses on the return content and usage context, which fully compensates for the lack of 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 specifies the tool's content: school name, tariff, number of courses and published ones, students, streams, and key permissions. It also distinguishes the tool's role by stating it is called first upon connection, setting it apart from the listed siblings.

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

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

The description explicitly says the AI should call this tool first when connecting and use its data to present itself in a human-friendly way. It gives clear context for when to use the tool, though it does not explicitly mention when not to use it or list alternative conditions, so a perfect score is not warranted.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive, closed-world). The description adds two non-obvious behavioral facts: correct answers ARE included in the response, and it justifies this via an access-control rule tied to role. That is meaningful disclosure beyond the annotations, though it says nothing about failure behavior if the test is out of scope.

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?

Front-loaded with what the call returns, then the question type vocabulary, then the authorization rule. Every sentence carries information and there is no filler, though the access-control sentence is slightly dense and could be split.

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

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

With no output schema, the description correctly compensates by describing the returned structure and even enumerating the question-type values. Combined with the role-based scope rule, an agent has enough to invoke it correctly; only the test_id parameter remains unexplained.

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?

There is a single parameter (test_id) with 0% schema description coverage, so the description carries the burden but adds nothing about what test_id is or where to obtain it. The name is largely self-evident, so it remains a minimum-viable 3 rather than a failure.

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 gives a specific resource and enumerates its contents (pass threshold, attempt count, ordered questions with type and correct answers), so the agent knows exactly what a successful call yields. It does not reference any sibling tool (e.g. create_test, get_lesson) to draw the retrieval boundary, 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?

It states who may retrieve which test (owner/methodologist get any test in the school; others only their course test), which is useful authorization context. However, it never says when to prefer this tool over alternatives such as question_stats or review_queue, leaving usage implied rather than prescribed.

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 this as read-only, idempotent, and non-destructive. The description adds practical behavioral context beyond the annotations: it specifies the fields returned (number, name, address, active status) and explains the downstream purpose of the bot number. Pagination or exact response formatting is not mentioned, but that is a minor gap for a zero-parameter read-only list.

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 earning its place: the first states the payload returned, the second explains why the bot number matters. The information is front-loaded and there is no filler, repetition, or restatement of schema details.

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 with no parameters, the description covers the core return values and gives practical context for using the data. It does not specify the exact JSON response shape or how the 'works' status is encoded, but with no output schema present, this is a minor omission rather than a blocking gap.

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

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

The input schema has no parameters, so there is no semantic ambiguity to resolve. The description does not need to explain parameter behavior, and the baseline of 4 applies for a zero-parameter tool. The mention of the bot number's purpose adds useful context to one of the returned fields, not to 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 identifies the resource clearly — Telegram bots of the school — and enumerates the returned attributes: number, name, address, and whether it works. Although there is no explicit verb in the description, the tool name 'list_bots' and the phrase 'Боты школы в Telegram' make the operation unambiguous. It does not risk confusion with any sibling tool.

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 sentence 'Номер бота нужен, чтобы читать его воронки и собирать новые' explicitly motivates the data returned by this tool and places it in a workflow before funnel read/creation operations. It does not name alternatives, but no sibling exposes bot data, so the contextual 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 declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context: the endpoint returns only cohorts with a common schedule, excludes students without a cohort, and distinguishes progress as a separate resource. For a zero-parameter read-only tool this is sufficient.

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 output fields, followed by a definition and boundary/edge-case routing. 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 simple, parameterless, read-only list endpoint with no output schema, the description fully covers what is returned, the concept of a cohort, exclusions, and pointers to related tools. Nothing needed for correct invocation is missing.

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

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

The tool has zero parameters and 100% schema coverage (empty schema), so there is nothing for the description to clarify about arguments. The baseline for zero-parameter tools applies.

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

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

The description identifies the resource (cohorts/потоки) and the fields returned (course, start/end dates, enrollment count), and it distinguishes this tool from cohort_progress and stuck_students by scope. However, it lacks an explicit verb such as 'list' or 'returns', relying on the tool name and context to convey the action.

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

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

It explicitly states that students outside cohorts are not included and directs the agent to stuck_students without cohort_id for that case, while also pointing to cohort_progress for progress data. This provides clear when-to-use and when-not-to-use guidance with named 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 provide readOnlyHint, idempotentHint, and destructiveHint, so the description only needs to add extra behavior. It explains that drafts are included, how drafts differ via is_published, and that students only see published courses, which is valuable 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 three short sentences with no wasted words. It front-loads the core purpose, then covers output fields, usage order, and a meaningful distinction between drafts and published courses.

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 zero-parameter listing tool with no output schema, the description is complete: it states what is returned, why it should be called first, and how to interpret the is_published field. Nothing essential is missing for an agent to invoke and use this 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?

The tool has no parameters, so the baseline is 4. The description adds relevant context about the output (course names, publication status, counts, course numbers) even though it does not need to explain parameter semantics.

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 lists all school courses including drafts, with name, publication status, and module/lesson counts. It also distinguishes this from other course-related tools by explaining it returns course numbers used by other requests, which is a specific and useful 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 explicitly says to call this tool first to learn course numbers for subsequent requests, giving a clear usage context. It does not explicitly name alternatives or state when not to use it, but the 'call first' guidance and mention of student-visible published courses provide strong situational 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses sort order, privacy handling for names, tag matching including legacy names, and a maximum result cap of 200. This adds substantial behavioral context not visible in 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?

The description is a single dense paragraph with no wasted words. It front-loads the core purpose and returns a useful enumeration, then adds examples and constraints. The structure is acceptable though it could be slightly clearer with separate clauses.

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 listing tool with no output schema, it covers the main returned fields, sorting, filtering examples, privacy behavior, and limit enforcement. The semantics of open_only and updated_since remain implicit, but the overall definition is adequate for most calls.

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%, so the description must compensate. It explains tag (including former names), stage filtering, and the 200-result cap. However, open_only and updated_since are not explained, and limit's default is not stated, leaving clear gaps for some 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 tool lists school deals (Сделки школы), newest first, and enumerates the fields returned (stage, course, amount, tags, source). It is easily distinguished from siblings like get_deal (single deal) and list_deal_tags (tags only).

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

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

Provides clear usage context with concrete examples: filtering by stage for 'deals awaiting payment' and by tag for 'who is silent'. It does not explicitly mention when to prefer get_deal or other siblings, but the intended use cases are clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable domain context beyond annotations: it details the tag attributes, explains the group behavior (one tag per group, new tag replaces old), and the source indicator. This helps the agent understand the data model without contradicting any annotation.

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. It front-loads the content of the reference and ends with a clear purpose statement. Every sentence adds value: the first lists attributes, the second explains the group rule, and the third states the use case. No redundant 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 list with no parameters, the description is complete. It explains what the tool returns (all relevant tag fields), the domain-specific behavior (group exclusivity), and the practical reason to call it. Since there is no output schema, this description compensates adequately. The absence of pagination details is acceptable for a reference list of likely small size.

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

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

The tool has zero parameters, so the baseline is 4. The description correctly focuses on what the tool returns rather than parameters. Since there are no parameters to document, the description adequately conveys the output semantics.

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 function: it provides a reference (справочник) of deal tags with specific attributes (name, color, group, source, previous names, usage count). It also states the intended use case (assigning an existing tag rather than creating a duplicate), which distinguishes it from sibling tools like add_deal_tag and remove_deal_tag. The verb 'list' and resource 'deal tags' are explicit, and the purpose is unambiguous.

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

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

The description implies when to use this tool: before tagging a deal, to check existing tags and avoid duplicates. It does not explicitly name alternatives or state when not to use it, but the context is clear. A more explicit reference to add_deal_tag or remove_deal_tag would strengthen this, but the implied guidance is adequate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful context about what data is included (state, unpublished edits, whose edits they are), but it does not disclose operational details such as pagination, ordering, or behavior when a bot has no funnels. 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 one compact sentence, front-loaded with the resource, and the parenthetical status translations pack useful information without filler. It is appropriately sized for a simple list tool.

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 output fields, and annotations cover safety, but it omits explicit list semantics, possible filtering, and any relationship to sibling tools. Since there is no output schema, the description should more clearly state that this returns all funnels for the given bot.

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 only parameter, bot_id, is self-evident and the description's 'Воронки бота' points to the bot context. The description does not explicitly explain that bot_id selects the bot, so it does not fully compensate for the missing schema documentation, but the parameter is simple enough to infer.

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 (bot funnels) and the key output dimensions: status, presence of unpublished edits, and ownership. It does not use an explicit verb like 'list' or 'return', relying on the tool name, and it does not explicitly distinguish this from get_funnel or check_funnel, but the scope 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?

No guidance is given on when to use list_funnels versus get_funnel, check_funnel, or other siblings. There are no alternatives, exclusions, or conditions mentioned, so the agent must infer usage from the tool 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 cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description adds useful context by enumerating the returned fields, including the 'problem' field explaining why a rule may not fire. It doesn't disclose anything beyond the field list, such as ordering or whether the result is exhaustive, but for a zero-parameter list tool that is a minor gap. 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?

One dense sentence that front-loads the subject ('Шаги правил продаж') and packs the entire field inventory into a compact colon-separated list. The heavy parenthetical nesting for action types is slightly dense but contains 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 zero-parameter read-only list tool, the description covers what an agent needs: the structure and meaning of each returned field, with annotations covering safety and idempotency. Since no output schema exists, the field enumeration in the description partially compensates. It could explicitly state that the result is the full set of rules, but this is a minor omission at this complexity level.

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

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

The input schema has no parameters, so the rubric baseline is 4 and there is nothing for the description to add about parameters. The description instead documents the returned item structure, which is the most relevant semantic content for a list tool.

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 name list_sales_rules supplies the verb+resource, and the description explains what a sales rule consists of: trigger (tag or stage with number), delay in minutes, action (bot funnel, tag_add, tag_remove, stage, task, goal), enabled flag, and problem. This distinguishes it from mutation siblings like create_sales_rule and update_sales_rule. However, the description never explicitly states that the tool returns the list of all sales rules.

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

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

Usage is implied: this is a read-only listing tool whose output is the configured sales rules with their steps. No explicit when-to-use guidance or alternatives are mentioned, which matters less here because the sibling set contains clear mutations (create/update_sales_rule) rather than competing list 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, idempotentHint, and destructiveHint, so safety is well covered. The description adds useful behavioral context by defining the exact stage semantics and indicating that stages are returned in order, 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 and front-loaded: it states what the tool returns, the order, the fields, and the stage values in two sentences. 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 zero-parameter read-only reference tool, the description fully covers what an agent needs: the returned data, the stage vocabulary, ordering, and the practical reason to call the tool. No output schema is needed to make this usable.

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 there is no schema burden to compensate for. The description adds relevant meaning about the output content (stage names and meanings), making the tool's data understandable without needing parameter documentation.

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 that the tool returns sales funnel stages in order with their number, name, and meaning, and explicitly lists the stage values (open, won, lost). This makes the tool's purpose immediately understandable and distinguishable from sibling tools like list_deals or move_deal.

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 states that the stages are needed to move a deal or select deals at a stage, giving the agent concrete context for when to call this tool. It does not explicitly mention exclusions or alternatives, but the use case is clear.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context beyond that: sorting is newest-first, each item has 30-day stats fields, pagination is capped at 200 with offset, and total is returned.

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 front-loaded with the resource and return shape, then filters, an example, and pagination. Despite its density, every clause adds needed information for a tool whose schema has no parameter descriptions.

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

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

With no output schema and 0% parameter description coverage, the description supplies the return fields, filter semantics, an example query pattern, and pagination limits. Together with the safety annotations, this is complete 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 carries the full burden. It explains q search scope, lists the allowed platform values, clarifies set_id as links for one video or campaign, describes archived=true, and covers limit/offset pagination behavior.

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

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

The description specifies the resource (school short links), the operation (list, newest first), and the item contents including stats_30d fields. It is clearly a list tool, but it does not explicitly name or contrast with the sibling get_link_stats, so sibling differentiation is inferred rather than stated.

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

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

It gives a concrete usage example ('which link under YouTube videos brought more money') and explains filter semantics such as q, platform, set_id, and archived. It provides clear context for when to use these filters but does not name alternatives or say when not to use this tool.

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

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

The description adds meaningful behavioral context beyond the annotations: it restricts movement to the same funnel, indicates that the optional reason is for refusal, and discloses a side effect—the transfer is written to the deal feed with attribution to the employee's API key. This is valuable for an agent deciding whether and how to call 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 concise: three short sentences that front-load the core action, then provide the optional-reason nuance and the important feed-logging side effect. No words are wasted.

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

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

For a simple mutation tool with three parameters and no output schema, the description covers the main action, scope constraint, optional parameter usage, and a relevant side effect. It lacks explicit sibling differentiation and any mention of response or error behavior, but these are not critical for this tool's complexity.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the reason parameter as being for refusals and implies stage_id must belong to the same funnel. However, deal_id and stage_id are only self-evident from names and receive no explicit semantic or constraint detail beyond the same-funnel statement.

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

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

The description uses a specific verb and resource: 'Перевести сделку' (move a deal) to another stage 'той же воронки' (of the same funnel). This clearly identifies the action and scope, but it does not explicitly differentiate from sibling tools such as add_deal_note or list_sales_stages.

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 strongly implied by the verb and resource, and the note about specifying a reason for refusal adds practical guidance. However, there is no explicit statement of when to use this tool versus alternatives, and no exclusions 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description explains that publication is subject to the tariff limit, only published courses count toward the limit, hitting the limit returns a 409 with guidance, and unpublishing is always available. This gives the agent actionable behavioral detail 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?

The description is three tight sentences: primary behavior first, then business rule, then error/unpublish clarification. Each sentence adds distinct information without redundancy, making it well-structured and easy 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 two-parameter mutation with no output schema, the description covers the core action, the tariff restriction, the error case, and the unpublish behavior. It does not describe the success response format, which is a minor gap given the absence of an output schema, but overall it is substantially complete.

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

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

Schema coverage is 0%, so the description must compensate. It explains the effect of the published flag through the two states (open to students vs draft) and mentions the tariff check, but it never explicitly maps course_id or published to the schema fields, leaving some inference required.

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

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

The description opens with a specific verb and resource: 'Открывает курс ученикам или возвращает в черновики', clearly indicating the tool toggles publication status on a course. This differentiates it from siblings like create_course or update_lesson, which handle creation and lesson edits respectively.

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

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

The description gives clear context for when to use the tool: publishing is the same as the dashboard button, runs through the tariff limit, and unpublishing is always possible. It does not explicitly name alternatives or exclusions, but no sibling tool offers the same publish/unpublish capability, 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?

The annotations already declare the tool read-only and idempotent, so the description's additional value is its non-obvious counting semantics: only completed attempts are considered, and ALL attempts are counted rather than just the last one. It also provides an interpretation heuristic. No contradiction with 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, purposeful sentences: the first states the core report contents, the second adds the crucial all-attempts behavior, and the third gives practical interpretation guidance. There is no filler or repetition of schema/annotation 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 low-complexity, one-parameter read-only report, the description covers the metric definitions, the attempt scope, and the meaning of low percentages. It does not specify the output format or ordering, but given no output schema and a simple integer input, the description is sufficiently complete for an agent to invoke 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?

The sole parameter test_id has no schema description, and the description only indirectly refers to 'the test' without explicitly stating that test_id selects which test's questions to analyze. This is a gap at 0% schema coverage, but the single integer parameter is simple and the description does provide some semantic link by framing the tool around a specific test.

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 specifies exactly what the tool computes: for each test question, the number of answers and the share of correct answers across completed attempts. It also adds the distinctive all-attempts-vs-last-attempt nuance, which differentiates it from other analytics tools, though it does not explicitly name a sibling.

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 is meant to reveal questions where people stumble, and it explains why counting all attempts is necessary ('a question stumbled on from the first time is visible only this way'). It offers an actionable interpretation threshold (<50% correct means the question should be reviewed), but it does not explicitly name alternatives or say 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 provide only basic flags, so the description adds real value by disclosing that the tag remains in the catalog and on other deals, and that an absent tag yields `changed: false`. This clarifies the non-destructive scope of the operation beyond what annotations state.

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; the action is front-loaded, followed by the important side-effect boundary and the no-op response. 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 simple two-parameter mutation tool with no output schema, the description covers the action, the key boundary condition, and one return-value case. The positive return case is only implied, but the essential call semantics are 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?

Schema description coverage is 0%, so the description must compensate. It clarifies that `name` may be the current or former tag name, which is valuable, but it does not add meaning for `deal_id` or explain where to obtain it. Compensation is 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 uses a specific verb ('Снять') and resource ('метку со сделки'), and adds how the tag is identified (by current or former name). This clearly distinguishes the tool from siblings like add_deal_tag and list_deal_tags.

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

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

The description implies the obvious use case—removing a tag from a deal—but it does not explicitly state when to prefer this tool over alternatives or when not to use it. The no-op caveat is useful, but explicit usage 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, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond annotations: the queue is sorted from oldest, contains specific metadata, and cannot be used to accept or reject submissions. No contradictions with annotations.

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

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

The description is one compact sentence that front-loads the purpose, includes the essential data fields, and ends with a clear capability limit. Every part adds value 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 zero-parameter read-only tool with thorough annotations, the description is complete. It tells the agent what the queue contains, how it is ordered, and that only viewing is possible. No output schema exists, but the description adequately covers what to expect.

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

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

The tool has zero parameters and schema covers 100% of them vacuously. Per baseline, 0 params gets a 4; the description correctly explains what the no-parameter call returns, so no parameter documentation gap exists.

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

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

The description names a specific resource (works waiting for curator review), the relevant fields (who submitted, assignment, time, hours waiting), and the sorting (oldest first). It also explicitly states the tool is read-only, distinguishing it from action-oriented tools among the siblings.

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

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

The description makes the use case clear: to inspect the review queue. It also states a firm when-not-to-use boundary: accept or return actions are not available via this API. It does not name an alternative tool explicitly, but the context is sufficient for an agent to avoid misusing this as a write tool.

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/idempotent/non-destructive annotations, the description explains the exact inactivity criteria, the meaning of `days`, the cohort scoping behavior, and that course drafts are excluded. This gives the agent a clear behavioral model of what the tool computes.

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 focused sentences, front-loaded with the core definition and followed by scoping and exclusion details. Every sentence adds value and no unnecessary text is present.

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 two optional parameters and rich annotations, the description is complete. It covers the definition, parameter semantics, scope behavior, interpretation guidance, and edge cases like drafts. Nothing essential is missing for correct selection and 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 carries the full burden for both parameters. It clearly explains `days` as the inactivity threshold and `cohort_id` as an optional cohort filter, including behavior when omitted. Both parameters are fully compensated for.

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 purpose: listing students who have been inactive for more than `days` days, with a precise definition of inactivity. It differentiates itself from sibling tools by framing this as a curator-facing address list rather than a progress or evaluation tool.

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

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

The description gives clear context on when to use the tool, including how `cohort_id` scopes the query and that without it the entire school is included. It also warns that this is not a student evaluation, but it does not explicitly name alternative tools or state when not to use this one.

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?

With annotations already marking it read-only, idempotent, and non-destructive, the description adds substantial behavioral context: it creates nothing, returns up to three available suggestions ranked best-first, and explains the format constraints. It also gives a concrete example of the output. This goes well beyond the structured safety 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 front-loaded with purpose and output format, then lists inputs, then explains usage with an example. It is informative and mostly efficient, but the long inline enumeration of parameters is dense and could be more scannable. It earns its length overall but is not maximally crisp.

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 9 optional parameters, no schema descriptions, no output schema, and clear annotations, the description provides everything needed: what it returns, how suggestions are built, what each input represents, and how to use the result with create_short_link. An agent has no missing context 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?

The input schema has 0% description coverage, so the description carries the full burden. It maps all nine parameters to their real-world meaning (url = target address, title = link name, button = video button text, set_id = video/school campaign, code = bot funnel code, etc.) and provides an example of how inputs translate into suggestions. This fully compensates for the schema 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 a specific action: generating up to three available, readable link paths for a new short link, best first. It distinguishes itself from the sibling create_short_link by explicitly saying it creates nothing and by describing the output format (Latin, hyphens, max 40 chars). An agent can tell exactly what it does.

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

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

It explicitly says to pass the chosen path to create_short_link and notes that without a path, create_short_link will choose the first suggestion itself. This gives clear when-to-use and how-to-use guidance relative to the alternative, leaving no inference needed.

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

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

The description adds useful behavioral details beyond the annotations: renaming preserves the old name so bots/rules still find the tag, and an empty string for group removes the tag from the group. These are non-obvious behaviors not expressed by readOnlyHint, destructiveHint, or idempotentHint. Null semantics and return behavior are not covered, but the key operational quirks are disclosed.

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: two sentences, no filler, and the main operations are front-loaded. The first sentence enumerates the supported updates, and the second sentence adds a critical limitation. It does not repeat schema titles or annotation 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 an update tool with five optional parameters, the description provides the essential semantic context: what can be changed, the rename-remembers-old-name behavior, group clearing via empty string, and the delete/merge restriction. The main gaps are the lack of explicit null/empty semantics for fields other than group and no mention of what the tool returns, which would be more important because no output schema is present.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It does explain the meaning of name, color, group, and is_source, and adds the empty-string-clears-group rule. However, it does not explain the required tag_id parameter, does not give valid value formats, and does not address null vs. omitted parameters, which is significant since most fields allow null.

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

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

The description names a specific resource (deal tag) and the exact operations available: rename, change color, change group, or change source flag. It also explicitly excludes deletion and merging, which distinguishes it from sibling operations like remove_deal_tag or any merge capability. This is a clear verb+resource statement with 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 clearly states what the tool is for and gives an explicit non-goal: deleting and merging tags can only be done in the office. This helps an agent avoid using this tool for destructive merge/delete actions. However, it does not name alternative tools such as create_deal_tag or remove_deal_tag, so the guidance stops short of full 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 mark the operation destructive, and the description adds valuable nuance: the published funnel remains live until the user publishes, replacing is all-or-nothing at the draft level, optimistic concurrency yields 409 on stale draft_version, and the response reports affected blocks and a check. 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 dense sentences cover the action, the concurrency model, the recovery path, and the response contents with no filler. The core verb and object are front-loaded before details.

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 destructive mutation with no output schema, it includes a response hint and a 409 retry path, which is good. But the definition does not describe how to build the graph object or where to obtain its shape, and it leaves the optional name parameter unexplained, so the agent is not fully equipped 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 prose must carry parameter meaning. It explains draft_version's role and 409 behavior, and 'replace entirely' implies graph is the full replacement object. However, funnel_id is only implicit, optional name is not mentioned, and the internal structure of graph is left undefined.

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

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

The description opens with 'Заменить черновик воронки целиком', a specific verb + resource statement: replace the entire funnel draft. It even clarifies the live-funnel scenario, which distinguishes this update/replace operation from sibling create_funnel_draft.

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

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

It gives a concrete workflow: take draft_version from get_funnel, call this tool, and on a 409 re-read the funnel. It also explains the draft-vs-published semantics so an agent knows editing here won't affect live users. It does not explicitly say when to prefer create_funnel_draft over this tool, so alternatives are not fully spelled out.

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?

Discloses rich behavior beyond annotations: the previous document moves to version history, recovery is possible via the cabinet UI, and a stale updated_at triggers a 409 refusal rather than silent overwrite. This is exactly the kind of context annotations (destructiveHint=true) cannot convey.

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?

Front-loads the action, then the version-history behavior, then the mandatory concurrency rule. Efficient with some line wrapping; every sentence carries 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 destructive mutation with no output schema and 0% schema docs, the description covers the critical risk (overwrite prevention via updated_at, recoverability via version history). Minor gap: the shape/format of the document object is unspecified.

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%, so the description must compensate. It explains updated_at as an optimistic-concurrency token sourced from get_lesson and ties title/document to the update, though it doesn't clarify that both are optional/nullable or what document's shape is.

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

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

States a specific verb and resource: changes the title and/or document of a lesson. Clear enough to distinguish from create_lesson and get_lesson, though it doesn't explicitly name those siblings.

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

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

Explicitly prescribes the required workflow: 'Сначала get_lesson, потом правка' and mandates passing updated_at from get_lesson when replacing the document. Names the alternative (get_lesson) and the ordering constraint.

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

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

Beyond the annotations, the description discloses useful behavioral details: only submitted fields are updated, enabled steps are protected, and the API responds with 409 in that conflict case. This adds real context without contradicting the annotations.

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

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

The description is two short sentences with no filler: it front-loads the core constraint ('only sent fields while disabled') and then adds the 409 caveat. Every clause carries useful 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 is complete about the disabled/enabled constraint but insufficient for a 14-parameter mutation tool with no output schema and no parameter descriptions. It does not explain what the fields mean, how they combine, or what a successful response 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?

With 14 parameters and 0% schema description coverage, the description needed to compensate by explaining or disambiguating field semantics. It only says 'only sent fields' and leaves fields like goal, event, action, target_tag_id, delay_minutes, and others unexplained. rule_id is required in the schema, but no additional parameter meaning is provided.

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

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

The description names a concrete operation — editing a rule step — and adds the scoping condition 'пока он выключен' (while it is disabled). This clearly distinguishes it from sibling tools like create_sales_rule and update_sales_stage without requiring schema inspection.

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

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

The description explicitly states that the tool should be used for disabled rule steps and that enabled steps return 409 and can only be changed by the owner in the dashboard. It provides a clear when-not condition, though it does not name a specific sibling alternative.

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 establish non-read-only, idempotent, non-destructive behavior. The description adds useful behavioral context beyond annotations by explaining how reordering works via after_stage_id and by explicitly noting that semantic stage meanings cannot be changed through this API. 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: it states the available actions first, then clarifies the one non-obvious parameter and adds an important limitation. Every sentence earns its place with no redundant wording.

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 four-parameter update tool with no output schema, the description covers the main operations, the reordering mechanism, and the critical restriction about semantic meanings. It could mention permissions or response behavior, but annotations already cover safety profile and the tool is simple enough that nothing essential 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?

With 0% schema description coverage, the description must compensate. It explains the non-obvious after_stage_id parameter ('the stage after which it will be placed') and maps name, color, and after_stage_id to the stated operations. It does not explicitly describe stage_id, but that parameter is self-evident as the target stage identifier.

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

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

The description names a specific resource (sales stage) and three concrete operations: rename, change color, and reorder. It clearly distinguishes this update/editing tool from siblings like create_sales_stage and update_sales_rule by scoping exactly what can be changed.

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

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

The description gives clear context for when to use this tool: renaming, recoloring, or repositioning a sales stage. It also tells the agent when NOT to use it by stating that changing the stage's semantic meaning (in progress, success, failure) happens only in the dashboard.

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=false, destructiveHint=true, and idempotentHint=true, so the safety profile is partly covered. The description still adds substantive context: the new URL propagates immediately to everyone clicking the link, archiving does not break the link (it only removes it from the list), and history is never deleted. It does not clarify permission requirements or what the response returns, hence a 4 rather than 5.

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?

Front-loaded with the mutability scope, followed by prerequisites, side effects, and an example, with no filler sentences. Slightly dense with multiple clauses about bot links and archival that could be trimmed, but every sentence carries operational meaning.

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 4-parameter mutation tool with no output schema, the description covers what changes, propagation effects, archival behavior, revert path, and absence of deletion. The only real gap is explicit identification/format of link_id and the exact response shape, both minor here.

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 carry parameter meaning, and it does explain url, title, and archived=false (restore) semantics in prose, plus a concrete JSON example for url. link_id is only implied via the 'make sure it's the right link' instruction rather than described, keeping it just short of 5.

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

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

The description names a specific verb+resource (change url/title/archive state of a short link) and enumerates exactly which fields are mutable, plus states the immutability of the short address itself. An agent can distinguish this from create_short_link, list_short_links, and get_link_stats without opening any schema.

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

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

It explicitly tells the agent to read the link first via list_short_links and verify it is the right one before mutating, and explains when the archive flag should be used (and how to revert it with false). It also rules out an expected alternative by stating there is no delete operation.

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