ruTS-mcp

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description need not repeat safety. It adds substantial behavioral context: warnings about short texts, non-Russian text, missing dictionaries/models, null values for undefined statistics, and a performance note that syntax parsing takes seconds on long text. It also explains the output schema structure (value, share, interpretation, description, count, found).

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

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

The description is long and dense, with a very detailed enumeration of what each statistic group computes. While structured, the group descriptions could be trimmed, and some sentences repeat schema-provided parameter guidance. It is front-loaded with purpose and usage, but the sheer length risks diluting key instructions.

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

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

Given the tool's complexity (10 statistical groups, many metrics, dictionary/model dependencies) and the rich schema/output schema, the description is complete enough for an agent to invoke it correctly. It covers all relevant caveats, warnings, and output structure, and nothing critical 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%, but the description adds deep meaning beyond the schema's brief parameter notes. It explains each of the 10 group enum values in detail, clarifies that path avoids resending long texts and ensures statistics are computed on the original text, and provides a rationale for readability_preset choices (e.g., fiction gives a class several years higher, academic uses Solovyov et al. for grades 5-11).

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 clear verb-resource statement: 'Измерить русский текст статистиками библиотеки ruTS.' It defines the tool's scope as measuring Russian text with ruTS statistics. However, it does not explicitly differentiate from sibling tools like compare_texts or collocations, so an agent must infer the distinction.

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

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

It explicitly states when to use the tool ('чтобы получить точные числа о тексте, а не оценивать его на глаз') and gives concrete guidance on parameter choice, such as forwarding long text via path instead of text and recommending 'plainrussian' for readability_preset without a special reason. It also advises using style and syntax groups together for канцелярит checks. What's missing is any mention of sibling alternatives or when not to use this tool.

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

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

Annotations only declare readOnly, openWorld=false, and idempotent; the description adds substantial behavioral context: ordered left/right pairs within the window, pymorphy3 lemmatization without homonym disambiguation, interpretation of freq_pair as repeated pairs rather than stable collocations, and warning conditions. There is no contradiction with the annotations.

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

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

The purpose is front-loaded, and the description is organized into clear paragraphs covering usage, pair ordering, output interpretation, and warnings. The detailed output-field explanation is partly redundant because an output schema exists, making it slightly longer than necessary, though most content 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 an 8-parameter analytical tool with annotations and an output schema, the description supplies enough context to call and interpret it correctly: purpose, use cases, pair ordering, frequency interpretation, and warning behavior. No critical gap remains for an agent deciding how to use this tool.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by clarifying directional window ordering and the lemmatization caveat. It adds little for parameters like top_n or min_freq beyond what the schema already says, so it is not 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?

States a specific verb and resource: 'Найти коллокации текста' and defines collocations as word pairs occurring together more often than chance. It does not distinguish this tool from siblings such as kwic or dispersion, so it is clear but lacks explicit sibling differentiation.

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

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

Gives intended use cases ('устойчивых сочетаний, терминологии и сочетаемости слова') and points to the node parameter. However, it provides no when-not guidance and does not name alternatives among the sibling tools, leaving usage selection implied rather than explicit.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the windowing mechanism, the ~150 ruTS features, corpus truncation behavior, warnings for dropped remainders and >10% word loss, and minimum two-window requirements. It also explains output semantics including Cliff's delta thresholds, Holm correction, bootstrap caveats about non-independent windows, and warnings. This is exceptionally rich behavioral context for a complex analysis tool.

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

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

The description is long but well-structured: purpose and usage are front-loaded, followed by mechanics, feature prefixes, and result semantics. The density is justified by the statistical complexity, though several sentences are verbose and could be tightened without losing 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 complex corpus-comparison tool with 7 parameters and an output schema, the description covers usage, input requirements, windowing behavior, feature families, result fields, statistical caveats, and warnings. An agent has enough context to call it correctly and interpret the response.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: it explains how window defaults are chosen when unset, that whole_texts means texts are compared in full, and that a_paths/b_paths are for file-based corpora. top_n is only implicitly covered through the result-ordering explanation, so it is not a full 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 first sentence states a specific verb and resource: compare two text corpora by style features and identify the strongest differences. The use-case list (authorship attribution, genre/translation/human-vs-model comparison) further clarifies intent. It does not explicitly distinguish itself from the sibling keyness tool, which also compares corpora, so it stops short of a 5.

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

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

The description gives concrete usage contexts: authorship attribution, genre comparison, translation comparison, and human-vs-model text comparison. It also states input requirements such as at least two windows per corpus and passing file texts via a_paths/b_paths. It lacks explicit when-not-to-use guidance or named alternatives, so it is clear but not exhaustive.

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

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

Annotations already declare this as a read-only, idempotent, closed-world operation, and the description adds substantial behavioral detail beyond that. It explains the text partitioning into parts, the meaning and direction of each dispersion measure, null handling for missing words, the frequency-below-parts caveat, and the warnings key.

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

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

The description is front-loaded with purpose and usage, then structured into a compact bullet list explaining the output measures. Despite its length, every section earns its place given the number of non-obvious statistical measures and edge cases.

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 specialized statistical tool with multiple output metrics, the description is complete: it covers purpose, use case, partitioning, measure interpretation, missing-word behavior, the low-frequency caveat, and warnings. Even though an output schema exists, the description provides the interpretive context an agent needs to use the results 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 schema already documents all six parameters. The description adds useful semantics beyond the schema by explaining that the text is divided into parts of roughly equal size, that words appear in request order or frequency order, and that frequency relative to parts affects interpretation of the measures.

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

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

The description clearly states a specific verb and resource: measuring how evenly words are distributed across a text using Gries dispersion. It also distinguishes the measure from raw frequency, which does not reveal whether a word is spread throughout the text or concentrated in one place. It does not explicitly name or differentiate itself from sibling tools such as analyze_text, keyness, or collocations.

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 clear use case: use it to distinguish a word that runs through the whole text from one concentrated in a single place, which frequency alone cannot do. However, it does not explicitly state when not to use it or name alternative tools for related analyses.

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 well beyond the readOnly/idempotent annotations: discloses normalization (lowercase, е instead of ё), that numbers and Latin-script tokens are dropped with a dictionary reference, that out-of-vocabulary words receive the dictionary's minimum frequency (~37) so names and typos surface as keywords, and the stemming edge cases for function words. It also documents the warnings key and the caveat that p_value is uncorrected, with a practical p < 0.0001 (g2 ≥ 15.13) threshold.

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 and usage in the first two paragraphs, then results interpretation; every block has a function. It is dense and long, and the digression about dictionary entries the lemmatizer misses (его, ее, их, во, со) is niche detail that could be trimmed, plus the results paragraph partly restates the output 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 9-parameter tool with an output schema, the description covers the setup prerequisite (dictionary download), normalization behavior, degenerate outcomes via warnings, and how to read the significance and effect-size fields. An agent has everything needed to call it and interpret the result 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 schema already carries parameter documentation; baseline is 3. The description does add interpretive value for measure ('мера сортировки и как ее читать'), the sign convention of g2/log_ratio, and the default reference dictionary, but it does not add per-parameter detail for top_n, min_freq, positive, or lemmatize 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 verb and resource: find words in a text that are significantly over- or under-represented relative to a reference. It also defines scope precisely by naming the two comparison modes (default frequency dictionary vs. another text via reference/reference_path), which separates it from generic analysis 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?

"Используйте, чтобы понять, чем лексика текста отличается от обычного языка … или от другого текста" gives an explicit use condition for both modes, and it flags the prerequisite of downloading the frequency dictionary via ruts-mcp download. It does not name a sibling (e.g. compare_texts) or state when to prefer that tool instead, so the boundary with siblings 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?

Goes well beyond the readOnly/idempotent annotations: case- and ё-insensitive matching, optional pymorphy3 lemma search, the rule that a phrase never crosses a sentence boundary, the row cap via limit plus an overall ~40k character response budget, and warnings for non-Russian input or truncated results. This is exactly the operational detail an agent needs before calling.

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 in the first sentence, then matching rules, then output shape – a logical order. Slightly long on the return-value paragraph, which partly restates what the output schema already declares, but every sentence carries usable content.

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

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

Covers input source, matching rules, limits, truncation and warnings, so an agent can call it and interpret results without surprises. Because an output schema exists, the detailed enumeration of n_matches/matches/left/keyword/right is somewhat redundant, which keeps it just short of 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 path, text, limit, window, keyword and by_lemma are all documented in the schema. The description adds matching semantics (case/ё folding, pymorphy3 lemma behavior) but does not clarify the meaning of path vs text or window beyond what the schema already says, so baseline 3 is right.

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 all occurrences of a word/phrase in text with surrounding context (KWIC concordance). A reader immediately knows what the tool returns. It does not explicitly name the sibling tools (collocations, dispersion, keyness) it should be chosen over, keeping it at 4 rather than 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?

Gives a concrete use case – see how a word is used in a text and quote it accurately – which implies when to reach for this rather than aggregate siblings. There are no explicit exclusions or named alternatives, so the routing is clear but not fully prescriptive.

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