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

With no annotations, the description carries the full burden: it declares the read-only, side-effect-free nature ('Только чтение, без побочных эффектов') and specifies the exact fallback behavior when the ID is missing or unpublished. That not-found text is critical behavioral context an agent needs to interpret the response.

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-loaded with purpose, then the parameter source, then behavior. Every sentence earns its place with no repetition.

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-param lookup with no output schema, the description covers purpose, ID provenance, safety, and the not-found case. A brief note on the successful return shape (fields returned) would make it complete, but nothing essential 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 coverage is 100% and includes the integer/positive constraint, so the schema does the heavy lifting. The description adds provenance for the ID value (from search_jokes or random_joke) which the schema does not state, giving it slight 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 verb and resource ('Возвращает запись юмора по её числовому ID') and clearly distinguishes from siblings (search_jokes, random_joke, get_jokes_by_category) by being a direct ID lookup. An agent can immediately tell what this tool does and how it differs from the search/list siblings.

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

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

Explicitly instructs where to obtain the ID ('ID можно получить из search_jokes или random_joke'), which tells the agent when to use this tool after those alternatives. No explicit exclusions, but the dependency chain is clear.

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

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

With no annotations, the description carries the full burden and does well: it declares read-only with no side effects, discloses the sort order, and explains the response shape (total plus items). It lacks any note on auth or rate limits, which keeps 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 purpose and ordering, then parameters, then response shape, in four tight sentences. There is mild duplication of the limit and categoryId rules already present in the schema, but nothing is wasted.

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

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

No output schema exists, yet the description explains that the response contains total and items, and covers pagination mechanics plus the required categoryId source. An agent has everything needed to call it correctly on the first try.

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 including min/max and defaults. The description restates limit default 15 and max 50 and adds only the procedural hint of stepping offset by limit, 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 specific verb and resource ('Возвращает список записей конкретной категории') plus the ordering (newest to oldest by descending id). It does not explicitly contrast with the nearest sibling search_jokes, so an agent must infer that distinction, but the scope is unambiguous.

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

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

Gives actionable context: categoryId must come from list_categories, and pagination is driven by increasing offset in multiples of limit. It does not state when to prefer search_jokes or random_joke instead, so alternatives are implied rather than excluded.

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 no annotations provided, the description carries the burden and does well: it explicitly states the operation is read-only with no side effects and describes the response format as a JSON array in content[0].text. It does not cover ordering, pagination, or error behavior, but for a simple list tool this is largely sufficient.

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

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

The description is compact and front-loaded: it identifies the resource, lists returned fields, states safety, gives response format, and explains downstream usage in just a few sentences. Every sentence adds value.

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

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

Given no output schema and no annotations, the description steps up by explaining the return shape and fields, and by stating read-only behavior. It is nearly complete, though it could mention ordering or whether categories are static to be fully self-contained.

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 input parameters, so the baseline is 4. The description adds useful output semantics by indicating that the returned id field maps to categoryId in other tools, though there are no input parameters to clarify.

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: returns the full list of humor categories, and names the exact fields included. It is clearly distinguishable from sibling tools like get_jokes_by_category, which lists jokes rather than categories.

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 explains that returned ids should be used as categoryId in random_joke and get_jokes_by_category, which is useful downstream context. However, it does not say when to choose this tool over similar siblings like popular_tags or search_jokes, leaving alternative selection implicit.

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

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

With no annotations, the description carries the full behavioral burden and explicitly declares read-only behavior with no side effects, descending frequency sorting, the default limit, and the returned {name, count} shape. It omits auth, rate-limit, and empty-result behavior, but for a simple public read this is a strong 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?

The definition is front-loaded with purpose and sorting, then covers safety, limit, and return shape in four tight sentences. The second sentence is mildly redundant with the first but still adds contextual value, keeping the overall structure efficient.

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

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

For a one-optional-parameter read tool with no output schema, the description supplies the missing return format ({name, count}) and safety profile, so an agent has enough information to call it correctly. No critical context is missing for this complexity level.

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

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

Schema description coverage is 100%, and the single optional limit parameter is already fully documented with range and default. The description repeats the same limit semantics rather than adding new meaning, so the baseline score 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: returns the most frequently used entry tags, sorted by descending frequency. The resource ('tags') is distinct from sibling resources like list_categories and search_jokes, so an agent can identify the 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?

It provides clear context by saying it shows the topics most often found in the database, which implies when the tool is useful. However, it does not explicitly contrast this with siblings such as list_categories or search_jokes, and it names no exclusions or when-not-to-use conditions.

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 no annotations, the description carries the full burden and does so well: it declares read-only/no side effects, warns that repeated calls with the same argument are non-deterministic, and describes the empty-category fallback string «Анекдот не найден». It omits permission/auth requirements and whether the 18+ inclusion can be suppressed, which keeps it below 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 behavior, then conditional logic, safety, non-determinism, and the empty-result case – every sentence carries real information. Slightly dense in a single block but no wasted clauses.

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

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

There is no output schema, and the description does explain the return (one random record, or the literal fallback text). It is a bit vague about the shape/fields of the returned record (id, text, category, tags) and about the 18+ flag, which is the main remaining gap for a single-parameter read 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%, and the parameter's own description already explains the category filter and the default of any category including 18+. The description restates this rather than adding format or lookup guidance 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: returns one random record (joke/story/aphorism) from the РжуНеМогу database. The randomness and single-item scope immediately distinguish it from siblings like get_jokes_by_category and search_jokes, so an agent can pick it 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?

Clearly states the two usage modes: with categoryId it samples only that category, without it samples all published records including 18+. It does not name an alternative tool or explicitly say when not to use it (e.g. 'for a specific joke use get_joke_by_id'), so it stops 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?

With no annotations, the description carries the full burden and does well: it discloses read-only/no-side-effects, relevance ordering via ts_rank, stemming behavior, and the empty-result consequence of a missing query. What it omits is the shape of returned records, but that is a modest gap for a read 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?

Front-loads what the tool is and the stemming example, then constraints, then pagination. Mostly efficient, though the limit default/ceiling restatement duplicates the schema and could be trimmed.

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 ranking, language/morphology, required query, and pagination. Only the returned record shape is unaddressed, which is a minor omission.

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 limit/offset defaults and bounds are already documented and the description largely repeats them. The one genuine addition is the morphology explanation showing that 'врач' matches 'врачи'/'врачом', which clarifies query semantics 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+resource: full-text keyword search over joke records, with Russian-language scope and ranking. It is clear what the tool does, but it never names how it differs from siblings such as get_jokes_by_category or random_joke, leaving that inference to the agent.

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

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

Usage is only implied: 'query обязателен; поиск без него вернёт пустой результат' tells the agent the parameter is mandatory but not when to prefer search over category browsing or random retrieval. No explicit when-to-use or when-not-to-use guidance appears.

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 no annotations provided, the description carries the full burden and does well: it declares read-only, no side effects, and low call cost relative to search. It also lists the returned metrics, compensating for the absence of an output schema. It stops short of stating anything about the freshness/update mechanics of the stats themselves.

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 is returned, then adds usefulness and cost context in efficient sentences. Slight redundancy between the 'general idea of size and activity' and 'quick availability checks' sentences, but nothing wasted.

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

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

A zero-parameter tool with no output schema, yet the description enumerates every returned field and adds the read-only/cost profile. An agent has everything needed to call it correctly and interpret the result.

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

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

Zero parameters, so the baseline of 4 applies. There is no parameter to document and the description correctly keeps the focus on returned values instead.

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 (returns statistics) and resource (the database), and enumerates the exact fields returned: total_jokes, total_categories, total_tags, last_update. An agent can immediately tell this apart from the sibling search/list tools 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 positions the tool for a 'general idea of database size and activity' and for 'quick availability checks', and contrasts its low cost with searching. Clear usage context, though it names no explicit when-not-to-use or alternative sibling tool.

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