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

Goes well beyond the destructiveHint=true annotation by disclosing the cascade effect (all unfinished assignments get closed), irreversibility, and the authorization constraint (author-only, refusal otherwise). These are non-obvious behavioral traits an agent must know before calling, not restatements of structured fields.

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

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

Four short sentences, front-loaded with the core action and cascade effect, then irreversibility, then the auth constraint, then the prerequisite workflow. Every sentence carries an operational fact 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 destructive one-parameter mutation with no output schema, the description supplies everything needed: effect scope, reversibility, auth constraint, and precondition checks. Nothing an agent needs to invoke it safely 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 coverage is 100% with a single parameter, so the schema already documents both the id meaning and the author requirement. The description reinforces the author constraint but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

Names a specific verb (abort/terminate) and resource (task), and clarifies the scope by stating that all unfinished assignments under the task are closed. An agent can distinguish it from rx_complete_assignment or rx_delete_tickets 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?

Explicitly states the condition under which it works (user must be the task author, else RX refuses), the prerequisite check via the named sibling rx_get_task, and the requirement to confirm with the user. This covers when to use it, when it will fail, and the recommended workflow.

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

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

Annotations already declare readOnlyHint=true, so 'Только чтение' largely restates structured data. However the description adds genuine behavioral context by disclosing payload shape (ordered columns, cards carrying code/assignees/deadlines) and clarifying that the board id must come from rx_boards, which is not captured by 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?

Front-loads the core purpose, then sequences the id-source note and the sibling routing. Every sentence carries routing or content information 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 single-parameter read tool with no output schema, the description is complete: it explains what the board payload contains, how to obtain the id, and which alternatives cover adjacent needs.

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 100% and the schema already spells out that id is 'число после # в строке rx_boards'. The description's 'Id доски берётся из rx_boards' reinforces the same sourcing hint but adds little beyond what the schema documents, so the baseline 3 is appropriate.

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

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

States a specific verb+resource: returns one whole agile board, describing its columns left-to-right and the cards within with code, assignees and deadlines. It explicitly distinguishes itself from rx_boards (id source) and rx_tickets (card lookup), so an agent can separate it from siblings without opening schemas.

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

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

Gives an explicit when-to-use (the 'what is currently in work on the board' question) and a when-not with a named alternative ('if the board is unknown or you need a card by name, use rx_tickets'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description reinforces read-only and adds the non-obvious default filtering (only open boards) and row cap (20, overridable). It does not describe ordering or pagination cursor behavior, which is a minor gap.

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?

Dense and front-loaded: purpose, returned fields, routing guidance, defaults, and sibling distinction each appear once with no filler. Slightly dense with several clauses, but 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?

With no output schema and straightforward annotations, the description supplies what is missing: the returned field set, default scoping, row limit, and routing to rx_board for content. Nothing needed to call it correctly is absent.

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 100% and all three parameters are already documented in the schema, including defaults and the max of 100. The description largely restates those defaults (open-only, include_closed=true) rather than adding new semantics, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (agile boards Directum RX) and enumerates the returned fields (Id, name, card prefix, owner, project). It is distinguishable from siblings like rx_board (board contents) and rx_tickets 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?

Explicitly says to use it to find a board and its Id before rx_board, rx_tickets, or rx_create_ticket, and clarifies that board contents are shown by rx_board instead. Default behavior (open only, up to 20 rows) and the include_closed toggle are 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?

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false, but the description adds meaning beyond them: the action may mutate data, is not always reversible, RX returns 404 (not a validation error) when a required parameter is missing, and the agent must confirm intent with the user first. This is exactly the extra context annotations 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?

Four short sentences, front-loaded with the core action, then routing rule, then risk/error behavior, then the confirmation requirement. No filler sentences.

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?

No output schema, so nothing is owed for returns, and the 404/destructiveness caveats cover the main failure modes. The one gap is how an agent discovers valid module/action names and their required params (e.g., whether a describe/search sibling should be consulted first), which is left implicit.

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

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

Schema description coverage is 100% and both parameters are documented (action format Module/Action, params as a JSON object). The description's 'по имени (Модуль/Действие) с параметрами' largely restates the schema, adding no format or discovery guidance for the action-specific params object, so the baseline 3 applies.

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

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

States a specific verb+resource: calling a named Directum RX module action (Module/Action) with parameters. It also distinguishes itself from the entire rx_* family by scoping itself to operations without a dedicated tool, so an agent can route correctly without opening any sibling 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?

Explicit when-to-use ('only for operations that don't have a ready rx_* tool') and an explicit when-not rule implied by the same sentence. It adds operational conditions (missing required param yields 404) and a mandatory pre-call step (retell the user what will happen).

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description adds real context beyond them: the comment is visible to all board participants, it is editable/deletable afterwards by the author, and it instructs the agent to show the user the comment text before calling. It doesn't cover failure modes (e.g., permissions or character limits), keeping it from a 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?

The purpose is front-loaded in the first sentence, followed by visibility, alternatives, prerequisites and the display-before-calling rule. Every sentence carries distinct information 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 two-parameter mutation tool with annotations present and no output schema, the description covers everything an agent needs: what it does, side effects (board-wide visibility), edit/delete follow-ups, the source of the required ID, and the user-confirmation step.

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

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

Schema description coverage is 100%, so both parameters are already fully documented, including the numeric-Id requirement and the note that a code like ABC-12 will not work. The description only restates the ID source (rx_tickets / rx_board) and adds nothing new about syntax or format, so the baseline 3 applies.

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

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

The description states a specific verb (add a comment) plus the exact resource (an agile board card) and the acting identity (on behalf of the user). It distinguishes itself from rx_edit_comment, rx_delete_comment, rx_update_ticket and rx_ticket by name, so an agent can select it without opening any sibling 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 states when to use the tool (to record work progress or reply in a discussion) and routes the agent to the correct alternatives: rx_edit_comment to fix, rx_delete_comment to remove, rx_update_ticket to change fields, rx_ticket to view existing comments. This is explicit when/when-not plus 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 declare the non-read-only, non-idempotent safety profile, and the description adds material context beyond that: the data change in RX, that the task closes and the process advances, and critically that the action cannot be cancelled. It also documents that the result defaults per task type and that signing is out of scope. Note: 'cannot be cancelled' is a soft tension with destructiveHint=false, but completing a task is an irreversible state change, not data destruction, so it is not a 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?

Front-loaded with the core action, then constraints, exclusions, and pre-call guidance in a logical order with zero filler. The resolution enumeration in the first sentence is long but each variant carries selection meaning; slightly dense, which keeps it short of a 5.

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 non-idempotent mutation tool with no output schema, the description covers what is missing elsewhere: the prerequisite review step, the side effects (task closes, process advances), irreversibility, and the signing exclusion. Nothing an agent needs to call this safely is absent.

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

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

Schema description coverage is 100%, and the schema already documents both the id and the result parameter, including per-type defaults and Russian synonyms. The description only restates the default-result behavior ('Без result берётся стандартный результат для типа задания') without adding syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

Names a specific verb+resource (execute an assignment on behalf of the user) and enumerates the concrete resolution types it covers (complete, accept, approve with/without comments, return for revision, acknowledge, review). It explicitly distinguishes itself from signing-related siblings by stating that signing tasks are not handled here. An agent can identify the tool's scope without opening the schema.

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

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

Gives explicit when-to-use context and an exclusion (signing tasks, where the signature is placed only in RX), and names the prerequisite alternative tool rx_get_assignment with the instruction to review and relay the task to the user first. Both the selection condition and the pre-call workflow are stated, not left to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the write/mutation nature is covered. The description adds genuinely useful context beyond that: the article is created on behalf of the user, visibility follows area rights, and it mutates data in RX. It does not describe failure modes or what happens on duplicate creation, keeping it from a 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?

It is a single dense paragraph that front-loads purpose and then prerequisites in a logical order, with no filler sentences. It is slightly packed with several distinct requirements, but every clause earns its place.

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

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

For a 3-parameter mutation tool with no output schema, the description covers purpose, required source of area_id, duplicate-check workflow, permission/visibility model, and a user-confirmation step. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates that title/text are markdown and that area_id comes from rx_kb_areas, but adds little semantic detail beyond what the schema already documents for these 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 gives a specific verb+resource (create a knowledge-base article) and names the required inputs (title and markdown text) plus the scoping entity (область/area). It is clearly distinguishable from siblings like rx_update_article, rx_kb_search and rx_kb_areas.

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 routes the agent: get the area Id from rx_kb_areas and verify via rx_kb_search that the article does not already exist before creating. It also states a pre-call UX requirement (show the user the title and start of the text), which is concrete when-to-use/when-to-check guidance.

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

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

Annotations declare it is a non-read-only, non-idempotent, non-destructive write. The description adds behavior beyond that: the board is mutated immediately ("Меняет доску сразу"), there is no default position so the column lands before the final column, and deletion is not possible via this server ("удалить колонку этим сервером нельзя"). These are concrete traits the annotations do not 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?

Purpose and fields are front-loaded, followed by default-placement behavior, then the mutation caveat, then the board-reference note and the pre-call instruction. It is dense but every sentence carries operational meaning, so it earns its length.

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

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

For a creation mutation with no output schema, the description covers the important points: immediate board mutation, default placement, inability to delete, and accepted board reference forms. Return behavior is unspecified, but the essential call-time context 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 100%, so the schema already documents all five parameters and their defaults, including the position default before the final column. The description largely restates field meanings (name, position, is_final, wip_limit) without adding syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

The opening clause states a specific verb and resource: "Создать колонку на agile-доске" (create a column on an agile board), then enumerates the configurable attributes. This clearly separates it from read/list siblings. It does not name any specific sibling to differentiate from, but the resource is distinct enough for selection.

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 usage-adjacent instruction ("Перед вызовом перескажите пользователю доску, название и место") and explains that the board may be given by name or Id from rx_boards, which is helpful context. However, it never states when to use this tool versus alternatives or any exclusions, so usage is only implied.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write nature is covered; the description adds real context — it mutates data in RX, performers immediately receive assignments, draft=true suppresses sending, notice=true sends without waiting for completion. It does not describe reversibility or what happens to omitted optional fields, keeping it short of a 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 core action and effects, then modes, then the sibling routing, then the pre-call instruction — a logical ordering. It is dense but each sentence carries a distinct instruction; 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 9-parameter mutation tool with no output schema, the description covers purpose, side effects, the key alternatives, and a pre-call confirmation step, while annotations and schema supply safety and parameter detail. Return/result format is unspecified, but the mutation outcome is implied clearly enough.

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 100% and every parameter (subject, deadline, draft, notice, observer_ids, etc.) is already documented in the schema, so baseline is 3. The description's restatement of draft/notice and the required fields adds little beyond the schema text.

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?

Specific verb + resource ('Создать простую задачу и сразу отправить её исполнителям') with the side effect (performers receive assignments) stated up front. It explicitly distinguishes itself from the sibling rx_create_ticket ('для карточки на agile-доске используйте rx_create_ticket'), so an agent can route correctly without opening schemas.

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?

Names the concrete alternative (rx_create_ticket) and the condition selecting it (agile board card), plus the required inputs and where to source performer ids (rx_find_employees). It also codifies the two operational modes (draft, notice) and a pre-call retelling requirement, leaving little to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is covered; the description adds genuine context beyond them: 'Меняет данные сразу', the constraint that tags must already exist on the board (a failure mode), server-side name resolution, and the default-column fallback. It stops short of return/error behavior, so not a 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-loads the purpose, then groups resolution rules, defaults, the destructive note, and the sibling routing into distinct sentences with no filler. It is dense but a couple of clauses (plan_hours/fact_hours restatement) partially duplicate the schema.

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

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

For an 11-parameter mutation tool with no output schema, the description covers defaults (first column, default priority implied by schema), name-resolution behavior, a key precondition, and sibling routing, while annotations carry the safety profile. Missing only error/return expectations, which is a minor 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?

Schema description coverage is 100%, so the baseline is 3; the description still earns credit by explaining semantics the schema does not, namely that board/column/performers/tags may be given as free-form words and the server resolves them, that tags must pre-exist, and that attachments accept links, RX document Ids, or disk files.

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?

Opens with a specific verb+resource ('Создать карточку на agile-доске') and immediately names the sibling it is not ('Для поручения с контролем срока ... используйте rx_create_simple_task'), so an agent can route between the two create tools without opening either 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?

Gives an explicit alternative and the condition that selects it (deadline-controlled tasks go to rx_create_simple_task), plus a concrete pre-call requirement to restate board, column, name and deadline to the user before invoking. Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true, but the description adds meaningful context beyond them: the effect is visible to all board participants (комментарий пропадает у всех участников) and a confirmation step is required. It does not cover permissions or irreversibility details beyond the destructive hint, so it earns a 4 rather than a 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?

The description is compact and front-loaded, stating the action first, then restrictions, then the alternative, then the confirmation requirement. Every sentence adds useful information, though it could be slightly tighter by merging the ownership constraint with the first sentence.

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 tool with two required parameters and no output schema, the description covers what is deleted, the ownership restriction, the alternative tool, and the pre-call UX requirement. It does not address error conditions or what happens if the comment is not found, which is a minor 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?

Schema coverage is 100% and both parameters are clearly documented in the schema with source references (id в скобках в строках rx_tickets и rx_board; число после # в rx_ticket). The description only names the parameters (Id карточки и Id комментария из rx_ticket) without adding new format or validation details, so the baseline 3 is appropriate.

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

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

StartsWith a specific verb+resource (Удалить свой комментарий к карточке agile-доски) and clarifies ownership scope (Чужие комментарии не удаляет), so it is immediately distinguishable from rx_comment_ticket and rx_edit_comment.

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 states the alternative (Исправить текст вместо удаления: rx_edit_comment) and adds a required pre-call step (Перед вызовом покажите пользователю, какой комментарий будет удалён), leaving no ambiguity about when and how to use it.

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

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

Annotations already flag destructiveHint=true, but the description adds the crucial consequence: the card leaves the board, gets Deleted status, and cannot be restored via this server. It also states the 100-item batch limit, giving behavior beyond the annotation set.

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 tight sentences, front-loading the destructive effect and irreversibility before the input constraints and the pre-call disclosure requirement. 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 destructive, single-parameter tool with no output schema, the description covers irreversibility, ID source and format, batch cap, and a required user-confirmation step. Annotations carry the safety profile; nothing needed to call it correctly is missing.

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

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

With a single parameter at 100% schema description coverage, the schema already documents the format (numeric ids, not codes, up to 100). The description largely repeats this, adding no new syntax or source detail 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 gives a specific verb+resource ('Удалить карточки с agile-доски') and clarifies the exact semantics by analogizing to the UI delete button and stating the resulting status (Deleted). It is immediately distinguishable from rx_update_ticket or rx_get_task.

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?

Strong preconditions: IDs must be numeric from rx_board or rx_tickets (not codes like ABC-12), max 100 per call, and the agent must list the affected cards to the user before invoking. No explicit when-not-to-use or named alternative tool, which keeps it just 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description still adds meaningful non-obvious behavior: it returns field/reference metadata with types and explicitly does not read records, which prevents an agent from expecting data rows. No rate-limit or output-format detail, but that gap is minor given 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?

Four short sentences, each carrying distinct information: what it returns, when to call it, where the input comes from, and what it does not do. Front-loaded with the purpose and zero 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 one-parameter, read-only metadata tool with no output schema, the description tells the agent everything needed: the return content is field/reference definitions with types, the input source is rx_find_entity, and the correct call ordering relative to rx_query.

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?

Single parameter with 100% schema description coverage, so the schema already explains that 'entity' is a set name like IContracts. The description only reinforces the provenance of that name ('берётся из rx_find_entity') without adding syntax beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource ('Поля и ссылки набора сущностей Directum RX с типами') and immediately scopes it against siblings by naming rx_query and rx_find_entity. An agent can tell this is a schema/metadata lookup distinct from record-reading tools 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?

Explicit when-to-use ('Вызывайте перед rx_query, чтобы правильно написать filter, select и expand'), the prerequisite for the input ('Имя набора берётся из rx_find_entity'), and an explicit exclusion ('Сами записи не читает'). All three routing questions an agent has are answered.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), but the description adds genuinely non-redundant behavior: the new text wholly replaces the old ('новый текст целиком заменяет прежний'), ownership is enforced, and a user-confirmation step is required before invoking. It does not describe failure behavior (e.g. what happens with an invalid or foreign comment_id), so it falls short of a 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?

The description is tightly front-loaded: verb+scope first, then the ID requirement and where to find it, then sibling routing, then the confirmation rule. Every sentence carries a distinct, actionable fact with no filler or repetition of the schema.

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

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

With no output schema to explain and a flat three-parameter input, the description covers everything an agent needs: identity scope, replacement semantics, ID provenance, sibling routing, and the user-confirmation obligation. Nothing material 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 100%, so all three parameters (ticket_id, comment_id, text) are already documented with their formats and provenance, which sets the baseline at 3. The description adds only the replacement semantics of 'text', which is already stated in the schema property description, so there is no meaningful lift beyond structured data.

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

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

States a precise verb+resource ('Исправить текст своего комментария к карточке agile-доски') and immediately constrains scope to the caller's own comments ('Чужие комментарии не меняет'), which separates it from every other comment-related sibling. An agent can distinguish it from rx_comment_ticket and rx_delete_comment 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?

Explicitly routes to alternatives by intent: 'Добавить новый комментарий: rx_comment_ticket, удалить: rx_delete_comment'. It also tells the agent where to source the required IDs ('комментарии с Id показывает rx_ticket') and adds a procedural prerequisite ('Перед вызовом покажите пользователю прежний и новый текст'). Nothing about when-to-use is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. Beyond that, the description discloses non-obvious behavior: content is not searchable, the default result set is restricted to official document types, and at least one filter must be supplied. It also describes the result row layout (#Id title · kind · number · state · author · date), though it does not cover permissions or rate/latency characteristics.

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 core purpose, then constraints, defaults, output format and next steps in tightly packed sentences with no filler. Every sentence carries operational information.

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

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

There is no output schema, so the description usefully specifies the returned row format, and it covers scope defaults, the minimum-condition rule, and the follow-up tools. For a 9-parameter filtered search, 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?

Schema description coverage is 100%, so every parameter is already documented in the schema (including the enum-like state values and all_types semantics). The description largely restates the searchable fields and adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource (document search in Directum RX) and enumerates the exact searchable card fields (title, kind, author, registration number, dates, state), so it cannot be confused with a list or fetch operation. It explicitly distinguishes itself from siblings by noting it does not search by content and routing reference-book lookups to rx_find_entity.

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

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

Gives an explicit negative boundary ('По содержимому не ищет'), the default scope (official documents only) versus the all_types=true widening, a hard precondition ('Нужно хотя бы одно условие'), and a follow-up path (rx_get_document / rx_get_document_text). It names the alternative tool for other entity types.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with «Только чтение» plus the added detail that every query token is matched across name, position, and department, and that inactive records are excluded by default. Some redundancy with annotations, but the tokenization rule and default-filter behavior are genuinely useful additions.

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 core search semantics and the returned fields are front-loaded in the first clause, followed by the usage pointer and default-scope note. It is somewhat dense with parenthetical detail, but every sentence contributes.

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 having no output schema, the description lists the return fields (Id, должность, подразделение, почта), which is exactly what an agent needs to map results to the Id required by downstream create-task 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 100%, so the baseline is 3; the description goes beyond it by explaining how the query string is split into tokens and matched across multiple fields, which is not conveyed by the schema's simpler 'фамилия или часть имени' note. The include_inactive default is also restated with its effect.

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?

Names a specific verb (Найти) and resource (сотрудников), and spells out the searchable fields (ФИО, должность, подразделение) with concrete example queries. It is clearly distinguishable from siblings like rx_find_entity or rx_find_documents.

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 states the primary use case: call this before rx_create_simple_task to obtain the executor's Id, or to discover who's who. It also names the default scope (active employees only) and the include_inactive escape hatch, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false; the description confirms 'metadata read only' and adds genuinely new context: what is returned (set names with field and reference counts) and the recommended continuation path. It does not contradict idempotentHint=false, though it also does not explain that nested trait.

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 sentences, front-loaded with the search scope, then the usage condition, then return shape and next steps. Dense and purposeful, with only mild overlap between the description's language note and the schema's query examples.

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?

No output schema exists, and the description compensates by stating the return shape (set names plus field/link counts) and the downstream tools to call. For a two-parameter read-only lookup, 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?

Schema description coverage is 100%, so both parameters are already documented, and the description merely echoes the search semantics (Russian/English names) without adding syntax or constraint detail beyond the schema. Baseline 3 applies when the schema carries the parameter burden.

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 (find Directum RX entity sets by name) and explicitly broadens scope to any type including customer customizations. It also differentiates itself from sibling finders (rx_find_documents, rx_find_employees) by declaring itself the fallback when no ready-made rx_* tool exists.

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

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

Gives an explicit trigger ('use when there is no ready-made rx_* tool for the data') and then an explicit two-step follow-up workflow: rx_describe_entity to see fields, rx_query to read records. Both when-to-use and the alternative route are named.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces that with 'Только чтение', so there is no contradiction. It adds real value by disclosing the returned content (full thread, attachments), but says nothing about size limits or truncation for long threads, which is the remaining unknown for a full-object fetch.

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 no filler, front-loading what the tool returns before the routing and provenance sentences. Every sentence carries a distinct piece of information.

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

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

With no output schema, the description compensates by enumerating the returned fields, plus the id source and the sibling boundary. An agent has everything needed to decide and invoke 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 coverage is 100%, so the id parameter is already documented, giving a baseline of 3. The description adds provenance beyond the schema by telling the agent the id is taken from rx_my_assignments, which is the concrete step the agent needs to obtain a valid value.

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+resource (retrieve a single assignment or notification in full) and enumerates the payload: subject, author, due date, task, attached documents, and the whole correspondence thread. It explicitly distinguishes itself from the sibling rx_get_task, which shows the task's progress with other executors.

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

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

Gives the when ('use it to understand what is actually being asked of the user'), the input provenance ('the id comes from rx_my_assignments'), and the alternative plus its distinguishing condition (rx_get_task for the task's progress with other executors). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces this with 'Только чтение' while adding useful boundary context: this tool does not return document text, which prevents a wrong-tool call. It does not, however, describe pagination or size limits for the version 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?

Dense and front-loaded: payload contents first, then usage, then the Id source, then the sibling boundary and read-only note. Every sentence carries information, though the 'Только чтение' clause slightly repeats the readOnlyHint annotation.

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?

No output schema exists, so the description correctly compensates by enumerating the returned fields, and it closes the biggest gap for a document tool by stating that text is returned elsewhere. Complete enough for an agent to call it correctly.

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

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

With a single parameter at 100% schema description coverage, the schema already documents the id fully ('число после # в строке rx_find_documents'). The description's note that the Id comes from rx_find_documents reinforces provenance but adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Карточка документа') and enumerates exactly what the card contains: вид, регистрация, состояния, автор, подразделение, список версий с Id. It also explicitly distinguishes itself from rx_get_document_text, so an agent can tell the two siblings apart without opening a 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?

Gives explicit when-to-use ('чтобы узнать статус документа или Id нужной версии'), names the source of the input ('Id документа берётся из rx_find_documents'), and routes the complementary case to rx_get_document_text. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, so the description's 'Только чтение' is somewhat redundant. It does add real behavior beyond annotations: supported formats, that scans/images are returned as page images (default 3, more via page_from), truncation by max_chars with offset continuation. Missing: rate limits or how version_id selection interacts with pagination.

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

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

Six dense sentences, each carrying information (formats, scan handling, truncation, as_images, id source, read-only). Front-loaded with purpose. Slightly packed, but there is no filler to cut.

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 return-value burden and does so: text for text-layer documents, page images for scans, truncation and continuation semantics. An agent can call this correctly across all 7 parameters without further context.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by wiring parameters into behavior: offset continues truncated text, as_images triggers image return for scans, pages/page_from govern image batches. Much of this overlaps with schema text, so it is incremental rather than essential.

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 the text of a document version, defaulting to the latest. It clarifies the return shape (text vs. page images for scans) so an agent knows exactly what it gets. It references rx_find_documents as the id source, though it does not explicitly contrast with rx_get_document.

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?

Explicit when-to-use ('пересказать документ, найти условия, суммы, сроки'), when to switch to as_images=true (scanned pages, seals/signatures), and how to continue truncated text via offset. It also states where to obtain the id, routing the agent correctly.

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

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

Annotations already declare readOnlyHint=true, so 'Только чтение' is partly redundant, but the description adds real value by disclosing the breadth of returned content (correspondence, attachments, all assignments with executors and results) – important since no output schema exists. It does not cover pagination or size limits for large tasks, but idempotentHint=false is not contradicted or addressed.

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 scope statement is front-loaded and each subsequent sentence (usage, id source, alternative) earns its place. Slightly dense but no filler.

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

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

For a single-parameter read tool with no output schema, the description adequately conveys what comes back and when to prefer it. Only minor gaps remain (e.g. behavior for very large tasks or missing ids), which are not critical 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 coverage is 100% with a single required id parameter, so the schema already carries the semantics. The description's note about where the id appears (rx_my_assignments / rx_list_tasks) largely duplicates the schema's own parameter description, adding no new syntax or format detail.

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?

Names a specific resource (задача) and enumerates its scope (статус, автор, сроки, вложения, переписка, задания с исполнителями). It explicitly distinguishes itself from the sibling rx_get_assignment, so an agent can route without opening either 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?

States the trigger condition ('когда нужен ход работы по задаче: кто что сделал и на ком она стоит'), names the alternative (rx_get_assignment для одного своего задания), and tells where to obtain the id. Both when-to-use and when-to-use-something-else are covered.

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 cover the safety profile (readOnlyHint, openWorldHint=false, idempotentHint=false), so the bar is lower, yet the description adds real behavioral context: help is stored locally and downloaded on first call, requiring the query to be repeated after a few minutes. That first-call non-idempotent side effect aligns with idempotentHint=false and is exactly the kind of latency/state caveat agents need. It stops short of describing ranking or result-count behavior, so not a 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 core purpose and scope, then usage, return shape, alternative routing, and the download caveat. Every sentence carries information; the only mild cost is that the caveat about local storage and re-querying could be tightened, keeping it just under maximum.

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?

No output schema, yet the description explains the return (articles with a fragment and file name) and points to rx_help_topic for full text. Combined with scope, alternatives, and the first-call download behavior, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the schema already documents all three parameters and the baseline is 3. The description goes beyond it by explaining query matching semantics — word search accounting for morphology, and reformulation advice when hits are sparse — which materially shapes how an agent phrases the query parameter.

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 (поиск по справке Directum RX), scopes it to the same version as the user's stand, and explicitly names what it is NOT for versus siblings rx_help_topic and rx_kb_search. An agent can distinguish it from every neighboring KB/help tool without opening a 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?

Gives explicit when-to-use (вопросы о самой системе: устройство механизма, настройка, значение поля/статуса), when-not-to-use (правила и инструкции компании — в rx_kb_search), and the alternative for reading full text (rx_help_topic). Also provides an in-tool fallback: reformulate the query if results are few.

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, openWorldHint=false, and idempotentHint=false. The description adds useful output context beyond annotations: it returns top-level sections or section contents including article file names, which helps an agent understand what the call produces.

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, front-loaded sentences with no filler: the first defines the tool, the second gives routing guidance, and the third states read-only behavior. Every sentence earns its place.

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

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

For a simple read-only TOC tool with full schema coverage and no output schema, the description is complete enough. It explains purpose, usage relative to a sibling, and the shape of returned data, while annotations and schema cover the rest.

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

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

Schema description coverage is 100%, so the schema already documents both depth and section parameters in detail. The description aligns with the section parameter semantics but does not add meaning beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb and resource: help table of contents for Directum RX, returning top-level sections or section contents with article file names. It also names the sibling tool rx_help_search, so an agent can distinguish this from keyword search without opening either 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?

Explicitly says to use this when rx_help_search does not find what is needed, to understand which section to search, or to show what exists in the help. This gives clear when-to-use guidance and names the alternative tool directly.

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

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

Annotations already declare readOnlyHint=true and the description only repeats 'Только чтение', but it adds genuinely useful behavior: long articles are truncated by max_chars and continued via offset, and hyperlinks map to other retrievable articles. That navigation/truncation workflow is context beyond the structured fields.

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

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

Four compact sentences, front-loaded with purpose, then link semantics, then pagination behavior, then the read-only note. No sentence is 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?

No output schema, but the description covers what is returned (full article text), how it paginates, and how to navigate linked articles. The only minor gap is no explicit statement of what a truncated response looks like, but the offset mechanism is explained well enough 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 coverage is 100%, so the baseline is 3, but the description adds meaning: it clarifies that 'topic' is a file name sourced from search results or from a link inside article text, and frames offset/max_chars as a continuation mechanism rather than raw integers.

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+resource ('Полный текст статьи справки Directum RX по имени файла') and explicitly ties input to the sibling tools rx_help_search and rx_help_toc. An agent can distinguish this retrieval tool from search/toc 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?

Clear routing context: the topic comes from rx_help_search or rx_help_toc results, and in-text links are followed with this same tool. It does not state explicit exclusions (e.g. when to prefer rx_help_search instead of fetching full text), so it stops just 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?

Annotations already declare readOnlyHint, openWorldHint=false and idempotentHint=false, so 'Только чтение' partly restates them. Beyond that, the description adds real behavioral context: these are internal company articles (not system documentation) and the record shape returned per area. It does not discuss pagination or ordering, so not a full 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?

Three tightly packed clauses: what the resource is and contains, what to use it for, and which sibling to use instead. Scope and routing are front-loaded with zero 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?

No output schema exists, and the description compensates by naming the returned fields (Id, name, starting article). Safety is covered by annotations, and the sibling routing plus internal-vs-system scope is present, so nothing an agent needs to call it correctly is missing.

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

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

One optional parameter with 100% schema description coverage ('подстрока названия области'), so the schema already carries the semantics. The description only nods to filtering via the area_id narrowing hint, adding no syntax or matching details beyond the schema; baseline 3 applies.

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

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

Names the specific resource (knowledge base areas in Directum RX, 'Знания' module) and enumerates what each area carries (Id, name, starting article). It is immediately distinguishable from rx_kb_search (article search) and rx_help_search (system docs).

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 states the use case — discover which knowledge sections exist and narrow rx_kb_search by area_id — and gives a negative routing rule: system questions belong to rx_help_search. Alternatives and conditions are spelled out, not implied.

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

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

The 'Только чтение' line merely restates readOnlyHint=true, but the description adds genuinely new behavior beyond annotations: long text is truncated by max_chars and continuation is fetched via offset, which an agent cannot infer from the hints. It does not cover error behavior (e.g. invalid id) or default limits context, keeping it below 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?

Four short sentences, front-loaded with what the tool returns, then how to obtain the id, then pagination, then the read-only note. Dense and waste-free, though the final read-only clause duplicates annotation 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?

With no output schema, the description carries the return-value burden and does so by naming the returned fields, and it explains the truncation/pagination contract. Missing only edge-case behavior (invalid id, empty article), which keeps it from a 5.

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 100%, so the baseline is 3; the schema already documents id, offset and max_chars. The description's offset-truncation sentence largely restates what the offset property description already says, adding little semantic value 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?

States a specific resource (company KB article) and enumerates the returned content (areas, tags, author, markdown text), which separates it from rx_kb_search (search) and rx_kb_areas (area listing). An agent can distinguish it from all siblings without opening a 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?

Explicitly tells the agent where the required id comes from — rx_kb_search or the starting article of an area in rx_kb_areas — routing it through the correct sibling tools. It stops short of stating when not to use this tool (e.g. for bulk or listing retrieval), so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds real value beyond them: it clarifies the negative search scope (no full-text search) and the exact output line format (#Id title · areas · author · date). Only minor gaps remain, such as pagination behavior beyond the limit parameter.

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 what the tool does and its scope limit before routing guidance, with no filler. Slightly dense with output-format and cross-reference sentences, but every sentence earns its place.

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

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

With no output schema, the description usefully describes the returned line format and search field semantics, and covers when to use it versus siblings. A 6-parameter tool could still benefit from more on result ordering or empty-result behavior, but the essentials are 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 100%, so every parameter is already documented in the schema. The description lists the same searchable fields but adds no syntax, format, or matching semantics beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource (searching company KB articles) and enumerates the searchable fields (title, area, tag, author). It explicitly distinguishes itself from two siblings (rx_kb_article for text, rx_help_search for system docs), so an agent can route correctly without comparing schemas.

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

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

Gives explicit when-to-use guidance with concrete query examples («как оформить командировку», «регламент закупок») and states the exclusion «По тексту статей не ищет». It also names the alternative tool for full-text retrieval and system docs.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds the default scope, the filterable fields, and — importantly given no output schema — the exact row layout. It does not mention the pagination cap, though the schema exposes limit.

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?

Five dense sentences, scoping and default first, then use-case, then filters, then return shape, then sibling routing. Zero 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?

With no output schema, the description compensates by spelling out the row format; with a 4-param schema fully covered and annotations handling safety, an agent has everything needed to call it correctly and interpret results.

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

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

Schema coverage is 100%, so all four parameters are already documented, including defaults. The description reinforces who=mine and the status/subject filters but adds no syntax or format beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (list outgoing/assigned tasks) with scope, distinguishing it explicitly from rx_my_assignments (incoming) and rx_get_task (single-task detail). An agent can select it for 'what did I assign' questions 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?

Gives an explicit when-to-use framing ('what did I assign and in what state'), names the two alternatives and the condition each covers, and explains the default scope (who=mine). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: default status is in_process, results are sorted by due date, scope is limited to the current user, and it documents the rendered line format including the unread marker.

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?

Dense but front-loaded: purpose first, then usage triggers, then modes, then output format, then sibling routing. Every clause earns its place, though the single-block paragraph is heavier than necessary and the format-string detail could be tightened.

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

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

For a four-parameter read-only list tool with no output schema, the description covers scope, default sorting, all status modes, notification mode, the rendered output shape, and where to go for related data. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: it explains that status=overdue/unread/completed/all restrict the result set, that notices=true swaps assignments for notifications, and that results are due-date sorted by default. This goes past restating 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?

States a specific verb and resource ("Мои входящие задания в Directum RX") and immediately scopes it to the current user's incoming assignments, which cleanly separates it from rx_list_tasks (tasks I sent) and rx_get_assignment (single task detail). An agent can pick this tool without opening the schema.

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

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

Gives concrete user-intent triggers («что у меня в работе», «что просрочено», «что нового»), spells out the default behavior and every status mode, and explicitly routes two adjacent cases to named siblings (rx_list_tasks, rx_get_assignment). When-to-use and alternatives are both covered.

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 readOnlyHint, openWorldHint and idempotentHint, so the safety profile is handled. The description still adds real behavioral content by enumerating what the card returns (team grouping, gates, plans with Ids), which matters since there is no output schema. "Только чтение" merely restates readOnlyHint and no auth/permission details are given, keeping it out of 5 territory.

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 content is front-loaded with the returned field set, then usage, then sibling routing, which is a sensible order. It is dense but not padded, with the only redundant element being "Только чтение" repeating the annotation.

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 compensates by listing exactly what fields the card contains, and it covers purpose, trigger, Id sourcing and sibling alternatives. For a single-parameter read tool this is nearly complete, though return volume/pagination behavior is unstated.

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

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

Schema description coverage is 100% and the schema already explains the id parameter (number after # in an rx_projects row). The description repeats the same sourcing rule ("Id проекта берётся из rx_projects") without adding format or edge-case detail, so the baseline 3 applies.

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

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

The description names a specific resource (project card) and enumerates the exact data it exposes: stage, planned/actual deadlines, manager, customer, team by groups, gates, description and plan Ids. It also distinguishes itself from siblings by stating that the project Id comes from rx_projects and that the work tree is shown by rx_project_plan.

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 an explicit trigger ("what state is the project in and who participates in it") and routes the agent to rx_projects for the Id and rx_project_plan for the work tree. No explicit when-not-to-use exclusions are stated, so it falls just 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?

Annotations already declare readOnlyHint=true, so the redundant «Только чтение» adds little. However, the description contributes a genuinely non-annotated behavior: large plans are truncated by max_rows, which tells the agent results may be incomplete. It stops short of describing pagination or return shape.

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, front-loaded with what the tool returns, then usage, then the id prerequisite, then the truncation caveat and read-only note. Nothing is padded; each sentence carries a distinct fact.

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 supplies the returned content (tree fields, percentages, overdue flags), the truncation behavior for large plans, the id sourcing requirement, and the read-only nature. That is sufficient for an agent to call it correctly and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond it by clarifying that the id is a plan/document id rather than a project id (a real misuse vector given sibling rx_project), and by explaining the truncation role of max_rows. No format or default syntax details 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?

Names the resource (план проекта) and enumerates exactly what it returns: разделы, работы, вехи, сроки, ответственные, проценты, просрочки. It also distinguishes itself from rx_project and rx_project_plans by stating the required id is a plan/document id, not a project id, so an agent can route correctly without opening schemas.

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

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

Gives concrete triggering questions («как идёт проект», «что отстаёт», «кто за что отвечает») and a hard prerequisite: the id must come from rx_project or rx_project_plans, explicitly not a project id. When-to-use and the sibling dependency are both 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, and 'Только чтение' merely restates that. The valuable addition is the disclosed result shape ('#Id название · состояние · проект · сроки · процент'), output information that exists nowhere in the structured fields since there is no output schema. It does not cover defaults/limits, but those live in the schema.

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

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

Three tightly packed sentences: purpose, result format, then usage routing. Front-loaded with the verb+resource and no filler; every sentence carries distinct information.

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

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

For a read-only search tool with no output schema, the description supplies purpose, sibling routing, search keys and the returned row format. An agent has everything needed to decide to call it and to 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?

Schema description coverage is 100%, so the schema already documents limit, query and project_id with defaults and maximums. The description only echoes the search-by-name / search-by-project split already implied by the params, adding no syntax or format detail. Baseline 3 applies.

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

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

States a specific verb+resource ('Поиск планов проектов') and the two search keys (название / Id проекта). It explicitly distinguishes itself from both rx_project_plan (use this to obtain the Id) and rx_project (which already lists a project's plans), so an agent can route without opening a sibling 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?

Gives an explicit when-to-use ('когда проект неизвестен' – to find the plan Id before calling rx_project_plan) and an explicit when-not-to-use (a single project's plans are already listed in rx_project). Both the condition and the alternative are named.

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, openWorldHint=false, and idempotentHint=false, so safety is covered. The description adds useful default behavior: open projects only, up to 20 rows, and what mine=true returns.

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 resource and returned fields, then usage and defaults. Four sentences with little waste, though some default information duplicates the schema.

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

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

No output schema exists, but the description names the key returned fields and row limit. Annotations cover read-only behavior, so the remaining gaps are minor.

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 100%, so the schema already documents mine, limit, query, stage, manager, and include_closed. The description repeats mine and the open-only default but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States the resource ('Проекты и инициативы Directum RX') and the fields it exposes (stage, state, manager, deadlines, completion). It also distinguishes itself from sibling rx_project by saying rx_project shows the project card.

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 says to use it for an overview of ongoing projects and for finding a project Id, and routes card lookup to rx_project. Defaults (open only, up to 20 rows) and the mine filter condition are stated.

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

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

With readOnlyHint/openWorldHint already declared, the description still adds substantial context: current user's rights govern access, a hard 100-record cap per call, pagination via skip, that omitting select returns all fields, compact-JSON response shape, and a prompt-injection warning that RX data is user data not instructions. This is well beyond what the annotations 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-loaded with the core capability, then constraints and usage in tight, non-redundant sentences. Every sentence carries operational information (scope, limits, field lookup, select default, safety 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 an 8-param generic query tool with no output schema, the description covers what the response is (compact JSON), the record cap, pagination, field selection default, permission behavior, and an injection-safety caveat. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% so the schema already documents all 8 params (the baseline is 3). The description adds real operational meaning not in schema: the default all-fields behavior when select is omitted, the per-call 100 cap, and skip-based paging for reading everything past the limit.

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+resource ('Прочитать записи любого набора сущностей Directum RX') and the two modes (single by id, list by OData condition). It explicitly positions itself against siblings by scoping to 'данных, под которые нет готового инструмента' and pointing field lookup to rx_describe_entity.

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 when-to-use: data types lacking a dedicated tool (contracts, counterparties, reference books), and the routing to rx_describe_entity for field names. It gives pagination guidance (skip) and a select recommendation but names no alternative data-retrieval sibling to contrast with, so the when-not is only implied.

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

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

Annotations declare readOnlyHint=false but not that it mutates RX state; the description adds 'Меняет данные в RX' and explains the electronic=true side effect (signature-based confirmation). Leaves unclear whether the deadline is enforced, whether the task can be recalled, or what an employee receives.

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 action, then prerequisites, then the electronic flag, then a mutation warning and a pre-call instruction. Every sentence has a distinct purpose with no padding.

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?

Covers the mutation, the required inputs and their sources, the electronic mode, and the confirmation step. No output schema exists, and the description doesn't say what the agent receives back (task ID, status) or how to handle partial failures among performer_ids.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including electronic semantics and deadline formats. The description restates the three required IDs and the electronic=true behavior but adds no syntax beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource in Russian: 'Отправить документ на ознакомление сотрудникам: создаёт и стартует задачу'. Distinguishes from sibling rx_send_for_approval (approval vs acquaintance) by naming the task type 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?

Specifies prerequisites (document ID from rx_find_documents, employee IDs from rx_find_employees, deadline) and a pre-call instruction to summarize the document, participants, and deadline to the user. Explicitly names the sibling tools that supply each required ID.

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 and idempotentHint=false, so the mutation profile is known. The description adds genuinely useful context beyond that: it creates and starts a task, it mutates RX data, it never signs the document, and it hard-fails when no approval rule exists.

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 purpose, then modes, then caveats, then the pre-call workflow instruction. Every sentence carries information, though the mode explanation partially duplicates the schema's own mode description.

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

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

For a six-parameter mutation tool with no output schema, the description covers the important decision points: mode choice, rule absence failure, signing exclusion, and the confirmation workflow. It does not say what the call returns (e.g., a task id), which is a minor gap given there is no output schema.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema (mode, deadline, approver_ids, signatory_id, document_id). The description largely restates the mode semantics already present in the schema field, adding little beyond what the structured data provides. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Отправить документ на согласование: создаёт и стартует задачу') and draws an explicit negative boundary ('Подпись документа этот инструмент не ставит'), which separates it from signing flows. The two mode behaviors further pin down what actually happens.

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?

Explains when each mode applies (free = named people and deadline; rule = route built by the RX regulation) and adds a failure condition ('если правила нет, RX откажет'). It also gives a workflow precondition ('перед вызовом перескажите пользователю...'). It does not, however, route the agent away from near siblings such as rx_send_for_acquaintance, so no explicit alternative is named.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces 'Только чтение' while pointing to the write tools. It adds real context beyond annotations by enumerating the returned content (comments with authors and times, attachments, etc.), though it says nothing about size limits, pagination, or error behavior for an invalid id.

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 paragraph that is well front-loaded: what the tool returns, then the required input, then the alternatives. Every clause carries information, though the id rule is restated in both the description and the schema, which slightly inflates the length.

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

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

There is no output schema, so the description carries the burden of describing the return value – and it does so precisely by listing every field the card exposes. Combined with the input rule and the mutation alternatives, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's parameter guidance (numeric id from parentheses, ABC-12 rejected, use rx_tickets for codes) nearly duplicates the schema's own id description verbatim, so it adds little 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?

It states a concrete verb+resource (retrieve one full agile-board card) and enumerates exactly what the card contains: status, column, assignees, deadlines, effort, tags, attachments, description and comments. It explicitly distinguishes itself from siblings, noting rx_tickets for code lookup, rx_update_ticket for changes, and rx_comment_ticket for comments.

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

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

Gives a clear when-to-use condition (a numeric card Id taken from the parenthesized id in rx_tickets or rx_board) and an explicit when-not (an ABC-12 code does not work here, use rx_tickets). It also routes mutations to the correct sibling tools, leaving nothing to inference.

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

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

Annotations cover the read-only profile, and the description adds genuinely useful behavior beyond them: only active cards are returned by default, and the exact result string layout (code (id N) название · исполнители · срок). Since no output schema exists, this output-format disclosure carries real weight; it stops short of noting nothing about pagination or ordering.

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?

Purpose is front-loaded and the sentences are dense with routing and format information rather than filler. Slightly overloaded with output-format detail mid-paragraph, but every clause delivers distinct 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 read-only search tool with no output schema, the description supplies the return format, default filtering, and sibling routing, which is close to what an agent needs. Minor gaps around result ordering and pagination remain, but nothing critical 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?

Schema description coverage is 100%, so all four parameters are already documented, including the query format, status values, board_id source (rx_boards), and the limit default/maximum. The description largely repeats this; its only added meaning is tying the numeric 'id N' to rx_ticket and rx_update_ticket, which justifies the baseline 3 rather than lower.

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 (карточки на agile-досках), plus the searchable key formats (название or code like ABC-12). It explicitly distinguishes itself from rx_ticket (full card) and rx_board (whole board), so an agent can route correctly without opening schemas.

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

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

Gives an explicit when-to-use condition (when the board is unknown or a specific card is needed) and names the alternatives with their selection criteria: rx_ticket for the full card, rx_board for the whole board. Nothing is left to inference.

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

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

Annotations mark readOnly=false, destructive=false, idempotent=false, but the description adds versioning behavior: new text saved as a new version, previous kept in history. It also states it changes data in RX and advises confirming with the user. Good added context beyond annotations, though it doesn't detail permissions or failure behavior.

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 core action, followed by versioning note, prerequisite workflow, and user-confirmation advice. Each sentence earns its place, though the 'Меняет данные в RX' sentence is somewhat redundant with the mutations described.

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-param mutation tool with no output schema and full annotation coverage, the description covers workflow, versioning, and confirmation. It's nearly complete; only permissions/error behavior isn't addressed, which is minor.

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

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

Schema description coverage is 100%, so each parameter is already documented in the schema (id from rx_kb_search, text as full markdown, title optional if unchanged). The description adds nothing param-specific beyond what the schema provides, so baseline 3 is appropriate.

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

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

Clear specific verb+resource: 'Изменить статью базы знаний' specifies editing a KB article, with fields named (название, текст). Distinguishes from siblings like rx_create_article and rx_kb_article by being the update operation.

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?

Explicit 'Сначала прочитайте статью через rx_kb_article и правьте её текст, а не пишите заново' — names the prerequisite tool and the correct workflow, and says to retell changes to the user before calling. This is clear when-to-use and how-to-use guidance naming an alternative sibling.

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 (destructiveHint=false, idempotentHint=false), the description adds real behavioral context: only the passed fields change (partial-update semantics), removals are impossible, and changes apply immediately with no confirmation step. It does not cover permissions/auth or what happens on invalid column/deadline values, so it is not exhaustive.

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 verb+resource is front-loaded and every sentence carries information (mutable fields, partial-update rule, removal restriction, id source, immediate effect). It is delivered as one dense run-on paragraph rather than structured bullets, which slightly hurts scanability for an 11-parameter 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?

For a non-idempotent mutation tool with no output schema, the description covers the essentials an agent needs: partial-update behavior, non-removable fields, id sourcing, and immediate application. Missing only secondary concerns like permission requirements or error behavior on bad enum-free values (e.g. unknown column).

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters in detail, including the attachment one-of (url/file/document_id) rule. The description restates the mutable field set but adds no syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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

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

The description opens with a specific verb+resource ("Изменить карточку на agile-доске") and enumerates exactly which fields are mutable (name, description, deadline, priority, plan/fact hours, performers, tags, attachments, column). It is clearly distinguishable from siblings such as rx_create_ticket or rx_ticket because it is framed as a partial update of an existing card.

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 concrete preconditions ("Нужен числовой Id карточки из rx_tickets или rx_board") and an explicit exclusion ("Убрать исполнителя, тег или вложение этим инструментом нельзя"), which is strong when-to-use guidance. It stops short of naming the alternative tool that should be used for removals, so it is not a full 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?

Goes beyond the readOnlyHint annotation by disclosing the cursor/mark semantics: the default advances the mark to now, since sets it explicitly, and peek=true suppresses the advance. This state-mutating side effect is exactly the kind of behavior an agent needs and it does not contradict idempotentHint=false. Minor gap: no note on what happens if the mark is stale.

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 returned content, then usage, then mechanics, in a compact paragraph with no filler. Slightly dense but every clause contributes; could be split for scannability.

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 return-value burden and does describe the three sections returned, plus the limit semantics (rows per section). Sufficient for correct invocation; a brief note on the response shape or ordering would round it out.

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 100% so the baseline is 3, but the description adds relational meaning the schema states only per-parameter: how since, peek, and the default cursor interact to determine the reporting window. That cross-parameter semantics is genuine added value.

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 resource and enumerates exactly what it surfaces: incoming assignments/notifications, items due by end of day including overdue, and the user's completed tasks. This is clearly distinguishable from sibling list tools like rx_my_assignments or rx_list_tasks.

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

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

Gives explicit triggering contexts ('что нового', 'что пришло, пока меня не было', start of the workday) and routes the agent to the correct follow-up tools (rx_get_assignment, rx_get_task) for row details. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's 'nothing changes' largely echoes them. It does add value by listing the concrete return fields (name, Id, position, department), which is meaningful since there is no output schema; it just doesn't cover auth or rate-limit behavior.

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

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

Two compact sentences, front-loaded with the core purpose and then the trigger condition; nothing is wasted for such a simple 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?

For a no-arg read tool with no output schema, the description is essentially complete: it names the returned fields and the calling condition. Nothing critical for correct invocation is missing, though it could not be richer.

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 zero parameters the baseline is 4; the description confirms 'no parameters,' which is trivially consistent with the empty schema. No additional semantic burden 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 states a specific verb+resource ('who is the current user in Directum RX') and enumerates exactly what is returned (name, Id, position, department). This clearly distinguishes it from siblings like rx_find_employees, which search for other people rather than identifying the caller.

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 explicit usage guidance: 'Call first if it's unknown on whose behalf work is being done.' This tells the agent the condition that should trigger the tool. It lacks explicit when-not conditions or named alternatives, but the context is clear.

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