ArcadeIndex

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

Annotations already declare readOnly, idempotent and non-destructive, so the remaining need is behavioural context, and the description supplies it well: a freshness window ('verified within the last 8 days'), the No-Match result code 'NO_MATCHES' with up to 3 relaxations and a re-callable retry, and the default 'content_rating_max' of teen. It does not state rate limits or result pagination, which keeps it below 5.

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

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

Purpose is front-loaded in the first clause, but the rest is a dense run-on that mixes result semantics, filter defaults, error handling, and client rendering and attribution rules. The output field is named 'similarity_reasons' at the start and 'match_reasons' later, which is an avoidable inconsistency an agent could trip over.

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 13-parameter discovery tool with an output schema and full annotations, the description covers the pieces the schema cannot: freshness, published and playable guarantees, the zero-result contract, relaxation retries and default rating filtering. Only the semantic meaning of most filter parameters is missing, which the enum values partially mitigate.

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 only 15% across 13 parameters, so the description needs to carry the explanation. It covers just three of them: include_listing_only, plays and the content_rating_max default. The other ten (mood, genre, limit, min_quality, inputs, players, difficulty, exclude_genres, session_length_max) are left entirely to short enum lists 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 and resource ('games similar to an anchor game'), plus the ordering ('by similarity') and the per-item output field. This is unmistakably different from the sibling tools get_game, search_games, trending and random_game, since it is the only anchor-based recommendation path.

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: an agent must infer that this tool is for 'I liked game X, give me more like it' versus filter-based search_games. The description does provide useful in-tool decision rules ('plays=here or plays=developer_site picks one kind', 'listing-only games with include_listing_only=true'), but it never names an alternative or a when-not-to-use condition.

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 read-only/idempotent safety profile, and the description goes well beyond them: alias resolution with requested_id set, the fact that listing-only, stale or suspect games are returned, the play_ready gate on play_url, and two named error conditions (NOT_FOUND, GONE) with their meanings. That is exactly the extra behavioral context annotations cannot carry.

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 what is returned, then the presentation caveat, then error semantics. Every clause carries operational information (identifier formats, requested_id, play_ready gate, error codes) 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?

An output schema exists, so the description correctly avoids enumerating return fields and instead covers what schema cannot: alias resolution behavior, degraded-data caveats, and error semantics. For a one-parameter read tool this is complete.

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's description already states the 6-char/slug-id format and alias resolution. The description's "by id or {slug}-{id}" largely restates that, so baseline 3 applies — it neither compensates for a gap nor adds new syntax detail.

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

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

"Full details of one game" gives a specific verb+resource, and the accepted identifier forms (6-char id or {slug}-{id}) scope it precisely. It is immediately distinguishable from search_games, games_like, trending and random_game, which return collections or selections rather than a single addressed record.

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 establishes the use case (fetch one known game, including aliased ids) and adds a concrete downstream rule: do NOT present play_url as playable unless play_ready is true. It does not explicitly route the agent to a sibling when the id is unknown or name-only, so the when-not path is implied by the NOT_FOUND error 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?

Goes well beyond the readOnly/idempotent annotations by disclosing the 8-day verification filter, the NO_MATCHES zero-result contract, and up to 3 executed relaxations whose args can be replayed. It also specifies presentation obligations (quote match_reasons, link play_url, attribution). Only the relaxation mechanics are left partially implicit.

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 time window and ordering before secondary rules, and every clause carries information. It is dense and somewhat run-on, which slightly hurts scanability, but 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?

Covers the edge cases an agent most needs (empty results, relaxation replay, listing-only, attribution) and an output schema handles return structure. Gaps remain on the numeric thresholds (min_quality, session_length_max) and mood semantics.

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 only 8% across 12 params, so the description must compensate. It explains plays, include_listing_only, and the content_rating_max default, but leaves mood, min_quality, session_length_max, difficulty, players, and inputs undefined beyond bare enums.

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+scope: 'Games published in the last 30 days, newest first', which distinguishes it from trending (popularity-based) and search_games (query-based). It does not name siblings explicitly, 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?

It clarifies conditional behavior (include_listing_only=true, plays=here vs developer_site, content_rating_max default) but never says when to prefer this over trending or search_games. Usage is implied by the 30-day window rather than contrasted with 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?

Goes well beyond readOnly/idempotent annotations: it explains host capability variance (MCP Apps player vs. new-tab fallback vs. plain-text play_url), the link_out outcome and its causes (listing-only, stale check, Mature, disallowed site), and names error codes. This is exactly the behavioral context an agent needs before claiming success.

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

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

Front-loaded with the core action and keeps everything in a single dense paragraph with no filler. It is somewhat run-on given the number of fallback cases, but each clause carries operational information the agent needs.

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

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

Covers the full decision surface: input forms, host capability differences, fallback link behavior, when not to assert playback, and error codes. Even though an output schema exists, the description's explanation of mode/link_out/reason is what makes the tool callable correctly across host environments.

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 descriptions already document the game_id forms and that query resolves to the top search_games hit. The description largely restates those semantics; its additional value is mainly outcome-related (link_out when only on the developer's site), not parameter-level detail. Baseline 3 is appropriate.

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

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

States a concrete verb and resource ('Play an ArcadeIndex game right inside the chat') and immediately distinguishes itself from retrieval siblings by describing what playback means here (embedded player vs. link out). An agent can tell this apart from get_game or search_games without opening a schema.

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

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

Explicitly says to pass game_id (with accepted forms, including URLs from search_games, trending, games_like, new_games results) or query (top search hit is played). It also tells the agent what to do when playback isn't possible: give the user the link_out URL, and don't claim the game is running unless the user says so. That is unusually clear 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?

Goes beyond the readOnly/idempotent annotations by disclosing a hard content gate (never Mature) and the no-match contract (game: null, code NO_MATCHES, and automatic filter relaxations). The relaxation behavior is the most important trait an agent needs, but it is left vague about which filters get relaxed and in what order.

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 dense sentences, front-loaded with the core action and no filler. The final sentence packs edge-case behavior efficiently, though terms like 'relaxations' and 'NO_MATCHES' are used as jargon without 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?

An output schema exists, so return shape needn't be explained, and the no-match case is covered. But for a 12-parameter tool, the non-enum parameters (min_quality, session_length_max, include_listing_only) and the interaction between 'never returns Mature' and content_rating_max='mature' are unexplained, leaving real ambiguity.

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 only 17%, so the description must carry the burden and does not: the only parameter it touches is seed, which the schema already documents. Ten filtering parameters (mood, genre, players, difficulty, min_quality, exclude_genres, content_rating_max, session_length_max, include_listing_only, inputs) get no semantics beyond self-evident enums.

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 ('One random eligible game') plus the flow it serves ('surprise me') and the seed-determinism variant. This is clearly distinguishable from search_games and games_like, which return filtered or similar lists rather than a single sampled pick.

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 clear usage context ('surprise me' flows) and a decision rule for the seed parameter (deterministic pick). It never names search_games or games_like as the alternative for explicit criteria, so the when-not-to-use case is left 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?

Given annotations already mark it read-only and idempotent, the description adds substantial behavioral context: natural-language interpretation, echoed interpreted_filters, explicit-param precedence, published/playable freshness constraints, listing-only behavior, content-rating default, and zero-result relaxation behavior. This is exactly the kind of operational detail an agent needs beyond the safety 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 description is dense but front-loaded with the core action, then layers query interpretation, special title behavior, return constraints, zero-result handling, and output requirements. Every clause contributes useful selection or invocation guidance for a complex 14-parameter search tool.

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

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

For a complex search tool with an output schema and read-only annotations, the description covers the critical gaps: interpretation behavior, filter precedence, freshness constraints, zero-result semantics, relaxation usage, and attribution requirements. An agent has enough information to select and 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 low at 21%, so the description has to compensate for many of the 14 parameters. It meaningfully explains the main filter families, natural-language phrase handling, explicit-param precedence, include_listing_only, plays behavior, and content_rating_max default, though it leaves some parameters such as limit, min_quality, and exclude_genres largely 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 a specific verb and resource: find web games from a natural-language query plus optional filters. It also distinguishes special behavior for titles via games_like results, so the agent can tell this is the primary search tool rather than a detail or random-selection 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?

Clearly implies use when searching by natural-language query or filters, and explicitly explains how 'like {title}' routes to games_like results. It also says explicit params win over interpreted phrases, but it does not explicitly contrast with siblings such as trending, random_game, or get_game.

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?

Despite annotations already marking the tool read-only and idempotent, the description adds substantial behavioral context: trending_basis indicates play-data vs recency fallback, results are limited to published/playable games verified within 8 days, listing-only handling is explained, and zero results returns NO_MATCHES with up to 3 executed relaxations. It also discloses output-handling requirements including quoting match_reasons, linking play_url, and rendering the attribution.

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 dense but front-loaded with the core purpose, then packs only relevant behavioral details into a short block. Every sentence contributes something material to selecting or invoking the tool correctly.

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 13-parameter tool with an output schema, the description covers the most important behavioral and return-related semantics: fallback basis, verification window, zero-result behavior, relaxation retries, and attribution requirements. It is not fully complete because several filtering parameters remain undocumented, but the output schema reduces the burden to explain return values.

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 only 8% across 13 parameters. The description meaningfully explains plays, include_listing_only, content_rating_max, genre scope, and window, but leaves many filters such as mood, inputs, players, difficulty, min_quality, exclude_genres, session_length_max, and limit unelaborated beyond their enum names.

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 scope: games trending over the last day or week, with genre scope when genre is set. This clearly distinguishes it from siblings such as new_games, random_game, and search_games without needing to name them.

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 implied by the 'trending' framing and by details such as plays=here vs plays=developer_site and include_listing_only=true, but it never explicitly says when to choose this tool over new_games or search_games. The zero-results retry guidance is useful but is post-result behavior rather than pre-call usage guidance.

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