Gamebeast

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

Annotations only declare write/non-idempotent/non-destructive; the description adds real value beyond that by saying the change is saved immediately when the tool runs and that a human-readable reason appears on an approval card. It does not describe post-write response shape, but the persistence and approval semantics are useful disclosures.

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 dense sentences with the core purpose front-loaded, followed by layout and prerequisite details. Every clause carries information, though the middle sentence packs default sizing, append order, save-on-run, and the reason field together in a slightly run-on way.

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 mutating dashboard-panel tool with 6 parameters (including nested gridPos) and no output schema, the description covers the prerequisite skill, default layout, immediate persistence, and approval-card reason. Nothing essential for correct invocation is missing, though an explicit contrast with add_markdown_panel would complete the picture.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning beyond the schema by stating the default size (24x1, full width), the default placement (appended in reading order), and that text is plain text without markdown — clarifying how the optional and required string parameters behave, not just their types.

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 ('Add a section heading to a dashboard') and then defines exactly what that resource is: 'one line of plain text, drawn without a card, that titles the panels below it.' That visual/structural definition cleanly separates it from add_markdown_panel and add_query_to_dashboard.

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

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

Gives a clear pre-condition (load the manage-dashboards skill via load_skill first) and explains placement behavior: appended in reading order unless gridPos overrides it. It does not explicitly contrast itself with add_markdown_panel, which is the closest ambiguous alternative, so it stops short of full when/when-not 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?

Goes beyond the annotations by disclosing placement behavior ("Appended in reading order unless gridPos places it") and persistence ("Saved when this runs"), plus the human-facing effect of reason on an approval card. With readOnlyHint=false and idempotentHint=false already declared, this is meaningful added context, though it doesn't say what is returned or what happens on a failed/invalid content save.

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?

Five short sentences, each doing distinct work: purpose, sibling exclusion, placement default, persistence plus reason guidance, and the skill prerequisite. Purpose and the exclusion are front-loaded, and nothing is redundant.

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 mutation tool with a nested gridPos object, the description covers purpose, alternative, placement defaults, persistence, and the required skill. The only gap is the absence of any return-value note, which matters slightly since there is no output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks: the default 6x8 panel size and the default placement order that applies when gridPos is omitted. That clarifies the optionality and consequences of gridPos beyond its own field 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?

States a specific verb and resource ("Add a markdown text panel to a dashboard") and immediately clarifies what that resource is ("a card of notes explaining the charts around it"). It also names the sibling it is not — add_heading_panel — so an agent can distinguish the two without opening either schema.

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

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

Explicit when-not guidance: "For a section title use add_heading_panel instead." Adds a prerequisite (load the manage-dashboards skill first) and a call-convention (explain it in reason), covering both selection and invocation 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses that the change is persisted immediately ('Saved when this runs'), that the user will see a reason on an approval card, and that re-adding an existing query moves it rather than duplicating — which is exactly what makes the idempotent hint meaningful.

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

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

Front-loaded with purpose, then defaults, then the alternative tool, then the prerequisite — a logical order with no filler. It is dense (multiple clauses packed into two sentences), but every clause carries information an agent needs.

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

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

For a mutating, nested-parameter tool with no output schema, the description covers prerequisites, persistence semantics, placement defaults, and the competing tool. The only small gap is that it doesn't hint at what the call yields (e.g. the created panel identifier), which matters slightly more given there is no output schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra credit by explaining the interaction between the optional parameters: position inserts among query panels in reading order, gridPos overrides placement and sizing, and omitting everything gives a default 12x8 appended panel. That precedence is not stated anywhere in the schema.

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

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

States a specific verb and resource ('Show an existing saved query on a dashboard as a panel') and immediately clarifies the one-to-many relationship. It is clearly distinguishable from create_<queryType>_query and remove_query_from_dashboard without opening either schema.

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

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

Explicitly routes the agent away from this tool when a new chart is needed ('To save a new chart, use create_<queryType>_query with dashboardId instead') and states a prerequisite ('Load the manage-dashboards skill ... first'). It also explains the default versus explicit placement behavior, so the agent knows which path to take.

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

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

Annotations declare write, idempotent, non-destructive, but say nothing about timing or preconditions. The description adds that the change applies immediately but takes effect on the unit's next configuration fetch, restricts to scheduled/active experiments, and implies an approval workflow via the reviewer-facing reason field — all behavior an agent needs and none of it is in the structured fields.

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

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

Front-loaded with the core action and its four modes, then prerequisites, then timing. Every sentence carries information, though the action enumeration partially duplicates the enum descriptions already present in 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 10 parameters, no output schema, and a mutation that affects live experiment membership, the description covers preconditions, propagation timing, and the workflow entry points. It leaves unstated what the caller gets back and how failures (e.g. unit type mismatch, wrong experiment state) surface, which is the main residual gap.

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

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

Schema coverage is 90% and the schema already defines the action enum, groupId's 'required for assign only' rule, the unitType/environment constraints, and the ignore* flags. The description restates the action modes compactly but adds no meaning to the one undocumented parameter (experimentId) and no format details beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Change one unit's place in an experiment') and then enumerates the four distinct modes (assign, clear_override, unenroll, reactivate) in plain language. An agent can distinguish this from siblings like update_experiment_rollout or terminate_experiment without opening 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?

Gives concrete use cases ('Use for QA (put a tester in the treatment) or to exclude a unit'), a precondition ('Only works on scheduled or active experiments'), a prerequisite read ('Check the unit's current state with list_experiment_members first'), and a required skill load. When-to-use and alternatives are explicit rather than inferred.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, and the description reinforces this with 'Saved when this runs', so the mutation is explicit. It also discloses the uniqueness constraint on names (a failure mode) and that reason is surfaced on an approval card. It stops short of covering permissions, error behavior on duplicate names, or what the response contains.

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 front-loaded sentences, with the save action and the uniqueness/dry-run prerequisites leading. The final sentence stacking two load_skill calls is slightly cluttered but every sentence carries actionable instruction.

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 parameter is a deeply nested AST, so the description wisely delegates to the cohorts skill and the dry-run tool instead of restating the schema, which is appropriate. With no output schema, it still tells the agent to derive the member count via run_cohort_definition, leaving little an agent needs missing.

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

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

Schema description coverage is 100%, so the schema already documents name, reason, projectId, definition, description and environment in detail. The description adds only marginal framing ('explain it in reason', 'optional description'), and calling description 'optional' sits slightly against the schema's 'Always write one', which muddies rather than clarifies. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource with scope: 'Save a new cohort (player segment) in the current project'. The word 'new' implicitly separates it from the sibling update_cohort, and the parenthetical gloss makes the domain object 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?

Gives an explicit pre-flight workflow: check list_cohorts first because names are unique, then dry-run with run_cohort_definition to obtain the member count, and load the manage-cohorts/cohorts skills before calling. That is real when-to-use and how-to-prepare guidance rather than an implied usage note.

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

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

Goes well beyond the annotations by disclosing the key lifecycle fact that the new configuration is not primary and therefore does not reach game servers until promoted or read by alias. It also bounds the security meaning of privateKeys (hidden from game clients but visible in the dashboard, unsuitable for real secrets) and notes the audit behavior of 'reason'.

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

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

Dense but front-loaded: creation, uniqueness, primary-status consequence, privateKeys caveat, then the reason requirement. Nearly every clause earns its place, though 'The configuration is created when this runs' is close to tautological and could be folded into the primary-status sentence.

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

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

For a 7-parameter mutation with full schema coverage and no output schema, the description covers the important operational context: uniqueness, activation gate, private-key scope, and audit reason. The only gap is that it never hints at what comes back (e.g. the new configuration's identifier) for use in follow-up calls.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by adding constraints the schema does not state, such as 'comments cannot' be private and that privateKeys is for values like a random seed rather than secrets. It adds the naming uniqueness contract and the mandate to always write a description even when unasked.

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 configuration in this project environment, optionally with initial JSON content') and implicitly separates it from update_configuration, get_configuration, and list_configurations by describing creation-time semantics. An agent can tell what it produces without opening 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?

Gives an explicit prerequisite ('Names must be unique — call list_configurations first') and explains the downstream alternative for activation ('set_primary_configuration'). It does not explicitly contrast create vs. update/duplicate for an existing configuration, so it falls short of a full when/when-not guide.

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

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

Annotations already declare a non-read-only, non-idempotent, non-destructive write. The description adds useful context beyond that: creation happens when this runs, the name must be unique, and the 'reason' surfaces on an approval card the user will read. It doesn't cover failure modes or whether the new dashboard is returned, but the added operational context is meaningful.

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

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

Purpose and the collision-avoidance rule are front-loaded, followed by the chart workflow and the skill prerequisite. It's dense with four short sentences but each carries actionable content; the skill-load instruction could arguably be trimmed into the first line.

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

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

For a 9-parameter mutation with no output schema, the description covers prerequisites (list_dashboards, load_skill), the post-creation chart workflow, and the reason field's purpose. Only the return value or confirmation behavior is unaddressed, which is minor given the depth of guidance provided.

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 each of the 9 parameters is already documented. The description reinforces the ordering of queryIds and the uniqueness of name, but adds little semantic detail beyond the schema, so 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?

States a specific verb and resource ('Create a new analytics dashboard') and adds scope detail about optionally attaching existing saved queries in order. The agent can distinguish it immediately from siblings like update_dashboard or duplicate_dashboard.

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

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

Explicitly says to check list_dashboards first to avoid name collisions, mandates loading the manage-dashboards skill before proceeding, and spells out the follow-up workflow using create_insight_query / create_funnel_query / create_retention_query with dashboardId. This is genuine when-and-how guidance, not an implied hint.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive mutation, and the description adds real context beyond that: the folder is created immediately when the call runs, and the reason string appears on a user-facing approval card, implying a human-in-the-loop gate. The 6-level nesting constraint adds another behavioral limit. It stops short of describing the return value or collision behavior on duplicate names.

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

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

Three short sentences, front-loaded with the core action and constraint, then the mutation/approval note, then the prerequisite. Very little waste; the middle sentence is slightly compressed but still 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 an 8-parameter mutation with no output schema but full schema coverage, the description supplies purpose, the nesting depth cap, the approval-card semantics of reason, and the required skill prerequisite. What is missing is minor: whether the new folder id is returned and how name conflicts are handled.

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 name, color, icon, index, parentId, projectId, and environment in detail. The description only restates that nesting is capped at 6 levels (already in the parentId description) and that reason should be one explanatory sentence (already in the reason description). Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Create a dashboard folder,' plus the key qualifier that it may be nested (max 6 levels). This is clearly distinct from create_dashboard and update_dashboard_folder by resource and operation, though it never names those siblings explicitly.

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

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

It gives a genuine workflow prerequisite ('Load the manage-dashboards skill first'), which tells the agent when in the process to call this. However, there is no guidance on when to use create_dashboard_folder versus create_dashboard or update_dashboard_folder, nor any exclusion or 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?

Beyond the destructive/non-idempotent annotations, the description discloses the side effects that matter: changed paths are locked against other experiments and configuration edits until the experiment ends, creation happens immediately on this call, the reason is recorded with the change, and a default start time applies. What it omits is what the call returns and what happens on validation failure (e.g. mismatched baseValue), so it is strong 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?

Front-loaded with the core action and organized from mechanics to prerequisites to guardrails, with no filler sentences. It is dense at roughly seven sentences, and 'The experiment is created when this runs' restates the obvious mutation, but every other sentence carries load-bearing 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 four-parameter but deeply nested request with no output schema, the description covers the failure-prone parts (fresh baseValue, lock conflicts, skill prerequisite, immutability) that an agent would otherwise get wrong. The remaining gap is the absence of any mention of the response or what identifiers come back after creation.

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% and the schema itself documents many fields, yet the description still adds meaning the schema does not: baseValue must equal the real current value in the base configuration, weights must total 100, and reason is what the approver reads. It does not elaborate on rollout, targeting, or assignmentMode, leaving those entirely to the schema.

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

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

States a specific verb and resource ('Create an A/B experiment on a configuration') and immediately explains the mechanism (groups apply set/add/delete operations to assigned units, weights split eligible units), which separates it cleanly from preview_experiment, get_experiment, terminate_experiment, and update_experiment_rollout.

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

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

Gives explicit prerequisite sequencing: load the manage-experiments skill first, read exact current values via get_configuration or search_configuration and pass them as baseValue, and check list_experiment_locks for already-taken paths. It also states the lifecycle constraint (cannot be edited after creation, only terminated), which tells the agent when this tool is the right one versus a later update path.

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

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

Annotations already declare it is not read-only and not destructive, and the description adds real value: the query is persisted the moment this runs, dashboard attachment requires edit permission, and the call surfaces an approval card to the user. It does not warn that the call is non-idempotent and could create duplicate charts if retried, which is the main missing behavioral note.

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

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

The core action and the critical prerequisite are front-loaded, and every sentence carries instructions. The final skill-loading sentence is a bit of an appendix, but it is actionable rather than 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 create tool with a deeply nested spec and no output schema, the description never says what comes back — notably the created chart/query id an agent would need to update or attach it later. Permissions, prerequisites, and approval behavior are covered well, so the gap is narrow but real.

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 all seven parameters are already documented, including reason, dashboardId append behavior, and description. The description mostly restates that spec must match the run_funnel_query spec, adding only marginal meaning over the schema.

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

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

States a specific verb and resource ('Save a new funnel query as a chart') plus the optional side effect of dashboard attachment. It also implicitly distinguishes itself from run_funnel_query, which executes rather than persists, and from update_funnel_query, which modifies an existing chart.

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 prescribes the prerequisite ('run it first so you know it works'), names the exact spec source (run_funnel_query), states the extra permission needed for dashboard attachment, and directs the agent to load the manage-dashboards and funnel-queries skills before calling. This is near-complete when/when-not guidance.

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

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

Annotations already declare a non-readonly, non-idempotent, non-destructive write, so the description adds genuinely new context: dashboard attachment requires edit-dashboard permission, the query is persisted on invocation, and reason surfaces on an approval card. It does not describe the returned identifier or confirmation, but the added operational and authorization context is substantial.

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

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

Front-loads the core action and dashboard attachment, then moves to prerequisites and permissions in decreasing order of importance. The trailing skill-loading sentence is useful but slightly cluttered by the repeated inline function syntax.

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 7-parameter tool with a deeply nested heatmap spec, the description covers the workflow, the permission requirement, and the persistence side effect well. With no output schema, it leaves unstated what comes back (chart or query id) and how to later modify the saved chart via update_heatmap_query, which is the remaining gap.

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 spec, dashboardId, reason, name, projectId, and environment thoroughly. The description reinforces that spec must be the exact previously-executed payload and that reason must explain the change, but those points largely restate the schema's own descriptions, 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?

States a specific verb and resource — save a new heatmap query as a chart, optionally attaching it to a dashboard — and implicitly contrasts with run_heatmap_query (execute) versus update_heatmap_query (modify). An agent can distinguish this from the other create_*_query siblings because it names the heatmap resource explicitly.

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

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

Gives a concrete precondition for invocation: run run_heatmap_query first and pass that exact spec, plus load the manage-dashboards and heatmap-queries skills beforehand. It lacks an explicit when-not statement (e.g. 'use update_heatmap_query to modify an existing saved heatmap query'), which is the only gap.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the write/repeat-run nature is partly covered. The description adds value beyond that by stating the query is persisted when this runs and that attaching to a dashboard requires dashboard-edit permission — a real auth constraint not visible in annotations.

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

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

Four short sentences, front-loaded with the action and followed by prerequisites and permission notes; nothing is padded. The skill-loading sentence is slightly boilerplate but still functional guidance, keeping it just below a top score.

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 7-parameter mutation tool with a large nested spec, the description covers the workflow, the spec-reuse requirement, permission needs, and the optional dashboard link. The only notable gap is that it never indicates what comes back on success (e.g. a saved query id), which would help an agent chain further calls.

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 still adds meaningful guidance by telling the agent the spec must be the exact one previously validated via run_insight_query, and that reason is what gets shown on the approval card — context the schema text does not fully carry.

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

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

The opening sentence gives a specific verb and resource — 'Save a new insight query as a chart' — plus the optional dashboard attachment, which cleanly separates it from run_insight_query (execute) and update_insight_query (modify existing). An agent can tell what this creates without opening 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?

It gives a concrete workflow prerequisite: run the spec with run_insight_query first and reuse the exact spec that succeeded. It also states the dashboard-edit permission requirement and directs loading the manage-dashboards and insight-queries skills first. It stops short of saying when to prefer update_insight_query or add_query_to_dashboard instead, so not a full 5.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds real value beyond those: it discloses that the query is persisted immediately on invocation, that dashboard attachment requires edit-dashboard permission, and that it is a creation (hence non-idempotent) operation. It does not spell out what happens on duplicate names, which keeps it from a 5.

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

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

Front-loaded with the core action, then the prerequisite, permission note, and skill-loading instruction in descending order of importance. Slightly dense with parenthetical function-call syntax, but no sentence is wasted.

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

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

Given a deeply nested spec schema and no output schema, the description correctly offloads spec details to run_retention_query and the skills, and covers the critical preconditions. It stops short of describing what the created chart reference looks like, but the schema depth and sibling guidance compensate.

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 every parameter including name, description, reason, projectId, environment, and dashboardId is already documented in the schema. The description reinforces the spec-provenance constraint and the reason field but mostly restates what the schema says, so the baseline 3 applies.

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

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

States a specific verb and resource ('Save a new retention query as a chart') plus the optional secondary effect (add to dashboard). An agent can distinguish it from run_retention_query and update_retention_query without inspecting either schema.

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

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

Explicit sequencing guidance: run run_retention_query first, pass that exact spec, and load the manage-dashboards and retention-queries skills before calling. It also names the permission precondition for the dashboard path, leaving little to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the write/non-idempotent profile is known. The description adds real value beyond that: "Saved when this runs" clarifies the save takes effect immediately on execution, the duplicate-check instruction reinforces the non-idempotent warning, and "explain it in reason" signals the user-facing approval card. It does not say what a duplicate attempt does (reject vs. create another) or what is returned.

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?

Five short sentences, front-loaded with the core identity of the tool before the workflow prerequisites. Nothing is redundant. The phrasing is telegraphic ("Saved when this runs; explain it in reason"), which is efficient but slightly terse for a mutation.

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 with a deeply nested definition schema, 5 required parameters, and no output schema, the description covers the workflow prerequisites, the expression/metrics linkage, and the user-facing reason. Remaining gaps (return value, duplicate-name behavior, display formatting) are modest against a schema that documents most 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 only 50%, and the bare `expression` field is just a length-bounded string, so the note that letters A, B, … in the expression refer to the entries of `metrics` in order supplies non-obvious meaning the schema cannot. It also directs the `reason` field's content for the approval card. It says nothing about `name`, `description`, `projectId`, `environment`, or `definition.display`, leaving roughly half the surface to the schema.

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

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

States a specific verb and resource: "Save a reusable formula: an expression plus its own metrics," and clarifies the internal structure (letters A, B map to metrics in order). It implicitly separates itself from list_saved_formulas and update_saved_formula via the entities involved, though it never names update_saved_formula as the editing counterpart, so sibling differentiation is only partial.

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

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

Gives an explicit ordered workflow: load the insight-queries skill first, dry-run the expression as a self-contained formula metric in run_insight_query, check list_saved_formulas to avoid duplicates, then save. It names the two alternative tools (run_insight_query, list_saved_formulas) and the condition under which each is used before this one.

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

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

Annotations only declare it as non-read-only, non-idempotent, and non-destructive; the description adds substantial context beyond that, including the hard 60-event cap, exact case-sensitive naming, and a real side effect ('each event's description and property descriptions are also copied into the event list where the event has none yet'). It also explains the post-save lifecycle (Gamebeast tracks events from planned to verified as data arrives), which helps the agent set expectations. It stops short of describing what the call returns or failure behavior, keeping it just under a 5.

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

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

The core action is front-loaded in the first sentence, with prerequisites and constraints following in priority order. Four sentences are all relevant, though the clause about descriptions being copied to the event list is embedded mid-paragraph and could be separated for scanability. No filler or marketing language.

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 nested, mutating creation tool with no output schema and 83% schema coverage, the description covers prerequisites, limits, side effects, and lifecycle well enough to call correctly. The main remaining gap is that it doesn't tell the agent what happens on success (e.g., an id or plan reference returned), which matters slightly for chaining into update_tracking_plan_items, but that is mitigated by the named follow-up tools.

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 already 83%, so the schema carries most parameter meaning (title, reason, projectId, environment, nested event fields). The description reinforces a few semantics, notably that reason is user-facing ('Saved when this runs; explain it in reason') and the 60-item cap, but these largely repeat schema constraints rather than adding new meaning. Baseline 3 is appropriate given the high 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 ('Save a tracking plan') and immediately enumerates the payload content: events ('marker types') with when they fire, why they matter, placement, and typed properties. It distinguishes itself from update_tracking_plan_items and get_tracking_plan by naming them as downstream/companion tools rather than alternatives, so an agent can identify the create path without opening 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?

Explicit preconditions and routing are given: 'Check list_event_types and get_tracking_plan first: continue an open plan rather than starting another, and don't plan events the SDK already sends by default.' It also mandates loading the manage-events skill first, which is a concrete when-to-use gate. Exclusion guidance (no default SDK events, no duplicate plans) is stated directly rather than inferred.

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

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

Annotations already flag destructiveHint=true and non-idempotent, but the description adds what annotations cannot: the referential-integrity consequence (queries and cohorts referencing it keep a broken reference), the server-side guard for active/upcoming experiments, and the required workflow prerequisite (load_skill). That is substantive behavior beyond structured fields.

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

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

Front-loaded with the action and permanence, then hazards, then workflow. Five short sentences all earn their place, though the reason/confirmation instruction is slightly split across two sentences and could be tighter.

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

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

For a destructive 4-param tool with no output schema, the description covers the irreversible effect, the blocking conditions, the side effects on referencing objects, and the required pre-call workflow. Nothing an agent needs before invoking it is missing.

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

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

Schema coverage is 100% and each parameter is already documented (reason is 'why you are making this change', cohortId from list_cohorts, etc.). The description only reinforces 'explain it in reason' and gives the cohort-name confirmation requirement; it adds little syntax or format meaning beyond the schema, so baseline 3 applies.

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

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

Specific verb 'Permanently delete' plus resource 'saved cohort' plus scope 'current project'. It is clearly distinguished from update_cohort and create_cohort, and the permanence qualifier separates it from reversible 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?

Gives explicit when-to-use preconditions (confirm exact cohort by name with the user first, load manage-cohorts skill first) and an explicit when-not condition (refused while an active or upcoming experiment targets it), plus the alternative for finding the cohort (from list_cohorts in schema).

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

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

Annotations already declare destructive=true, idempotent=true and readOnly=false, yet the description still adds substantial value: irreversibility, the two hard preconditions, the downstream effect on game servers resolving the configuration by alias, and that the deletion executes immediately rather than being staged for approval. This is exactly the kind of blast-radius detail annotations cannot express.

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

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

Front-loaded with the action, then consequences, then preconditions, then the reason requirement — a logical order with no filler. "This cannot be undone from here" and "The delete happens when this runs" are close in intent (irreversibility vs synchronous execution) but read slightly redundant.

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 destructive, no-output-schema operation this covers timing, failure preconditions and side effects well. It omits permission/authorization requirements and what an error response looks like when a precondition blocks the delete, which an agent handling failures would want.

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 goes slightly beyond by telling the agent to always populate reason and that it is recorded with the change, complementing the schema's note that it is shown to the approver. projectId, environment and configurationId are left entirely to the schema, which is acceptable given full 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?

States a specific verb and resource ("Delete a configuration") plus its scope ("from this project environment"), which clearly distinguishes it from get_configuration, list_configurations, update_configuration and create_configuration. An agent can identify the operation without opening 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?

Gives explicit when-not conditions: the primary configuration and configurations backing a scheduled or running experiment are off limits, and it supplies the remediation path ("make another one primary first"), implicitly pointing at set_primary_configuration. It does not reference sibling tools by name (e.g. preview_configuration_change, search_configuration for finding an id), so routing is inferred rather than spelled out.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds genuinely new behavior: only the dashboard object is removed, its queries persist elsewhere, and the action is irreversible "from here" and takes effect immediately. It does not address repeat-invocation behavior despite the idempotent hint, which keeps it just under a 5.

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

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

Four short sentences, front-loaded with the action and its scope, then the irreversibility warning, then the prerequisite. The clause "Deleted when this runs; explain it in reason" is slightly compressed and awkwardly punctuated, but nothing is padding.

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

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

No output schema exists, but the description covers what an agent needs for a destructive, 4-required-param call: effect scope, irreversibility, required justification, and the skill prerequisite. It does not state what a successful response looks like or how to recover from a wrong dashboardId, a minor gap for an irreversible operation.

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 dashboardId, projectId, environment, and reason are all already documented in the schema. The description only echoes the reason parameter ("explain it in reason") without adding format or approval-card context beyond what the schema states, so baseline 3 applies.

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

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

States a specific verb and resource ("Delete a dashboard") and immediately scopes the blast radius by clarifying that saved queries survive and remain in list_queries. That distinguishes it cleanly from delete_query and delete_dashboard_folder without the agent needing to open any schema.

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

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

Gives a concrete prerequisite (load the manage-dashboards skill first) and implicitly routes query-only deletions to delete_query by stating the queries are kept. It stops short of naming delete_query explicitly or saying when not to delete, so it is clear context rather than 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?

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is known; the description still adds genuine value by disclosing the cascade behavior (children get reparented, not destroyed) and that the delete takes effect immediately. It leaves out reversibility/undo and any permission 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 short sentences, action front-loaded, with the consequence of the call before the prerequisite. The fragment "Deleted when this runs" is terse to the point of ambiguity but wastes no words.

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

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

For a destructive four-parameter mutation with no output schema, the description covers what happens to child objects, immediacy, the required justification, and a prerequisite skill. Remaining gaps (undo, permissions, return value) are minor given the annotation coverage.

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 all four parameters are already documented, including reason and folderId semantics. The description's "explain it in reason" restates the schema rather than adding format or constraint detail, so baseline 3 applies.

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

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

States a specific verb and resource ("Delete a dashboard folder") and immediately delimits scope: dashboards and subfolders move to the parent, "no dashboard is deleted." That contrast distinguishes it from delete_dashboard and delete_query without the agent needing to open a schema.

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

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

Gives an explicit prerequisite workflow (load the manage-dashboards skill first) which is real when-to-use guidance. It does not, however, contrast this with update_dashboard_folder or explain when reparenting-delete is preferable to moving contents manually.

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

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

Annotations already declare destructiveHint and idempotentHint, but the description adds real context beyond them: deletion is cross-dashboard in scope, irreversible "from here," and gated by a human approval card that surfaces the reason. It does not describe the return value or what happens to panels left empty, but that is a minor gap given the annotation coverage.

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

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

Four short sentences, front-loaded with the destructive scope before the alternative and the skill prerequisite. Slight compression loss in "Deleted when this runs; explain it in reason," which reads telegraphically and requires the reader to infer what "it" refers to.

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 destructive mutation with four required params and no output schema, everything an agent needs is present: scope of destruction, irreversibility, the safer alternative, the approval-reason expectation, and the required skill step. Nothing essential is left to inference.

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 all four parameters are already documented in detail, including the approval-card semantics of reason. The description only reinforces that reason should explain the deletion; it adds no new syntax, format, or constraint information beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ("Permanently delete a saved analytics query") and immediately clarifies the blast radius ("disappears from EVERY dashboard"). The final routing sentence distinguishes it from the closely named sibling remove_query_from_dashboard, so an agent can choose without inspecting either schema.

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

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

Gives an explicit when-not and the alternative: use remove_query_from_dashboard to remove from one dashboard but keep the query. It also states a precondition — load the manage-dashboards skill first — which is actionable 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?

Beyond destructiveHint=true and idempotentHint=false, it discloses the non-obvious downstream effect: linked saved queries keep rendering the last version with a warning until someone detaches them. It also states that deletion happens immediately when this runs and that the reason string is user-facing on the approval card.

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

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

Four short sentences, with the permanent-deletion fact front-loaded and the prerequisites following in order. The clause "Deleted when this runs; explain it in reason" is slightly compressed but not wasted.

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

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

For a destructive mutation with no output schema, the definition covers consequences, side effects on dependents, verification steps and a required skill load. With all four parameters fully described in the schema and safety hints in annotations, 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 coverage is 100%, so formulaId, projectId, environment and reason are already documented in the schema. The description only adds a light nudge to explain the deletion in reason, which largely restates the schema's own wording about the approval card.

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?

"Permanently delete a saved formula" gives a specific verb plus resource and makes the contrast with update_saved_formula obvious from the name alone. The word "permanently" signals irreversibility right away.

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 prescribes concrete preconditions before calling: verify the formula by name and count dependent queries via list_saved_formulas with formulaId, and load the insight-queries skill first. It does not state when a caller should instead use update_saved_formula or detach queries rather than delete, so the alternative path is implied rather than spelled out.

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

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

Annotations declare a non-read-only, idempotent, non-destructive mutation, and the description goes further by disclosing patch semantics (omitted fields are unchanged, null or empty string clears a value) and per-call caps of 100 types and 500 arguments. This is the kind of context annotations cannot carry. It's weaker on what the call returns and how a partial failure across many types/arguments behaves.

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?

Sentences are front-loaded and each earns its place: what it does, the pre-ship scenario, patch semantics, caps, save behavior, and the skill prerequisite. The phrasing is dense and readable. The only weakness is that the crucial prerequisite appears last rather than up front, and 'and/or hide or show them' is slightly loose.

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 five-parameter mutation with no output schema, the description supplies the essential context: that it writes immediately, that it applies partial patches, that it is meant for pre-instrumentation use, that it is capped per call, and that it requires a skill load first plus a human-readable reason. An agent has enough to call it correctly without opening the schema.

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

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

With 100% schema description coverage, the schema already documents reason, projectId, environment, and the omitted-keeps-current / null-clears semantics of each nested field. The description mostly restates that behavior and adds the batch limits (100/500), which the schema expresses structurally as maxItems. It adds confirmation rather than new meaning, 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 opens with a specific verb and resource: 'Describe analytics event (marker) types and their arguments, and/or hide or show them in the dashboard's query builder.' It also makes the write semantics clear ('Saved when this runs', 'Patches are partial'), which implicitly distinguishes it from the read-only list_event_types sibling. It stops short of naming that sibling, so sibling differentiation is left to inference rather than stated outright.

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 preparatory scenario (describe events while instrumenting the game, before shipping so the descriptions exist when data arrives) and a hard prerequisite ('Load the manage-events skill first'). What's missing is a negative boundary: it never says when to use list_event_types for reading instead of this tool for writing.

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

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

Annotations only declare write/non-idempotent/non-destructive, but the description adds real semantic behavior: queries are deep-copied so the copy is independent of the original, the action happens immediately when invoked, and a user-facing reason is required for the approval card. The minimum-query precondition is likewise behavior an agent could not get from 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?

Four short sentences, front-loaded with the action and scope, then non-obvious constraints. No filler or restatement of the tool name.

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 mutating tool with no output schema, it covers side effects, independence of the copy, and preconditions well. The one remaining gap is that it never says what comes back (presumably the new dashboard's id), which an agent would want in order to chain further calls.

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 name, reason, projectId, dashboardId and environment are already fully documented. The description only reinforces that the new name is chosen here and that reason is user-facing, which duplicates rather than extends 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 opening sentence gives a specific verb (copy) and resource (a dashboard) with an explicit new name, and the follow-up clarifies that all queries are copied too, which separates it from create_dashboard. It stops short of naming any sibling tool outright, so the routing signal is inferential rather than explicit.

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

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

It supplies a hard precondition ('must have at least one query') and a workflow prerequisite (load the manage-dashboards skill first), which are the main things that could make a call fail. It does not say when to prefer create_dashboard or update_dashboard over duplication, so alternative selection is left to inference.

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

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

Annotations only declare non-read-only, non-idempotent, non-destructive; the description adds the key facts those hints cannot convey: the key is shown exactly once, retries are rate-limited/refused, storage is platform-specific (Roblox server-side only), and the reason string is persisted on the key. It does not describe the response shape beyond the storage note, so it stops short of a 5.

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

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

Purpose is front-loaded in the first sentence, followed by precondition, result/security, and retry behavior in a logical order. Every sentence carries information, though the security admonition about not printing the key is agent-policy guidance rather than a property of the tool itself.

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 must carry the return contract, and it does partially by saying the result indicates where the key must be stored. Combined with the one-time-visibility and retry-refusal notes, an agent has enough to call this safely, though the actual response fields are not described.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by explaining that `reason` is recorded on the key (which is why it must justify the need) rather than being a throwaway note. `label`, `projectId`, and `environment` are left entirely to the schema, which already handles them 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?

States a specific verb and resource ('Create a Gamebeast SDK key') plus an immediate gloss of what the resource is ('a public key for the game client or server SDK'), scoped to project and environment, and notes the one-time return. No sibling tool overlaps, and an agent can tell exactly what this 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?

Gives an explicit precondition with concrete search targets (.env files, secret/config modules, an existing Gamebeast:Setup / GamebeastSdk.Setup call) and says to call only when none is found. It also warns that a second call within a few minutes is refused, which is real when-to-call guidance an agent would otherwise trip over.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds real value on top: the automatic chart rendering is a visible side effect the agent should know about, and the heatmap breakdown exclusion is a genuine behavioral limit not encoded in the schema. It still omits error behavior, whether the chart render is suppressible, and what the raw result payload looks like.

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

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

Three sentences, no filler, with the core action stated first and constraints following. The skill-loading prerequisite is arguably the most critical instruction yet sits last, which is a minor front-loading weakness rather than a wording problem.

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 carries the burden of explaining returns, and 'return its results' plus 'rendered as a chart' is thin for a tool whose payload is the whole point. For a 5-parameter tool with a deeply nested time-range schema, the absence of any guidance on relative-vs-absolute time construction leaves a meaningful gap.

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 earns above that by clarifying that `time` and `breakdowns` are overrides that replace the saved query's stored values, and by flagging that `breakdowns` does not apply to heatmaps. It does not explain how to choose between the relative and absolute branches of the nested `time` object, which is the most error-prone part of 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 gives a specific verb and resource ('Execute a saved analytics query') and enumerates the supported query kinds (insight, funnel, retention, heatmap). The word 'saved' plus the required queryId distinguishes it from the ad-hoc run_insight_query / run_funnel_query / run_retention_query / run_heatmap_query siblings, though it never names them explicitly to confirm the distinction.

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

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

It gives a concrete prerequisite ('Load the run-analytics-query skill first') and states what can and cannot be overridden (breakdowns unsupported for heatmaps). What it lacks is an explicit routing rule: it never says when to prefer this over the sibling run_*_query tools or get_query, so the agent must infer that this is the path for an already-saved query.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered. The description adds the qualifier 'current,' hinting that the count is live rather than historical, but never clarifies freshness, whether it is exact or approximate, or what the return value looks like (there is no output schema).

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

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

Two short sentences with zero waste: purpose first, then the intended use case. Nothing is repeated and nothing is buried.

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 three-parameter read tool with full schema documentation and annotations covering safety, the description covers what is needed to call it correctly. The only real gap is the shape of the return value, since no output schema exists to state that the count is a plain number.

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 each of cohortId, projectId, and environment documented in the schema itself, so the baseline applies. The description adds no parameter-level meaning beyond what the schema already supplies.

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: 'Return the current member count for a player cohort.' That distinguishes it in spirit from get_cohort_members and get_cohort_membership, but the description never names those siblings, so the differentiation is implicit rather than explicit.

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

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

'Use to size a cohort before sampling members or checking membership' gives a clear motivating context for calling it. It stops short of naming the alternatives (get_cohort_members, get_cohort_membership) or stating 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: results are a *sample*, not an exhaustive list, and must be paginated. It stops short of explaining what kind of sample (random vs. first-N) or whether pagination is stable across pages, which materially affects how an agent interprets results.

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, zero filler, with the core purpose front-loaded and the pagination constraint immediately after. 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 read-only tool with no output schema, the description conveys the essential shape of the return value (player ids) and the pagination model, which is what an agent most needs. The only real gap is the undefined nature of the sample and any cap on pages, a minor omission given the fully documented schema and annotations.

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 cohortId, projectId, environment, pageSize (default 25, max 100) and pageNumber all documented inline, including pointers to list_projects. The description adds nothing beyond that, 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?

The description names a specific verb and resource: returning a paginated sample of player ids within a cohort. That is clearly distinct from sibling tools like get_cohort_member_count or list_cohorts, though it never explicitly contrasts itself with get_cohort_membership, which an agent might confuse it with.

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 one concrete operational instruction — page through results rather than dumping all members in one call — which is real when-to-use guidance. However, it offers no routing guidance versus siblings (get_cohort_membership, get_cohort_member_count, run_cohort_definition), leaving the agent to infer which cohort tool to pick.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered by structured data. The description adds only the 250-id cap, which is already in the schema's maxItems. It says nothing about whether non-member ids are omitted or returned as false, or about failure modes for invalid cohort/project ids.

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, zero filler, and the core purpose is stated first with the usage constraint second. Nothing is redundant or buried.

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 leaves the return shape unexplained: an agent cannot tell whether it receives a boolean per id, a subset of matching ids, or per-id status objects. For a simple read-only lookup with full schema coverage and safety annotations, this is the one remaining gap, but it is a real one.

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 all four parameters (userIds, cohortId, projectId, environment) are already documented, including the 1–250 range and the pointer to list_projects. The description restates the player-id and batch-limit semantics rather than adding new meaning, 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?

The description uses a concrete verb and resource: 'Check whether specific player ids belong to a cohort.' An agent can immediately tell this is a membership test rather than a listing or count. It stops short of naming the closely related siblings (get_cohort_members, get_cohort_member_count), so differentiation is implicit.

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

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

'Use for bulk "is player X in cohort Y" lookups (up to 250 ids per call)' gives a clear usage context and the intended batch pattern. However, it never states when NOT to use it or names the alternative tools — notably get_cohort_members, which the agent could easily confuse with this one. Usage is implied more than routed.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description is fully consistent with a safe read. Beyond that it discloses the non-obvious behavioral traits: the data is a pre-synthesized snapshot rather than live data (with query_sentiment named as the live alternative), and that quote ids are indirect references requiring a second resolution call.

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

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

Front-loaded with the core definition before the routing guidance, and each sentence carries actionable information. The 'fastest way to get a high-level picture of player sentiment' line mildly restates the pre-synthesized framing, a small redundancy in an otherwise tight definition.

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

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

There is no output schema, so the description carries the return-value burden and does so thoroughly by naming every returned field group and the quote-id indirection. Combined with the sibling routing and skill preloading instruction, nothing an agent needs to invoke and interpret this 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% and both parameters (projectId, environment) are documented in the schema itself, including the list_projects discovery hint. The description adds no additional meaning about scoping, defaults, or environment semantics, so it sits at the baseline for a fully documented two-parameter schema.

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

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

States a specific verb and resource ('Get the latest Community Pulse snapshot') and immediately defines it as 'the pre-synthesized topic rollup the dashboard's Community Pulse page shows', which anchors it to a concrete artifact. It also enumerates the payload (volume, sentiment split, trend, insight clusters, quote ids), so an agent can distinguish it from query_sentiment without opening either schema.

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

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

Explicitly routes between this tool and the sibling: use this for a high-level picture, use query_sentiment for live data, drill-downs, or custom time windows. It even names the exact follow-up call syntax (query_sentiment({ operation: 'quotes', contentIds })) for resolving quote ids, and recommends loading the understand-community-pulse skill first.

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

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

Annotations only cover readOnlyHint and openWorldHint, but the description adds substantial behavior: a 20 KB byte budget with truncatedPaths reporting elision, _hidden: true marking of private keys that are hidden from SDK clients but not the dashboard, contentHash as a version token for optimistic concurrency, and deepLinkPath as a shareable ?path= fragment. These are exactly the operational facts an agent needs and none are inferable from annotations.

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

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

Purpose is front-loaded in the first sentence and subsequent sentences cover modes, truncation recovery, hidden keys, versioning, and documentation fields in a logical order. It is dense and mostly earns its length, though the deepLinkPath and description/keyDescriptions sentences could be tightened slightly.

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 six parameters, the description proactively explains the response payload surface (truncatedPaths, _hidden, contentHash, deepLinkPath, description/keyDescriptions) so the agent can act on the result without a return-type spec. Nothing material for a correct call is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description nevertheless adds cross-parameter meaning the schema lacks — that 'path' is a key array used specifically to drill into truncatedPaths, and that 'structure' is the default mode while 'values' is budget-bound. It does not restate depth semantics in more detail than the schema, so a 4 rather than 5.

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

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

States a specific verb and resource ('Read a configuration by id') and immediately distinguishes the operation from sibling reads (list_configurations, search_configuration) and writes (update_configuration) by describing the two read modes and their cost/safety tradeoff.

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 the agent: mode 'structure' is default and cheap/safe at root, mode 'values' is for actual values, and when output is truncated the agent should re-call with 'path' set to a truncatedPaths entry. It also names the follow-up tool (update_configuration_descriptions) for editing docs, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered structurally; the description adds useful context by disclosing exactly what the response contains (query, markdown, and image panel types with geometry). It says nothing about behavior when the dashboard id does not exist or about permission scoping, which would have completed the picture.

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

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

Two sentences, front-loaded with the action and payload, then the usage rule. The parenthetical list of panel fields is dense but each item earns its place by telling the agent what it can read from the result; minor trimming of "(board)" would tighten it further.

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

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

With no output schema, the description carries the burden of describing the return value and does so concretely, including panel types and grid coordinates, which is exactly what an agent needs before calling update_dashboard_layout. Nothing essential for a read-only, three-required-parameter fetch 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 projectId, dashboardId, and environment each documented including discovery via list_projects. The description only restates that lookup is "by id" and adds no scoping or format detail beyond the schema, 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?

The description uses a specific verb+resource ("Fetch a single analytics dashboard (board) by id") and immediately enumerates the payload: saved queries with type/chart style/events and every panel on a 24-column grid with id and x/y/w/h. This clearly distinguishes it from list_dashboards and from the panel-mutation siblings like add_markdown_panel.

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

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

It explicitly says to use it after list_dashboards for full detail on a specific board and before changing its layout, which gives the agent a clear position in the workflow. It does not state any when-not conditions or mention that update_dashboard_layout is the follow-up mutation tool by name, so it falls 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?

The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it details the returned fields, explains that assignedUnitCount null means counts could not be read rather than zero enrollment, and points to get_experiment_results for performance.

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 action and then enumerates the returned data in a dense but useful first sentence. Every subsequent sentence adds distinct value: id discovery, null-count semantics, the performance alternative, and the skill prerequisite.

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 carries the burden of explaining return content, and it does so by listing the major fields and group-level configuration changes. It also covers the important null-count caveat and performance alternative, making the definition complete for a read-only single-experiment fetch.

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 projectId, environment, and experimentId. The description only indirectly helps by saying to use list_experiments to find ids; it does not add further meaning about how projectId or environment scoping works.

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 gives a specific verb and resource: 'Fetch one experiment by id'. It enumerates exactly what the result contains, including state, unit type, schedule, base configuration, targeting, group allocations, and configuration changes, which clearly distinguishes it from list_experiments and get_experiment_results.

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

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

It explicitly names list_experiments as the way to find ids and get_experiment_results as the better performing alternative when appropriate. It also states a required prerequisite to load the understand-experiments skill first, leaving little ambiguity about when and how to use the tool.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial computation semantics beyond that — counting starts only after unit assignment, denominators are enrolled units over the experiment's run, non-control groups are compared with a two-sided test yielding lift, 95% CI, p-value and one of four verdicts, plus a sample-ratio check. That is exactly the kind of behavior an agent needs to trust the output.

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

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

Front-loaded with the purpose, then prerequisites, then result shape; no sentence is filler. It is one dense block though — the metric-kind enumeration would scan better as a list, which is the only structural weakness.

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 takes on the burden of describing results and does so completely (lift, CI, p-value, verdict values, sample-ratio check), and it covers result-window semantics for the range parameter. 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?

The hardest parameter, `metrics`, is fully disambiguated: all three `kind` variants are defined, and `sum_per_unit`'s `value` (argument vs property) is explained with a concrete example ('revenue per player'). The remaining parameters (range, projectId, environment, controlGroupId) already carry schema descriptions, so the description's silence there is acceptable at 67% 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?

Starts with a specific verb and resource: 'Measure how an experiment's groups perform on up to 5 metrics, with statistics.' The scope (per-group, up to 5 metrics, statistical comparison vs control) is precise enough to distinguish it from get_experiment or preview_experiment without opening any schema.

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

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

Gives explicit prerequisites: resolve event/argument names via list_event_types / get_property_values first, and load the understand-experiments skill before calling. It does not, however, contrast this tool with named siblings such as preview_experiment or execute_query, so the when-not path is left implicit.

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

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

Annotations already declare readOnlyHint=true, and the description does not contradict that. It adds real behavioral context beyond the annotations: a 1024px maximum scale, the fact that the image is the bare map with no query overlay, and the X/Z orientation across the heatmap bounds. It does not cover return format, error behavior for a missing or not-yet-uploaded background image, or caching, which keeps it at a solid 3.

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

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

Front-loaded with the core action, then the use case, then the key caveat, then the coordinate convention and prerequisite — every sentence adds a distinct piece of information with no repetition 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?

With no output schema, the description does the work of describing the returned image (bare top-down map, max 1024px, X horizontal / Z vertical) and includes the required skill prerequisite, which is good. It still omits what happens when a heatmap has no uploaded background image and whether the response is a URL or binary payload, leaving a gap for an agent handling 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?

Schema description coverage is 100% and each parameter already documents its source (list_heatmaps, list_projects), so the schema carries the burden. The description mentions the heatmap's bounds, which loosely relates to heatmapId but adds no syntax, format, or constraint detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource ("Fetch a heatmap's background image") and immediately narrows it with concrete identifying detail: the top-down map of the game region uploaded by the SDK, capped at 1024px. This separates it cleanly from data-returning siblings like run_heatmap_query.

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 states the use case explicitly — see layout and name places when explaining heatmap query hotspots — and rules out a misreading by noting query results are not drawn on the map. It also gives an ordering prerequisite (load the heatmap-queries skill first) but never names the sibling tool an agent should call instead when it actually wants hotspot data.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered and the description only adds the downstream purpose of the result. It says nothing about result size, ordering, truncation, or scoping behavior beyond the schema, so genuine behavioral context is thin.

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

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

A single well-formed sentence with the core action front-loaded and the usage rationale immediately after. Nothing is redundant and the parenthetical examples are compact.

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 read-only lookup with 7 parameters (5 required) and no output schema, the description covers what the tool returns conceptually ('distinct values') but omits how many values come back, whether results are bounded, and how the optional event/search parameters shape output. Adequate but leaves real gaps for a multi-scope query 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 every parameter including the enums for kind and dataType is already documented in the schema; baseline 3 applies. The description's value examples (country codes, platform names, item ids) add only illustrative color, not new meaning for any parameter such as the optional event or search filters.

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

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

The description gives a specific verb and resource: 'Discover distinct values for a specific event property or argument', and even clarifies the two lookup modes (property vs argument) that map to the 'kind' enum. It is clearly distinct from siblings like list_event_types or describe_event_types, though it never names those alternatives.

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 states a concrete when-to-use condition: 'use before building string or number filters to know which values exist', which tells the agent to call this as a discovery step prior to filter construction. It stops short of explicit when-not guidance or naming sibling tools to use 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: a conditional response shape where `spec` is omitted for options agents cannot author, plus a `notEditable` field explaining why, and a skill-loading prerequisite. It stops short of describing error behavior or the dashboard-list shape, keeping it at a 4.

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

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

The purpose and return contents are front-loaded in the first sentence, with editing workflow and the editability caveat following in priority order. It is dense but nearly every clause carries actionable information; the skill-loading note at the end is slightly tacked on but useful.

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

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

There is no output schema, so the description must describe the return values, and it does: the editable spec tagged with queryType, the dashboards it appears on, and the notEditable degradation case. Combined with the prerequisite and the follow-up update path, an agent has everything needed for a 3-required-param read tool.

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

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

Schema coverage is 100% and every parameter carries a description pointing to discovery tools (list_queries, get_dashboard, list_projects), so the schema does the heavy lifting. The description adds only indirect meaning ("by id", "without queryType") and says nothing about projectId or environment scoping.

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

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

Opens with a specific verb and resource: "Fetch one saved analytics query by id with its full definition as an editable spec ... and the dashboards it appears on." It also disambiguates from siblings by naming the exact spec format that run_insight_query / run_funnel_query / run_retention_query consume and by naming update_query separately.

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

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

Gives explicit when-to-use guidance ("Read a query with this before changing it") and routes to the correct alternatives: pass the edited spec to update_<queryType>_query, or use update_query for rename-only. It also states a prerequisite (load the manage-dashboards skill first) rather than leaving it to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description then adds genuinely non-obvious behavioral context: statuses are refreshed against events received so far (data freshness semantics), the possible status values including mismatch, and that the response carries "what to do next." It stops short of discussing pagination or size limits for large plans.

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, each doing distinct work: what is returned, how status is maintained, how to choose planId, and the workflow prerequisite. The return payload is front-loaded before the parameter guidance, so an agent can decide to call the tool before parsing the 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?

For a read-only, three-parameter tool with no output schema, the description covers the response shape in enough detail that an agent knows what it will get back and how to act on it. Nothing needed to invoke 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 all three parameters are already documented in the schema, including the alternate meaning of an omitted planId. The description's planId sentence largely restates the schema text, adding only the mild framing "when you were given one," and says nothing extra about projectId or environment. Baseline 3 is appropriate when the schema carries the 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 opens with a specific verb and resource ("Read a tracking plan") and then enumerates exactly what is returned: events, descriptions, placement hints, typed properties, and lifecycle status. Because the sibling set contains create_tracking_plan and update_tracking_plan_items, the read-oriented framing makes the distinction between this tool and its write siblings unmistakable.

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

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

It gives concrete when-to guidance for the optional parameter ("Pass planId when you were given one; omit it for the project's latest open plan") and a workflow rule ("Read the whole plan before changing any code"). What it does not do is explicitly route the agent to update_tracking_plan_items or create_tracking_plan as the follow-on alternatives; the exclusion is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered structurally. The description adds genuine value by describing the return payload — a 'description' field and a 'summary' with block/condition counts and referenced event names — plus the prerequisite skill load. It stops short of covering pagination behavior or what happens when cohortId does not resolve.

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

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

Front-loaded with the core action and mode, followed by result shape, then search, then the skill prerequisite. Three sentences with little waste, though the clause 'use them for a quick shape of the definition' is mildly redundant after already describing the fields.

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

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

With no output schema, the description carries the return-value burden and does so adequately by naming the description and summary fields. Combined with the skill-load instruction and mode explanation, an agent has enough to call it correctly; only pagination and error behavior are unaddressed.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds intent beyond the schema: it frames 'search' as a discovery mechanism and cohortId as a mode switch between listing and single fetch. It omits any mention of includeDefinitions, so the raw-definition toggle is left entirely to the schema.

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

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

States a specific verb and resource ('List player cohorts'), parenthetically disambiguates the resource ('dynamic player segments'), and covers the two modes (list vs. fetch one by id). An agent can distinguish it from create_cohort, update_cohort, and get_cohort_members without opening any schema.

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

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

Gives clear context: use 'search' to locate cohorts by name or description, set cohortId to fetch a single cohort, and load the cohorts skill first. It does not explicitly name sibling alternatives (e.g., get_cohort_members for membership, create_cohort for creation), so routing guidance is contextual rather than exhaustive.

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

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

The readOnlyHint/openWorldHint annotations already establish the safety profile, so the description's job is to add operational context. It does add useful detail about what is returned, including the semantic meaning of the primary flag ('the one SDKs receive') and why the structure summary exists, but it says nothing about result ordering, whether results are capped, or behavior on an invalid project/environment.

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

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

It is front-loaded with purpose and return contents, and every clause is functional. The final two sentences about search duplicate what the schema already says, which is the only wasted space.

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

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

With no output schema, the description carries the burden of describing return values, and it does so thoroughly, including the primary flag and the structure summary fields. The remaining gaps (ordering, result caps, error behavior) are minor for a simple read-only 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 all three parameters are already documented, including that search is a case-insensitive substring match and that list_projects discovers valid ids. The description's sentence about search restates the schema almost verbatim and adds no new semantics, 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 gives a specific verb and resource ('List the remote configurations') and scopes it to 'the current project and environment', then enumerates exactly what each row contains (id, name, alias, primary flag, structure summary). It implicitly distinguishes itself from get_configuration by framing the result as a way to 'decide which config to read ... before requesting content', but it never distinguishes itself from the sibling search_configuration, and its 'Use search' phrasing refers to a parameter in a way that could be misread as naming that sibling 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?

There is clear when-to-use guidance: call this to survey configurations and gauge size before requesting content with get_configuration. It also explains the search parameter's optionality ('Omit it to get all configurations'). It stops short of stating when to prefer search_configuration over this tool, which is the one routing decision an agent still has to guess.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value beyond them by disclosing the result shape (folder paths, contained dashboards, top-level dashboards) and a depth bound of 6 levels, which matters for organizing operations.

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 zero waste: the returned content and depth limit come first, followed by usage timing and the skill prerequisite. Nothing is buried or repeated.

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 read-only list tool with no output schema, the description covers what is returned, the hierarchy depth, and the calling context. An agent has everything needed to call it correctly without guessing.

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 both projectId and environment fully documented, including how to discover valid values via list_projects. The description adds no parameter-level meaning beyond the schema, 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 (List) and resource (dashboard folders) and adds precise scope: nested up to 6 levels, each folder's path, contained dashboards, plus top-level dashboards. This distinguishes it clearly from list_dashboards, which would not return folder paths or hierarchy.

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

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

Gives explicit when-to-use guidance ('before creating, moving, or organizing dashboards') and a prerequisite ('Load the manage-dashboards skill first'). It does not explicitly name sibling alternatives such as list_dashboards or get_dashboard for narrower needs, so 4 rather than 5.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: project scoping, the fact that queries are returned inline by default, and the OR-matching rule for search. It omits result-size limits, pagination, or ordering, which keeps it from a 5.

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

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

Three sentences, front-loaded with the core action, then search semantics, then use cases — nothing wasted. There is mild redundancy between "including the saved queries on each" and "what queries they contain," which keeps it off 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?

With no output schema, the description usefully sketches what comes back (dashboards with their saved queries) and how filtering works. It leaves the includeQueries=false behavior and any pagination or volume characteristics unstated, a modest gap 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 coverage is 100%, so every parameter including 'search' and 'includeQueries' is already documented in the schema, and the description's search explanation largely restates it. The one added bit is the example topic ('FTUE funnel'), which is marginal. 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?

The description gives a specific verb and resource ("List the analytics dashboards (boards) in the current project") and adds scope detail (queries inlined on each). It implicitly distinguishes itself from get_dashboard and list_queries by covering the collection plus its nested queries, but never names those siblings explicitly.

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 states the concrete use cases — answering which dashboards exist, what queries they contain, or locating a specific dashboard — and explains when to use the 'search' parameter with a worked example ('FTUE funnel'). It stops short of exclusionary guidance such as "use get_dashboard when you already have an id."

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), yet the description still adds real behavioral value: the exact return shape, the four type values, and the special case where web_url links additionally return taggedUrl with UTM values and utm_id=gb_<slug>. It does not address ordering or pagination, which are the only obvious behavioral gaps.

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 front-loads the core action and scope, then moves to return fields, then to workflow routing. Four sentences, all of them informative, though the dense run-on enumeration of return fields is slightly harder to scan than a compact list.

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

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

There is no output schema, so the description must describe the return values, and it does so field by field, including the conditional web_url extras. It also supplies the skill prerequisite and the follow-up tool, which is enough for an agent to call this correctly without further context.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining what the type values actually mean, especially that web_url points at a site running the Gamebeast JavaScript SDK. It does not add anything about the search or projectId/environment parameters beyond the schema, so it stops short of a 5.

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

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

States a specific verb and resource ('List deeplinks created for the current project') with an explicit scope bound to the project. It then enumerates the returned fields, so an agent knows exactly what kind of data comes back, and it implicitly separates itself from query_deeplink_metrics, which is named later.

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

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

Gives an explicit sequencing rule ('Use list_deeplinks first, then query_deeplink_metrics with the deeplink id for analytics') and names the alternative tool plus the condition that selects it. It also adds a prerequisite ('Load the understand-deeplinks skill ... first'), so there is no ambiguity about when and how to start.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description goes well beyond them by disclosing sort behavior (relevance when searching, otherwise total sent descending), the pagination/truncation signal via totalCount, and the meaning of pendingEventTypes and pending arguments. It lacks any note on permissions, rate limits, or cost for a potentially large listing.

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

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

Purpose is front-loaded in the first sentence, followed by ordering, pagination, and result-shape semantics in a logical order with no filler. The backtick-heavy run of sentences about defaultProperties, properties, arguments, and pendingEventTypes is dense but each carries distinct information the schema cannot.

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 carries the return-shape burden and does it: it explains defaultProperties versus an event's own properties/arguments, the type/dataType fields usable as filters or breakdowns, and the pending flags for described-but-unseen data. For a 7-parameter read-only listing tool, an agent has enough to call it and interpret the response.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds genuine meaning: 'search' is described as filtering AND ranking by relevance, and limit is tied to a re-call strategy when totalCount is exceeded. It does not clarify includeHidden, sortBy, or sortOrder 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?

Opens with a specific verb and resource: 'List the analytics event (marker) types tracked in the current project and environment', naming both scoping dimensions. It is clear what the tool returns, but it never distinguishes itself from the sibling describe_event_types, so an agent must infer the split between listing and describing.

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

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

Gives actionable in-tool guidance: use 'search' to find markers by name, and call again with a higher limit or narrower search when totalCount exceeds the returned results. It does not state when to prefer this over describe_event_types or explain what happens with includeHidden, so alternatives are left implicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's job is to add meaning beyond that. It does by explaining lock semantics — a reserved path and everything under it cannot be changed by another experiment or a configuration edit until the owning experiment ends. It stops short of describing the fields each lock entry returns, which would have completed the picture.

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

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

Three tight sentences, front-loaded with the definition, then the consequence, then the usage routing and prerequisite. Nothing is redundant with the structured fields.

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

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

With no output schema, the description does need to convey what comes back, and it identifies the returned concept (reserved paths) and who owns them. It is complete enough to call correctly; only the shape of a lock entry is left unspecified.

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

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

Schema coverage is 100%, including descriptions for projectId, environment, and configurationId, so the schema carries parameter meaning. The description's 'optionally for one configuration' merely corroborates the configurationId semantics; 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?

The description opens with a specific verb and resource: 'List configuration paths reserved by scheduled or active experiments, optionally for one configuration.' That is unmistakably distinct from siblings such as list_configurations or preview_configuration_change, so an agent can select it without opening 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?

It gives explicit when-to-use guidance: before create_experiment and when explaining a refused configuration change, plus a prerequisite step (load_skill("understand-experiments")). This is exactly the routing information an agent needs, not just implied 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds useful behavior beyond that: newest-first ordering, the assignment-source taxonomy, and the enrollment flag. It doesn't cover pagination behavior or response size limits, which the schema's defaults only partly imply.

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 front-loaded paragraph that opens with the resource and scope before the filters and workflow example. The dense em-dash phrasing packs in a lot, but every sentence, including the skill prerequisite, carries operational 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?

For a 9-parameter, non-mutating list tool with no output schema, the description does the heavy lifting on return shape and filtering and adds a workflow pointer. Minor gaps remain around pagination semantics and the required experimentId parameter.

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 67% schema coverage the baseline is 3, but the description adds practical meaning: search matches on unit id, the filters are group/status/source, and the source values are explained as how a unit got into its group. The required experimentId and page/pageSize parameters remain undescribed in both schema and description.

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

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

The description names a specific verb and resource (list the units assigned to an experiment) and enumerates the returned fields: current group, assignment source (weightedHash/roundRobin/manual), and enrollment state. This is clearly distinguishable from siblings such as get_cohort_members or get_experiment_results.

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

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

It gives concrete when-to-use guidance ('to check which group a specific player is in before changing it with assign_experiment_unit') and a prerequisite (load the understand-experiments skill first). It doesn't explicitly state when not to use it, e.g. that aggregate results belong to get_experiment_results.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses the non-obvious default state filter (a silent scoping behavior an agent could otherwise miss) and the 'enrolledUnits null means the count could not be read, not zero' caveat, which prevents a real misinterpretation. It also flags the load_skill prerequisite, which is operationally important.

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

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

Front-loaded with purpose and return contents, then defaults, then sibling routing, then the skill prerequisite. Most sentences carry distinct information, though the return-field enumeration is somewhat dense and the trailing skill instruction could be positioned earlier for prominence.

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 carries the burden of explaining return values — and it does so field by field, including the null-count edge case. Combined with default-filter semantics and sibling routing, an agent has everything needed to call this 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, but the description adds real meaning by explaining the default value set for 'state' and its filtering consequence. Minor gap: it lists states as scheduled/active/ended/terminated while the schema enum also includes 'pending', leaving one accepted value unexplained.

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

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

States a specific verb and resource ('List A/B experiments') plus the scope ('current project and environment'), then enumerates the returned fields (id, name, state, unit type, schedule, groups, enrolled units). This makes it instantly distinguishable from sibling list_* tools and from get_experiment / get_experiment_results.

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

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

Explicitly tells the agent that the default is active+scheduled experiments and that 'state' must be passed to see ended or terminated ones. It also routes to concrete alternatives by name: get_experiment for targeting/configuration and get_experiment_results for group performance, plus a required skill load first.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered structurally; the description reinforces it by stating agents cannot create or edit heatmaps and explaining how heatmaps come into existence (SDK registration plus Data page management). It adds provenance and id semantics but says nothing about result size, pagination, or ordering, which is what an agent still lacks for a list call with no output schema.

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

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

Front-loaded with the resource definition, then the disambiguation, then the constraint, then the prerequisite — a sensible priority order with no filler. The first sentence is long and packs definitional detail into stacked clauses, which costs a little immediate scannability.

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 read-only list tool with four documented parameters and no output schema, the description covers what the objects are, why the id matters for downstream query tools, and what an agent cannot do. The remaining gap is return-shape expectations such as pagination or ordering, which matters here because no output schema is present to answer it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds conceptual meaning the schema does not: it explains that the heatmap id is the value a heatmap query's heatmapId points at, which tells an agent why heatmapId filtering exists and how to chain into run_heatmap_query. The search and environment parameters are left entirely to their 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?

States a specific verb and resource (list the project's heatmaps) and then defines the resource itself as map definitions with bounds, resolution and background image, so an agent knows exactly what object class it is enumerating. Crucially it disambiguates from the similarly named heatmap-query siblings by declaring 'A heatmap is not a query' and explaining that its id is the target of a query's heatmapId.

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?

Names the alternatives explicitly (run_heatmap_query, create_heatmap_query) and the relationship that routes between them, states a hard exclusion ('Agents cannot create or edit heatmaps'), and gives an ordering prerequisite ('Load the heatmap-queries skill first'). This is the full when/when-not/alternatives pattern.

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

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

Annotations already cover readOnlyHint=true and openWorldHint=false, so safety is declared. The description adds meaningful scope information beyond that: the results are limited to what "this connection can reach," which tells the agent to expect a connection-scoped, possibly partial inventory. It does not describe ordering or pagination, but with no output schema it still conveys the shape of the return.

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, both earning their place: the first declares the returned resources and fields, the second tells the agent what to do with them. The most actionable information (what you get) 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 a zero-parameter, read-only discovery tool with no output schema and no nested structures, the description covers what is returned, the field-level detail for organizations, and the intended downstream use of the results. Nothing an agent needs in order 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing the description needs to compensate for. It does not waste words re-explaining an empty 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 uses a specific verb ("List") and enumerates the actual resources returned: organizations with id and name, projects, and environment names. It is slightly broader than the tool name list_projects, but that broadening is clarifying rather than confusing. It does not explicitly distinguish itself from the many list_* siblings (list_dashboards, list_cohorts, etc.), which is why it falls short of 5.

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

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

"Use the returned project ids and environment names for other tool calls" gives clear context that this is a discovery/bootstrap call whose outputs feed subsequent operations. It does not state when not to use it or name an alternative, but no obvious alternative exists for this discovery role.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered by structured data. The description adds genuine behavioral context beyond that: it discloses what is returned (query type, chart style, event names, dashboard membership) and describes a truncation/pagination behavior ('if totalCount exceeds the returned results, call again with a more specific search'). It does not mention default page size, but the schema does.

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

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

Three short sentences, front-loaded with the purpose and followed by return contents and then the narrowing tactic; nothing is padding. Minor risk: "Use 'search' to find queries..." is unquoted-path ambiguous and could momentarily read as a sibling tool reference.

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 four parameters, two required scoping params (projectId, environment), and no output schema, the description does cover what comes back and how to page. It does not state that results are scoped to the current project/environment combination beyond a passing phrase, nor mention ordering, so an agent must infer some scoping and result-shape details.

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

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

Schema coverage is 100%, so the baseline would be 3, and the description earns above baseline by clarifying that 'search' matches and ranks on name or description with concrete example terms, and by tying 'limit' to a totalCount-driven refine-and-retry loop. It adds meaning about result semantics rather than restating the schema.

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

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

The description opens with a specific verb and resource ('List the saved analytics queries in the current project') and then enumerates the returned fields (type, chart style, tracked event names, dashboards), which lets an agent distinguish this from get_query or the create_*_query siblings. It stops short of explicitly naming a contrasting sibling, so it is clear but not fully 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?

There is real usage context: use the 'search' argument for name/description lookups (with concrete examples 'FTUE funnel', 'DAU') and refine the search when totalCount exceeds the returned page. However, that guidance is about how to use a parameter rather than when to choose this tool over alternatives like get_query, list_dashboards, or the run_*_query tools, so selection guidance is only implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: listing mode returns per-formula usage counts, detail mode returns the queries that use it, and a chart-based formula metric always resolves to the formula's current definition. Return shape itself is not described, but the semantics an agent needs are.

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 dual-mode behavior is front-loaded in the first sentence and the prerequisite is placed last, which is the right order. It is dense but nearly every clause carries information; the data.savedFormulaId sentence is slightly tangential to calling this tool, keeping it from 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?

For a read-only, four-parameter listing/detail tool with no output schema, the description covers both modes, the prerequisite skill, and the conceptual meaning of a saved formula. What an agent needs to call it correctly is present; only result-shape and pagination behavior are unaddressed.

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

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

Schema description coverage is 100%, so formulaId, search, projectId and environment are already documented in the schema. The description reinforces formulaId's dual behavior but says nothing about the search parameter's matching/ranking or the environment scoping. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description gives a specific verb and resource ("List the project's saved formulas") and parenthetically defines what a saved formula is, then states the second mode ("fetch one by formulaId with the queries that use it"). An agent can distinguish this from create_saved_formula or update_saved_formula without opening any schema.

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

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

It clearly states the condition that selects each mode: omit formulaId to list, set formulaId to fetch one with its queries. It also gives a usage prerequisite ("Load the insight-queries skill first") and explains the downstream usage path via data.savedFormulaId. It does not name sibling alternatives such as list_queries, 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?

Annotations only give readOnlyHint=true and openWorldHint=false, so the description carries the substantive load: it discloses that counts come from the ClickHouse store, that sources can be active/paused, and what fields come back. It does not mention result size, pagination, or whether paused sources are always included.

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

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

Front-loaded with the purpose, then a one-line explanation of what a source is, then returns, then call ordering. Four sentences each add something, though the trailing two instructions could be merged for tighter flow.

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

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

With no output schema, the description usefully enumerates the returned fields and adds the prerequisite skill call plus call ordering, which is enough to invoke correctly. Minor gaps remain on whether paused sources are returned or how large the list can get.

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 both projectId and environment, including the list_projects discovery hint. The description's phrase 'configured for this project' only restates the scoping 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?

States a specific verb and resource ('List the community pulse sentiment sources') and immediately scopes it to the project. It distinguishes itself from both query_sentiment and the similarly named get_community_pulse by describing sources as the configuration/metadata layer rather than the analysis result.

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

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

Explicitly tells the agent to call this first to see what data exists before running query_sentiment, and names the prerequisite skill load. It lacks an explicit 'when not to use' (e.g., if sources are already known), 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the bar is lower, but the description still adds real behavior: the tool returns instructional text that the agent is expected to follow, and the same content is mirrored as an MCP resource. That is meaningful context beyond the safety profile.

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

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

Two sentences, front-loaded with what the tool does, then the invocation rule. Every clause earns its place, with no restating of the schema or annotations.

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 read tool with no output schema, the description covers what it returns (task instructions), how to use the result (follow it), when to call it, and the equivalent resource path. Nothing an agent needs to invoke 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% with a 25-value enum, so the baseline is 3, but the description adds discovery context by noting that the server instructions enumerate the available skills. That helps the agent pick a valid enum value rather than guessing at the list.

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 ('Load a Gamebeast skill') and clarifies what a skill is ('detailed instructions for a task') with concrete examples (insight queries, experiment data). It does not explicitly distinguish itself from doc-reading siblings like read_doc or search_docs, which an agent might plausibly confuse it with.

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

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

Gives a clear trigger: 'Call this before a task a skill covers', and points to server instructions as the authoritative list. It also names an alternative access path (the skill://<name>/SKILL.md resource). No explicit when-not-to-use case is given, but the pre-task condition is a strong, actionable 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?

Annotations already declare non-read-only, idempotent, non-destructive, so the safety bar is partly met. The description adds real context beyond them: the move is persisted immediately ('Saved when this runs') and the reason text surfaces on a user approval card. It does not mention permission requirements or failure behavior for invalid folder/index values.

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

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

Three short sentences, front-loaded with the operation and its scope, followed by the persistence/justification note and the prerequisite. Nothing is padded and no sentence restates the tool name.

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 mutation with no output schema, this covers the essentials: what changes, that it is saved, why reason matters, and which skill to load first. Minor gaps remain around how index interacts with an unchanged folder and what the tool returns on success.

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 per-parameter baseline is 3. The description adds genuine meaning on top by framing folderId and index as independently optional ('and/or'), telling the agent that reordering without refiling, and refiling without reordering, are both valid call shapes.

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: moving a dashboard into a folder (or top level) and/or repositioning it in the project's shared sidebar order. The phrase 'shared sidebar order' sharply scopes it away from layout/panel siblings like update_dashboard_layout, but no sibling is named explicitly, so the agent must infer the boundary.

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

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

Gives an actionable prerequisite (load the manage-dashboards skill first) and instructs the agent to justify the change in reason because it is user-visible and saved. There is no explicit when-not guidance, e.g. how this differs from update_dashboard_folder for folder-level operations.

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

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

Goes well beyond readOnlyHint=true by explaining the non-persistence explicitly and disclosing the shape of what comes back: per-change before/after values, which keys' privacy would flip, the primary-configuration flag with its meaning (live to game servers), and the contentHash needed to chain into update_configuration. That last detail is behaviorally important and appears nowhere in the annotations.

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

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

Three sentences, front-loaded with the dry-run framing and the return summary before the usage note. Minor slack in the "Optional: use it to check a change, or to show the user..." phrasing and in restating the update_configuration relationship, but nothing is 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?

There is no output schema, yet the description enumerates the return payload precisely enough (before/after, privacy flips, primary flag, contentHash) that an agent knows what it will get and how to feed the result into update_configuration. For a 5-parameter read-only preview tool this leaves nothing an agent would need 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 changes, privacy, projectId, environment and configurationId in detail, including the set/remove op semantics and the private-key explanation. The description mentions changes and privacy flips only in passing and adds no path syntax, ordering or limits beyond what the schema states. Baseline 3 applies.

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

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

States a specific verb and resource ("Dry-run a configuration change without saving it") and immediately distinguishes itself from update_configuration by declaring it runs the same validation but persists nothing. An agent can tell exactly what this does versus its nearest sibling without opening 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?

Names the alternative explicitly ("update_configuration runs the same validation and saves the change when it runs") and gives two concrete triggers: checking a change, or showing the user the before/after. The only gap is that it never says when not to reach for it — e.g. use get_configuration to simply read the current state — so the routing is clear against one sibling but not the whole config toolset.

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