Kineticist

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: output arrives as markdown, and news articles are truncated to headline/date/summary/link with the full article only at the link — a return-shape quirk the annotations do not convey.

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 core action is front-loaded in the opening clause, and the example query plus the news-article caveat are short and purposeful. The second sentence listing page types is slightly padded but still earns its place by clarifying scope.

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

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

For a one-parameter fetch tool with full annotation coverage and a fully documented schema, the description supplies what is missing: markdown output, the news truncation behavior, and where to obtain the URL. No output schema exists, yet the description still hints at the return shape, which is appropriate.

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 `url` parameter already carries its own description and example, so the baseline is 3. The description only restates the www.kineticist.com link constraint already present in the schema, adding no new format or validation 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?

States a specific verb and resource: 'Reads a Kineticist page by its link, as markdown', and enumerates the page types it covers (game, Hype Index entry, place to play, manufacturer, person, mod, creator). It does not, however, explicitly separate itself from the overlapping siblings get_game_details and get_game_credits, so an agent must infer the boundary.

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

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

It gives an example query and says 'Use the `url` from search or another tool', which is useful sourcing guidance. But it never states when to prefer this over get_game_details or the other specific getters, so the when-to-use decision against siblings 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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds substantial value beyond that: it discloses the return shape and subtle semantics such as 'no is_lead means no ranking, not "not the lead"' and the role vs role_name distinction for filtering versus display. With no output schema present, this disclosure carries real weight.

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 example queries before explaining output fields, which is the right ordering for an agent deciding whether to call it. There is mild redundancy in 'The design team for a pinball game — designer, artist, programmer, mechanical engineer, sound designer, animator, etc.' after the credit list was already implied, but no sentence is wasted overall.

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

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

With no output schema, the description does the heavy lifting by documenting role, role_name, is_lead, url, and game_url and how to use each. Gaps remain minor: it does not state ordering of results or behavior on an unknown/invalid id, but for a one-parameter lookup the definition is nearly 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 description coverage is 100% and the single `id` parameter is already documented as 'Game slug or ID'. The description never elaborates on the id (e.g. how to obtain a slug, or whether the display name is accepted), so it adds nothing beyond the schema, which is the baseline 3 for a fully covered single-parameter tool.

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

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

Names a specific verb and resource ('Who designed a pinball machine', 'Get a game's design team') and pins down scope with 'Returns the full credited team, not just the lead designer', which separates it from a general sibling like get_game_details. It also enumerates the credit types returned (designer, artist, programmer, etc.), so an agent knows exactly what data this yields.

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 three example questions ('who designed Medieval Madness?', 'who did the art for Twilight Zone?') give concrete usage triggers, which is stronger than vague context. However, it never names an alternative sibling or states a when-not condition (e.g. use get_game_details for release dates), so guidance stops short of full routing.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds substantial extra context: best_image and its meaning, the url/remake url semantics, that remake editions are nested under the remake, and the newest_edition_year vs in_production distinction. This is rich behavioral/output disclosure beyond the structured fields.

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

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

It is on the long side and the quoted example questions are slightly cluttered, but every sentence carries substantive information (edition grouping, best_image fields, ID formats, field semantics) and the return shape is front-loaded. Little is wasted, though it could be tightened.

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 return-value burden and does so thoroughly, explaining editions, pricing, images, and the year/production fields. An agent has everything needed to call it 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?

Schema coverage is 100%, so baseline is 3, but the description adds real value: concrete examples of slug (godzilla-2021), OPDB group ID (weeP), and OPDB machine ID (GweeP-MW95j) disambiguate the id formats, and it explains the include=credits effect beyond the schema's one-line boolean description.

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 names a specific resource (pinball machine details) and enumerates exactly what it returns: pricing, production status, editions (Pro/Premium/LE), images, tags, description, and rules links. The example queries ('how much is the Godzilla Premium, and is it still made?') make the scope concrete and distinguish it from a generic search 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?

It gives clear context for use via representative questions and lists the accepted identifier forms, and it points to `?include=credits` for design-team data (a soft alternative to get_game_credits). It doesn't explicitly state when not to use it or name sibling tools as alternatives, so it falls short of 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 readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds the list of statistics returned but no further behavioral details such as data freshness or caching, which is adequate for a simple read-only 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 two sentences: first framing the use case with example questions, then listing the exact metrics. It is front-loaded and every sentence earns its place, though the conversational framing is slightly less direct than possible.

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 usefully enumerates the returned metrics (total games, manufacturers, designers, average fun score, most rated game, newest game). For a parameterless read-only tool, this covers nearly everything an agent needs, though the return format is unspecified.

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

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

There are zero parameters, so per the rubric the baseline is 4. The empty schema requires no parameter semantics, and the description rightly does not discuss inputs.

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 names the specific resource (Kineticist database statistics) and enumerates exact aggregate metrics like total games, games in production, and total manufacturers. This makes it clearly distinct from sibling game, file, and search tools without requiring schema inspection.

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 concrete example questions ('how many pinball machines are in production?') that imply the appropriate aggregate-count use case. It does not name alternatives or exclusions, but the context for when to call it 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?

Annotations already cover safety (readOnlyHint=true, destructiveHint=false) and non-idempotence. The description adds useful context beyond them: that the result is non-deterministic and that the payload includes best_image, the single picture to display.

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

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

Three short sentences, front-loaded with the user intents that trigger the tool. The opening 'Suggest a pinball machine' and the following sentence overlap slightly, a minor redundancy.

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

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

With no input parameters and no output schema, the description carries the return-value burden and does so adequately by noting full details and the best_image field. Coverage of what the response contains is good, though not exhaustive.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter meaning is missing or misrepresented.

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 clear verb+resource: returns a random pinball game with full details. It distinguishes itself from siblings like get_game_details by emphasizing randomness ('different game every time'), though it doesn't explicitly name a sibling it replaces.

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?

Provides concrete trigger intents ('surprise me', 'pinball game of the day') that tell the agent when this tool is appropriate. It stops short of naming alternatives or exclusions (e.g., use search when the user has a specific title in mind).

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description still adds real behavior: output is grouped by machine, each line carries a differentiator when the title is ambiguous, results end with the game page's Documentation link, and downloads are gated behind an external account. This is context an agent cannot get from the annotations.

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

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

Front-loaded with the purpose and example queries, and every sentence carries some information (file types, grouping, differentiators, account gate). The two quoted search phrasings are mildly redundant with the surrounding prose, keeping it just short of maximally tight.

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 full burden of describing return shape and does so: results grouped by machine, per-file differentiating descriptions, and a trailing Documentation link. The machine filter and the account-gated download caveat close the remaining gaps for a read-only listing 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 both parameters are already documented; the description's 'trm_ id, slug, UUID or OPDB machine id' phrasing essentially restates the `machine` schema description. It confirms `machine` narrows to one machine, but adds no new format or constraint detail beyond the schema — 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 ('Lists a pinball game's downloadable files') and enumerates the file types involved (manuals, ROMs, schematics, parts lists, bulletins). It distinguishes itself from the get_* siblings by its explicit focus on documentation/schematic lookup rather than game details or credits.

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 triggering questions ('where's the Firepower manual?', 'schematics for Fish Tales') and states the answering goal — 'which file is for which machine'. It also clarifies the capability boundary (metadata only; downloading requires a Kineticist account on the game page), but never names a sibling tool as an alternative.

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 safety bar is low. The description nonetheless adds real behavioral context the annotations lack: result cap of 10, best-first ordering, and the shape of each match (type, title, subtitle, url). It says nothing about auth requirements or rate limits, but for a read-only search that is minor.

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, then examples, then coverage scope, then the result contract, then routing rules – a sensible order with no filler. It is on the verbose side for a two-parameter tool, with three inline example queries that are helpful but not strictly necessary.

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 describing the return payload and ordering. For a simple two-parameter, read-only search with full schema coverage, nothing an agent needs in order to select or invoke it 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 3 is the baseline, but the description goes further: it explains that `type` restricts to one kind and effectively restates the enum in human terms, and it supplies example query strings that map onto the schema's own examples. This adds useful framing beyond the raw field docs.

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 ('Look up anything pinball on Kineticist') and enumerates the entity types it covers: games, articles, locations, manufacturers, people, mods, Hype Index entries, creators. It explicitly separates itself from siblings get_game_details and get, so an agent can pick it without opening any schema.

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

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

Gives concrete invocation examples, an explicit narrowing rule ('Pass `type` to look in one kind only'), and a routing rule: use get_game_details for game details, pass any other result's url to `get`. When-to-use and which-alternative are both spelled out.

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, non-destructive profile, and the description adds real value on top: the returned fields, the instruction to link each game's kineticist.com page when citing, and the caveat that newest_edition_year is not the year production ended. It omits pagination behavior, which the limit parameter partially implies.

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 and examples before the field semantics, and every sentence carries information. It is somewhat dense and the parameter caveats at the end run together, but there is little waste.

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 carries the burden of describing returns (names, slugs, manufacturers, fun scores, edition counts, page URLs) and adds the citation instruction and field-semantics caveat. An agent has everything needed to call and interpret 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by clarifying that in_production means 'machines Kineticist lists as currently made' rather than an objective production fact. It also explains the newest_edition_year field semantics, which sharpens interpretation of the year filters.

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 concrete verb+resource ('Find pinball machines') and backs it with three realistic example queries plus an explicit statement that it searches and filters the Kineticist pinball database. The multi-result, filter-oriented scope is clearly distinguishable from detail-fetch siblings like get_game_details.

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 example queries give clear context for when this tool applies ('what Stern machines are in production right now?', 'pinball games from 1992'), and the in_production filter is tied to a concrete use case. It stops short of naming an alternative tool or stating exclusions, so it is context-rich 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.

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

Beyond the read-only/idempotent annotations, the description explains field semantics such as `members_section`, `games`, `from_creators`, `change_this_week`, `up`, and a data-freshness caveat about recently announced editions not yet in the database. That is substantial behavioral context that an agent cannot infer from annotations alone.

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

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

The description is front-loaded with the purpose and example queries, and it has enough detail for a rich aggregate tool. However, it is a single dense paragraph with nested parentheticals, which makes it slightly harder to scan than a cleaner structured layout would be.

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 lack of an output schema and the aggregated nature of the tool, the description does a thorough job of explaining the returned sections, field meanings, and a subtle data-freshness caveat. Combined with the annotations and fully described parameters, an agent has everything needed to invoke 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 100% and both parameters are already documented in the input schema. The description implies the default week window but does not add syntax, limits or guidance for `days` or `creators` beyond what the schema provides, so the 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?

The description opens with a specific purpose and concrete example queries, then enumerates exactly what the tool returns: Kineticist news articles, creator videos/podcasts/posts, and the Hype Index. It also distinguishes itself from get_game_details by explaining that game details should be fetched separately.

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 example queries and the 'covers the week in pinball' framing make the intended use clear, and it explicitly routes agents to get_game_details for a game's editions, prices and design team. It lacks an explicit 'do not use this for X' exclusion versus siblings like search, so it falls short of 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 cover the safety profile, and the description adds substantial operational context beyond them: a hard cap of 10 results, nearest-first ordering, the returned fields (city, distance in miles, machine count, venue kind, url), the meaning of `searched` (city centre vs venue-placed smaller cities) and `note` (nearest anywhere vs nearby), plus a data-freshness caveat that machine lists from Pinball Map can lag.

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?

Dense but front-loaded: purpose and example queries come first, then input formats, then return shape and caveats. Every sentence carries distinct information, with 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?

With no output schema and no nested objects, the description carries the return-value burden itself and does so fully: count, ordering, fields, url usage guidance, the semantics of `searched` and `note`, and a staleness caveat. An agent has everything needed to call this 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 interaction semantics the schema does not: `country` matters only for postal codes outside the US, and `game` accepts either a display name or a slug. That clarifies how the parameters combine rather than merely restating them.

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: finds pinball venues near a place, optionally filtered to a machine. The opening example queries and the 'pinball bars in Portland' phrasing make it instantly distinguishable from siblings like search, search_pinball_games and get_pinball_stats.

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 routing examples for natural-language intents and states when to pass `game` (name or slug) and what `place` accepts (postal code vs city), including the country-code requirement for non-US postal codes. It does not explicitly name a sibling as the alternative for overlapping lookup needs, so it stops short of a 5.

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