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

Annotations already declare read-only/idempotent/non-destructive, and the description adds real substance on top: sampling over the first 100 elements, coverage as present_in k/n, up to 3 examples capped at 1500 chars, and an explicit caveat that the schema is reconnaissance, not a complete schema. It also discloses that terminal aggregates ($count, $sum) surface as a scalar in value.

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 trigger condition ('Когда вызывать') before the return-shape details and closes with the follow-up action. Dense but every clause (sampling size, example cap, aggregate caveat) 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?

No output schema exists, yet the description fully specifies the return value: type enumeration, total count, per-field coverage, and example limits. An agent knows both when to call it and exactly what it will get back.

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% for both parameters, so the schema already documents query and query_goal. The description adds context about the JSONata expression behavior for aggregates but gives no extra syntax or format detail for the parameters themselves, 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 (describe the shape of a query result) and immediately contrasts it with the sibling seaf_jsonata_query, which executes queries. An agent can tell the two apart 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?

Explicit ordering and condition: call this BEFORE seaf_jsonata_query when unsure of the result shape, then follow up with seaf_jsonata_query using a refined query. Both the when and the next step 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds value beyond them by disclosing the shape of the response (attribute frequencies, relation fields, ID examples) and its role as a discovery step. It stops short of describing result size, pagination, or cost, which keeps 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?

Three compact, front-loaded clauses: when to call, the contrasting alternative, and follow-on tools. Every sentence carries routing or scope 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?

No output schema exists, so the description must convey return content, and it does at a summary level (attributes with frequency, incoming/outgoing relation fields, ID examples). It is sufficient to decide and call the tool, though the depth and format of those results remain only loosely characterized.

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

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

There is a single required parameter and schema coverage is 100%, with the schema itself giving a concrete example ('seaf.company.systems'). The description only implies the single-section constraint ('ОДНОГО раздела') and adds no format or syntax 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 uses a specific verb+resource ('structure of ONE section') and enumerates what it returns: attributes with frequency, outgoing/incoming relation fields, and ID examples. It explicitly distinguishes itself from inspect_sections, so an agent can pick correctly 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?

It opens with an explicit 'when to call' condition ('structure of ONE section without samples') and names the alternative for the contrasting case ('data samples and multiple sections at once -> inspect_sections'). It even chains the likely next tools (list_entities, describe_query_result), which is unusually complete routing guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive, so the safety profile is covered. The description adds value beyond them by disclosing the return shape (total and items {section, id, title}), which is important given there is no output schema. It stops short of describing matching semantics (case sensitivity, ranking, truncation at limit), which is a real remaining 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?

Three short sentences, front-loaded with the when-to-call condition, then the return shape, then routing to alternatives and next steps. Every sentence carries distinct information; none restates the name or 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 a three-parameter read-only search with no output schema, the description covers what it does, when to prefer it, what it returns structurally, and where to go next. Nothing essential to a correct first 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the `text` parameter matches against ID, title and description specifically, and `section` is framed as restricting the otherwise all-section search. That field-level detail is genuinely beyond "Подстрока для поиска".

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 operation (substring search over ID/title/description) and the resource (entities across all sections or one section), and explicitly contrasts itself with sibling list_entities. An agent can distinguish it from get_entity / list_entities / find_relation_paths 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?

States the triggering condition explicitly ("известно только примерное название объекта"), names the alternative (list_entities) and the condition that selects it (section and field conditions known precisely), and prescribes the follow-up tools (get_entity, get_relations) on a found 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?

Beyond the read-only/idempotent annotations, the description discloses the return shape {id, question, sections, expression, explanation}, the default limit, the special template=true substitution requirement, and conditional YAML metamodel fragments when SEAF_METAMODEL_PATH is configured. These are concrete behavioral details an agent would not otherwise know.

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

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

The description is front-loaded with the when-to-call guidance, followed by return shape, special cases, and the next tool. Its sentences are dense and purposeful, with no wasted framing.

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 is present, so the description carries the burden of explaining returns and does so completely: it lists returned fields, the limit default, template handling, and optional metamodel YAML additions. An agent has enough context to invoke this correctly and know what to do next.

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 real meaning for the queries parameter: it specifies what fields are searched (question, group, sections, expression text) and notes that Russian word forms match by prefix. The limit parameter is mostly restated from the schema, keeping this from a 5.

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

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

The description states a specific verb-like action (take a proven example) and resource (JSONata query examples), and scopes it with keyword search over question, group, sections, and expression text. It clearly distinguishes itself from the downstream seaf_jsonata_query sibling by naming it as the next step.

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

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

It explicitly says when to call this tool: before writing JSONata, to get a proven example of a similar query. It also names the alternative/downstream tool seaf_jsonata_query for applying the adapted expression, leaving no ambiguity about routing.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantive behavior: at most 10 shortest routes, up to 5 steps, per-step shape (from_section, field, to_section, direction out/in), and explicit non-behavior (no entity data returned, no JOIN executed). This is exactly the disclosure an agent needs beyond the annotations.

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

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

Front-loaded with the trigger condition, then return shape, then constraints, then next steps. Every clause carries information: no filler, no repetition of the title.

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 shoulders the burden of describing the return value and does so precisely (route list size, step cap, per-step fields, what is not returned). Nothing an agent needs to call it correctly or to interpret the result 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% and already defines start_section, end_section and via_sections with examples. The description's mention that via_sections limits intermediate sections only restates the schema wording, so it adds little meaning beyond structured fields – 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 and resource: determine which fields and sections connect two sections (e.g. people and products) before writing a JOIN. It clearly delineates the tool from raw relation listing and from the query-execution siblings (find_jsonata_examples, seaf_jsonata_query), which are named as follow-ups rather than as the tool's own job.

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 opens with 'Когда вызывать' and gives the exact precondition (before writing a JOIN), then states when to reach for alternatives: find_jsonata_examples (relations group) or seaf_jsonata_query afterward. It also states the via_sections restriction, so the caller knows how to narrow the search.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description adds real behavioral context beyond that: the return shape ('объект объектов', keyed by record ID) and the presence of technical fields __id__/__link_to_card__. It stops short of noting size/pagination concerns for a full-dataset fetch, which keeps it at 4.

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 usage condition, then scope, then return shape, then the sibling hand-off — a logical order with no filler. It is dense and a slightly long single block, but every clause 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, the description compensates by describing the return shape (object keyed by record ID) and example fields. Parameters are covered by the schema, and the scoping constraint plus sibling routing make this complete 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% and both parameters (dataset_id, params) are documented in the schema with the same seaf.company.ds.people example. The description adds little parameter meaning beyond the schema, 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?

States a concrete retrieval action on a named object: 'нужен именованный датасет представлений ЦЕЛИКОМ' with an example (seaf.company.ds.people) and the field types returned. It explicitly scopes to seaf.company.ds.* and distinguishes itself from query_dataset, so an agent can tell exactly what this returns vs. the sibling.

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

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

Opens with 'Когда вызывать' and states the selecting condition (you need the whole named dataset, only seaf.company.ds.*), then names the alternative: 'Для выборок по датасету и служебных seaf.ds.* — query_dataset'. Both when-to-use and when-not-to-use are given explicitly.

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

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

The annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds valuable context that the tool returns the object's section and all attributes, which partially compensates for the missing output schema, though it does not describe 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?

The description is three short, front-loaded sentences: when to call, what it returns, and the fallback/next-step tools. Every sentence carries useful routing or result information with no wasted text.

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

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

For a simple one-parameter lookup tool with rich annotations and no output schema, the description covers the essential context: exact-ID usage, what is returned, the unknown-ID fallback, and the relation follow-up. Nothing an agent needs in order 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?

There is only one parameter and its schema description coverage is 100%, already documenting it as the object ID with an example. The description reinforces that an exact ID is required but does not add syntax or format details beyond the schema, 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 states a specific verb and resource: it returns a section and all attributes of an object identified by an exact ID. It explicitly distinguishes this tool from find_entities for unknown IDs and points to get_relations for relations, so an agent can tell it apart from siblings.

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

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

It gives an explicit when-to-use condition: call it when the exact object ID is known. It also handles the main alternative case: if the ID is unknown, use find_entities first, and it names get_relations as the next step for relation data.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, and the description does not contradict them. It adds useful behavioral context by disclosing the GET endpoint and the expected response body {"message": "app is alive"}, though it does not describe failure behavior or auth requirements.

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

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

The description is compact and front-loads the usage condition, then gives return value and follow-up step. Every element is relevant, including the endpoint, with no filler.

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

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

For a simple zero-parameter health-check, the description supplies the when-to-call guidance, the concrete endpoint, the expected return body, and the next workflow step. With annotations covering safety traits and no output schema, nothing essential appears to be missing.

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

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

The tool has zero parameters and the schema coverage is 100%, so there are no parameter semantics for the description to explain. Per the baseline for zero-parameter tools, this is adequate without additional description 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?

The description states a specific verb and resource: checking portal availability via a health-check, with the concrete endpoint GET /health. It is clear what the tool does, but it does not explicitly differentiate itself from neighboring diagnostic/storage-problem tools such as get_seaf_core_api_core_storage_problems.

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

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

It explicitly says when to call it: to verify portal availability (health-check). It also gives the follow-up step, list_sections, which helps workflow selection, but it does not state when not to use it or name 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 readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered; the description adds the return shape (groups by field, count, title) and — crucially — discloses truncation ('до limit элементов') and that large objects need narrowing. It does not say how to paginate past the limit, which is the main remaining 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?

Front-loaded with the trigger phrase, then return shape, then narrowing advice, then the next step — a well-ordered chain of sentences. The enumerated subsystem/component/table relation examples are slightly verbose but they carry real domain 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?

With no output schema, the description carries the burden of describing returns and does so (field groups, counts, titles, per-group truncation) for a 4-parameter read tool. Missing only edge-case behavior — nonexistent id, empty results, and how to fetch beyond the limit.

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 would be 3; the description earns extra by explaining direction as outgoing/incoming semantics and by establishing that limit is per-group, not total. It still does not spell out what 'both' merges or how group ordering works.

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 (fetch an object's relations) and disambiguates the two directions with concrete domain examples: outgoing = what it references, incoming = who references it (subsystems via is_part_of, components via realizes_system, tables via system). An agent can distinguish this from find_relation_paths or get_entity on the name alone.

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?

Opens with an explicit trigger ('Когда вызывать: нужны связи объекта'), gives a mitigation for the large-object case ('сужайте direction/field'), and a follow-up step ('Дальше: get_entity на связанном id'). It never names a sibling alternative or a when-not condition, so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the meaningful context that results are post-manifest-load validation errors, but says nothing about result shape, emptiness, or error semantics — adequate but not rich.

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

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

Three short lines, front-loaded with the call condition and ending with the endpoint. The 'Дальше: зависит от найденных проблем' line is filler that does not earn its place, keeping it below 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?

With no output schema, the description carries the burden of explaining the return value, and it does not: an agent learns only that problems exist, not their structure (per-field errors, severity, manifest path). For a zero-param read tool this is workable but leaves a real gap.

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

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

The tool takes zero parameters, so there is nothing for the description to compensate for; baseline 4 applies. Schema coverage is 100% and the input is an empty object.

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

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

The description states a specific resource and outcome: validation errors detected during manifest loading, backed by an explicit storage/problems endpoint. It is clear what the tool returns, though it never explicitly contrasts itself with sibling tools like get_seaf_core_api_core_storage_versions.

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

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

The 'Когда вызывать' clause gives a usable trigger (to inspect manifest validation errors), but the follow-up 'Дальше: зависит от найденных проблем' is boilerplate that gives no real guidance on next steps or alternatives. No when-not-to-use or exclusion against siblings is offered.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the returned data points (version, manifest hash) but no cost, rate-limit, or failure-mode context; it is a small, additive contribution on top of annotations.

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

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

Three short lines, front-loaded with the trigger condition, then the follow-up, then the endpoint. Everything earns its place; the endpoint line is mildly redundant given no parameters, but still informative.

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 does the right thing by naming what comes back (core version and manifest hash), and the zero-param schema needs no further explanation. Minor gap: the exact response shape (e.g., whether hash is a separate field) is left unspecified.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is nothing the description could add on this dimension. The endpoint path it names is the only parameter-adjacent information and is consistent with the empty 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: retrieving the portal core version and manifest hash, plus the concrete endpoint GET /seaf-core/api/core/storage/versions. It is clearly distinct from siblings like list_sections or get_health, though the difference from get_health (also a diagnostic read) is only implied.

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 frames the trigger, and "Дальше: list_sections" gives a concrete follow-up step, which is genuinely useful routing. It stops short of saying when NOT to call it (e.g., versus get_health), 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?

Аннотации уже покрывают профиль безопасности (readOnly, idempotent, non-destructive), а описание добавляет поведение сверх них: точный состав ответа (count, атрибуты, поля-связи, до sample_limit образцов), факт усечения выгрузки и предупреждение о росте времени ответа при API_MIN_INTERVAL_SECONDS пропорционально числу разделов.

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?

Форма компактная и фронт-лоад: «Когда вызывать», «Возвращает», «Дальше» — каждый блок несет отдельную полезную информацию без повторов. Предупреждение о задержке вынесено в конец, что соответствует его вторичности.

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?

Output-схемы нет, и описание полностью компенсирует это, перечисляя возвращаемые поля и границы образцов. Для инструмента с двумя параметрами и покрытыми аннотациями описание достаточн для корректного вызова.

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?

Покрытие схемы 100%, поэтому оба параметра уже документированы; описание лишь повторяет диапазон 1-5 для sections и 1-3/по умолчанию 2 для sample_limit. Добавлена только косвенная деталь — что sample_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?

Указан конкретный глагол и ресурс: получить структуру И образцы по 1-5 разделам, с явным ограничением области (раздел целиком не выгружается). Тул четко отделен от соседа describe_section, который покрывает случай одного раздела без образцов.

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?

Явно задано когда вызывать («нужны структура И образцы сразу»), когда не нужно (для одного раздела без образцов достаточно describe_section) и что делать дальше (seaf_jsonata_query со связывающим запросом). Все условия выбора между альтернативами заданы.

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, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds useful behavior beyond that: execution happens on the portal, a concrete filter example, dot-path/array semantics, and the exact response shape. It omits permission or rate-limit details, but for a read-only list tool this is sufficient.

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

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

Front-loaded with 'Когда вызывать', followed by an example, semantic notes, sibling routing, and return shape. Dense but every sentence carries distinct information, with no restatement of the name or schema.

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

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

No output schema exists, and the description compensates by naming the return object ('{section,total,offset,items}') and the natural next step ('get_entity по id из items'). With filter semantics and sibling routing also covered, 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 80%, so the baseline is 3, but the description meaningfully exceeds it: dot notation for nested fields ('stakeholders.name'), array semantics ('для массивов eq/contains срабатывает на любой элемент'), boolean string formatting, and a concrete `where` example. It does not re-explain limit/offset/fields defaults, which the schema already documents.

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 ('объекты раздела' with field filters and pagination) and distinguishes itself from siblings: 'find_entities' for approximate-name search, 'list_sections' when the section is unknown. An agent can tell exactly what this tool does and when it is the right one.

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 'Когда вызывать' block, plus named alternatives with the condition that selects each ('Не знаете раздел — list_sections; ищете по примерному названию — find_entities'). Nothing is left to inference about when to use it versus its siblings.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds the useful behavioral fact that the response carries per-section object counts and descriptions, though it does not mention size, paging or whether the section list is 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?

Three short sentences, front-loaded with the 'when to call' trigger, then the return content, then the next-step routing. Every clause carries information; 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 parameterless discovery tool with no output schema, the description supplies everything needed: when to call it, what comes back (section identifiers plus counts and descriptions), and which sibling to chain into. Nothing an agent needs in order 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?

The tool takes zero parameters and the description correctly implies no input is needed, so there is nothing to mis-specify. No meaningful parameter semantics remain to be added.

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

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

States a specific verb and resource: it returns the seaf.company.* sections together with an object count and a description. It also explicitly separates itself from inspect_sections and describe_section, so an agent can pick it out of a crowded sibling list 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 trigger ('at the start of work, or when it's unknown which section holds the data') plus named alternatives with the distinguishing condition for each: inspect_sections for structure and samples of several sections, describe_section for one section without samples. Both when-to-use and the routing decision are handed over 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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds that the payload is prose reference text and that list_sections is the next step, which is useful, but it says nothing about the size/format of that text or whether it should be read whole versus in parts — relevant for a documentation dump.

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

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

Three compact segments: trigger condition, return payload, next step. Front-loaded with the when-to-call clause and zero filler, which is ideal for a zero-argument documentation 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?

With no input parameters, no output schema, and annotations carrying the safety profile, the description supplies what an agent needs: what the content covers, that it comes back as text, and where to go afterwards. Missing only a hint about how large the returned text is or how to consume it.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. Nothing in the description misdescribes input in a way that would mislead the agent.

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 concretely what the tool yields: SEAF metamodel concepts, relation semantics, and verified JSONata techniques (checklist, patterns, pitfalls), plus 'Возвращает текст справочника'. That is a specific content scope rather than a restatement of the name. It does not explicitly distinguish itself from the closely related sibling find_jsonata_examples, so it stops short of a 5.

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

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

The 'Когда вызывать' clause gives a clear trigger condition (need metamodel concepts, relation meaning, JSONata recipes) and names a follow-up step ('Дальше: list_sections'). It gives no when-not-to-use condition and does not route the agent away from find_jsonata_examples, so it is strong but not complete.

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

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

The annotations already cover the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description only needed to add what they don't say — and it does: source is auto-wrapped in parentheses, any dataset including seaf.ds.* is reachable, and the answer is computed whole on the portal, which is a real cost signal. It stops short of stating permissions or result-size limits, so it falls just short of full disclosure.

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 front-loaded with a 'when to call' clause and every sentence carries information (root $ semantics, origin forms, auto-wrapping, cost warning, fallback). The telegraphic, parenthesis-heavy style is dense but not padded; a slightly more linear phrasing would reach 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?

There is no output schema, and the description compensates by saying the tool returns the expression's result and that evaluation happens entirely on the portal. Given three parameters, a nested origin type, and annotations that already declare the safety profile, this is essentially complete 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 a 3 is the baseline; the description earns extra credit by explaining that origin accepts either a dataset ID or an {alias: dataset_id} map, and — importantly — what that choice does to the root $ (a map, with the dataset at $."alias"), plus that source gets wrapped automatically. The optional params object is left to its schema description, which is acceptable.

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

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

The description states a specific verb and resource — a JSONata selection over a named dataset — and immediately separates it from the sibling seaf_jsonata_query by naming which resource each one targets. An agent reading only the description can tell these two query tools apart 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?

It opens with an explicit 'Когда вызывать' condition (you need a JSONata selection over a named dataset), names the alternative for the model manifest case (seaf_jsonata_query), and closes with a fallback rule ('use seaf_jsonata_query if the data isn't in the dataset'). The conditions for choosing among siblings are spelled out rather than inferred.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds useful context beyond them: root $ is the manifest, the return is the raw expression result, and JSONata errors arrive as S0xxx/T0xxx with a correction hint. It does not say anything about result size limits or expression cost, which is the only remaining behavioural 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?

Front-loaded with the usage cue, then return/error behaviour, then the next-step alternatives, with the endpoint as a closing tag. Every clause earns its place and the ordering matches how an agent decides-and-calls.

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, annotation-rich tool with no output schema, the description covers intent, the root-context an agent needs to author a query, error signalling, and the sibling routing. Nothing required for a correct first call 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% and the single parameter is documented (including the auto-parenthesisation behaviour), so the baseline applies. The description nevertheless adds genuinely new semantics — that '$' resolves to the model manifest — which an agent needs in order to write a valid expression.

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 ('произвольный JSONata по манифесту модели') and immediately distinguishes itself from query_dataset, describe_query_result and get_entity/list_entities. An agent can tell exactly what this tool does and does not do 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?

Explicitly framed as 'Когда вызывать' with the selecting condition (arbitrary JSONata over the manifest), plus named alternatives with their own conditions (query_dataset for datasets, describe_query_result for exploring result shape, get_entity/list_entities for typical selections). Both directions — when to use and when not to — are covered.

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