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

With no annotations provided, the description carries the full behavioral disclosure burden. It reveals that the tool is composite, returns specific fields, and explains that friction_diff is the higher-signal field while deltas is preserved for back-compat. It could mention error cases, authentication needs, or env behavior, but the core behavior is transparent.

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 tightly written sentences, front-loaded with 'Composite tool' and the core purpose. Every sentence adds useful information: what is fetched, when to use it, and what the return shape means.

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 composite tool with no output schema and no annotations, the description adequately covers purpose, trigger questions, return fields, and field priorities. The main gaps are undocumented env semantics and lack of failure-mode guidance, but an agent can still call the tool correctly with the required parameters.

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 75%, with game, version_a, and version_b already described. The description reinforces the baseline/comparison relationship and maps versions to build_a/build_b in the output, but it does not add meaningful detail beyond the schema and leaves env undocumented.

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 composed operation: fetch two builds' rollups, per-build AI summaries, and a classified friction diff between them. It also names the classification categories, which clearly distinguishes it from single-build tools like get_build_summary and list_builds.

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 a concrete use case: 'what changed between 0.4.9 and 0.5.0?' style questions. It does not explicitly contrast with sibling diff-like tools such as get_experiment_comparison, but the intended usage is clear enough for an agent to select it appropriately.

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

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

With no annotations provided, the description carries the full burden — and it delivers. It discloses role-based auth failures (viewers get 403), the specific 409 error code and normalized-weights response, the re-submission protocol, lifecycle state (players NOT assigned yet in draft), and the 201 return shape. This is exemplary behavioral disclosure for a mutation 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?

Three dense sentences that earn their place: purpose first, then auth requirements, then validation/error flow, then lifecycle handoff, then return format. No filler or repetition of schema content. The length is fully justified by the complexity of the normalization workflow it explains.

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 tool with 8 parameters, no annotations, and no output schema, the description covers every operational concern: who may call it, what validation can reject it and how to recover, what state the resource is created in, how to transition it, and the response format. The remaining details (config locking, targetBuilds/audienceId exclusivity) are already documented in the schema, so nothing critical 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% with already-rich parameter descriptions: variants constraints (2–8, config primitives only, max 20 keys), allocation normalization semantics, acknowledgeNormalization's role after a 409, and targetBuilds/audienceId mutual exclusivity. The description reinforces the normalization flow but adds little parameter meaning beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb (Create), resource (DRAFT A/B experiment), and scope (for a game). The DRAFT qualifier is the key differentiator — it clearly tells the agent this tool does not activate the experiment, distinguishing it from sibling start_experiment without needing to open either schema. Precision here is outstanding.

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 routes to the sibling: 'call start_experiment to go live.' It also prescribes the exact error-handling workflow (409 allocations_need_normalization → re-submit with acknowledgeNormalization: true). The agent knows precisely when to use this tool and what to do next, with zero inference required.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the auth failure mode (403 for members/viewers), defaults for active and allowRepeatSubmissions, the SDK surfacing behavior, and the return shape `{ form }`. This is unusually transparent.

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

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

Four dense sentences each add essential information without filler. Key constraints are front-loaded and the structure flows naturally from purpose to requirements to defaults to return value.

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

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

The definition is complete for a create tool: it covers required fields, optional fields, defaults, auth expectations, and return value. Even without an output schema, the `{ form }` return note is sufficient.

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 adds some useful nuance (unique field ids key answers, field kinds, guidance on repeat submissions), but most parameter meaning is already documented 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?

The description explicitly names the action ('Create'), the resource ('Player Feedback form'), and the surrounding context (SDK forms via `feedback.open`/`feedback.submit`). This clearly distinguishes it from siblings like list_game_feedback_forms and other create 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 provides strong practical guidance: role requirements, field count/schema constraints, defaults, and a specific instruction about when allowRepeatSubmissions should be true. It does not explicitly name alternatives or exclusions, so it stops 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?

With no annotations provided, the description carries the full burden and does well: it discloses the auth failure mode (viewers get 403), the fact that results are computed from existing telemetry, and the success response format (201 { funnel }). It does not mention idempotency or validation errors, but the key side effects and expectations are stated.

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

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

Four dense sentences with the core action first, then role, then configuration semantics, then follow-up/return. Every clause contributes operational knowledge, and there is no filler or repetition of schema boilerplate.

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 8-parameter creation tool with no annotations and no output schema, the description covers prerequisites, key mode semantics, return status, and the follow-up fetch tool. It omits details on optional parameters like audienceId and conversionWindowMs, but those are fully documented in the schema and are not behaviorally critical.

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, and the description adds real value above the schema by explaining the meaning of mode ('ordered' = sequence, 'any-order' = set membership) and scopeMode ('events' vs 'players'). It also reinforces the 2–20 step range and property-filter capability without re-documenting every field.

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 ('Create') and resource ('conversion funnel for a game'), and immediately distinguishes itself from read/fetch siblings like list_game_funnels and get_funnel_result. The scope is unambiguous.

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

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

It gives clear usage prerequisites: requires member/admin/owner (viewers get 403) and existing telemetry with no SDK change needed. It also routes the follow-up action to get_funnel_result, though it does not explicitly contrast against alternative tools or state when not to use it.

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?

Discloses authorization behavior (403 for non-admin roles), success response code and payload (201 `{ game, ingestKey }`), the unusual show-once/write-only nature of ingestKey and its later visibility on the Connections page, plus automatic slug derivation. With no annotations present, this rich detail carries the full burden.

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 focused sentences front-load the action, then cover role, response, and key detail. No filler or 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?

Covers role requirements, return status and payload shape, special handling of ingestKey, and slug behavior, which is sufficient without an output schema. Minor gaps remain (shape of the `game` object, duplicate-name behavior), but they do not prevent correct invocation.

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. The only parameter-related note in the description (slug derived from name) repeats the schema's own name description, adding no new meaning beyond structured fields.

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 ('Create a new game in the active workspace') and is clearly differentiated from siblings like get_game, update_game, and list_games by the 'new' qualifier and the create action.

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 a clear precondition: ADMIN or OWNER role required, with members/viewers receiving 403. It also signals that this is for creating a new game rather than updating or reading an existing one, though it stops short of explicitly naming alternatives like update_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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does this well: it explains silent filing, instructs the agent to confirm recording without mentioning GitHub/backlog/tickets, notes that suggestions may be returned and should be shared, and clarifies that server-side deduplication removes the need for duplicate checks.

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

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

The description is compact yet information-dense. Each sentence earns its place: purpose, trigger conditions, response behavior, silent-filing requirement, and deduplication note. The critical behavioral warning is called out with 'IMPORTANT' and placed before the end, making it easy to notice.

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

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

For a three-parameter tool with 100% schema coverage and no output schema, the description covers all essential operational context: when to use it, what the response may contain, how to communicate with the user, and what not to say. No critical behavioral gaps remain.

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 parameters are already fully documented. The description reinforces that 'kind' corresponds to capability requests vs. broken behavior, but it does not add meaning beyond what the schema provides. This matches the baseline of 3 for high schema coverage.

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 uses specific verbs and resources: 'Record a feature request or bug report from the user into the Playloop backlog.' It clearly differentiates from sibling read/list tools by focusing on filing/recording rather than querying, and explicitly names the two input kinds (feature, bug).

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

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

The description gives explicit trigger conditions: 'Use when the user asks for a capability Playloop does not have, or reports something broken.' It also tells the agent not to check for duplicates because deduping is server-side. It does not explicitly name alternative tools or state when not to use this tool, so it falls just 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?

With no annotations provided, the description carries the behavioral disclosure burden. It explains the comparison structure, the return fields, and the live/peak aspects, giving the agent a solid sense of what the call will produce. It does not detail edge cases such as empty data or environment behavior, but the core behavior is transparent.

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

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

The description is compact, front-loaded with the core concept, and uses a concise return-shape snippet. Every sentence adds value: what it measures, what question it answers, and what it returns.

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?

Even without an output schema, the description includes the exact return object shape and the semantic meaning of current vs previous. For a read-only analytics tool with fully documented parameters, this is complete enough for an agent to invoke it confidently.

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 game, days, and env. The description reinforces that 'days' controls the window and that the tool compares last N days to prior N days, which adds context, but it does not add substantial meaning beyond the schema.

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

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

The description is specific: it defines get_activity as a windowed volume comparison tool covering players, sessions, peak concurrency, and current online users. It clearly states what it answers ('how many people played this week / are my numbers growing?') and goes beyond the generic title. The mention of trend and online-now differentiates it from likely siblings like get_live_activity.

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

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

The description implies when to use the tool through the question it answers, making the use case clear. It does not explicitly exclude alternatives or name sibling tools, so it stops short of full routing guidance.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses how windows are computed (UTC days), defaults (today), how explicit from_ms/to_ms override presets, and what the return object contains. It does not cover auth, rate limits, or failure modes, but given the absent annotations, the provided behavioral detail is strong.

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 each clause serves a purpose. It front-loads the core purpose, then lists contents, then gives routing guidance, then parameter usage, then return shape. It is a long single sentence but remains readable and efficient for the amount of information conveyed.

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?

This is a complex aggregation tool with no output schema and no annotations, yet the description fully explains what the agent can expect: input options, defaults, overrides, and a detailed return shape key by key. There is no significant gap that would prevent correct invocation.

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 schema already describes all parameters (100% coverage), so the baseline is 3. The description adds value by explaining the intended use of window versus from_ms/to_ms and clarifying that windows are UTC-based, which reinforces and extends the schema's meaning.

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 exactly what the tool does with a specific verb and resource: 'The one-call 'what happened today / yesterday / this week' digest for a game'. It enumerates the exact contents (sessions, playtime, testers, crashes, feedback, insights, top drop reason), clearly distinguishing it from alternatives like 'stitching several 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?

The description gives explicit usage guidance: 'Prefer this over stitching several tools for "what happened <period>?" / "how long did they play <period>?" questions.' This tells an agent when to choose this tool over composing other calls. It does not enumerate specific exclusions, but the context is clear enough.

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

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

With no annotations provided, the description carries the burden, and it adds meaningful behavioral context: it is structured/machine-readable, returns per-cluster counts with distinct-tester semantics, and includes both testersWhoDropped and testersDroppedNoClearCause. It does not explicitly state read-only or side-effect-free behavior, but the 'get' prefix and rollup language imply a safe analytical read.

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 sentences with no wasted words: the core definition is first, sibling differentiation comes second, and a compact return-shape summary closes. Every sentence earns its place and the length is appropriate for the content.

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

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

No output schema exists, so including the return fields is valuable and largely sufficient for a straightforward rollup tool. It could add edge-case behavior such as empty clusters or version-not-found handling, but the required inputs and expected outputs are clear enough for correct invocation.

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 env, game, and version. The description adds no new parameter-level meaning; it only echoes gameId and version in the return shape. This meets the baseline but does not exceed it.

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: a structured 'why players quit' rollup for one build, with per-cluster drop reasons and distinct-tester counts. It clearly distinguishes itself from get_build_summary by contrasting prose versus machine-readable breakdown, so an agent can tell them 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?

It gives clear context: use this for the machine-readable drop-cause breakdown for a build, and it explicitly names get_build_summary as the prose alternative. It does not enumerate broader when-not-to-use cases against other analytic siblings, but the primary alternative distinction 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does explain the return shape, the summarized fields, and the conditional nature of the AI summary ('if present'). However, it does not clarify behavior for missing builds, whether the summary field is null or omitted, or any data freshness/aggregation nuances beyond what the schema 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?

The description is compact and front-loaded: the first sentence states the action and result contents, and the second gives the exact return shape. Every sentence earns its place, with no filler or redundant information.

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

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

For a simple retrieval tool with three well-documented parameters and no output schema, the description does a good job by explaining both what is returned and the shape of the response. It is slightly incomplete regarding edge cases like not-found builds, but the given context is largely sufficient for an agent to call this tool 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 description coverage is 100%, so the schema already documents all three parameters. The description adds value by naming the output shape and rollup contents but does not add additional meaning for input parameters such as the env's default aggregation behavior, which is already covered in the schema. Baseline of 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 uses a specific verb ('Return') with a clear resource ('one build') and enumerates exactly what is included: session count, unique devices, first/last seen, total playtime, and the persisted AI build summary if present. This clearly differentiates it from sibling tools like list_builds or compare_builds by emphasizing it returns a single build's rollup.

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

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

The description clearly implies use when the agent needs a rollup for a single build plus its AI summary, which provides solid contextual guidance. It does not explicitly name alternatives or state when not to use this tool, but the phrase 'for one build' establishes a clear scope versus list and compare tools.

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?

No annotations are present, so the description carries the burden. It discloses aggregation behavior, row-level fields, the optional build filter, and the return envelope { game, groups }. It does not clarify whether resolved crashes are included or specify ordering/limits, but as a read-style query this is mostly sufficient.

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

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

Three purposeful sentences, front-loaded with the grouping behavior, then a user-question framing, sibling contrast, optional scoping, and return shape. No filler or 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?

Given no output schema, the description still lists the key returned fields and the envelope. It misses finer details like whether resolved/unresolved crashes are included and any sorting or limit behavior, so it falls just short of a 5.

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. The description only adds 'optionally scope to one build', which slightly reinforces the build parameter's optionality but does not add substantial meaning beyond the schema.

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

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

States a specific verb+resource: crashes grouped by signature. Lists concrete output fields (occurrence count, affected-session count, first/last seen, affected build versions, latest message/stack) and distinguishes from sibling list_crashes, which is described as the flat unresolved list.

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 contrasts with list_crashes (the flat unresolved list) and frames the question this tool answers: 'what's the most common crash and how many people hit it?'. Also notes the optional build scope, giving clear selection context.

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

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

With no annotations, the description carries the burden and does disclose aggregation scope, the exact return object, top sorting, and the 50-item cap. It does not discuss optional filter defaults or side effects, but the read-only query nature is reasonably clear.

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 tight sentences with the core behavior first and the return shape second. There is no filler or redundant 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 five parameters and no output schema, the description provides a good outline but omits important context: what happens when from/to are omitted, how sessionCount relates to sessions, and which sibling analytics tools should be preferred for non-event aggregations.

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?

Only 3 of 5 parameters have schema descriptions, and the description adds no input-parameter meaning beyond 'for a game.' The env and build parameters remain undocumented in both the schema and 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?

States a specific verb and resource: 'Sum event-name occurrences across sessions for a game.' The return-shape detail also makes it distinguishable from generic sibling analytics tools like get_metric_trend or get_platform_breakdown.

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 clear context is when the agent needs event-name occurrence counts aggregated across sessions for a game. It does not explicitly name alternatives or exclusions, so it stops short of 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?

With no annotations provided, the description carries the full behavioral burden. It discloses the return shape, that the digest is null until first generated, what fields are contained, and that 404 is returned when the experiment doesn't exist or belongs to another user. This is rich, non-obvious behavioral 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 description is front-loaded with the main purpose, then efficiently expands on the comparison and digest structures, and ends with error behavior and the exact return object. Every sentence adds information needed by an agent, especially given there is no output 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?

Even though there is no output schema, the description fully documents the output: top-level keys, per-variant fields, digest fields, null semantics, and error conditions. Nothing critical for correctly invoking or interpreting the tool 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 description coverage is 100% with 'Experiment id.', so the baseline is 3. The description adds meaning by explaining the ownership and existence constraints: 404s occur for non-existent or other-user experiments. This goes beyond the schema's bare parameter label.

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 uses a specific verb ('Return') plus a precise resource: one experiment's latest per-variant raw-stats comparison and the persisted AI cross-variant digest. It clearly differentiates this tool from sibling list/get tools by emphasizing the per-variant comparison and digest nature.

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

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

The description provides clear context: this tool is for retrieving the comparison and digest for a single existing experiment owned by the current user. It doesn't explicitly name alternatives or exclusions, but there is no sibling tool that performs the same function, so the usage context is sufficiently clear.

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

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

With no annotations provided, the description carries the full burden. It transparently discloses the read-only nature ('never triggers AI'), the null case when no themes exist, and the shape of the response. It does not mention error handling or authentication, but for a read-only rollup tool these are minor gaps, so a 4 is appropriate.

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 three efficient sentences. Each sentence earns its place: the first defines output with an example, the second details theme attributes, and the third adds behavioral and null-case context. No filler or 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?

For a simple single-parameter read tool, the description is complete. It explains the return structure, the null behavior, and the non-AI nature, all without an output schema to rely on. The only minor omission is explicit alternatives, but that is already covered under usage_guidelines and does not detract from overall completeness.

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 single parameter 'game' is fully documented in the schema ('Game id, slug, or exact name.'), providing 100% coverage. The description adds no further parameter-level detail, so the baseline of 3 applies.

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

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

The description defines the resource explicitly: recurring themes clustered from players' written feedback, with an illustrative example ('N testers said the tutorial is confusing'). It details what each theme carries and clarifies it reads a stored rollup, clearly distinguishing it from raw feedback or AI-triggering operations.

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 phrase 'Reads the stored rollup only (never triggers AI)' gives clear context about when to use this tool: when the precomputed theme rollup is desired rather than triggering new AI analysis. It does not explicitly name an alternative sibling, so it falls short of a 5, but the context is strong enough for an agent to choose appropriately.

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

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

With no annotations provided, the description carries the full burden, and it does so well. It explicitly says recommendations are directional, not fabricated, does not assert unsupported causes, and degrades to a deterministic ranking when credits are unavailable, adding important failure-mode 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?

Each sentence earns its place: purpose, input signals, output form, honesty guarantees, fallback behavior, and return shape. The key phrase 'what should I fix first?' is front-loaded, and the description is dense without being bloated.

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?

The description is largely complete for a synthesis tool: it explains behavioral nuance, fallback behavior, and the top-level return shape despite no output schema. It leaves a small gap by not explaining the `env` parameter or explicitly routing the agent away from similar sibling tools, but the core invocation context is well covered.

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 schema describes the game parameter's meaning, but the env parameter is only given a regex pattern with no semantic explanation. The description does not directly clarify env either, though the output field `environment` provides a mild hint. With 50% schema coverage and no parameter-focused description, this is adequate but not strong.

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 starts with a specific, memorable purpose: a whole-game 'what should I fix first?' synthesis. It clearly names the cross-source inputs and the single prioritized output, making its job distinct from per-source tools like get_crash_groups or get_feedback_themes.

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

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

The description makes the use context clear by emphasizing that it synthesizes ACROSS sources into one priority list, so an agent can infer when to choose it over narrow per-signal tools. It does not explicitly name an alternative like suggest_fixes or state when not to use it, so it misses the strongest form of guidance.

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

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

With no annotations provided, the description carries the burden and does disclose the operation: it computes and returns a funnel result object rather than mutating anything. It also specifies the returned content ('steps with reach/conversion + the drop step'). It omits caveats like default time windows or error behavior, but the main behavioral contract is clear.

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 key information is front-loaded in the first sentence and the use case is clearly stated. There is minor redundancy between the opening sentence and the final sentence, both describing reach/conversion/drop-step output, but overall it remains compact and readable.

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 6-parameter tool with no output schema, the description says what the result object contains and what question it answers. It does not spell out defaults when optional filters are omitted or explicitly enumerate error cases, but the schema covers parameter formats and required fields.

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 adds value by grouping the optional parameters into conceptual filters ('scope by build, a time window, or an environment') and by explaining that funnel_id comes from list_game_funnels. This bridges the schema fields and the tool's purpose.

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 deliverable: 'COMPUTED result for one funnel, per-step reach + step-to-step conversion + the biggest drop-off.' It explicitly contrasts with sibling list_game_funnels, which 'returns only definitions,' so an agent can distinguish this tool immediately.

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 frames the tool around a concrete question—'where's the drop-off in my funnel?'—and notes that list_game_funnels only provides definitions, which tells the agent when this tool adds value. It does not explicitly rule out get_funnel_trend for time-series comparisons, so it stops short of full 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?

With no annotations, the description carries the full burden and does well: it explains that both current and previous windows are computed, that deltas are percentage-point changes, and that deltas is null when either window has no players. It also enumerates the return object fields, though it does not define 'scope' or address auth/rate limits.

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 core question and then gives precise behavioral details and return shape. It is slightly redundant between the opening question and the later 'did this week's build move the funnel?' phrasing, but every sentence still contributes useful 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?

Given there is no output schema, listing the exact return fields is valuable and makes the tool fairly self-contained. The main gaps are the unexplained 'scope' field and the lack of explicit comparison to sibling get_funnel_result for when a single snapshot is needed rather than a trend.

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 five parameters. The description adds some nuance by clarifying that 'days' defines both the current and prior window length, but it does not meaningfully expand the semantics of env, build, game, or funnel_id beyond what the schema already says.

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 tool as a funnel-change detector: it compares the last N days with the prior equal window and returns per-step deltas and completion change. This distinguishes it from siblings like get_funnel_result, which likely returns a single snapshot, by emphasizing the trend/comparison 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?

The description gives a concrete use case ('did this week's build move the funnel?') and implies this is for change analysis over time. However, it does not explicitly state when to prefer this over get_funnel_result or when not to use it, so it stops short of full alternative 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?

With no annotations, the description carries the full burden and does well: it discloses the exact return shape and the fact that missing or another user's games return 404. This adds behavioral context beyond the tool name, though it does not mention authentication or other error cases.

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, each earning its place: the core behavior, the return shape, and the key failure mode. The most identifying detail is front-loaded and there is no filler.

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

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

For a simple single-parameter retrieval tool with no output schema, the description is complete: it states what is returned, the exact response structure, and the 404 condition. No critical information for calling it correctly 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 description coverage is 100%, and the schema already explains that game_id accepts an id, slug, or exact display name and recommends slugs for agents. The description only echoes 'by id OR slug' and adds no new parameter semantics.

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 ('Return'), a specific resource ('one game'), and a distinguishing scope ('by id OR slug') plus the bundled counts. This clearly separates it from list_games and get_game_summary without needing to open 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?

The description implies usage: call this when you need a single game with counts, and the schema says game_id can be an id, slug, or display name. However, it does not explicitly say when to prefer this over siblings like get_game_summary or list_games, nor does it state any 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?

With no annotations provided, the description carries the full burden of disclosing behavior. It explicitly states 'Reads the stored summary only,' clarifies null behavior when none has been generated, and documents the return shape. This is strong behavioral disclosure for a simple 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?

The description is compact and front-loaded, with the core action stated in the first sentence. The clarifying constraints and return shape follow efficiently without fluff.

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 simple read tool with no output schema, the description covers the essential behavior (read-only, null when absent, return shape) and identifies the resource scope. It could further clarify the summary content type, but the provided information is sufficient for most calling scenarios.

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 both parameters. The description adds no parameter-level detail beyond what the schema provides, so the baseline score of 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 clearly identifies the operation ('Return the persisted whole-game AI rollup summary') and the specific resource ('stored summary'). It distinguishes itself from sibling tools like get_build_summary and get_tester_summary by emphasizing the whole-game scope.

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

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

The description provides clear context that this tool reads the stored summary and returns null if none exists, indicating this is a read/fetch operation. It does not explicitly name sibling alternatives, but the whole-game wording and read-only framing make the intended use clear.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does disclose the data source and the exact return shape, which is helpful, but it does not explain aggregation window, grid contents, or behavior for missing/unknown games. It is transparent but not exhaustive.

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 with no filler. The first sentence states the core behavior and data source, and the second gives the return contract. Everything present is useful and 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?

The return shape is fully specified even without an output schema, which is valuable. However, there is no guidance on temporal scope, default environment, or how `grid` values are represented, and the sibling context does not help an agent decide when exactly to call this tool. It is adequate for a straightforward data retrieval but leaves some operational 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?

The schema already describes `game` and `build` well, covering 67% of parameters, and the description adds no additional parameter-level meaning. The undocumented `env` parameter remains unexplained, so the description does not compensate for that gap, though the schema coverage keeps this at the baseline.

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 uses a specific verb ('Return') and a precise resource ('per-room player-position density grids for a game'), and it distinguishes itself from sibling analytics tools by naming the source telemetry events (`player_pos`). This is immediately clear and differentiated.

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

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

The description implies the tool is used when per-room player-position heatmap data is needed and that it is scoped to a game, but it does not explicitly state when to choose this over siblings like get_event_stats or get_game_summary. No exclusions or alternative routing are provided.

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?

Without annotations, the description discloses key behaviors: recency boundary ('heartbeat in the last ~2 min'), event categories, and non-streaming poll semantics. It also explains the return shape since there is no output schema. It doesn't cover permissions, rate limits, or pagination, but those are less critical for this read-only snapshot.

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?

Every sentence carries useful information: what the snapshot is, how current it is, what events are included, and what it returns. It's front-loaded and has 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?

For a 2-parameter tool with no output schema and no annotations, the description provides enough to call and interpret results. The only gap is not explicitly distinguishing from similarly named activity tools, but 'live', 'right now', and 'poll snapshot' largely cover that.

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?

Input schema covers 100% of parameter descriptions, so baseline is 3. Description adds only that `game` appears in the return payload; it doesn't add semantics beyond 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 clearly defines the function: a real-time snapshot of online player count and recent events, with a concrete example question and return shape. It differentiates itself from a stream ('A poll snapshot, not a stream'), though it doesn't explicitly contrast with sibling tools like get_activity or get_activity_digest.

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 strong contextual clues for when to call it: to answer 'is anyone playing right now?' and to get a poll-style snapshot rather than a persistent stream. However, it does not name alternative tools or state when not to use it.

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?

No annotations are provided, so the description carries the full disclosure burden. It explicitly defines both rates, states that rates are null for an empty window and deltas null without a baseline, and reveals the returned object shape. This gives the agent clear behavioral expectations before invoking.

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

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

The definition is compact and front-loaded: the opening question states purpose, followed by formulas, edge cases, and output shape. Every clause contributes, and there is no filler or redundant schema repetition.

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

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

With no output schema, the description compensates by giving the exact return fields and null semantics. It also addresses empty-window and missing-baseline cases, and the schema covers the parameters. A caller has enough information to invoke the tool 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?

All three parameters have schema descriptions, so the schema already covers formats and constraints. The description adds operational context for 'days' as a comparison window, but it does not introduce new parameter formats, defaults, or constraints, so it stays at the high-coverage baseline.

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 a specific computation: crash rate and drop rate for the last N days vs the prior equal window, with percentage-point deltas. It includes concrete rate formulas and names the return object, so an agent knows exactly what the tool produces and can distinguish it from list/funnel/retention 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?

The description supplies target questions ('is my game crashing more this week?' / 'are more players dropping out?') that tell an agent when the tool is appropriate. It does not name sibling tools or exclusions, but the use-case context is unambiguous and actionable.

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?

No annotations are provided, so the description carries the behavioral disclosure burden. It does reveal the return shape, counts included, and 'biggest first' ordering, which is helpful. However, it does not mention data scope, time windows, or any behavioral caveats beyond that.

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

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

The description is compact and front-loaded with the core action, then gives concrete use cases and the return object. Every sentence contributes meaning and there is no 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 output schema and no annotations, the description compensates well by specifying the return shape, segmentation dimensions, count types, and ordering. It could go slightly deeper into how env/build affect results, but the core invocation context is sufficiently 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?

The input schema already describes all three parameters at 100% coverage. The description itself does not add param-level details, but given the high schema coverage, the baseline of 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 names a specific verb and resource—'Segment a game's sessions by country and by source (SDK/engine)'—and clarifies the exact outputs: session counts, distinct-device counts, and ordering by count. It also answers concrete use-case questions, making its purpose unambiguous and 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?

The description gives clear context by stating the questions it answers ('where are my players from?' and 'what engine are my sessions coming from?'). It does not explicitly name alternatives or when-not-to-use scenarios, but the context is strong enough for an agent to select it for country/source breakdowns.

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

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

With no annotations provided, the description carries the behavioral burden. It clearly states the return shape, warns that instructions can be long, and explicitly declares that key cleartext/ciphertext is never returned under any circumstances. This is strong security-relevant behavioral disclosure, though it does not cover error behavior or auth requirements.

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 sentences with no filler. The core purpose is front-loaded, the differentiation from list_playtest_batches is immediate, the security constraint is explicit, and the return shape is stated compactly. Every sentence earns its place.

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?

Despite lacking an output schema, the description explains the return structure and content precisely. It also covers the key edge about potentially long instructions and the absolute prohibition on returning keys. For a simple single-batch getter with two well-documented parameters, nothing essential 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 description coverage is 100%, so the schema already documents both parameters. The description adds context about the response including PlaytestBatch and instructions, but it does not add new meaning to the game or batch_id parameters beyond what the schema provides.

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: 'Detail for one playtest batch.' It also differentiates itself from the sibling list_playtest_batches by noting it returns the same fields plus the full instructions Markdown. An agent can immediately tell what this tool does and how it differs.

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

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

The description implies when to use this tool: when you need full detail for a single batch, especially the instructions copy, rather than a list of batches. It also distinguishes itself from list_playtest_batches, though it does not explicitly state exclusions or alternative selection criteria.

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

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

With no annotations, the description carries the full burden, and it delivers: it precisely defines cohort eligibility, retained-device semantics, and the per-window shape `{ eligible, retained, rate }`. It also discloses the output structure, making the tool's behavior clear and predictable.

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 metric and scope, then adds eligibility semantics and a practical usage example in three tight sentences. Every sentence earns its place, and there is no filler or 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?

The description covers the core metric definition, the return shape, and a realistic comparison use case, which is strong for a tool with no output schema. It leaves small gaps, such as what `devices` means and how `env` affects results, but these are minor for correct invocation.

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 input schema already describes env, game, and build, with 100% schema description coverage, so the baseline is 3. The description adds the useful 'call twice with build' workflow but does not provide additional parameter-level meaning beyond what the schema already contains.

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 names the resource ('cohort-eligible retention (D1/D2/D7/D30) for a game') and the optional build scoping, so an agent can tell what it does. However, it does not explicitly differentiate this from sibling tools like get_metric_trend or compare_builds, so it stops short of a perfect score.

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

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

The description gives a concrete use case: 'Call twice with `build` to answer did 1.5 improve retention vs 1.4?' and explains the optional build scope. It does not explicitly state when not to use this tool or name alternatives, so it lacks the exclusion guidance needed for 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?

No annotations are provided, so the description carries the full burden. It discloses two genuinely non-obvious behaviors: the exact return contract `{ session, insights }` and the 404-on-ownership-mismatch existence-leak convention, which is important security context. Minor omissions like permissions or auth requirements are acceptable for a simple read-style lookup.

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 compact clauses earn their place: purpose first, then return shape, then error behavior. No filler, no repetition of the title or schema, and the most decision-relevant detail (the 404 convention) is positioned last as a warning.

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 1-parameter, no-output-schema lookup, the description supplies the essentials: what is returned, its shape, and the failure mode. Minor gaps are the absence of insight ordering/completeness guarantees and what 'ownership' means in practice, but these are not blocking for correct invocation.

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%; the schema already documents session_id as a uuid with minLength 1 and marks it required. The description adds no parameter-specific syntax or format details, which is fine because the schema handles it. 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?

Description states a specific verb (Return) + resource (one session) + distinguishing scope ('with all its insights joined'), which sets it apart from list_sessions (listing) and query_insights (free-form insight querying). The explicit return shape `{ session, insights }` reinforces what 'joined' means.

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: 'Return one session with all its insights joined' signals this is the tool for a single session's full context. However, it never names alternatives explicitly, such as list_sessions for browsing or query_insights for insight-level queries, nor does it state when NOT to use it.

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?

No annotations are present, and the description carries the burden well: it specifies oldest-first ordering, the exact engagement-trend values and their meaning, the device_id fallback precedence, and the `{ journey }` or 404 response contract. This is a comprehensive behavioral disclosure for a retrieval 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?

Three dense sentences, each earning its place: the primary output, the trend classification, and the input/response contract. The most important scope 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?

With no output schema, the description supplies the essential return contract: a journey with per-session metadata, insights, friction summary, praise, and an engagement-trend classification, plus the 404 error case. Together with the input behavior, it is enough for an agent to invoke the tool correctly and know what to expect.

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 schema already documents game and device_id formats, and the description adds the important nuance that device_id tries a handle before a device id. The optional env parameter is not described in the description, but its pattern constraint is enough to invoke it safely.

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 precise verb and resource: 'Return one tester's full session-by-session timeline for a game.' It enumerates the per-session content and the engagement-trend classification, making it clearly distinct from single-session tools or summary 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?

The intended use is implied by the content—one tester, all sessions, chronological—so an agent can infer this is for detailed per-session journeys rather than summaries or single sessions. However, the description never names alternatives (e.g., get_tester_summary or get_session) or gives an explicit when-not-to-use 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 no annotations, the description must carry the behavioral burden. It does communicate that this is a read-style operation ('Return') and clarifies the identity semantics of the device GUID. However, it does not disclose potential edge cases, absence of results, scoping to a particular game/environment, or any side effects, so it is adequate but not rich.

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 with no filler. It front-loads the core purpose, lists the rollup contents in compact parentheses, states the identity model, and gives the exact return keys. Every sentence earns its place.

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 focused get-summary tool, the description is largely complete: it names the inputs via schema, explains the device GUID, and defines the return object. The main gap is the undocumented 'env' parameter, but for the typical use case this does not seriously hinder correct invocation.

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 schema already describes 'game' and 'device_id' reasonably well, and the description adds value by reinforcing that device_id is a persistent anonymous device GUID. However, the 'env' parameter has no description in the schema and no explanation in the description, so the 67% schema coverage is only partially compensated for.

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 uses a specific verb ('Return') and identifies the resource ('rollup for one tester') with enumerated contents: session count, first/last seen, playtime, geo, last build, plus sessions and AI summary. It also clarifies the tester identity mechanism (persistent anonymous device GUID) and gives the exact return shape, leaving no ambiguity about what the tool produces.

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

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

The description clearly implies when to use the tool: when you need a rollup plus sessions and an AI summary for a single tester, identified by device GUID. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select it over broad summary or list tools.

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

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

With no annotations, the description carries full responsibility and does so thoroughly: it discloses scope (management key's workspace), what is included (plan, credit breakdown, storage), special null behavior for unlimited accounts, and the return shape. There is no hidden side-effect or 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 description is well-structured: the core scope is front-loaded, followed by concrete details, example questions, and a clear return contract. Every sentence contributes meaningful information without unnecessary repetition.

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

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

For a zero-parameter read-only tool with no output schema, the description is fully complete. It states the scope, enumerates the returned fields, explains the null case, and even defines the low-balance flag and reset timing. Nothing an agent needs to invoke it successfully 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?

The tool has zero parameters, so schema coverage is trivially 100% and the baseline of 4 applies. The description adds useful output-level semantics even though there are no parameters to explain.

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 (your account's own usage, plan state, credits, storage) and clearly scopes it to the management key's workspace. It distinguishes itself from the many game/session/analytics sibling tools by focusing exclusively on account-level usage and billing state.

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

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

The description gives clear contexts for use by listing the exact questions it answers ('how many credits do I have left / am I running low / how much storage am I using?'). It does not explicitly name alternatives or exclusions, but the scope is unmistakable and no competing sibling covers account billing/usage.

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?

No annotations are provided, so the description carries the full burden. It discloses the grouping (one rollup per distinct metadata.gameVersion), ordering (newest-active first), the set of metrics returned, and the return shape `{ game, builds }`. It does not mention side effects or auth requirements, but list operations usually imply read-only behavior and the description covers the essential behavioral traits.

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 sentences with no waste: the first lists the core behavior and rollup fields, the second gives the usage rule and sibling pointer, and the third states the return shape. Every sentence earns its place and the most important 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?

With no output schema and no annotations, the description compensates by explicitly stating the response format and enumerating the fields included in each rollup. It also includes a concrete use case and the exact prerequisite for using get_build_summary. No critical information needed to call the tool correctly 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 description coverage is 100%, so the baseline is 3. The description adds context about the game parameter by framing it as a prerequisite for discovering builds, but it does not add any syntax or format details beyond what the schema already provides. The env parameter is not elaborated further, but the schema already explains it well.

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 starts with a specific verb and resource ('List every build ... for a game') and details the exact rollup fields (session count, unique devices, first/last seen, total playtime, dominant country). It also distinguishes itself from get_build_summary by stating that list_builds is for discovery of builds and latest version, while get_build_summary needs an exact version.

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

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

The description explicitly says 'Use this to discover a game's builds and find the LATEST version before calling get_build_summary', providing a clear when-to-use rule and naming the alternative tool. This tells an agent exactly when to pick this tool over a sibling.

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

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

With no annotations, the description carries the transparency burden. It discloses the return shape (`{ crashes }`), a 200 cap, ordering, and the per-group fields. It does not explicitly state 'read-only', but 'List' and the overall framing make side effects unlikely.

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 three sentences with no filler. It front-loads the purpose, then covers output contents, filtering options, and return shape efficiently. Every sentence contributes useful 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?

Despite the lack of an output schema, the description explains what the response contains and how results are ordered/capped. The only mild gap is that 'newest / most-frequent first' is slightly ambiguous about which sort applies, but overall the description is complete enough for a list 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 baseline is 3. The description adds some helpful framing around platform prefix and from_ms/to_ms as a 'report-time window', but it mostly restates what the schema already documents. It does not add significant new per-parameter meaning.

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 names the verb ('List'), the resource ('unresolved crash groups for a game'), and the use case ('what's crashing in my game?'). It does not explicitly differentiate from the sibling get_crash_groups, but the 'unresolved' qualifier and the listed group fields make the scope reasonably distinct.

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

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

The description states a clear use context: answering crash-overview questions for a game. It also explains optional filtering by platform and report-time window. It does not mention when to prefer an alternative tool like get_crash_groups, so it stops short of full routing guidance.

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

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

With no annotations provided, the description carries the full burden, and it delivers: it states the tool is paginated and filterable, describes the data content (verbatim responses), explains the `attention` shorthand, and gives the exact return envelope `{ game, submissions, total, page, perPage }`. This gives the agent a clear model of what will happen when invoked.

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 three well-organized sentences: what the tool returns, how it differs from its sibling, and what filters/output to expect. Every sentence earns its place, and the most important distinction 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?

For an 11-parameter list tool with no output schema, this description is unusually complete. It names all meaningful filter axes, defines the special `attention` flag, states the response shape, and differentiates from the nearest sibling. An agent has everything needed to decide to call it and to construct a correct request.

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%, giving the baseline of 3. The description adds value above the schema by grouping filters conceptually (form, build, environment, rating, attention, q, time window) and explaining `from_ms/to_ms` as a submission-time window with the shorthand 'feedback today'. This contextual framing helps the agent choose parameters more intelligently.

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, concrete resource: 'The actual player feedback-form RESPONSES (verbatim answers)'. It explicitly contrasts itself with the sibling `list_game_feedback_forms`, which returns only form definitions, so the agent can immediately distinguish this tool from a closely related one.

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 answers the use case directly ('Answers what did my testers actually say?') and names the exact alternative for form definitions. It also enumerates the available filter dimensions, telling the agent exactly when this tool is appropriate and when the sibling would be chosen instead.

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?

There are no annotations, so the description carries the full behavioral disclosure burden. It does well by stating default ordering, deleted-exclusion, field-level details like audienceName being null for all-player targeting, winnerVariantKey being nullable, and the response envelope. It does not mention pagination or rate limits, but for a list tool this is a minor 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?

The description is rich yet tightly packed: it starts with the core purpose, then lists essential response fields, and ends with a return-shape hint. Every sentence adds value, and there is no filler or repetition of schema details.

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 compensates by specifying the response envelope and explaining the important fields including status, variant catalog, audienceName, winnerVariantKey, and timestamps. It is complete enough for an agent to invoke the tool and interpret results, though it could mention pagination or limits for exhaustive listing.

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 game, sort, and order. The description's 'default newest first' reinforces the sort/order defaults but does not add significant new parameter-level meaning beyond what the schema provides. This matches the baseline for high schema coverage.

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

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

The description opens with a specific verb and resource: 'List the A/B experiments for a game.' It also adds meaningful scoping details—default newest first and exclusion of deleted experiments—that distinguish this tool from sibling tools like list_games or get_experiment_comparison. The agent can immediately tell what this tool does.

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

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

The description gives a clear usage context: 'Use this to answer what experiments am I running?' This tells the agent when to invoke the tool. It does not explicitly mention when not to use it or name alternative experiment-related tools, but the usage guidance is still clear enough for correct selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly discloses what is included per form (field definitions, trigger hint, active flag, submission count), what is excluded (tester-level submission rows), and the return shape. This is transparent and non-obvious behavior that an agent would otherwise not know.

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 every sentence earns its place: it defines the resource, details the returned fields, clarifies an important exclusion, gives a concrete use case, and states the return shape. It is front-loaded with the primary purpose and avoids 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?

For a tool with one simple required parameter and no output schema, the description is complete: it explains what the output contains, what it deliberately omits, and when to use it. An agent has everything needed to invoke it correctly and interpret the result.

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

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

Schema description coverage is 100%, and the single parameter 'game' is already documented as 'Game id, slug, or exact name.' The description adds no parameter-specific semantics beyond what the schema provides, so the baseline score of 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 specifies the exact verb and resource: listing studio-defined Player Feedback forms for a game, and explains what those forms are via the SDK context. It also distinguishes itself by explicitly noting that tester-level submission rows are NOT returned, so an agent can tell this apart from related feedback 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?

The description gives a direct use case: 'Use this to answer "what feedback am I collecting from my testers?"' It also provides an explicit when-not-to-use signal by stating that submission rows live on the session and slot into get_session, effectively routing the agent to the correct sibling 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?

With no annotations, the description carries the burden and does a good job: it reveals the default ordering, the exact return shape, the meaning of mode and scopeMode, and warns that conversion numbers are excluded. It does not cover pagination or error behavior, so it is not fully exhaustive.

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 long but information-dense; it front-loads the core purpose and default ordering, then packs return-field semantics into a compact form. The detailed return structure earns its place because there is no output schema.

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

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

For a list endpoint with no output schema, the description covers the return payload, field semantics, and what is intentionally absent. The only notable omissions are pagination behavior and explicit routing to the funnel-result siblings.

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 game, sort, and order; the baseline is 3. The description adds value by interpreting the default ordering as 'most-recently-updated first' and by tying the game parameter to the intended use case. This lifts it above the baseline.

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

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

The description opens with a specific verb and object: 'List the conversion funnels defined for a game...' and includes a concrete intended question. It clearly distinguishes these funnel definitions from computed conversion numbers, which separates it from sibling tools like get_funnel_result and get_funnel_trend.

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 explicit use case ('Use this to answer what funnels are set up for this game?') and an explicit exclusion: computed step-by-step conversions are not returned here. It does not name the alternative sibling tools directly, but the exclusion is clear enough.

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

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

With no annotations provided, the description carries the full behavioral burden. It explicitly states 'Read-only', which is a crucial safety disclosure for a tool with no annotation hints. It also discloses the access scope ('owned by the management-key holder') and the return shape, which goes beyond the 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?

Three short sentences deliver scope, safety, parameters, and return shape with no filler. The most important fact (what the tool lists) is front-loaded, followed by read-only status and parameter/return details.

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?

The description is complete for a simple list tool: it states what is returned, the access scope, that it is read-only, and which optional filters are available. The lack of an output schema is mitigated by explicitly noting the return shape as { games: Game[] }.

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 fully documents q, sort, and order. The description only restates these parameter names and categories without adding new meaning, so it neither improves nor harms parameter understanding.

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 ('List'), a concrete resource ('games'), and a precise scope ('every game owned by the management-key holder'). This clearly distinguishes it from siblings like get_game or get_game_summary, which target a single game or summary rather than a full list.

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

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

The description gives clear context for when to use the tool: whenever you need the full set of games owned by the management-key holder. It does not explicitly name alternatives or exclusions, but the scope is specific enough that an agent can infer it should be used for listing rather than fetching one game or a summary.

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

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

With no annotations, the description carries the behavioral disclosure burden. It clarifies that the tool returns every playtest batch for a game, not a filtered subset, and includes the response shape `{ game, batches: PlaytestBatch[] }`. It does not explicitly state pagination or non-mutation, but the verb 'List' and the return-type mention make the read-only intent clear.

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

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

The description is compact and well-structured: purpose first, use case second, return shape last. Every sentence earns its place, and there is no redundant or filler wording.

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 list tool with only one required parameter and fully documented schema, the description is complete enough. It explains the scope, the returned fields, the batch-level rollup counts, and the expected response shape. Since there is no output schema, the explicit mention of `{ game, batches: PlaytestBatch[] }` is especially valuable.

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 input schema already documents all three parameters and their enums. The description only loosely maps to the `game` parameter ('for a game') and adds no extra detail about sort or order. Baseline 3 is appropriate because 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?

The description uses a specific verb and resource: 'List every playtest batch for a game'. It also enumerates the returned fields, making it clear this is a batch-level aggregation tool rather than a key- or session-level tool. This distinguishes it from siblings like get_playtest_batch and list_playtest_keys.

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

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

The description gives a clear use case: answering 'how is my Steam Next Fest distribution going?', which implies batch-level distribution monitoring. It does not explicitly name alternatives or state when not to use it, but the context is strong enough for an agent to select it for a batch overview request.

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

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

With no annotations, the description carries the full transparency burden and does so thoroughly. It discloses pagination, default sorting, the return shape, and the important security behavior that the one-shot claim token is never returned. This gives the agent accurate expectations beyond just the tool name.

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

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

The description is compact and front-loaded: it states the main purpose first, then defaults, then security and pagination. Every sentence carries useful information, and there is no filler or repetition of the parameter 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?

There is no output schema, so the description correctly fills that gap by specifying the paginated response shape: { game, handles: PlaytestHandle[], hasMore, total }. Combined with the sort, pagination, and security disclosures, an agent has enough context to call this tool correctly for a variety of lookup and analysis use cases.

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 schema already has 100% coverage for all parameters, so the baseline is 3. The description adds meaningful extra context by explaining how to use the sort options to find engaged testers and how distinct_countries can indicate shared keys, going beyond the raw parameter definitions.

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 uses a specific verb and resource: 'List SDK-linked tester handles for a game with rollup metrics.' It clearly defines the scope and what data is returned, and distinguishes this tool from related list tools like list_playtest_keys and list_playtest_batches by focusing on handles with rollup analytics.

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

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

The description gives concrete usage guidance: it explains the default sort order, tells users to sort by session_count or total_play_time_ms to find engaged testers, and points out that a wide distinct_countries value may indicate a shared key. It does not explicitly name alternative tools or list when not to use this tool, but the context is clear enough.

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?

There are no annotations, so the description carries the burden. It discloses that the tool returns lifecycle/redemption metadata while never exposing cleartext keys, and states pagination behavior plus the response shape. This covers key behavioral expectations well, though it could mention rate limits or error conditions.

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

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

The description is compact yet dense: two sentences front-load the value, enumerate the metadata, state the security property, and give the return shape. No filler or duplication of the schema.

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

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

For a 6-parameter tool with full schema coverage and no output schema, this description is largely complete: it explains purpose, key metadata, security boundary, pagination, and response shape. The only gap is lack of explicit error conditions or rate-limit behavior, but the core call semantics are well covered.

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 six parameters. The description adds meaning by explaining the high-level purpose (batch listing, metadata, no cleartext keys), which helps an agent infer that game and batch_id are the required filters. Since the schema covers parameter details fully, a 4 is appropriate – not 5 because the description doesn't add per-parameter nuance beyond the purpose.

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 ('List') and resource ('keys in a batch'), and goes beyond by enumerating the exact metadata returned (status, redemption time, email+handle, country, user-agent, linked invite id). This is clearly distinct from sibling list_playtest_batches or list_tester_invites.

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 frames the use case: 'Use this to answer who redeemed what, when, and from where without ever holding a cleartext key.' It does not explicitly name an alternative tool to use instead, but the use-case framing plus the mention of pagination gives clear context. Would be stronger with an explicit 'use list_playtest_batches for batch metadata instead'.

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

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

With no annotations, the description carries the behavioral disclosure burden. It discloses pagination ('Paginated'), optional filtering, and the return contract ('Returns { items, hasMore, total }'). It doesn't explicitly say the operation is read-only, but 'list' strongly implies it. The return shape is a useful behavioral disclosure not present elsewhere.

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, with the core action and resource front-loaded. Every sentence adds information: pagination, filter optionality, and return shape. No filler or repetition of schema details.

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 rich 83% schema coverage and the simple listing behavior, the description is mostly complete. It includes the return shape even though no output schema exists. The main gap is not explicitly routing agents to get_session when a single session is needed, but the description is sufficient for correct invocation in most cases.

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 83%, and the input schema already documents each parameter including q, from, to, game, sort, limit, and order. The description only says 'All filters optional,' which adds little beyond the schema's zero required parameters. Baseline of 3 is appropriate since 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?

The description uses a specific verb and resource: 'Paginated playtest sessions across the user's games.' This clearly identifies what the tool returns and distinguishes it from sibling tools like list_games or get_session. The scope is explicit, so an agent immediately knows this is the session-listing 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?

The description gives clear context: this is for listing playtest sessions with all filters optional. It doesn't explicitly say 'use get_session for a single session' or contrast with list_builds, but the paginated listing behavior makes the primary use case obvious. Slight deduction for not naming 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?

With no annotations, the description carries the full burden and delivers: it specifies the exact return shape ({ archetypes, testerCount, reason?, modelId? }), guarantees it "always returns a result object," enumerates the failure reason values (requires_byo_key / insufficient_data / api_error), and details each archetype's contents including the "Cluster N" fallback label. This gives an agent a complete behavioral contract for orchestration.

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 purpose is front-loaded in the first sentence, and every subsequent clause earns its place by explaining the return contract, fallbacks, and archetype structure. It is a dense but efficient paragraph; slightly more structural separation of the failure contract from the success shape would earn a 5.

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?

Because there is no output schema, the description correctly assumes the burden of documenting the return value, and it does so thoroughly (top-level shape, reason codes, archetype fields). The only meaningful gap is the undocumented env parameter, which an agent would have to infer from its pattern and sibling conventions.

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 exactly 50% — game is described as "Game id, slug, or exact name" but env has only a regex pattern and no semantics. The description adds no parameter-level guidance and does not compensate for the undocumented env parameter, though it does hint at a data prerequisite (narrative summaries) via the insufficient_data failure mode.

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 precise verb+resource: "Group the game's testers into behavior archetypes based on their per-tester narrative summaries." This clearly distinguishes it from per-tester siblings like get_tester_summary and get_tester_journey, which operate on individual testers rather than aggregating across 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?

The intended use case is implied by the first sentence — an agent can infer this tool is for cross-tester behavioral grouping — but there is no explicit statement of when to prefer it over alternatives such as get_tester_summary or get_tester_journey, and no exclusions are given.

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

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

With no annotations provided, the description carries the full behavioral burden. It explains that opened_at is a best-effort beacon and may be null even when the recipient opened, that redeemed_at is the definitive signal, and that the per-tester redemption token is never returned. These are concrete behavioral disclosures beyond the basic 'list' operation.

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 sentences with no filler: the first front-loads purpose and included fields, the second provides important caveats about open tracking, and the third states what is excluded and the return shape. Every sentence earns its place.

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?

Even without an output schema, the description gives the return shape '{ batch, invites: TesterInvite[] }', explains key field semantics, flags the null behavior of opened_at, and explicitly notes the token is not returned. This is sufficient for an agent to call the tool and interpret results 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 description coverage is 100%, so the baseline is 3 and the description need not repeat parameter docs. The description mentions batch scope and invite fields but adds no additional parameter-level semantics beyond what the schema already provides for game, batch_id, sort, and order.

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 ('List'), a specific resource ('every 1:1 invite in a batch'), and enumerates exactly what will be returned: recipient email, optional note, and send/opened/redeemed timestamps. This clearly distinguishes it from sibling tools like list_playtest_batches or list_playtest_keys by focusing on per-tester invites.

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

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

The description makes the usage context clear: call this when you need per-tester invite details for a specific playtest batch. It doesn't explicitly name alternatives or when-not-to-use scenarios, but the batch-scoped framing gives an agent enough directional guidance among the large sibling set.

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

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

With no annotations provided, the description carries the full burden and does well: it discloses error conditions, reversibility, non-destructive behavior, role requirements, and the return shape. This gives an agent a solid model of side effects and prerequisites.

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

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

Four tightly packed sentences with no filler. Each sentence delivers distinct useful information: operation semantics, error cases, side-effect profile, authorization, and return value.

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

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

The description covers operational states, failure modes, authorization, reversibility, and return value. For a simple two-parameter mutation with no output schema, this is complete enough for an agent 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%, so the baseline is 3. The description adds value by clarifying that null unsets the winner, that the key must match an existing variant, and that a mismatch produces a 400. This goes slightly beyond the schema descriptions.

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 uses a specific verb phrase ('set, change, or unset') with a clear resource ('winner variant of a RUNNING or STOPPED experiment'). It clearly differentiates this decision-recording action from related experiment operations like pinning or unpinning variants.

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

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

The description states valid experiment states (RUNNING or STOPPED), explicitly calls out draft experiments as invalid (409), and notes the required member/admin/owner role. It does not explicitly name alternative sibling tools, but the context and constraints make when-to-use reasonably clear.

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

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

With no annotations, the description carries full behavioral burden and does so thoroughly: it discloses the override semantics, re-pinning behavior, status independence, error cases (400/409), role requirement, and return shape. This goes well beyond a typical tool description.

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?

Seven sentences, each carrying distinct information: purpose, usage, re-pin behavior, status, errors, auth, and return. The QA purpose is front-loaded and no sentence is redundant or 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?

Despite having no output schema, the description states the exact return shape. It also covers edge cases, failure modes, status independence, and authorization, making the tool callable without external documentation. The only minor omission is an explicit pointer to unpin_experiment_variant, but that is available as a sibling name.

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 every parameter. The description adds little parameter-specific nuance; the main added value is contextual (variant key error handling) rather than new meaning for individual parameters, so 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?

Description opens with a specific verb and resource: 'force a specific device into a specific variant of an experiment'. It clearly labels the tool as QA pinning and contrasts it with normal assignment by saying it bypasses split and audience/new-player filters. This makes it easy to distinguish from the sibling unpin_experiment_variant and other experiment 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 explicit when-to-use guidance: QA feel-testing on a dev machine, and pin before starting to guarantee first assignment. It also states applicable statuses and required role, but it does not explicitly name alternatives or state when not to use it, relying on 'QA pinning' to imply the 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?

No annotations are provided, so the description carries the full disclosure burden. It only states that the tool searches insights and gives examples; it does not disclose whether the operation is read-only, how results are scored or paginated, what counts as an insight, or how errors are handled. These gaps leave the agent guessing about important runtime behavior.

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

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

Two short sentences with zero fluff. The core action is front-loaded, and the quoted examples are illustrative without being verbose. Every word earns its place.

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?

This is a complex query tool with 10 parameters, 0 required, no output schema, and no annotations. The description provides no information about return values, default behavior beyond what the schema states, pagination, or the nature of the searched content. An agent cannot predict what a successful response looks like or how to handle edge cases.

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

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

With 60% schema description coverage, the description adds meaningful value by showing how parameters combine: 'stuck-points' maps to type, 'build 0.5.0' to build, 'positive moments' to sentiment/type, and 'this month' to the date range. It does not explain all undocumented parameters, but it compensates partially for the schema gaps.

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 clear verb ('Search') and a specific resource ('the user's insights'), with examples that illustrate intent. It does not explicitly distinguish this from sibling search tools like search_docs or search_everything, though the focused resource is implied by the name and description.

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

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

The description gives clear usage context through two concrete use cases: friction analysis ('show me all stuck-points in build 0.5.0') and praise hunts ('top positive moments this month'). It does not explicitly mention when not to use this tool or point to alternatives, so it falls 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?

With no annotations provided, the description carries the behavioral disclosure burden. It explicitly states 'Read-only' and describes the return shape as top-k relevant passages with source, returning `{ results }`. This gives agents a clear expectation despite the lack of a detailed 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?

The description is three short sentences with no filler. The core purpose is front-loaded, the doc scope is listed compactly, and the read-only and return-shape notes are both relevant and concise.

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?

The tool is simple, the schema covers both parameters, and the description explains the result content and read-only nature. It could mention an alternative for non-doc searches, but for its intended grounding use case it is sufficiently 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%, so the schema already fully documents `q` and `k`. The description adds context by mentioning 'top-k', which maps to the `k` parameter, but it does not need to add more; 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 states a specific verb ('semantic search'), a clear resource ('Playloop documentation'), and a defined output (top-k passages with source). It is clearly distinguishable from siblings like search_everything because it is scoped to docs about how the platform works.

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

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

The description gives clear context for when to use this tool: for grounding answers about how Playloop works, and it enumerates covered doc areas such as SDKs, billing, and security. It does not explicitly name alternatives or exclusion conditions, but the doc-scoped purpose is unambiguous.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It conveys that results are capped per type, ordered by most-relevant first, and returns a specific shape with four keys. This meaningfully informs expected behavior, though it does not detail auth, pagination, or error behavior.

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 with no filler. The core search scope is front-loaded, followed by concrete usage examples and the return shape. Every sentence contributes useful guidance.

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 simple 2-parameter search tool, the description provides enough context: what it searches, why to use it, how results are ordered, and what it returns. It is slightly less complete because it does not mention result count behavior or edge cases, but overall it is well-rounded.

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 input schema already documents both parameters fully, including default, range, and min length, so the description does not need to repeat them. The description adds the context that results are capped and relevance-ranked, but this is behavioral rather than parameter-specific 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?

The description clearly states a specific action (full-text search) and a defined resource set (sessions, games, insights, events), which distinguishes it from narrower sibling tools like search_docs or query_insights. The scope is explicit and immediately actionable.

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

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

The description provides concrete use cases: resolving fuzzy names and finding sessions where players mentioned something. It does not explicitly contrast with alternatives or state when not to use it, but the use-case guidance is clear enough for an agent to select this tool appropriately.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the action replaces any existing cover, requires elevated permissions, returns 403 for unauthorized users, returns 415 on mismatched contentType, enforces a 3 MB limit, and returns a specific payload shape. This is exemplary transparency.

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 every clause earns its place: action, role requirement, encoding rules, size cap, contentType validation, replacement semantics, and return shape. It front-loads the core purpose and keeps all critical constraints in a compact, readable form.

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 mutation tool with no annotations and no output schema, the description is fully self-sufficient. It covers authorization, error conditions, input format, size limits, destructive behavior, and the return value. 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%, so the schema already documents each parameter. The description adds meaningful operational detail beyond the schema: the 3 MB max before encoding, the requirement that contentType match actual bytes, and the explicit no-data-URL rule. This raises it above the baseline.

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

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

The description opens with a specific verb and resource: 'Set (or replace) a game's cover image.' This clearly distinguishes it from sibling tools like update_game, which cover general game metadata, and leaves no ambiguity about what the tool operates on.

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

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

The description gives explicit role preconditions ('Requires an ADMIN or OWNER role (members/viewers get 403)') and format/size constraints, so an agent knows when it is appropriate to call this tool. It does not explicitly name an alternative for other game updates, but the context is strong enough that no exclusion is needed.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states concrete side effects (locks variants, allocations, audience; players start being assigned), an error condition (409), permission requirements (member/admin/owner), and the return shape. This is notably transparent for a state-changing 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 three tight sentences with no filler. It front-loads the core action and state transition, then adds side effects, error handling, permissions, and return value efficiently. Every sentence earns its place.

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?

Despite having no annotations or output schema, the description covers the essential context: when the tool is valid, what side effects to expect, failure conditions, required authorization, and the response envelope. For a simple one-parameter mutation tool, nothing necessary for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already fully defines experiment_id. The description adds no additional semantic detail about the parameter itself, but it does reinforce the experiment context. This matches the baseline of 3 for high schema coverage.

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

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

The description opens with a specific verb and resource: 'Start a DRAFT experiment (draft → running).' It clearly distinguishes starting from related operations like stopping, pinning, or creating experiments. The side effects mentioned further clarify what the tool does.

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

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

The description makes the intended context clear: only draft experiments should be started, and a 409 error occurs for already-running or stopped experiments. It also advises resuming stopped experiments from the dashboard, which acts as a when-not-to-use signal. However, it does not name an alternative MCP tool explicitly, 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.

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It thoroughly covers side effects (players stop getting assigned), data safety (data stays intact), reversibility (not a delete), error behavior (409 on other status), and permissions. This is unusually transparent.

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

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

The description is compact and front-loaded with the core action. Every sentence provides distinct value: state transition, behavioral effects, error condition, role requirement, and return shape. There is no filler or repetition.

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

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

For a single-parameter tool with no output schema and no annotations, the description is complete. It explains when the operation is valid, what happens, what happens to data, what causes an error, what permissions are needed, and what the response contains.

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

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

Schema description coverage is 100% for the single required parameter, experiment_id, and the schema already documents it. The description does not add parameter-level detail, but it does not need to; the baseline of 3 applies because the schema handles the semantic load.

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 ('Stop') and resource ('a RUNNING experiment') and gives an explicit state transition (running → stopped). It clearly distinguishes this from related sibling operations like start_experiment or pick_experiment_winner by focusing on the running state and the stop action.

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

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

The description gives clear context: only running experiments can be stopped, and a 409 is returned for any other status. It also specifies required roles (member, admin, or owner). It does not explicitly name an alternative tool for the opposite operation, but the state-based restriction provides adequate guidance.

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

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

With no annotations provided, the description carries the behavioral transparency burden. It discloses mode-dependent behavior, the premium/paywall behavior (returns requiresPremium with 402 without a BYO key), and the general return shape including ok, mode, game, environment, suggestions, source, and emptyInput. It does not explain all return fields or edge cases, but it is substantially transparent for a read-oriented analysis 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 compact and front-loaded, stating the core purpose in the first sentence and then efficiently covering modes, authentication requirements, and return shape. Each sentence adds useful information without repetition or filler. The format is scannable and appropriate for the tool's complexity.

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 that there is no output schema, the description compensates by describing the return envelope and important failure behavior. It explains the two modes, the free-tier key requirement, and the main output fields. However, some terms such as source and emptyInput are left unexplained, and there is no mention of how parameters interact or what happens if both build and a/b are supplied. Still, an agent has enough context to invoke the tool correctly in most cases.

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 80%, so the schema already documents most parameters. The description adds meaningful semantics beyond the schema by explaining that build refers to single-build mode and a/b together enable compare mode targeting worsening or emerging friction. It also clarifies the output fields that map to these parameters, adding value beyond the bare property descriptions.

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 states that this tool generates AI prescriptive fix suggestions for friction in a single build or the diff between two builds. It names the two operational modes and the resource being analyzed, so an agent can understand what it does. It does not explicitly contrast itself with closely named siblings like get_fix_first, so it stops short of full sibling differentiation.

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

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

The description gives clear usage context: use single-build mode (?build=) for a build's top friction, and compare mode (?a=&b=) for friction that worsens or emerges between builds. It also documents the free-tier requirement and the 402 response when a key is missing. It does not explicitly state when not to use this tool or name alternative tools, so it lacks 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It covers the core effect, the 404 error when no pin exists, the required member/admin/owner role, and the return value (`{ overrides }` with the remaining pin list). This is rich, specific behavioral context beyond what structured data provides.

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 three sentences, front-loaded with the primary effect, then error behavior, then auth and return value. Every sentence adds distinct, necessary information with no filler or 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?

For a two-parameter tool with no output schema, the description is complete: it explains the action, the behavioral consequence, error handling, authorization requirements, and the return shape. Nothing an agent needs to call this correctly 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 description coverage is 100%, so the schema already fully documents both parameters. The description does not add additional parameter-level meaning beyond what the schema provides; it only refers to the device and experiment in general terms. Per the baseline rule, a score of 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 states a specific verb ('Remove') and resource ('QA pin'), and explains the effect: the device returns to normal bucketed assignment. This clearly distinguishes the tool from its sibling pin_experiment_variant, even without naming the sibling, because the action and outcome are unambiguous.

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

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

The description gives clear context for when to use the tool: when a device should stop using a QA pin and resume normal assignment. It also mentions the 404 error case, which helps agents anticipate failure. It does not explicitly name alternatives or exclusions, but the inverse relationship to pin_experiment_variant is implied.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly: it discloses partial-update semantics, null-clears clearable fields, role-based 403s, immutability of slug/engine, server-side clamping and length caps, default restoration on null, and the `{ game }` return shape. This is exemplary transparency.

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 a single dense paragraph that front-loads the action and field groups, then packs in behavioral rules, permissions, and return value without redundancy. Every sentence earns its place given the tool's complexity.

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

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

For a 12-parameter mutation tool with no annotations and no output schema, the description covers the essentials: what is updated, how partial updates and nulls behave, permission requirements, immutability constraints, and the return format. The schema documents individual parameters, so nothing needed to call it correctly 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 the baseline is 3, but the description adds meaning beyond the schema by explaining the cross-cutting partial-update rule ('only the fields you send change') and noting that slug/engine are fixed and therefore not updateable. This is useful context the schema alone does not make explicit.

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

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

The description opens with a specific verb and resource ('Update a game's AI/analysis configuration') and enumerates the exact fields covered, including name, genre, AI context, KPI buckets, toggles, and event names. This clearly separates it from read-only siblings like get_game and from the narrowly scoped set_game_cover.

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

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

The description gives clear operational context: it is a partial update, it requires ADMIN or OWNER role, and slug/engine are fixed at creation. It does not explicitly name alternatives or state when not to use this tool, so it falls just 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.