Glitchless

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real behavior — default ordering (newest first), the fact that id mode attaches preceding game events and frame-rate data, and that screenshot: true returns an image. It does not say whether the list is capped or paginated, which is the main remaining 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 what the tool is, then pivots to the two modes and the cross-references with no filler sentences. The dense semicolon-chained phrasing is slightly run-on but every clause carries 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?

With 7 optional parameters, no output schema, and light annotations, the description carries its weight by describing the returned fields and the per-id context. It stops short of stating result limits or how hours interacts with the newest-first ordering, which an agent would want for a 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 coverage is 100%, so a 3 is the floor; the description earns above that by explaining that supplying id changes the response shape entirely (single report plus context) and that screenshot only matters with id ('what the player saw'). The level and hours semantics are already fully covered in the schema, so no further credit there.

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 ('bug reports players sent from inside the game') and enumerates the payload it carries (text, level, position, device, version, session). It also splits behavior by mode (no id vs. with id), so an agent understands what it gets before opening the schema. Sibling references to glitchless_session and glitchless_triage make the boundary explicit.

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?

'Without an id: the window's reports, newest first, optionally on one level' and 'With an id: one report with the game events just before it' give clear mode-selection conditions. Siblings are named as related sources rather than as explicit substitutes ('use X instead when...'), so there is routing signal but no stated exclusions.

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 establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context about release-order comparison, default newest-vs-previous behavior, branch/build/session-property modes, and daily aggregation beyond 31 days, though it does not describe the response shape in detail.

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

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

The purpose is front-loaded, but the description is long and dense, with several convoluted sentences and parenthetical clauses. The complexity justifies some length, yet the structure could be clearer and more scannable.

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 nine parameters, nested props, and no output schema, the description covers the core comparison behavior and modes well. It does not fully explain the return format or response organization, but it lists the built-in measures and aggregation behavior sufficiently for an agent 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 100%, so the schema already documents all nine parameters. The description adds some meaning around by-mode comparisons and defaults for a and b, but most parameter semantics remain schema-driven rather than elaborated in the 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 states a specific verb and resource: compare game versions side by side. It enumerates the compared measures and explicitly references related tools such as glitchless_dashboard and glitchless_events, making it distinguishable from sibling analytics 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?

It gives a clear intended use case: confirming a fix or design change after shipping a new version. It also explains comparison modes and defaults for versions, Steam branches/builds, and session properties, though it does not explicitly state when not to use it or name a direct alternative comparison 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 declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real behavioral context: `spec` is editable and round-trips to glitchless_set_dashboard, money panels answer `currency`, and `mismatch` amounts sent in another currency are excluded. Auth needs and pagination are not covered, keeping it from a 5.

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

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

It is front-loaded with purpose and most clauses carry distinct information about the response, but the whole description is one dense run-on paragraph chained with semicolons. The trailing parenthetical about where people upload logos in the UI ('Edit pages → Look') is peripheral and could be cut.

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 nine optional params, a nested `props` object, no output schema, and 100% schema coverage, the description's main burden is conveying the response shape, which it partly does (source, spec, brand, currency, mismatch). It stops short of a coherent return-value overview and mixes input and output fields, leaving an agent with some ambiguity about what exactly is returned.

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 itself richly documents all nine parameters, so the baseline is 3. The description adds little beyond that—it restates `page` and mentions a `where` concept that is not an actual input parameter (property filtering is done via the schema's `props`), which is mildly confusing.

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 names the resource ('The game's dashboard') and enumerates what it returns: pages in order, boards vs built-in views, and one board's panels with numbers, which lets an agent distinguish it from single-metric siblings like glitchless_performance. The verb is implicit ('fetch/read') rather than stated, and the long list of built-in view names slightly blurs the core purpose.

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 some routing: '`page` picks the board (default: the first)' and `spec` is 'what to edit and send back to glitchless_set_dashboard', implying read-before-edit usage. But it never says when to use this over glitchless_overview or the dedicated view tools, nor any when-not conditions.

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

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

Annotations already carry readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real content the annotations cannot: the shape and granularity of results (clustered positions, per-spot death share, top cause, rage quits) and the scope of level-level context returned. It does not mention look-back defaults or data-retention effects, which is the main remaining 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?

Two sentences, front-loaded with the result content, then the use case. The parenthetical enumeration is dense but every element names an actual returned field rather than padding.

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 adequately by listing the cluster fields and level stats. For a nine-parameter read tool with full schema coverage, the missing piece is mostly the retention/look-back framing, which the hours param documents instead.

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

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

Schema description coverage is 100%, so the schema already explains level, hours, env, props, session_type and the rest with examples. The description only implies that a level must be supplied and does not add syntax or behavioral detail about the nine filters. Baseline 3 applies when the schema does the heavy lifting.

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 subject and content: 'clustered death positions in world coordinates' with named fields (x range, share of deaths, top cause, rage quits) plus level bounds and completion stats. That is clearly distinguishable from sibling analytics tools like glitchless_overview or glitchless_session, though it never names a sibling 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?

'Use it to find difficulty spikes, then look up the level data around those coordinates' gives a use case and a follow-up workflow, but names no alternative tool and states no exclusions. The agent gets implied usage rather than an explicit when/when-not rule.

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

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

With annotations already declaring a safe read-only, idempotent operation, the description adds substantial context: counted events are summed on-device per window so they have no spread, identifier_like flags properties with more than 200 values a day, past 744 hours answers are by day, and min defaults to 30 for rates and 10 for averages. It also explains session_type defaults for findings. It stops short of discussing rate limits, auth, or error behavior, which keeps it from a 5.

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

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

The content is dense and mostly relevant, but it is delivered as one long, heavily parenthetical paragraph rather than being structured for scanning. For a 15-parameter tool some length is warranted, yet the run-on structure and the confusing `properties` clause reduce clarity.

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, multi-mode analytics tool with no output schema, the description covers the important output concepts (counts, sessions, players, breakdowns, currency sums, percentiles, hours) and key caveats (device-summed counted events, day granularity beyond 744 hours, row-size thresholds). It does not describe the response shape or the undocumented `properties` mode, leaving minor gaps.

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 per-parameter meaning is already documented, but the description adds real value by explaining mode combinations: name plus rate or avg measures an event, adding by gives per-value rates with 95% intervals, and name plus of produces a distribution with optional split. The one flaw is the reference to a `properties` mode that has no corresponding input parameter, which introduces ambiguity.

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 (the game's custom events from track() and count()) and enumerates the metrics returned: counts, sessions/players, attribute breakdowns, sums, percentiles, and hours. It is clear what the tool does, but it never explicitly differentiates itself from siblings like glitchless_player_funnel, which overlaps on funnel analysis.

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 explains how to trigger each mode (funnel, rate, avg, of, by) and mentions that every read tool filters via props, but it gives no explicit guidance on when to choose this tool over glitchless_overview, glitchless_revenue, or glitchless_player_funnel. Usage is implied by the capability list rather than by selection criteria or exclusions.

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 a safe, read-only, idempotent operation, so safety needs no restatement. The description adds genuinely non-obvious behavior: the list is ranked by sessions affected, the detail view includes breadcrumbs of preceding game events, and source-map uploads change whether locations are original or minified (with `frames` and `minified` fields). It never says how many issues the list returns or whether it is capped.

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 two-mode contract is front-loaded before the return-content detail, and every clause carries information. The final sentence is long and packs source-map behavior, `frames`, and `minified` together, which makes it denser than ideal but not wasteful.

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-shape burden alone, and it does describe both response forms plus the source-map variation. Gaps are minor: list size, ordering ties, and error/empty behavior are unaddressed for a 9-parameter 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. The description still adds meaning the schema cannot: `fingerprint` is a mode switch, not just a filter, and the source-map note explains how the `location`/`stack` output differs. The remaining eight parameters 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 resource (error issues for a game) and a specific dual behavior: a ranked list without a fingerprint, the full issue with a fingerprint. The mode split is stated up front, so an agent can distinguish this from glitchless_triage or glitchless_bug_reports without reading the schema.

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

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

Explicitly tells the agent which mode applies based on whether a fingerprint is supplied, and points at glitchless_triage as the way to obtain one. It does not set out exclusions against siblings such as glitchless_bug_reports, so it stops short of full when/when-not 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?

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description usefully adds what data is exposed (client tokens) and the 'last seen' freshness signal, but says nothing about pagination, limits, or authorization expectations, so it only modestly exceeds the annotation bar.

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?

A single front-loaded sentence that splits the behavior by key scope and enumerates return contents. No filler, no repetition of the title.

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

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

For a one-optional-parameter read tool with no output schema and full annotation coverage, the description is nearly complete: it explains both invocation modes and what comes back. It falls slightly short of full marks because pagination/limits and the workspace-vs-game key source are left implicit.

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 schema already explains that the game parameter is ignored when using a game key and is retained by later calls. The description repeats that scoping semantics without adding format/syntax detail, so 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 clear verb+resource (list games) and then enumerates exactly what the listing contains in each of the two key scopes (workspace key -> games with id, name, client token, services; game key -> services, versions, environments, last-seen). It's specific about the return contents rather than tautological. It doesn't differentiate from siblings like glitchless_overview, which is the only gap.

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 two-mode framing ('with a workspace key...' vs 'with a key for one game...') implicitly tells the agent how to invoke it for a desired result, and the schema notes later calls keep the game. But there's no explicit when-to-use/when-not guidance or naming of alternatives such as glitchless_overview for a higher-level view.

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 annotations, it describes what each mode returns: recent-first or sorted match lists with level, players, outcomes, disconnects, ping and lag definition; and per-slot match detail with a verdict distinguishing whole-lobby lag from one-player lag. This adds substantial behavioral context without contradicting the read-only 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 front-loaded and organized around the with-id / without-id split. It is dense and parenthetical in places, but the length is largely justified by the tool's two modes and rich output detail.

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 a 12-parameter tool with no output schema, the description is complete enough for an agent to understand both modes, the sort and slots behavior, and the shape of returned match data. Remaining parameter details are well covered by 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?

Schema coverage is 100%, so baseline is 3, but the description adds meaningful semantics for id, sort, slots, and the hours window beyond what the schema states. It does not explain all 12 parameters, but the schema already documents them thoroughly.

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

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

The description clearly identifies the resource as multiplayer match data and distinguishes its two modes: listing a window of matches without an id, and inspecting one match slot-by-slot with an id. It does not explicitly differentiate itself from sibling tools such as glitchless_session or glitchless_network, 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 gives clear operational guidance for the main branching parameter: without id lists matches and supports sort; with id returns one match slot-by-slot, with slots: true for all players. It does not mention alternatives or when another sibling tool would be more appropriate.

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 (read-only, idempotent, non-destructive, closed-world), so the description's contribution is meaning: it defines lag as share of connected play over 150 ms, clarifies disconnects are 'never counted as fails', and explains where the data originates (engine netcode hooks — NGO, Mirror, ENet, Unreal net driver, WebRTC — or netSample calls). That tells the agent how to interpret an empty or partial result. It does not describe the response shape or pagination, which is the remaining 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-loaded correctly: metrics first, then breakdown dimensions, then the worst-matches pointer, then findings, then data provenance. It is information-dense rather than padded, though the long run-on sentences and heavy parenthetical nesting make it slower to scan than it needs to 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?

For a 9-parameter analytics tool with no output schema, the description covers what the metrics mean, what dimensions arrive, what findings look like, and where the data comes from — enough to call it correctly and interpret the result. The absence of any indication of the response structure (sections, per-finding shape) is the main thing left to the schema and guesswork.

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

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

Schema coverage is 100%, so the schema already carries parameter meaning and the baseline is 3. The description adds only a little, chiefly the default behavior of `by` (region when the game sets a region property, otherwise any property given as `by`) and the standard breakdown dimensions. It adds nothing about env, version, session_type, steam_branch, or hours beyond what the schema documents.

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 precise resource (multiplayer network quality) and enumerates its constituents — ping median/slowest 5%, lag share over 150 ms RTT, packet loss, jitter, disconnects per hour by reason — plus the breakdowns and findings it produces. It distinguishes itself from siblings by pointing at glitchless_match for an individual worst match and by framing its own findings as lobby-wide vs. connection-type/region-wide, which separates it from glitchless_servers and glitchless_triage.

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 routes the agent outward for adjacent needs: 'glitchless_match opens one' for a worst match, glitchless_events for property values, glitchless_list_games for game ids. However, it never states explicitly when to pick this tool over glitchless_performance or glitchless_servers — the exclusions are implied by topic rather than declared.

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, destructiveHint=false, and closed-world, so the safety profile is covered. The description adds the scope of what is returned (the metric set) but says nothing about defaults (24h window), aggregation behavior, or truncation limits, which matter for a summary endpoint with no output schema.

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?

A single front-loaded sentence with no filler, and the KPI list is genuinely informative. It is a bare noun phrase with no verb, which slightly weakens the framing but wastes no words.

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?

Lacking an output schema, the description usefully enumerates the returned metrics, which is the main thing an agent needs. However, for an 8-parameter aggregation endpoint it omits defaults, the effect of the filters on the answer, and routing versus sibling overview tools, leaving real gaps.

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

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

Schema description coverage is 100% and the parameter descriptions are unusually detailed (env, props, hours/day rollover, session_type defaults). The description contributes nothing about parameters, so the baseline 3 applies — it neither helps nor hurts.

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 enumerates the exact contents (sessions, players, crash-free/error-free sessions, frame-time percentiles, hitches, rage quits, top errors, level funnel) for a specific resource: a game's headline KPIs. It never says how this differs from close siblings like glitchless_dashboard, glitchless_performance, or glitchless_player_funnel, so an agent must guess which overview to call.

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?

There is no statement of when to use this tool, when not to, or which alternative to prefer. With 17 siblings including a dashboard, a performance tool, and a funnel tool that overlap heavily with the listed metrics, this absence is costly.

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 bar is lower; the description still adds substantive behavior by enumerating what hitch causes are surfaced, that memory growth is measured per level load, that the slowest recent hitches carry script attribution, and that multiplayer adds a `network` block. It does not discuss result size or ordering of the returned lists.

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

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

The purpose is front-loaded in the first clause, but the body is a single sprawling comma-chained enumeration that is hard to scan. Most items are informative, yet the list is long enough that it should be broken up or trimmed of lower-value entries.

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 10 optional parameters, nested props object and no output schema, the description appropriately documents the returned structure in detail, which the structured fields cannot supply. Remaining gaps (volume of output, how per-level and per-zone sections are ordered) are minor for an analysis tool.

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

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

Schema description coverage is 100%, so the schema already documents all 10 parameters including hours, props, by_prop and session_type. The description reinforces by_prop's effect on output rather than adding new syntax or constraints, which is the expected baseline when the schema carries the parameter burden.

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+resource ("Frame-time breakdown for a game") and then enumerates the concrete content: percentiles vs budget, per-level p50/p95/p99, hitch causes, memory growth, slowest hitches. It also differentiates itself from the sibling glitchless_network by naming it as the deeper network source.

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 explains the operational mode switch clearly: "With by_prop, frame time, hitches and crash-free sessions per value of a session property", and routes network-focused questions to glitchless_network. It does not state when to prefer glitchless_overview or glitchless_session instead, so the guidance is clear but not exhaustive.

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

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

It adds critical behavioral context not in the schema or annotations, such as how 'runs' are counted (once per level reached), how disconnect events are categorized (not counted as fails), and the data limitations regarding retention privacy ('anonymous' vs. 'install' SDK status).

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 extremely dense and spans multiple paragraphs covering numerous metrics and logic branches. While every sentence is functional, the overall structure is overwhelming and lacks the front-loaded, quick-scan nature expected of an ideal tool definition.

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 complexity of calculating funnels, retention (D1, D7, D30), and session metrics, the definition is maximally complete. It covers the data returned, the grouping mechanism, the filtering logic, and operational caveats.

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?

Although the schema is 100% covered, the description adds crucial semantic value by explaining the operational logic of parameters. For example, it clarifies that the 'by' parameter can accept game attributes ('tier'), session properties ('$class'), or technical splits ('$platform').

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 functions as a comprehensive document detailing player experience metrics across levels. It is clearly distinct from other sibling tools like glitchless_overview or glitchless_events because it specifically aggregates flow, failure rates, and retention.

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?

While the description is massive, it acts as an exhaustive guide, explicitly detailing how specific variables (`by`, `count`, `by_prop`) alter the resulting view, which serves as a usage guide for complex queries.

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 annotations, the description discloses substantial behavior: RevenueCat production-only counting, Stripe test-mode caveats, how version scoping interacts with game-wide metrics, and how Glitchless joins purchases to its own session/player data. This is unusually rich operational context.

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

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

The purpose is front-loaded and the content is relevant, but the description is a very dense single paragraph with long semicolon-chained sentences. It could be structured more clearly without losing the important distinctions.

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 revenue tool with no output schema, the description thoroughly explains what data is returned, how each source is treated, and key caveats. An agent has enough context to use it correctly for the intended money questions.

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 parameter definitions already do most of the work. The description adds semantics for `source` and some caveats around `version`, but it does not add much meaning for `hours`, `game`, or `service` beyond what the schema states.

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, revenue, and precisely scopes it to RevenueCat and/or Stripe data for a connected game. It clearly distinguishes what the tool returns from `glitchless_events` and makes the source-specific coverage explicit.

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

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

It gives a clear intended use case for money questions and explicitly routes item/level/player purchase analysis to `glitchless_events`. It lacks explicit exclusions against other analytical siblings like `glitchless_overview`, but the guidance is strong.

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 cover the safe-read profile (readOnly, idempotent, non-destructive, closed-world). The description contributes behavior the annotations cannot: server sessions live under a separate companion service "<game>.server", so every other tool must be told that service, and findings default to production player sessions unless env or session_type is supplied. No return shape or cost hints, though.

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 resource framing is front-loaded, which is good, but the first sentence is an unpunctuated run-on that heaps eight metric groups into one clause chain, making it hard to scan. The companion-service paragraph earns its place; the metric enumeration 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?

For an aggregate, no-output-schema tool with 8 optional filters, the description covers what is reported and how server data is partitioned. It does not describe the shape of the returned sections or how the tick-budget breakdowns are grouped, but the annotations carry the safety profile and the schema carries filtering.

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 would be 3, but the description adds real meaning for the service parameter — that server sessions are addressed as "<game>.server" rather than the plain game service — which the schema's generic "Game service name" text does not convey. Other params (env, hours, props, version, steam_branch) 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?

The description pins down a specific resource with an explicit scope restriction — dedicated servers running the Glitchless SDK in server mode, naming the Node/Unity/Godot/Unreal entry points — then enumerates exactly what it reports (live servers and connected players, tick time vs budget, CPU/memory/networked objects, crashes, leak suspects, latest runs, findings). The companion-service note separates it cleanly from session-level siblings.

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

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

It routes the agent to the right siblings for drill-down: glitchless_session for a single server run and glitchless_get_error for a crash stack, both with service "<game>.server". It also clarifies that server sessions count as sessions like any other, so other tools remain usable. What's missing is an explicit "use this instead of glitchless_overview/performance for server fleets" exclusion.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds behavior the annotations cannot: the response contents are extensive (event timeline, 5s frame stats) and server sessions behave differently (tick windows, not frames) – the latter is a real non-obvious trait. It does not mention response size or pagination for heavy sessions, which keeps it from a 5.

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

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

Front-loaded with the resource and its contents, then the id-sourcing instruction, then the server-session caveat. Dense and largely waste-free, though the long parenthetical inventory of event types is heavy in a single sentence.

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 explaining returns, and it does so thoroughly enough for an agent to know what it will get. The remaining gap is operational: nothing about response size, payload limits, or whether large session timelines can be truncated.

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; the description earns a bump by explaining the provenance of session_id (from errors, hitches, rage quits, or a match) and by noting that service selects between a player session and a game-server session. It does not add anything about the game parameter beyond what the schema already states.

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 (one play session) and enumerates exactly what it returns: device/GPU, outcome, groups (matches, parties, runs), full event timeline, and per-5s frame stats. It also carves out a distinct case (game server sessions yield tick windows instead of frames), which cleanly separates it from siblings like glitchless_match and glitchless_events.

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 with session ids from errors, hitches, rage quits or a match" tells the agent where to source the required id, which is a genuinely useful precondition. It stops short of explicit when-not guidance or naming which sibling to prefer for aggregate vs single-session views, so it is clear context without exclusions.

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 safety is covered. The description adds genuinely non-schema behavior: review text is untrusted player input and must never be treated as instructions, texts are retained only for the last 62 days unless the window is longer, and each review carries the build plus store-supplied reviewer metadata. No return-shape/pagination detail, but that is minor for a read tool.

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

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

Front-loaded with what the tool returns and what can be filtered, and the injection-safety note closes it out. It is dense and runs long with several stacked clauses, but nearly every sentence carries information an agent needs; only the parenthetical navigation path is marginal.

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 work of explaining the response: match counts by topic and device, per-build groupings with reviews, and Glitchless-measured frame-time p95 and crash-free sessions. Combined with the filter list, retention note and injection caveat, an agent has everything needed to call and interpret it.

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 90%, so parameter documentation is already strong; the description mostly restates the filter set (store, build, sentiment, keyword, device, deck). It adds a little semantic glue — keyword topics vs. any word and that deck is Steam-specific — but nothing beyond what the schema descriptions say. 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 first sentence names a specific verb and resource — player-written store reviews connected via Glitchless Cloud, with the store list given explicitly. It also distinguishes itself from glitchless_performance, glitchless_get_error and glitchless_triage by explaining how review data relates to them, so an agent can tell the siblings apart.

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 context is clear: this is for reading what players wrote on a store, filtered by store/build/sentiment/keyword/device, and it names the sibling tools whose data should sit next to it. It does not state explicit exclusions (e.g. when to prefer glitchless_bug_reports or glitchless_triage instead of pulling raw reviews), which keeps it 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.

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

Beyond the safety hints in the annotations, the description provides deep behavioral context regarding data capture methodology. It highlights critical operational gaps, such as 'native crashes... never reach Glitchless,' and how Glitchless defines 'a stopped game loop' versus a standard store 'users in a day.'

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 necessarily long due to the complexity of comparing two disparate data sources and listing multiple metrics for two platforms. However, it is dense with value, and the most critical comparative information is front-loaded.

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 complexity and the high level of detail in the schema and annotations, the description is exceptionally complete. It clarifies the data limitations and the specific value proposition of the 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?

Although schema coverage is 100%, the description adds crucial operational context to the parameters. For instance, it notes that 'Google Play reports a day or two late' regarding slow rendering, adding vital temporal context to the `hours` parameter definition.

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 excels at stating its purpose by defining the relationship between store-reported vitals and Glitchless metrics. It explicitly differentiates its scope by listing specific metrics for Google Play (e.g., slow rendering, ANR) versus the App Store (e.g., hang rate, p90/p50).

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

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

It provides explicit usage guidance by telling the agent exactly *how* to apply the data: 'Use it to tell whether a problem players report is one Glitchless can see, and which devices to test on.' This defines the primary decision-making context for the 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 declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine output-shape context beyond annotations: findings are ranked by severity and player impact, each carries evidence plus a suggested fix, and a session property is named when most of a problem concentrates in one value. It says nothing about scan cost, coverage gaps, or how many findings are returned, which for a synthesis tool across 8 filters leaves real ambiguity.

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 first sentence runs well over 100 words, welding a dozen finding categories together with em-dashes and nested parentheticals; an agent must parse a wall of clauses to extract the core behaviour. The one genuinely differentiating line ('Start here when asked...') is buried at the end. It is information-dense but poorly front-loaded and unstructured.

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 return semantics, and it does: ranked, severity- and impact-ordered, evidence plus suggested fix, per-finding session-property attribution. It also enumerates the anomaly families sufficiently that an agent can predict whether its question is answerable. Minor gap: nothing on result volume or how to disambiguate when a finding points to another sibling.

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% (env, game, hours, props, service, version, session_type, steam_branch all documented inline), so the baseline is 3 and the description does not need to restate them. Beyond the schema, the description only reinforces the props behaviour ('naming a session property when most of a problem falls on one value'), without adding formats, defaults, or interactions between filters. Baseline 3 is correct.

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+resource framing ('Ranked findings for a game') and enumerates the anomaly classes it detects, so an agent knows it is an aggregate diagnostic, not a single-metric reader. It does not cleanly separate itself from lookalike siblings (glitchless_performance, glitchless_network, glitchless_servers) whose domains it partly re-lists. The closing 'Start here when asked what's wrong with my game' sharpens the role, but only after a very long enumeration.

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

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

Explicitly positions itself as the entry point ('Start here when asked...'), which is real when-to-use guidance and implies the siblings are drill-downs. It stops short of naming any sibling or stating when to skip triage in favor of glitchless_network or glitchless_get_error for a specific finding. No prerequisites or cost/latency guidance is given.

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