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 still adds substantive behavior: images and videos are dropped, the body is Persian, reviews carry a structured `review` block with score out of 10, and `tags` can be reused as slugs elsewhere. This is exactly the content-shape and content-loss information 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?

The opening clause is front-loaded and does the most work, and the remaining sentences are informative rather than filler. Minor deduction for the second paragraph, which is a dense run-on and even leaves a parenthesis unclosed ('or use the article id with gf_comments)').

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 fully: it describes the review sub-object fields, the tags, the removal of media, and the language of the text. For a two-parameter read tool with these annotations, nothing essential to a correct 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 schema already explains both `article` (id or slug) and `max_chars` (truncation with truncated=true), so the description adds little about the inputs themselves. Its extra detail about slugs and ids concerns downstream reuse of returned values rather than the parameters, 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: 'Read one Gamefa article as plain text', and immediately scopes it with 'the editors' score box when it is a review'. The singular 'one' plus the sibling names make it unambiguous versus the list/search tools.

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

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

Explicit sequencing guidance: 'Use after gf_search_articles, gf_latest_articles or gf_popular', which tells the agent this is the follow-up step to a listing call. It does not mention gf_reviews or gf_game/gf_film as neighboring ways to get review or entity data, so the exclusion set is incomplete.

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, so the description is free to add domain behavior and does: comments carry likes and dislikes, replies are linked via `reply_to` to a parent comment id, content is Persian, and default ordering is newest first. It also warns that `author` is the name stored at comment time and may be stale after a rename — a genuinely useful caveat not present in structured fields. It stops short of describing volume, pagination limits, or what a partial/empty result looks like.

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 sentence is front-loaded and the usage hint follows immediately; nothing is padded. The trailing sentences about `reply_to` and `author` are informative but describe response fields in a block that an agent may read as input guidance, a minor structural misplacement.

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

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

There is no output schema, so the description must carry the return shape and largely does: comments with likes/dislikes, nested replies linked by `reply_to`, `author` naming, Persian language, newest-first ordering. Combined with four fully documented parameters and complete annotations, an agent has enough to call this correctly; only pagination limits and a notion of result size are missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description restates the default ordering ("newest first by default") that the `sort` enum already declares and mentions `author`/`reply_to`, which are response fields rather than inputs. It adds no format or interpretation detail for `post_id`, `page`, or `limit` beyond the schema.

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

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

The description opens with a specific verb+resource: "Read the public reader comments under a Gamefa article or a game/film profile, with likes and dislikes." That is unambiguous about what is returned and where it comes from. It does not, however, distinguish itself from the sibling gf_reviews, which an agent could easily confuse with comments given the line "what do readers think of X".

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?

"Use for 'what do readers think of X'" plus the note that profile comments hold user verdicts and ratings gives implied usage context. But there is no explicit when-not guidance and no named alternative, so the gf_reviews vs gf_comments boundary is left to inference — the single most consequential routing decision for this tool.

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

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

Annotations already grant read-only, idempotent, non-destructive access, so the lower bar applies. The description adds genuinely useful behavioral context beyond them: the text is served as Gamefa has it, with mostly English names but Persian descriptions, which warns the agent to expect mixed-language content in the result.

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

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

Two short sentences: the payload first, the input/language caveat second — well front-loaded with no filler. The line break mid-sentence is slightly awkward but costs nothing in comprehension.

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 by listing the fields an agent will receive, plus a language caveat. What is missing is minor: no indication of error behavior for a bad or unknown slug, and no note on whether related items (cast/director as links) are included.

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

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

Schema coverage is 100% and the schema already documents the slug with its pattern and a source/example. The description's 'slugs come from gf_films' largely restates that, adding only provenance emphasis rather than new syntax or validation detail, 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?

Opens with a specific verb and resource ('Get one film or series profile') and immediately enumerates the payload (IMDb and user score, genres, cast, director, writers, countries, runtime, release date). Naming 'one film' plus the pointer to gf_films clearly separates it from the sibling list tool.

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

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

States that slugs come from gf_films, which effectively tells the agent to call the list/search tool first and this one second. It stops short of naming an explicit exclusion (e.g. when to prefer gf_films or gf_popular instead), so it is clear context without full routing rules.

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, openWorld), so credit goes to the added behavioral facts: results are either read completely (`complete`: true) or truncated to the first `depth` pages (`partial`: true), and depth scans cost one request per 36-title page. That is real operational context an agent cannot get from the annotations. The one flaw is the claim "top_rated sorts by IMDb score," which conflicts with the schema's note that top_rated is the Gamefa editors' score.

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

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

Front-loaded with purpose, then usage examples, then constraints, then routing to siblings — a sensible order with no filler sentences. The style is telegraphic and a few clauses are compressed to the point of ambiguity (the depth/complete/partial sentence), which costs a point.

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 12-parameter browse tool with no output schema, the description covers the returned fields, the pagination envelope (complete vs partial, depth limits), the filter combination rule, and the follow-up tool for detail. Nothing an agent needs in order to call it correctly or interpret the result shape 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 baseline is 3; the description earns a step above it by stating the filter exclusivity rule ("at most one of type, genre, person, company, country, language, year; query works alone"), which is not expressed anywhere in the schema and is essential for correct calls. Its top_rated/IMDb-score sentence directly contradicts the sort parameter's own description, which could mislead sort selection.

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

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

Opens with a specific verb pair ("Browse or search") and the exact resource (Gamefa film/TV series profiles), then enumerates the fields returned. It actively separates itself from siblings: gf_film for cast/runtime detail, gf_terms for slug discovery. An agent can distinguish it from every listed sibling without opening another schema.

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

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

Gives concrete natural-language queries that map to this tool ("top rated films", "Nolan films", "finding a slug") and names two explicit alternatives with the condition that selects them (gf_terms for slugs, gf_film once you have a slug). It also states the mutually exclusive usage rule that governs correct invocation.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond them by disclosing that slugs are cross-tool currency (reusable as gf_games filters) and that the review URL is meant to be consumed via gf_article. It does not say what happens for an unknown slug, which is the only notable 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-loads the primary return fields in the first sentence and relegates secondary fields and the cross-tool hints to the second, so the agent gets the essentials first. The field enumeration is dense but every item is a real return value, so little 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?

With no output schema, the description carries the burden of explaining return values and does so thoroughly, including which fields are actionable links to other tools. For a one-parameter read tool this leaves nothing an agent needs 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 the single slug parameter is fully documented in the schema with a pattern and an example. The description adds only the framing that exactly one game is targeted, which is marginal beyond the schema. Baseline 3 is correct here.

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 singular resource ("Get one game's Gamefa profile") and then enumerates the payload: editors' score, user score and votes, Metacritic, release date, description, platforms, genres, developers, publishers, website, playtime and review URL. The singular "one game" clearly separates it from the list-oriented siblings gf_games and gf_upcoming_games.

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

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

Gives concrete usage context: the slug must come from gf_games or gf_upcoming_games, and the returned platform/genre/developer/publisher slugs can be fed back into gf_games as filters. It also routes the review URL to gf_article. It stops short of an explicit when-not statement, but the single-entity scope makes the alternative obvious.

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

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

Annotations only declare the safety profile (readOnly, idempotent, non-destructive); the description adds the crucial behavioral fact that small result sets are read completely and flagged `complete`: true, while large filters only scan the first `depth` pages of the sorted site list — i.e. results may be partial. It also notes the per-page request cost and that release dates come as Jalali plus ISO.

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 use cases, then constraints, then sibling routing — good ordering with no filler. It is dense to the point of being run-on in the middle (depth/complete explanation packed into one long clause), which costs some readability.

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

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

For a 10-parameter, no-output-schema, multi-mode listing tool, it covers modes, constraints, partial-result semantics and next steps well. Minor gap: it does not say what a result entry contains beyond the named fields, nor what happens on invalid slug combinations.

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 not encoded in the schema: the mutual-exclusivity rule among platform/genre/developer/publisher, that `query` cannot combine with those filters, and that `sort=top_rated` means Gamefa editors' score. The depth/page interaction is explained in prose as well as in 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 (browse/search Gamefa game profiles) and enumerates the returned data (editors' score, user score, genres, platforms, release date). It also positions itself against siblings by naming gf_game for full profiles and gf_upcoming_games for unreleased titles.

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

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

Gives concrete example intents ("best rated PS5 games", "games by Capcom", "best games of 2024") plus explicit constraints: at most one of platform/genre/developer/publisher, query works alone. It routes to alternatives explicitly — gf_terms for slugs, gf_game for the full profile, gf_upcoming_games for unreleased.

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, openWorldHint and destructiveHint=false, so the safety profile is covered structurally. The description adds real value by listing the return fields (id, title, date, url, short summary), but says nothing about pagination limits, how many pages are available, or how results are ordered beyond 'newest'.

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 use triggers, then a compact routing block for alternatives. Three sentences carry a lot of navigation value; the only slight cost is that the alternative-routing sentence is dense and mixes several sibling references.

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?

All five parameters are optional and documented, and since there is no output schema, describing the returned fields is the right compensating move. Complete enough to call correctly; only the pagination ceiling (page max 500, limit max 30) and result ordering nuances are left to the schema.

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

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

With schema coverage at 80%, the baseline is a 3, and the description genuinely exceeds it by explaining how parameters interact: `category` best-lists/scores pair with `year` for yearly roundups, and `tag` should be resolved via gf_terms (with an example slug). It does not explain `page` vs `limit` interplay, which the schema already covers adequately.

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

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

The opening sentence gives a specific verb and resource ('List the newest Gamefa articles') plus the optional scoping dimension (section). It also separates itself from siblings such as gf_popular ('ranks by views'), gf_article ('read one') and gf_search_articles by implication, so an agent can route 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?

Explicit when-to-use triggers are quoted ('what is new at Gamefa', 'latest PlayStation news'), and alternatives are named with their selecting conditions: best-lists/scores with `year` for top lists, `tag` from gf_terms for a single game, gf_article to read, gf_popular for view-ranked results.

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, openWorld and non-destructive, so the safety profile is covered. The description usefully adds the returned fields (id, title, url and view/comment/like counts) and result ordering, but says nothing about result caps beyond the schema or what happens when no articles match.

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

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

Two short sentences with the core action and sort order front-loaded and the cross-reference second. No filler, though the sentence break between behavior and drill-down could be marginally tighter.

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 naming the returned fields and ordering. For a three-parameter, default-laden read tool this is nearly enough; only edge behavior (empty results, max result ceiling) is unaddressed.

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% with enums on period and section, so the schema carries parameter meaning. The description only echoes the period values ('week, month, season or year') and ordering; it adds nothing about section values or how limit interacts with total results. 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 ('List the most viewed Gamefa articles') plus the supported time windows and the sort order ('most viewed first'). That cleanly separates it from recency-oriented siblings like gf_latest_articles, though it never names gf_latest_articles or gf_search_articles explicitly to draw the contrast.

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 ('Use for "what is trending at Gamefa"') and routes follow-up work to a named sibling ('read one with gf_article'). It does not state when to prefer gf_latest_articles or gf_search_articles instead, so the exclusion side is only 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?

Annotations already declare read-only, idempotent, open-world and non-destructive, so safety is covered. The description adds meaningful behavior beyond that: the articles mode returns records with id, title, date and counts, and points to gf_article for full reads, while the similar mode returns full profile objects shaped like gf_games output. That return-shape disclosure matters because there is no output schema. Pagination/limits are unmentioned.

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

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

Front-loaded with the core purpose in the first clause, then usage and return shape. Two short paragraphs, no filler. The second paragraph is dense but every clause carries routing or return-format 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 3-parameter read tool with no output schema, the description covers purpose, both mode semantics, the slug prerequisite, and an outline of returned fields. Remaining gaps are minor: no statement of result limits, ordering, or behavior on an unknown slug.

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

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

Schema coverage is 100% and both enums are documented there, so the baseline is 3. The description still adds value by explaining what each 'what' value actually yields (aggregated post records vs. profile objects shaped like gf_games output), which the schema's one-line enum descriptions do not convey.

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 ('list the articles Gamefa links to a game or film profile') and splits the second mode ('the games/films it shows as similar') explicitly, so the two behaviors behind the single tool are unambiguous. The second sentence routes the agent from gf_games/gf_films, which separates it from keyword-search siblings like gf_search_articles.

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 trigger for each mode: 'news and reviews about X' after gf_games or gf_films returned a slug, and 'games like X' for the similar mode. The prerequisite (you need a slug, not a query string) is spelled out. It stops short of naming the alternative sibling for free-text lookup (gf_search_articles), so an exclusion is only implied.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, and the description adds genuinely non-obvious traits: reverse-chronological ordering, post-pagination filtering (a page may return fewer than `limit`), and missing score boxes on older reviews. The only unaddressed area is pagination bounds/termination behavior across the 500-page range.

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 returns and in what order, then pivots to usage, then to caveats and alternatives. Every sentence carries distinct information; the Persian gloss is functional for matching native queries rather than decorative.

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

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

With no output schema, the description correctly compensates by enumerating the returned fields and the missing-score edge case. For a five-parameter read-only list tool it leaves nothing an agent needs in order to call it correctly.

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

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

Schema coverage is 80%, so the baseline is 3, but the description adds real meaning beyond the schema: `year` is scoped to a single publishing year, and `min_score` is disclosed as being applied after paging rather than during it, which changes how an agent should interpret short result pages. `query` and `page` semantics are left entirely to 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 the specific verb and resource ("List Gamefa's game reviews"), the ordering (newest first), and the payload (editors' score out of 10, label, pros and cons). It also explicitly differentiates from siblings — gf_article for full text, gf_game for a game's profile score.

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

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

Gives concrete trigger phrases ("how did Gamefa rate X", "latest reviews") plus the narrowing conditions for `year` and `min_score`. It also names the two alternatives and when to prefer them, so routing is unambiguous.

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 safety and idempotency, and the description adds real context beyond them: sort order (newest first) and the returned field set (id, title, date, url, short summary), which matters because there is no output schema. It stops short of covering pagination behavior or empty-result handling.

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

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

Front-loads the core action and ordering, then adds follow-up routing in one short block. Every sentence carries information an agent needs; there is no filler or repetition of the schema.

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

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

For a six-parameter search tool with no output schema and strong annotation coverage, the description supplies the return field list, sort order, narrowing filters, and next-step tools. 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 83%, so the schema already documents query, tag, year, page, limit and category. The description merely restates that tag narrows to one topic and year to one publishing year, adding no syntax, defaults, or interaction rules (e.g., how query and tag combine) 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 ('Search Gamefa's news, reviews and features by keyword') plus result ordering ('newest matches first'), which immediately separates it from listing tools like gf_latest_articles or gf_popular. The scope of returned fields is also named, so an agent knows what kind of result to expect.

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 case ('what has Gamefa written about X') and routes follow-ups correctly: gf_article for full text, gf_game/gf_reviews for review scores. It never explicitly rules out the closest siblings (gf_latest_articles, gf_popular) by name, so the exclusion is implied by the keyword requirement rather than stated.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: each hit returns slug, name and a usage count, and results are ordered by size when no `query` is given — ordering logic the agent cannot infer from the schema. It says nothing about rate limits or total result caps, but the essential behavior is disclosed.

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

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

Two short sentences: the first defines the lookup space, the second gives the call site and the payload/ordering contract. The most decision-relevant information (what it returns and when to call it) is front-loaded, and there is 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?

There is no output schema, so the description must convey the return shape, and it does so compactly (slug, name, counts). Combined with annotations covering safety and a fully documented schema, an agent has what it needs to call this correctly; only pagination beyond `limit` remains unaddressed.

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

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

With 100% schema coverage the baseline is 3, and the description earns a bump by explaining the semantics of omitting `query` (the most-used entities come back first), which is not something the schema's 'default: null' conveys. It does not elaborate on `limit` or the fuzzy-match behavior of partial names, so it is not exhaustive.

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

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

The description opens with a specific verb and resource: 'Find the slug of a platform, genre, developer, publisher, film person or studio, or an article topic tag.' It enumerates the entity kinds covered, matching the enum in the schema, and the title 'Find filter slugs' reinforces a resolvable, distinct purpose versus the record-fetching siblings (gf_games, gf_films, gf_article).

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 names the downstream consumers ('Use before gf_games, gf_films or the `tag` filter of the article tools') and the triggering condition ('when you only know a name'). The inverse case — skip this if you already have a slug — is only implied rather than stated, which keeps it just below 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?

Annotations already declare read-only, idempotent, open-world and non-destructive behavior, so the bar is lower; the description still adds real value by warning that far-off dates may be placeholders and that far-ahead months scan up to `depth` pages, which implies multiple requests and latency. It does not describe pagination limits or the shape of returned items, leaving some behavioral detail unstated.

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

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

Four short sentences, front-loaded with the definition before use cases, caveat, and next steps; no filler. The sentence 'Months far ahead scan up to `depth` pages' is slightly opaque without reading the schema, costing a point on structure.

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

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

For a six-parameter, no-output-schema read tool, the description covers purpose, when-to-use, data reliability caveats, and follow-up tools, which is close to complete. The one gap is the return payload: it mentions ISO release dates and implies slugs but never states what a result item contains.

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

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

With 100% schema description coverage the baseline is 3, but the description adds meaning beyond the schema by showing the `month` parameter in a realistic query ('games releasing in December 2026') and by framing `depth` as a cost tradeoff for distant months. Genre/platform filtering is not elaborated in the description, which keeps it 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?

States a specific verb and resource with a clear scope constraint: 'List games that have not been released yet, soonest first (Gamefa's release calendar), with ISO release dates.' The 'not released yet' qualifier cleanly separates it from the sibling gf_games, and the ordering rule is stated up front.

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

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

Gives concrete trigger phrases ('what comes out next', 'upcoming PS5 games', 'games releasing in December 2026') and ties the month case to the `month` parameter. It also routes onward to the right siblings: gf_game for per-title detail and gf_search_articles for news coverage.

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